SetThreadAffinityMask 函式 (winbase.h)

發行項
03/09/2024

設定指定線程的處理器親和性遮罩。

語法

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

參數

[in] hThread

要設定親和性遮罩之線程的句柄。

此句柄必須具有 THREAD_SET_INFORMATION 或 THREAD_SET_LIMITED_INFORMATION 訪問許可權，以及 THREAD_QUERY_INFORMATION 或 THREAD_QUERY_LIMITED_INFORMATION 訪問許可權。如需詳細資訊，請參閱線程安全性和訪問許可權。

Windows Server 2003 和 Windows XP： 句柄必須具有 THREAD_SET_INFORMATION 和 THREAD_QUERY_INFORMATION 訪問許可權。

[in] dwThreadAffinityMask

線程的親和性遮罩。

在超過 64 個處理器的系統上，親和性遮罩必須在線程的目前處理器群組中指定處理器。

傳回值

如果函式成功，傳回值就是線程先前的親和性遮罩。

如果此函式失敗，則傳回值為零。若要取得擴充的錯誤資訊，請呼叫 GetLastError。

如果線程親和性遮罩要求未針對進程親和性遮罩選取的處理器，則會ERROR_INVALID_PARAMETER最後一個錯誤碼。

備註

線程親和性遮罩是位向量，其中每個位都代表允許線程執行所在的邏輯處理器。線程親和性遮罩必須是包含線程進程的進程親和性遮罩子集。線程只能在其進程可執行的處理器上執行。因此，當進程親和性遮罩指定該處理器的0位時，線程親和性遮罩無法為處理器指定1位。

設定進程或線程的親和性遮罩可能會導致線程接收較少的處理器時間，因為系統受限於在特定處理器上執行線程。在大部分情況下，最好讓系統選取可用的處理器。

如果新的線程親和性遮罩未指定目前正在執行線程的處理器，線程會在其中一個允許的處理器上重新排程。

從 Windows 11 和 Windows Server 2022 開始，在超過 64 個處理器的系統上，依預設，進程和線程親和性會跨越系統中的所有處理器。 dwThreadAffinityMask 必須在線程的目前主要群組中指定處理器。

規格需求

需求	值
最低支援的用戶端	Windows XP [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows Server 2003 [傳統型應用程式 \|UWP 應用程式]
目標平台	Windows
標頭	winbase.h (包含 Windows.h)
程式庫	Kernel32.lib
DLL	Kernel32.dll