StorPortSetSystemGroupAffinityThread-Funktion (storport.h)

Artikel
02/07/2025

StorPortSetSystemGroupAffinityThread ändert die Gruppennummer und das Affinitätsformat 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 StorPortCreateSystemThreadempfangen wurde.

[in] Affinity

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

[out/optional] PreviousAffinity

Zeiger auf eine STOR_GROUP_AFFINITY Struktur, in der diese Routine die Gruppennummer und die Affinitätsmaske für den Aufrufthread 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.

Bemerkungen

Ein Miniport kann StorPortSetSystemGroupAffinityThread- aufrufen, um die Gruppennummer und das Affinitätsformat auf Gruppenebene des aufrufenden Threads zu ändern.

Die Gruppennummer und die Affinitätsmaske in der STOR_GROUP_AFFINITY Struktur, auf die durch Affinity verwiesen wird, einen Satz von Prozessoren identifizieren, auf dem der Thread ausgeführt werden kann. Bei erfolgreicher Ausführung plant StorPortSetSystemGroupAffinityThread den Thread auf einem Prozessor in diesem Satz auszuführen.

Wenn der parameter PreviousAffinity ungleich NULL ist, speichert StorPortSetSystemGroupAffinityThread Informationen über die vorherige Gruppenaffinität, die am Anfang 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 sie StorPortRevertToUserGroupAffinityThread- aufrufen, um die Threadaffinität auf den ursprünglichen Wert zurückzugeben, bevor der Thread beendet wird.

Ein Thread kann jeweils 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 sie zugewiesen wird, indem sie diese Routine aufruft.

StorPortSetSystemGroupAffinityThread ä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.

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

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

Wenn StorPortSetSystemGroupAffinityThread- 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 StorPortSetSystemGroupAffinityThread- 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.