SetThreadAffinityMask function
Applies to: desktop apps only
Sets a processor affinity mask for the specified thread.
Syntax
DWORD_PTR WINAPI SetThreadAffinityMask( __in HANDLE hThread, __in DWORD_PTR dwThreadAffinityMask );
Parameters
- hThread [in]
-
A handle to the thread whose affinity mask is to be set.
This handle must have the THREAD_SET_INFORMATION or THREAD_SET_LIMITED_INFORMATION access right and the THREAD_QUERY_INFORMATION or THREAD_QUERY_LIMITED_INFORMATION access right. For more information, see Thread Security and Access Rights.
Windows Server 2003 and Windows XP: The handle must have the THREAD_SET_INFORMATION and THREAD_QUERY_INFORMATION access rights. - dwThreadAffinityMask [in]
-
The affinity mask for the thread.
On a system with more than 64 processors, the affinity mask must specify processors in the thread's current processor group.
Return value
If the function succeeds, the return value is the thread's previous affinity mask.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
If the thread affinity mask requests a processor that is not selected for the process affinity mask, the last error code is ERROR_INVALID_PARAMETER.
Remarks
A thread affinity mask is a bit vector in which each bit represents a logical processor that a thread is allowed to run on. A thread affinity mask must be a subset of the process affinity mask for the containing process of a thread. A thread can only run on the processors its process can run on. Therefore, the thread affinity mask cannot specify a 1 bit for a processor when the process affinity mask specifies a 0 bit for that processor.
Setting an affinity mask for a process or thread can result in threads receiving less processor time, as the system is restricted from running the threads on certain processors. In most cases, it is better to let the system select an available processor.
If the new thread affinity mask does not specify the processor that is currently running the thread, the thread is rescheduled on one of the allowable processors.
Requirements
|
Minimum supported client | Windows XP |
|---|---|
|
Minimum supported server | Windows Server 2003 |
|
Header |
|
|
Library |
|
|
DLL |
|
See also
- GetProcessAffinityMask
- Multiple Processors
- OpenThread
- Process and Thread Functions
- Processor Groups
- SetProcessAffinityMask
- SetThreadIdealProcessor
- Threads
Send comments about this topic to Microsoft
Build date: 3/7/2012
I believe that above the writer is trying to indicate, by writing "the thread is rescheduled" that the thread's mask is updated and it immediately yields the current processor core.
This could result in a small, but significant time between the SetThreadAffinityMask call and the next instruction being executed, since then all other threads with equal or greater priority will get their processor quantum before the scheduler returns to the thread that called SetThreadAffinityMask.
I believe a documentation update should be made to make this operation clear, since currently timer methods are in existence that routinely set and reset the thread's affiniity mask prior to accessing QueryPerformanceCounter or other thread-specific counters. This operation undoubtedly results in timer errors when the thread being timed is NOT on the correct core in the first place.
- 3/22/2012
- Chief Scientist
<DllImport("kernel32.dll", CharSet:=CharSet.Auto, SetLastError:=True)> _
Public Shared Function SetThreadAffinityMask(ByVal handle As IntPtr, ByVal mask As HandleRef) As IntPtr
End Function
