SetThreadAffinityMask-Funktion (winbase.h)

Artikel
03/03/2024

Legt eine Prozessoraffinitätsmaske für den angegebenen Thread fest.

Syntax

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

Parameter

[in] hThread

Ein Handle für den Thread, dessen Affinitätsmaske festgelegt werden soll.

Dieses Handle muss über das THREAD_SET_INFORMATION - oder THREAD_SET_LIMITED_INFORMATION-Zugriffsrecht und das THREAD_QUERY_INFORMATION - oder THREAD_QUERY_LIMITED_INFORMATION-Zugriffsrecht verfügen. Weitere Informationen finden Sie unter Threadsicherheit und Zugriffsrechte.

Windows Server 2003 und Windows XP: Das Handle muss über die THREAD_SET_INFORMATION und THREAD_QUERY_INFORMATION Zugriffsrechte verfügen.

[in] dwThreadAffinityMask

Die Affinitätsmaske für den Thread.

Auf einem System mit mehr als 64 Prozessoren muss die Affinitätsmaske Prozessoren in der aktuellen Prozessorgruppe des Threads angeben.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert die vorherige Affinitätsmaske des Threads.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Wenn die Threadaffinitätsmaske einen Prozessor anfordert, der nicht für die Prozessaffinitätsmaske ausgewählt ist, wird der letzte Fehlercode ERROR_INVALID_PARAMETER.

Hinweise

Eine Threadaffinitätsmaske ist ein Bitvektor, in dem jedes Bit einen logischen Prozessor darstellt, auf dem ein Thread ausgeführt werden darf. Eine Threadaffinitätsmaske muss eine Teilmenge der Prozessaffinitätsmaske für den enthaltenden Prozess eines Threads sein. Ein Thread kann nur auf den Prozessoren ausgeführt werden, auf denen sein Prozess ausgeführt werden kann. Daher kann die Threadaffinitätsmaske kein 1 Bit für einen Prozessor angeben, wenn die Prozessaffinitätsmaske ein 0 Bit für diesen Prozessor angibt.

Das Festlegen einer Affinitätsmaske für einen Prozess oder Thread kann dazu führen, dass Threads weniger Prozessorzeit erhalten, da das System die Ausführung der Threads auf bestimmten Prozessoren eingeschränkt ist. In den meisten Fällen ist es besser, das System einen verfügbaren Prozessor auswählen zu lassen.

Wenn die neue Threadaffinitätsmaske nicht den Prozessor angibt, der den Thread derzeit ausführt, wird der Thread auf einem der zulässigen Prozessoren neu geplant.

Ab Windows 11 und Windows Server 2022 umfassen auf einem System mit mehr als 64 Prozessoren standardmäßig Prozess- und Threadaffinitäten alle Prozessoren im System, und das über alle Prozessorgruppen hinweg. Die dwThreadAffinityMask muss Prozessoren in der aktuellen primären Gruppe des Threads angeben.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	winbase.h (einschließlich Windows.h)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll