KeSetSystemGroupAffinityThread-Funktion (wdm.h)
Die KeSetSystemGroupAffinityThread Routine ändert die Gruppennummer und das Affinitätsformat des aufrufenden Threads.
Syntax
void KeSetSystemGroupAffinityThread(
[in] PGROUP_AFFINITY Affinity,
[out, optional] PGROUP_AFFINITY PreviousAffinity
);
Parameter
[in] Affinity
Ein Zeiger auf eine GROUP_AFFINITY Struktur, die die neue Gruppennummer und das gruppenrelative Affinitätsformat für den aufrufenden Thread angibt.
[out, optional] PreviousAffinity
Ein Zeiger auf eine vom Aufrufer zugewiesene GROUP_AFFINITY Struktur, in die die Routine Informationen über die vorherige Gruppenaffinität des aufrufenden Threads schreibt. Der Aufrufer kann diesen Zeiger später als Eingabeparameter für die KeRevertToUserGroupAffinityThread Routine verwenden, um die vorherige Threadaffinität wiederherzustellen. Häufig schreibt KeSetSystemGroupAffinityThread- Werte in diese Struktur, die keine gültigen Gruppenaffinitäten sind, die jedoch eine besondere Bedeutung für KeRevertToUserGroupAffinityThreadhaben. Stellen Sie keine Zeiger für diese speziellen Werte als Affinity Parameter in nachfolgenden KeSetSystemGroupAffinityThread Aufrufen bereit.
Bei Bedarf kann der Aufrufer die Threadaffinität mehrmals ändern, indem er KeSetSystemGroupAffinityThread- mehrmals aufruft. Während der ersten dieser Aufrufe sollte der Aufrufer einen Wert ohneNULL für PreviousAffinity- angeben, sodass die ursprüngliche Threadaffinität erfasst und später wiederhergestellt werden kann. Die späteren Aufrufe von KeSetSystemGroupAffinityThread können jedoch als Option PreviousAffinity = NULL-festlegen. Weitere Informationen finden Sie in den Hinweisen.
Rückgabewert
Nichts
Bemerkungen
Diese Routine ändert die Gruppennummer und die gruppenrelative Affinitätsmaske des aufrufenden Threads. Der parameter Affinity verweist auf eine GROUP_AFFINITY Struktur. Die Gruppennummer und die Affinitätsmaske in dieser Struktur identifizieren eine Reihe von Prozessoren, auf denen der Thread ausgeführt werden kann. Bei erfolgreicher Ausführung plant die Routine den Thread für einen Prozessor in diesem Satz.
Wenn der parameter PreviousAffinity nichtNULList, speichert die Routine Informationen zur vorherigen Gruppenaffinität, die am Anfang des Aufrufs wirksam waren, in der GROUP_AFFINITY Struktur, auf die PreviousAffinity verweist. Um die vorherige Threadaffinität wiederherzustellen, kann der Aufrufer den Zeiger auf diese Struktur als Eingabeparameter für die KeRevertToUserGroupAffinityThread Routine bereitstellen.
In einem Multiprozessorsystem muss eine Kernelmodustreiberroutine, die im Kontext eines Benutzermodusthreads ausgeführt wird, möglicherweise KeSetSystemGroupAffinityThread- aufrufen, um die Gruppenaffinität des Threads vorübergehend zu ändern. Bevor die Routine beendet wird, sollte KeRevertToUserGroupAffinityThread- aufgerufen werden, um die Affinitätsmaske des Threads auf den ursprünglichen Wert wiederherzustellen.
Ein Prozess kann eine Affinität für mehrere Gruppen gleichzeitig haben. Ein Thread kann jedoch immer nur einer Gruppe zugewiesen werden. Diese Gruppe befindet sich immer in der Affinität des Prozesses des Threads. Ein Thread kann die Gruppe ändern, der sie zugewiesen wird, indem KeSetSystemGroupAffinityThread-aufgerufen wird.
KeSetSystemGroupAffinityThread ändert die Gruppennummer und das Affinitätsformat in die werte, die in *Affinity angegeben sind, nur, wenn folgendes zutrifft:
- Die Gruppennummer ist gültig.
- Die Affinitätsmaske ist gültig (d. a. es werden nur Maskenbits festgelegt, die logischen Prozessoren in der Gruppe entsprechen).
- Mindestens einer der Prozessoren, die in der Affinitätsmaske angegeben ist, ist aktiv.
Darüber hinaus schreibt KeSetSystemGroupAffinityThread null in die Gruppennummer und das Affinitätsformat in *PreviousAffinity, wenn die vorherige Gruppenaffinität dem Thread im Benutzermodus zugewiesen wurde. Als Reaktion auf eine GROUP_AFFINITY Struktur, in der die Gruppennummer und die Affinitätsmaske null sind, stellt KeRevertToUserGroupAffinityThread die aktuelle Benutzermodusthreadaffinität wieder her. Wenn sich die Threadaffinität im Benutzermodus zwischen dem KeSetSystemGroupAffinityThread und KeRevertToUserGroupAffinityTh read-Aufrufe ändert, wird der letzte Benutzermodusaffinität dem Thread zugewiesen. (Eine Anwendung kann eine Funktion wie SetThreadGroupAffinity- aufrufen, um die Benutzermodusgruppenaffinität eines Threads zu ändern.)
Bevor die neue Affinitätsmaske in *Affinity- wirksam wird, entfernt KeSetSystemGroupAffinityTh read (Sätze auf Null) alle Affinitätsmaskenbits, die Prozessoren entsprechen, die derzeit nicht aktiv sind. In einem nachfolgenden KeSetSystemGroupAffinityThread Aufruf kann der Wert, den die Routine in *PreviousAffinity- schreibt, ein Affinitätsformat enthalten, das auf diese Weise geändert wurde.
Eine verwandte Routine, KeSetSystemAffinityThreadEx, ändert die Affinitätsmaske des aufrufenden Threads, aber diese Routine, im Gegensatz zu KeSetSystemGroupAffinityThread, akzeptiert keine Gruppennummer als Eingabeparameter. Ab Windows 7 wird KeSetSystemAffinityThreadEx davon ausgegangen, dass sich die Affinitätsmaske auf Prozessoren in Gruppe 0 bezieht, die mit dem Verhalten dieser Routine in früheren Versionen von Windows kompatibel ist, die keine Gruppen unterstützen. Dieses Verhalten stellt sicher, dass vorhandene Treiber, die KeSetSystemAffinityThreadEx- aufrufen und keine gruppenorientierten Features verwenden, ordnungsgemäß in Multiprozessorsystemen mit zwei oder mehr Gruppen ausgeführt werden. Treiber, die gruppenorientierte Features in Windows 7 und höheren Versionen des Windows-Betriebssystems verwenden, sollten jedoch KeSetSystemGroupAffinityThread- anstelle von KeSetSystemAffinityThreadEx-aufrufen.
KeSetSystemGroupAffinityThread und KeRevertToUserGroupAffinityThread eine Vielzahl von Aufrufenmustern unterstützen. Zwei Beispiele sind in den folgenden Diagrammen dargestellt.
Das folgende Diagramm stellt einen Treiberthread dar, der KeSetSystemGroupAffinityThread dreimal aufruft, um die Threadaffinität zu ändern, und ruft dann KeRevertToUserGroupAffinityThread- auf, um die ursprüngliche Threadaffinität wiederherzustellen.
Im vorherigen Diagramm sind die drei Felder mit der Bezeichnung "Set affinity" Aufrufe an KeSetSystemGroupAffinityThread, und das Feld mit der Bezeichnung "Affinität zurücksetzen" ist ein Aufruf von KeRevertToUserGroupAffinityThread. Der erste KeSetSystemGroupAffinityThread Aufruf verwendet den PreviousAffinity Ausgabezeiger, um die ursprüngliche Threadaffinität zu speichern. In den nächsten beiden Aufrufen von KeSetSystemGroupAffinityThread (mit Sternchen gekennzeichnet) legt der Aufrufer PreviousAffinity auf NULL-fest. Bevor der Thread beendet wird, wird KeRevertToUserGroupAffinityThread- aufgerufen, um die Threadaffinität wiederherzustellen, die vom ersten KeSetSystemGroupAffinityThread Aufruf gespeichert wurde.
Das folgende Diagramm zeigt ein etwas anderes Aufrufmuster, in dem Paare von KeSetSystemGroupAffinityThread und KeRevertToUserGroupAffinityThread- aufrufe geschachtelt sind. In diesem Diagramm verwendet jeder Aufruf von KeSetSystemGroupAffinityThread- im Treiberthread den PreviousAffinity Ausgabeparameter, um die vorherige Threadaffinität zu speichern, und jeder dieser Aufrufe wird mit einem Aufruf von KeRevertToUserGroupAffinityThread gekoppelt, mit dem die gespeicherte Threadaffinität wiederhergestellt wird.
Im vorherigen Diagramm ruft Funktion A im Treiberthread zweimal Funktion B auf. Gehen Sie davon aus, dass der Thread bei der Eingabe der Funktion A weiterhin die Affinität der Anwendung für den Benutzermodus zugewiesen hat. Daher speichert der KeSetSystemGroupAffinityThread Aufruf in Funktion A die ursprüngliche Threadaffinität im Benutzermodus. Während des ersten Aufrufs von Funktion B speichert das KeSetSystemGroupAffinityThread die threadaffinität, die vom Treiber in Funktion A zugewiesen wird, und der entsprechende Aufruf von KeRevertToUserGroupAffinityThread diese Affinität wiederhergestellt. Nach dem Zurückgeben von B stellt die KeRevertToUserGroupAffinityThread- in A die ursprüngliche Threadaffinität im Benutzermodus wieder her. Während des zweiten Aufrufs von B speichert der KeSetSystemGroupAffinityThread Aufruf die ursprüngliche Threadaffinität im Benutzermodus und den entsprechenden Aufruf von KeRevertToUserGroupAffinityThread diese Affinität wiederhergestellt. Der Punkt in diesem Beispiel ist, dass Funktion B nicht wissen muss, ob der Aufrufer (Funktion A) die Threadaffinität vor dem Aufrufen von B in einen treiberdefinierten Wert geändert hat.
Wenn KeSetSystemGroupAffinityThread- bei IRQL <= APC_LEVEL aufgerufen wird und der Aufruf erfolgreich ist, wird die neue Gruppenaffinität sofort wirksam. Wenn der Aufruf zurückgegeben wird, wird der aufrufende Thread bereits auf einem Prozessor ausgeführt, der in der neuen Gruppenaffinität angegeben ist. Wenn KeSetSystemGroupAffinityThread- bei IRQL = DISPATCH_LEVEL aufgerufen wird und der Aufruf erfolgreich ist, wird die ausstehende Prozessoränderung zurückgestellt, bis der Aufrufer die IRQL unter DISPATCH_LEVEL verringert.
Ab Windows 11 und Windows Server 2022 umfasst ein System mit mehr als 64 Prozessoren, Prozess- und Threadaffinitäten alle Prozessoren im System, über alle Prozessorgruppenstandardmäßig. Um die Systemgruppenaffinität eines Threads über mehrere Prozessorgruppen festzulegen, verwenden Sie PsSetSystemMultipleGroupAffinityThread-.
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Verfügbar ab Windows 7. |
| Zielplattform- | Universal |
| Header- | wdm.h (include Wdm.h, Wdm.h, Ntifs.h) |
| Library | NtosKrnl.lib |
| DLL- | NtosKrnl.exe |
| IRQL- | <= DISPATCH_LEVEL (siehe Abschnitt "Hinweise"). |
| DDI-Complianceregeln | HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm) |