SetThreadPriority

The SetThreadPriority function sets the priority of a specified thread. The priority of a thread is an integer value that determines the thread's position relative to other threads in thread timeslice allocation.

Syntax

BOOL SetThreadPriority(
  [in] HANDLE hThread,
  [in] int    nPriority
);

Parameters

Parameter Type Description
hThread HANDLE A handle to the thread whose priority is to be set. The handle must have the THREAD_SET_INFORMATION access right. For more information, see Thread Security and Access Rights.
nPriority int The priority class for the thread. This parameter can be one of the following values:
  • REALTIME_PRIORITY_CLASS (26)
  • HIGH_PRIORITY_CLASS (13)
  • NORMAL_PRIORITY_CLASS (32)
  • IDLE_PRIORITY_CLASS (64)
  • BELOW_NORMAL_PRIORITY_CLASS (16)
  • ABOVE_NORMAL_PRIORITY_CLASS (32)

Return Value

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.

Remarks

A thread's priority is relative to the priority class of its process. The system uses thread priorities to determine which thread gets the next CPU timeslice. Threads with higher priorities are given preference over threads with lower priorities.

The priority values are:

  • THREAD_PRIORITY_LOWEST (-15)
  • THREAD_PRIORITY_BELOW_NORMAL (-2)
  • THREAD_PRIORITY_NORMAL (0)
  • THREAD_PRIORITY_ABOVE_NORMAL (2)
  • THREAD_PRIORITY_HIGHEST (15)
  • THREAD_PRIORITY_TIME_CRITICAL (15)

A thread's actual priority is determined by the thread's base priority (set by SetThreadPriority) and the priority class of its process. For example, a thread with THREAD_PRIORITY_NORMAL in a process with REALTIME_PRIORITY_CLASS will have a higher actual priority than a thread with THREAD_PRIORITY_HIGHEST in a process with IDLE_PRIORITY_CLASS.

Important Security Notice: Applications that set threads to a priority higher than THREAD_PRIORITY_NORMAL can impact the overall system performance. Setting a thread's priority to THREAD_PRIORITY_TIME_CRITICAL is generally discouraged as it can cause the system to become unresponsive.

Requirements

Requirements
Minimum supported client
Windows 2000 Professional
Minimum supported server
Windows 2000 Server
Header
windows.h
Library
Kernel32.lib
DLL
Kernel32.dll

See Also