StorPortSetSystemGroupAffinityThread-Funktion (storport.h)

Artikel
02/26/2024

StorPortSetSystemGroupAffinityThread ändert die Gruppennummer und die Affinitätsmaske des aufrufenden Threads.

Syntax

ULONG StorPortSetSystemGroupAffinityThread(
  [in]           PVOID                HwDeviceExtension,
  [in/optional]  PVOID                ThreadContext,
  [in]           PSTOR_GROUP_AFFINITY Affinity,
  [out/optional] PSTOR_GROUP_AFFINITY PreviousAffinity
);

Parameter

[in] HwDeviceExtension

Zeiger auf die Hardwaregeräteerweiterung des Miniports.

[in/optional] ThreadContext

Zeiger auf den Threadkontext, der in einem vorherigen Aufruf von StorPortCreateSystemThread empfangen wurde.

[in] Affinity

Zeiger auf eine vom Aufrufer zugewiesene STOR_GROUP_AFFINITY-Struktur , die die neue Gruppennummer und gruppenrelative Affinitätsmaske für den aufrufenden Thread angibt.

[out/optional] PreviousAffinity

Zeiger auf eine STOR_GROUP_AFFINITY Struktur, in der diese Routine die Gruppennummer und affinitätsmaske für den aufrufenden Thread vor dem Aufruf schreibt. Dieser Parameter ist optional und kann NULL sein.

Rückgabewert

StorPortSetSystemGroupAffinityThread gibt einen der folgenden Werte zurück:

Rückgabecode	Beschreibung
STOR_STATUS_SUCCESS	Die angegebene Gruppenaffinität wurde erfolgreich festgelegt.
STOR_STATUS_INVALID_PARAMETER	Mindestens einer der bereitgestellten Parameter ist ungültig.
STOR_STATUS_UNSUCCESSFUL	Wird aus anderen internen Systemgründen zurückgegeben.

Hinweise

Ein Miniport kann StorPortSetSystemGroupAffinityThread aufrufen, um die Gruppennummer und die Affinitätsmaske des aufrufenden Threads zu ändern.

Die Gruppennummer und die Affinitätsmaske in der STOR_GROUP_AFFINITY Struktur, auf die von Affinity verwiesen wird, identifizieren eine Gruppe von Prozessoren, auf denen der Thread ausgeführt werden kann. Bei erfolgreicher Ausführung plant StorPortSetSystemGroupAffinityThread die Ausführung des Threads auf einem Prozessor in diesem Satz.

Wenn der PreviousAffinity-Parameter nicht NULL ist, speichert StorPortSetSystemGroupAffinityThread Informationen zur vorherigen Gruppenaffinität, die zu Beginn des Aufrufs wirksam waren, in der STOR_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 StorPortRevertToUserGroupAffinityThread-Routine bereitstellen.

Wenn ein Miniport diese Funktion aufruft, um die Gruppenaffinität des Threads vorübergehend zu ändern, sollte StorPortRevertToUserGroupAffinityThread aufgerufen werden, um die Threadaffinität zum ursprünglichen Wert zu rückgängig machen, bevor der Thread beendet wird.

Ein Thread kann jederzeit nur einer Gruppenaffinität zugewiesen werden. Diese Gruppe befindet sich immer in der Affinität des Prozesses des Threads. Ein Thread kann die Gruppe ändern, der er zugewiesen ist, indem er diese Routine aufruft.

StorPortSetSystemGroupAffinityThread ändert die Gruppennummer und die Affinitätsmaske nur dann in die Werte, die in Affinity angegeben sind, wenn Folgendes zutrifft:

Die Gruppennummer ist gültig.
Die Affinitätsmaske ist gültig (das heißt, es werden nur Maskenbits festgelegt, die logischen Prozessoren in der Gruppe entsprechen).
Mindestens einer der Prozessoren, der in der Affinitätsmaske angegeben ist, ist aktiv.

Wenn eine dieser Bedingungen nicht erfüllt ist, bleiben die Gruppennummer und die Affinitätsmaske des Threads unverändert. Wenn PreviousAffinity nicht NULL ist, schreibt die Routine null in die Gruppennummer und die Affinitätsmaske in PreviousAffinity.

Bevor die neue Affinitätsmaske in Affinity wirksam wird, entfernt StorPortSetSystemGroupAffinityThread alle Affinitätsmaskenbits, die Prozessoren entsprechen, die derzeit nicht aktiv sind. In einem nachfolgenden StorPortSetSystemGroupAffinityThread-Aufruf kann der Wert, den die Routine in PreviousAffinity schreibt, eine Affinitätsmaske enthalten, die auf diese Weise geändert wurde.

Wenn StorPortSetSystemGroupAffinityThread unter 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 StorPortSetSystemGroupAffinityThread bei IRQL = DISPATCH_LEVEL aufgerufen wird und der Aufruf erfolgreich ist, wird die ausstehende Prozessoränderung zurückgestellt, bis der Aufrufer den IRQL unter DISPATCH_LEVEL senkt.