Funzione StorPortSetSystemGroupAffinityThread (storport.h)

Articolo
08/07/2023

StorPortSetSystemGroupAffinityThread modifica il numero di gruppo e la maschera di affinità del thread chiamante.

Sintassi

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

Parametri

[in] HwDeviceExtension

Puntatore all'estensione del dispositivo hardware del miniport.

[in/optional] ThreadContext

Puntatore al contesto del thread ricevuto in una chiamata precedente a StorPortCreateSystemThread.

[in] Affinity

Puntatore a una struttura STOR_GROUP_AFFINITY allocata dal chiamante che specifica il nuovo numero di gruppo e la maschera di affinità relativa al gruppo per il thread chiamante.

[out/optional] PreviousAffinity

Puntatore a una struttura STOR_GROUP_AFFINITY in cui questa routine scrive il numero di gruppo e la maschera di affinità per il thread chiamante prima della chiamata. Questo parametro è facoltativo e può essere NULL.

Valore restituito

StorPortSetSystemGroupAffinityThread restituisce uno dei valori seguenti:

Codice restituito	Descrizione
STOR_STATUS_SUCCESS	L'affinità di gruppo specificata è stata impostata correttamente.
STOR_STATUS_INVALID_PARAMETER	Uno o più parametri forniti non sono validi.
STOR_STATUS_UNSUCCESSFUL	Restituito per altri motivi di sistema interni.

Commenti

Un miniport può chiamare StorPortSetSystemGroupAffinityThread per modificare il numero di gruppo e la maschera di affinità a livello di gruppo del thread chiamante.

Il numero di gruppo e la maschera di affinità nella struttura STOR_GROUP_AFFINITY a cui punta Affinità identificano un set di processori in cui è possibile eseguire il thread. In caso di esito positivo, StorPortSetSystemGroupAffinityThread pianifica l'esecuzione del thread in un processore in questo set.

Se il parametro PreviousAffinity è diverso da NULL, StorPortSetSystemGroupAffinityThread salva le informazioni sull'affinità di gruppo precedente, applicata all'inizio della chiamata, nella struttura STOR_GROUP_AFFINITY a cui punta PreviousAffinity . Per ripristinare l'affinità del thread precedente, il chiamante può fornire il puntatore a questa struttura come parametro di input alla routine StorPortRevertToUserGroupAffinityThread .

Se un miniport chiama questa funzione per modificare temporaneamente l'affinità di gruppo del thread, deve chiamare StorPortRevertToUserGroupAffinityThread per ripristinare l'affinità del thread con il valore originale prima che il thread venga chiuso.

Un thread può essere assegnato a una sola affinità di gruppo in qualsiasi momento. Tale gruppo è sempre nell'affinità del processo del thread. Un thread può modificare il gruppo a cui è assegnato chiamando questa routine.

StorPortSetSystemGroupAffinityThread modifica il numero di gruppo e la maschera di affinità ai valori specificati in Affinity solo se i valori seguenti sono true:

Il numero di gruppo è valido.
La maschera di affinità è valida, ovvero vengono impostati solo i bit mask che corrispondono ai processori logici nel gruppo.
Almeno uno dei processori specificati nella maschera di affinità è attivo.

Se una di queste condizioni non viene soddisfatta, il numero di gruppo e la maschera di affinità del thread rimangono invariati. Se PreviousAffinity è diverso da NULL, la routine scrive zero sia nel numero di gruppo che nella maschera di affinità in PreviousAffinity.

Prima che la nuova maschera di affinità in Affinity abbia effetto, StorPortSetSystemGroupAffinityThread rimuove (imposta su zero) tutti i bit affinity mask che corrispondono ai processori che non sono attualmente attivi. In una successiva chiamata StorPortSetSystemGroupAffinityThread , il valore che la routine scrive in PreviousAffinity potrebbe contenere una maschera di affinità modificata in questo modo.

Se StorPortSetSystemGroupAffinityThread viene chiamato in IRQL <= APC_LEVEL e la chiamata ha esito positivo, la nuova affinità di gruppo diventa effettiva immediatamente. Al termine della chiamata, il thread chiamante è già in esecuzione in un processore specificato nella nuova affinità di gruppo. Se StorPortSetSystemGroupAffinityThread viene chiamato in IRQL = DISPATCH_LEVEL e la chiamata ha esito positivo, la modifica del processore in sospeso viene posticipata fino a quando il chiamante non abbassa irQL sotto DISPATCH_LEVEL.