The SetThreadPriority function sets the priority value for the specified thread. This value, together with the priority class of the thread's process, determines the thread's base priority level.
BOOL SetThreadPriority(
HANDLE hThread, // handle to the thread
int nPriority // thread priority level
);
Windows NT: The handle must have the THREAD_SET_INFORMATION access right associated with it.
| Priority | Meaning |
|---|---|
| THREAD_PRIORITY_ABOVE_NORMAL | Indicates 1 point above normal priority for the priority class. |
| THREAD_PRIORITY_BELOW_NORMAL | Indicates 1 point below normal priority for the priority class. |
| THREAD_PRIORITY_HIGHEST | Indicates 2 points above normal priority for the priority class. |
| THREAD_PRIORITY_IDLE | Indicates a base priority level of 1 for IDLE_PRIORITY_CLASS, NORMAL_PRIORITY_CLASS, or HIGH_PRIORITY_CLASS processes, and a base priority level of 16 for REALTIME_PRIORITY_CLASS processes. |
| THREAD_PRIORITY_LOWEST | Indicates 2 points below normal priority for the priority class. |
| THREAD_PRIORITY_NORMAL | Indicates normal priority for the priority class. |
| THREAD_PRIORITY_TIME_CRITICAL | Indicates a base priority level of 15 for IDLE_PRIORITY_CLASS, NORMAL_PRIORITY_CLASS, or HIGH_PRIORITY_CLASS processes, and a base priority level of 31 for REALTIME_PRIORITY_CLASS processes. |
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Every thread has a base priority level determined by the thread's priority value and the priority class of its process. The system uses the base priority level of all executable threads to determine which thread gets the next slice of CPU time. Threads are scheduled in a round-robin fashion at each priority level, and only when there are no executable threads at a higher level does scheduling of threads at a lower level take place.
The SetThreadPriority function enables setting the base priority level of a thread relative to the priority class of its process. For example, specifying THREAD_PRIORITY_HIGHEST in a call to SetThreadPriority for a thread of an IDLE_PRIORITY_CLASS process sets the thread's base priority level to 6. For a table that shows the base priority levels for each combination of priority class and thread priority value, see the SetPriorityClass function.
For IDLE_PRIORITY_CLASS, NORMAL_PRIORITY_CLASS, and HIGH_PRIORITY_CLASS processes, the system dynamically boosts a thread's base priority level when events occur that are important to the thread. REALTIME_PRIORITY_CLASS processes do not receive dynamic boosts.
All threads initially start at THREAD_PRIORITY_NORMAL. Use the GetPriorityClass and SetPriorityClass functions to get and set the priority class of a process. Use the GetThreadPriority function to get the priority value of a thread.
Use the priority class of a process to differentiate between applications that are time critical and those that have normal or below normal scheduling requirements. Use thread priority values to differentiate the relative priorities of the tasks of a process. For example, a thread that handles input for a window could have a higher priority level than a thread that performs intensive calculations for the CPU.
When manipulating priorities, be very careful to ensure that a high-priority thread does not consume all of the available CPU time. A thread with a base priority level above 11 interferes with the normal operation of the operating system. Using REALTIME_PRIORITY_CLASS may cause disk caches to not flush, hang the mouse, and so on.
Windows CE: The thread's priority level is one of the following values:
Windows CE does not support priority classes. The order in which threads are scheduled is determined only by their thread priorities.
When manipulating priorities, ensure that a high-priority thread does not consume all of the available CPU time. A thread with a priority level of THREAD_PRIORITY_TIME_CRITICAL will execute until it explicitly yields processing to other threads. Processing of these threads is not yielded to other threads with the THREAD_PRIORITY_TIME_CRITICAL priority level. Such a thread can interfere with the normal operation of the operating system if the thread does not explicitly yield processing quickly.
Windows NT: Requires version 3.1 or later.
Windows: Requires Windows 95 or later.
Windows CE: Requires version 1.0 or later.
Header: Declared in winbase.h.
Import Library: Use kernel32.lib.
Processes and Threads Overview, Process and Thread Functions, GetPriorityClass, GetThreadPriority, SetPriorityClass