Funzione SetThreadAffinityMask (winbase.h)

Articolo
08/27/2023

Imposta una maschera di affinità del processore per il thread specificato.

Sintassi

DWORD_PTR SetThreadAffinityMask(
  [in] HANDLE    hThread,
  [in] DWORD_PTR dwThreadAffinityMask
);

Parametri

[in] hThread

Handle per il thread la cui maschera di affinità deve essere impostata.

Questo handle deve avere il diritto di accesso THREAD_SET_INFORMATION o THREAD_SET_LIMITED_INFORMATION e il diritto di accesso THREAD_QUERY_INFORMATION o THREAD_QUERY_LIMITED_INFORMATION. Per altre informazioni, vedere Thread Security and Access Rights.For more information, see Thread Security and Access Rights.

Windows Server 2003 e Windows XP: L'handle deve avere i diritti di accesso THREAD_SET_INFORMATION e THREAD_QUERY_INFORMATION .

[in] dwThreadAffinityMask

Maschera di affinità per il thread.

In un sistema con più di 64 processori, la maschera di affinità deve specificare processori nel gruppo di processori corrente del thread.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è la maschera di affinità precedente del thread.

Se la funzione ha esito negativo, il valore restituito è zero. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Se la maschera di affinità del thread richiede un processore non selezionato per la maschera di affinità di processo, l'ultimo codice di errore è ERROR_INVALID_PARAMETER.

Commenti

Una maschera di affinità del thread è un vettore di bit in cui ogni bit rappresenta un processore logico in cui è consentito eseguire un thread. Una maschera di affinità del thread deve essere un subset della maschera di affinità del processo per il processo contenente un thread. Un thread può essere eseguito solo sui processori in cui è possibile eseguire il processo. Pertanto, la maschera di affinità del thread non può specificare un bit per un processore quando la maschera di affinità di processo specifica un bit 0 per tale processore.

L'impostazione di una maschera di affinità per un processo o un thread può comportare una ricezione di meno tempo del processore, poiché il sistema è limitato all'esecuzione dei thread in determinati processori. Nella maggior parte dei casi, è preferibile consentire al sistema di selezionare un processore disponibile.

Se la nuova maschera di affinità thread non specifica il processore attualmente in esecuzione il thread, il thread viene riprogrammato su uno dei processori consentiti.

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. DwThreadAffinityMask deve specificare processori nel gruppo primario corrente del thread.

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [app desktop \| App UWP]
Server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	winbase.h (include Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll