KeSetSystemGroupAffinityThread, fonction (wdm.h)
La routine KeSetSystemGroupAffinityThread modifie le numéro de groupe et le masque d’affinité du thread appelant.
Syntaxe
void KeSetSystemGroupAffinityThread(
[in] PGROUP_AFFINITY Affinity,
[out, optional] PGROUP_AFFINITY PreviousAffinity
);
Paramètres
[in] Affinity
Pointeur vers une structure GROUP_AFFINITY qui spécifie le nouveau numéro de groupe et le masque d’affinité relative au groupe pour le thread appelant.
[out, optional] PreviousAffinity
Pointeur vers une structure GROUP_AFFINITY allouée par l’appelant dans laquelle la routine écrit des informations sur l’affinité de groupe précédente du thread appelant. L’appelant peut ultérieurement utiliser ce pointeur comme paramètre d’entrée pour la routine KeRevertToUserGroupAffinityThread pour restaurer l’affinité de thread précédente. Fréquemment, KeSetSystemGroupAffinityThread écrit des valeurs dans cette structure qui ne sont pas des affinités de groupe valides, mais qui ont une signification particulière pour KeRevertToUserGroupAffinityThread. Ne fournissez pas de pointeurs vers ces valeurs spéciales en tant que paramètres d’affinité dans les appels KeSetSystemGroupAffinityThread suivants.
Si nécessaire, l’appelant peut modifier l’affinité de thread plusieurs fois en appelant KeSetSystemGroupAffinityThread plusieurs fois. Au cours de la première de ces appels, l’appelant doit spécifier une valeur deNULL non pour PreviousAffinity afin que l’affinité de thread d’origine puisse être capturée et restaurée ultérieurement. Toutefois, les appels ultérieurs à KeSetSystemGroupAffinityThread peuvent, en tant qu’option, définir PreviousAffinity = NULL. Pour plus d’informations, consultez Remarques.
Valeur de retour
Aucun
Remarques
Cette routine modifie le numéro de groupe et le masque d’affinité relative de groupe du thread appelant. Le paramètre affinity pointe vers une structure GROUP_AFFINITY. Le numéro de groupe et le masque d’affinité dans cette structure identifient un ensemble de processeurs sur lesquels le thread peut s’exécuter. Si elle réussit, la routine planifie l’exécution du thread sur un processeur dans cet ensemble.
Si le paramètre PreviousAffinity n’est pasNULL, la routine enregistre des informations sur l’affinité de groupe précédente, qui étaient en vigueur au début de l’appel, dans la structure GROUP_AFFINITY qui PreviousAffinity pointe vers. Pour restaurer l’affinité de thread précédente, l’appelant peut fournir le pointeur à cette structure en tant que paramètre d’entrée à la routine KeRevertToUserGroupAffinityThread.
Dans un système multiprocesseur, une routine de pilote en mode noyau qui s’exécute dans le contexte d’un thread en mode utilisateur peut avoir besoin d’appeler KeSetSystemGroupAffinityThread pour modifier temporairement l’affinité de groupe du thread. Avant la sortie de la routine, elle doit appeler KeRevertToUserGroupAffinityThread pour restaurer le masque d’affinité du thread à sa valeur d’origine.
Un processus peut avoir une affinité pour plusieurs groupes à la fois. Toutefois, un thread ne peut être affecté qu’à un seul groupe à tout moment. Ce groupe est toujours dans l’affinité du processus du thread. Un thread peut modifier le groupe auquel il est affecté en appelant KeSetSystemGroupAffinityThread.
KeSetSystemGroupAffinityThread remplace le numéro de groupe et le masque d’affinité par les valeurs spécifiées dans *Affinity uniquement si les valeurs suivantes sont vraies :
- Le numéro de groupe est valide.
- Le masque d’affinité est valide (autrement dit, seuls les bits de masque qui correspondent aux processeurs logiques dans le groupe sont définis).
- Au moins un des processeurs spécifiés dans le masque d’affinité est actif.
En outre, KeSetSystemGroupAffinityThread écrit zéro dans le numéro de groupe et le masque d’affinité dans *PreviousAffinity si l’affinité de groupe précédente a été affectée au thread en mode utilisateur. En réponse à une structure GROUP_AFFINITY dans laquelle le numéro de groupe et le masque d’affinité sont tous deux zéro, KeRevertToUserGroupAffinityThread restaure l’affinité de thread en mode utilisateur actuel. Si l’affinité de thread en mode utilisateur change entre les appels KeSetSystemGroupAffinityThread et KeRevertToUserGroupAffinityThread appels, l’affinité en mode utilisateur la plus récente est affectée au thread. (Une application peut appeler une fonction telle que SetThreadGroupAffinity pour modifier l’affinité de groupe en mode utilisateur d’un thread.)
Avant que le nouveau masque d’affinité dans * d’affinité prenne effet, KeSetSystemGroupAffinityThread supprime (définit sur zéro) tous les bits de masque d’affinité qui correspondent aux processeurs qui ne sont actuellement pas actifs. Dans un appel de KeSetSystemGroupAffinityThread, la valeur que la routine écrit dans *PreviousAffinity peut contenir un masque d’affinité qui a été modifié de cette façon.
Une routine associée, KeSetSystemAffinityThreadEx, modifie le masque d’affinité du thread appelant, mais cette routine, contrairement à KeSetSystemGroupAffinityThread, n’accepte pas un numéro de groupe comme paramètre d’entrée. À compter de Windows 7, KeSetSystemAffinityThreadEx suppose que le masque d’affinité fait référence aux processeurs du groupe 0, qui est compatible avec le comportement de cette routine dans les versions antérieures de Windows qui ne prennent pas en charge les groupes. Ce comportement garantit que les pilotes existants qui appellent KeSetSystemAffinityThreadEx et qui n’utilisent aucune fonctionnalité orientée groupe ne s’exécutent correctement dans les systèmes multiprocesseurs qui ont deux groupes ou plus. Toutefois, les pilotes qui utilisent toutes les fonctionnalités orientées groupe dans Windows 7 et versions ultérieures du système d’exploitation Windows doivent appeler KeSetSystemGroupAffinityThread au lieu de KeSetSystemAffinityThreadEx.
KeSetSystemGroupAffinityThread et KeRevertToUserGroupAffinityThread prendre en charge divers modèles d’appel. Deux exemples sont présentés dans les diagrammes suivants.
Le diagramme suivant représente un thread de pilote qui appelle KeSetSystemGroupAffinityThread trois fois pour modifier l’affinité de thread, puis appelle KeRevertToUserGroupAffinityThread pour restaurer l’affinité de thread d’origine.
Dans le diagramme précédent, les trois zones intitulées « Définir l’affinité » sont des appels à KeSetSystemGroupAffinityThread, et la zone intitulée « Rétablir l’affinité » est un appel à KeRevertToUserGroupAffinityThread. Le premier appel KeSetSystemGroupAffinityThread utilise le pointeur de sortie PreviousAffinity pour enregistrer l’affinité de thread d’origine. Dans les deux appels suivants à KeSetSystemGroupAffinityThread (marqué avec astérisques), l’appelant définit PreviousAffinity sur NULL. Avant la sortie du thread, il appelle KeRevertToUserGroupAffinityThread pour restaurer l’affinité de thread enregistrée par le premier appel KeSetSystemGroupAffinityThread.
Le diagramme suivant montre un modèle d’appel un peu différent dans lequel les paires de KeSetSystemGroupAffinityThread et KeRevertToUserGroupAffinityThread appels sont imbriqués. Dans ce diagramme, chaque appel à KeSetSystemGroupAffinityThread dans le thread de pilote utilise le paramètre de sortie PreviousAffinity pour enregistrer l’affinité de thread précédente, et chacun de ces appels est associé à un appel à KeRevertToUserGroupAffinityThread qui restaure l’affinité de thread enregistrée.
Dans le diagramme précédent, la fonction A dans le thread de pilote appelle deux fois la fonction B. Supposons que, lors de l’entrée à la fonction A, le thread a toujours l’affinité qui lui est attribuée par l’application en mode utilisateur. Ainsi, le KeSetSystemGroupAffinityThread appel dans la fonction A enregistre l’affinité de thread en mode utilisateur d’origine. Pendant le premier appel à la fonction B, le KeSetSystemGroupAffinityThread enregistre l’affinité de thread affectée par le pilote dans la fonction A, et l’appel correspondant à KeRevertToUserGroupAffinityThread restaure cette affinité. Une fois B retourné, le KeRevertToUserGroupAffinityThread dans A restaure l’affinité de thread en mode utilisateur d’origine. Pendant le deuxième appel à B, l’appel KeSetSystemGroupAffinityThread enregistre l’affinité de thread en mode utilisateur d’origine et l’appel correspondant à KeRevertToUserGroupAffinityThread restaure cette affinité. Le point de cet exemple est que la fonction B n’a pas besoin de savoir si l’appelant (fonction A) a changé l’affinité de thread en une valeur définie par le pilote avant d’appeler B.
Si KeSetSystemGroupAffinityThread est appelée à IRQL <= APC_LEVEL et que l’appel réussit, la nouvelle affinité de groupe prend effet immédiatement. Lorsque l’appel est retourné, le thread appelant est déjà en cours d’exécution sur un processeur spécifié dans la nouvelle affinité de groupe. Si KeSetSystemGroupAffinityThread est appelé à IRQL = DISPATCH_LEVEL et que l’appel réussit, la modification du processeur en attente est différée jusqu’à ce que l’appelant diminue l’IRQL ci-dessous DISPATCH_LEVEL.
À compter de Windows 11 et Windows Server 2022, sur un système avec plus de 64 processeurs, processus et affinités de thread s’étendent sur tous les processeurs du système, sur tous les groupes de processeurs , par défaut. Pour définir l’affinité de groupe système d’un thread sur plusieurs groupes de processeurs, utilisez PsSetSystemMultipleGroupAffinityThread.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Disponible à partir de Windows 7. |
| plateforme cible | Universel |
| d’en-tête | wdm.h (include Wdm.h, Wdm.h, Ntifs.h) |
| bibliothèque | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | <= DISPATCH_LEVEL (voir la section Remarques). |
| règles de conformité DDI | HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm) |