Funzione KeSetSystemGroupAffinityThread (wdm.h)
La routine KeSetSystemGroupAffinityThread modifica il numero di gruppo e la maschera di affinità del thread chiamante.
Sintassi
void KeSetSystemGroupAffinityThread(
[in] PGROUP_AFFINITY Affinity,
[out, optional] PGROUP_AFFINITY PreviousAffinity
);
Parametri
[in] Affinity
Puntatore a una struttura GROUP_AFFINITY 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 di GROUP_AFFINITY allocata dal chiamante in cui la routine scrive informazioni sull'affinità del gruppo precedente del thread chiamante. Il chiamante può successivamente usare questo puntatore come parametro di input per la routine KeRevertToUserGroupAffinityThread per ripristinare l'affinità del thread precedente. Spesso KeSetSystemGroupAffinityThread scrive valori in questa struttura che non sono affinità di gruppo valide, ma che hanno un significato speciale per KeRevertToUserGroupAffinityThread. Non fornire puntatori a questi valori speciali come parametri di affinità nelle successive chiamate KeSetSystemGroupAffinityThread .
Se necessario, il chiamante può modificare l'affinità del thread più volte chiamando KeSetSystemGroupAffinityThread più volte. Durante la prima di queste chiamate, il chiamante deve specificare un valore non NULL per PreviousAffinity in modo che l'affinità del thread originale possa essere acquisita e ripristinata in seguito. Tuttavia, le chiamate successive a KeSetSystemGroupAffinityThread possono, come opzione, impostare PreviousAffinity = NULL. Per altre informazioni, vedere la sezione Osservazioni.
Valore restituito
nessuno
Osservazioni
Questa routine modifica il numero di gruppo e la maschera di affinità relativa al gruppo del thread chiamante. Il parametro Affinity punta a una struttura GROUP_AFFINITY . Il numero di gruppo e la maschera di affinità in questa struttura identificano un set di processori in cui è possibile eseguire il thread. In caso di esito positivo, la routine pianifica l'esecuzione del thread in un processore in questo set.
Se il parametro PreviousAffinity non è NULL, la routine salva le informazioni sull'affinità del gruppo precedente, che erano effettive all'inizio della chiamata, nella struttura GROUP_AFFINITY a cui PreviousAffinity punta. Per ripristinare l'affinità del thread precedente, il chiamante può fornire il puntatore a questa struttura come parametro di input alla routine KeRevertToUserGroupAffinityThread .
In un sistema multiprocessore, una routine driver in modalità kernel eseguita nel contesto di un thread in modalità utente potrebbe dover chiamare KeSetSystemGroupAffinityThread per modificare temporaneamente l'affinità di gruppo del thread. Prima dell'uscita della routine, deve chiamare KeRevertToUserGroupAffinityThread per ripristinare la maschera di affinità del thread al relativo valore originale.
Un processo può avere affinità per più di un gruppo alla volta. Tuttavia, un thread può essere assegnato a un solo gruppo in qualsiasi momento. Tale gruppo è sempre nell'affinità del processo del thread. Un thread può modificare il gruppo a cui viene assegnato chiamando KeSetSystemGroupAffinityThread.
KeSetSystemGroupAffinityThread modifica il numero di gruppo e la maschera di affinità ai valori specificati in *Affinity solo se sono true:
- Il numero di gruppo è valido.
- La maschera di affinità è valida, ovvero solo i bit maschera che corrispondono ai processori logici nel gruppo sono impostati.
- Almeno uno dei processori specificati nella maschera di affinità è attivo.
Inoltre , KeSetSystemGroupAffinityThread scrive zero nel numero di gruppo e nella maschera di affinità in *PreviousAffinity se l'affinità del gruppo precedente è stata assegnata al thread in modalità utente. In risposta a una struttura GROUP_AFFINITY in cui il numero di gruppo e la maschera di affinità sono entrambi zero, KeRevertToUserGroupAffinityThread ripristina l'affinità del thread in modalità utente corrente. Se l'affinità di thread in modalità utente cambia tra le chiamate KeSetSystemGroupAffinityThread e KeRevertToUserGroupAffinityThread , l'affinità in modalità utente più recente viene assegnata al thread. Un'applicazione può chiamare una funzione, ad esempio SetThreadGroupAffinity , per modificare l'affinità del gruppo in modalità utente di un thread.
Prima che la nuova maschera di affinità in *Affinità abbia effetto, KeSetSystemGroupAffinityThread rimuove (imposta su zero) eventuali bit di maschera di affinità corrispondenti ai processori che non sono attualmente attivi. In una successiva chiamata KeSetSystemGroupAffinityThread , il valore che la routine scrive in *PreviousAffinity potrebbe contenere una maschera di affinità modificata in questo modo.
Una routine correlata, KeSetSystemAffinityThreadEx, modifica la maschera di affinità del thread chiamante, ma questa routine, a differenza di KeSetSystemGroupAffinityThread, non accetta un numero di gruppo come parametro di input. A partire da Windows 7, KeSetSystemAffinityThreadEx presuppone che la maschera di affinità faccia riferimento ai processori nel gruppo 0, compatibile con il comportamento di questa routine nelle versioni precedenti di Windows che non supportano i gruppi. Questo comportamento garantisce che i driver esistenti che chiamano KeSetSystemAffinityThreadEx e che non usino funzionalità orientate al gruppo verranno eseguite correttamente nei sistemi multiprocessore con due o più gruppi. Tuttavia, i driver che usano funzionalità orientate al gruppo in Windows 7 e versioni successive del sistema operativo Windows devono chiamare KeSetSystemGroupAffinityThread anziché KeSetSystemAffinityThreadEx.
KeSetSystemGroupAffinityThread e KeRevertToUserGroupAffinityThread supportano diversi modelli di chiamata. Due esempi sono illustrati nei diagrammi seguenti.
Il diagramma seguente rappresenta un thread driver che chiama KeSetSystemGroupAffinityThread tre volte per modificare l'affinità del thread e quindi chiama KeRevertToUserGroupAffinityThread per ripristinare l'affinità di thread originale.
Nel diagramma precedente, le tre caselle etichettate "Set affinity" sono chiamate a KeSetSystemGroupAffinityThread e la casella etichettata "Revert affinity" è una chiamata a KeRevertToUserGroupAffinityThread. La prima chiamata KeSetSystemGroupAffinityThread usa il puntatore di output PreviousAffinity per salvare l'affinità del thread originale. Nelle due chiamate successive a KeSetSystemGroupAffinityThread (contrassegnato con asterischi), il chiamante imposta PreviousAffinity su NULL. Prima dell'uscita dal thread, chiama KeRevertToUserGroupAffinityThread per ripristinare l'affinità del thread salvata dalla prima chiamata KeSetSystemGroupAffinityThread .
Il diagramma seguente mostra un modello di chiamata leggermente diverso in cui vengono annidate coppie di KeSetSystemGroupAffinityThread e KeRevertToUserGroupAffinityThread . In questo diagramma ogni chiamata a KeSetSystemGroupAffinityThread nel thread driver usa il parametro di output PreviousAffinity per salvare l'affinità del thread precedente e ognuna di queste chiamate viene associata a una chiamata a KeRevertToUserGroupAffinityThread che ripristina l'affinità del thread salvato.
Nel diagramma precedente, la funzione A nel thread driver chiama la funzione B due volte. Si supponga che nella funzione A il thread abbia ancora l'affinità assegnata dall'applicazione in modalità utente. Pertanto, la chiamata KeSetSystemGroupAffinityThread nella funzione A salva l'affinità di thread in modalità utente originale. Durante la prima chiamata alla funzione B, KeSetSystemGroupAffinityThread salva l'affinità del thread assegnata dal driver nella funzione A e la chiamata corrispondente a KeRevertToUserGroupAffinityThread ripristina questa affinità . Dopo che B restituisce, l'affinità del thread in modalità utente KeRevertToUserGroupAffinityThread in A ripristina l'affinità di thread in modalità utente originale. Durante la seconda chiamata a B, la chiamata KeSetSystemGroupAffinityThread salva l'affinità di thread in modalità utente originale e la chiamata corrispondente a KeRevertToUserGroupAffinityThread ripristina questa affinità . Il punto di questo esempio è che la funzione B non deve sapere se il chiamante (funzione A) ha modificato l'affinità del thread in un valore definito dal driver prima di chiamare B.
Se KeSetSystemGroupAffinityThread viene chiamato in IRQL <= APC_LEVEL e la chiamata ha esito positivo, la nuova affinità di gruppo ha effetto immediatamente. Quando la chiamata viene restituita, il thread chiamante è già in esecuzione in un processore specificato nella nuova affinità di gruppo. Se KeSetSystemGroupAffinityThread 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 riduce il controllo IRQL sotto DISPATCH_LEVEL.
A partire da Windows 11 e Windows Server 2022, in un sistema con più di 64 processori, processi e affinità di thread si estendono su tutti i processori nel sistema, in tutti i gruppi di processori, per impostazione predefinita. Per impostare l'affinità del gruppo di sistema di un thread su più gruppi di processori, usare PsSetSystemMultipleGroupAffinityThread.
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Disponibile a partire da Windows 7. |
| Piattaforma di destinazione | Universale |
| Intestazione | wdm.h (include Wdm.h, Wdm.h, Ntifs.h) |
| Libreria | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | <= DISPATCH_LEVEL (vedere sezione Osservazioni). |
| Regole di conformità DDI | HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm) |