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 nouveau masque d’affinité relative au groupe pour le thread appelant.
[out, optional] PreviousAffinity
Pointeur vers une structure de GROUP_AFFINITY allouée à l’appelant dans laquelle la routine écrit des informations sur l’affinité de groupe précédente du thread appelant. L’appelant peut ensuite utiliser ce pointeur comme paramètre d’entrée de la routine KeRevertToUserGroupAffinityThread pour restaurer l’affinité de thread précédente. Fréquemment, KeSetSystemGroupAffinityThread écrit dans cette structure des valeurs 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. Lors du premier de ces appels, l’appelant doit spécifier une valeur non NULL 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 la section Notes.
Valeur de retour
None
Remarques
Cette routine modifie le numéro de groupe et le masque d’affinité relative au 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. En cas de réussite, la routine planifie l’exécution du thread sur un processeur de cet ensemble.
Si le paramètre PreviousAffinity n’a pas la valeur NULL, 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 vers laquelle previousAffinity pointe. Pour restaurer l’affinité de thread précédente, l’appelant peut fournir le pointeur vers cette structure en tant que paramètre d’entrée vers 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 modifie le numéro de groupe et le masque d’affinité en valeurs spécifiées dans *Affinity uniquement si les éléments suivants sont true :
- 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 du 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 nombre de groupes et le masque d’affinité sont tous deux nuls, KeRevertToUserGroupAffinityThread restaure l’affinité de thread en mode utilisateur actuelle. Si l’affinité de thread en mode utilisateur change entre les appels KeSetSystemGroupAffinityThread et KeRevertToUserGroupAffinityThread , 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 *Affinity ne prenne effet, KeSetSystemGroupAffinityThread supprime (définit sur zéro) tous les bits de masque d’affinité qui correspondent aux processeurs qui ne sont pas actuellement actifs. Dans un appel KeSetSystemGroupAffinityThread suivant, 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 de 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, ce 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 s’exécutent correctement dans les systèmes multiprocesseurs qui ont deux groupes ou plus. Toutefois, les pilotes qui utilisent des 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 prennent 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és avec des astérisque), l’appelant définit PreviousAffinity sur NULL. Avant la sortie du thread, il appelle KeRevertToUserGroupAffinityThread pour restaurer l’affinité de thread qui a été enregistrée par le premier appel KeSetSystemGroupAffinityThread .
Le diagramme suivant montre un modèle d’appel quelque peu différent dans lequel des paires d’appels KeSetSystemGroupAffinityThread et KeRevertToUserGroupAffinityThread sont imbriquées. 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 la fonction B deux fois. Supposons qu’à l’entrée de la fonction A, le thread a toujours l’affinité qui lui est attribuée par l’application en mode utilisateur. Ainsi, l’appel KeSetSystemGroupAffinityThread dans la fonction A enregistre l’affinité de thread d’origine en mode utilisateur. Lors du premier appel à la fonction B, KeSetSystemGroupAffinityThread enregistre l’affinité de thread attribuée par le pilote dans la fonction A, et l’appel correspondant à KeRevertToUserGroupAffinityThread restaure cette affinité. Une fois que B est retourné, keRevertToUserGroupAffinityThread dans A restaure l’affinité de thread d’origine en mode utilisateur. Lors du deuxième appel à B, l’appel KeSetSystemGroupAffinityThread enregistre l’affinité de thread d’origine en mode utilisateur, 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 modifié l’affinité de thread en une valeur définie par le pilote avant d’appeler B.
Si KeSetSystemGroupAffinityThread est appelé au niveau 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é au niveau IRQL = DISPATCH_LEVEL et que l’appel réussit, le changement de processeur en attente est différé jusqu’à ce que l’appelant abaisse l’IRQL sous DISPATCH_LEVEL.
À compter de Windows 11 et De Windows Server 2022, sur un système avec plus de 64 processeurs, les affinités de processus et de thread s’étendent par défaut à tous les processeurs du système, dans tous les groupes de processeurs. Pour définir l’affinité de groupe système d’un thread sur plusieurs groupes de processeurs, utilisez PsSetSystemMultipleGroupAffinityThread.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Disponible à partir de Windows 7. |
| Plateforme cible | Universal |
| En-tête | wdm.h (inclure 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) |