Skip to main content
スキップしてメイン コンテンツへ
GetThreadPriority function

Retrieves 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.

Syntax


int WINAPI GetThreadPriority(
  _In_ HANDLE hThread
);

Parameters

hThread [in]

A handle to the thread.

The handle must have the THREAD_QUERY_INFORMATION or THREAD_QUERY_LIMITED_INFORMATION access right. For more information, see Thread Security and Access Rights.

Windows Server 2003:  The handle must have the THREAD_QUERY_INFORMATION access right.

Return value

If the function succeeds, the return value is the thread's priority level.

If the function fails, the return value is THREAD_PRIORITY_ERROR_RETURN. To get extended error information, call GetLastError.

Windows Phone 8.1:  This function will always return THREAD_PRIORITY_NORMAL.

The thread's priority level is one of the following values.

Return code/valueDescription
THREAD_PRIORITY_ABOVE_NORMAL
1

Priority 1 point above the priority class.

THREAD_PRIORITY_BELOW_NORMAL
-1

Priority 1 point below the priority class.

THREAD_PRIORITY_HIGHEST
2

Priority 2 points above the priority class.

THREAD_PRIORITY_IDLE
-15

Base priority of 1 for IDLE_PRIORITY_CLASS, BELOW_NORMAL_PRIORITY_CLASS, NORMAL_PRIORITY_CLASS, ABOVE_NORMAL_PRIORITY_CLASS, or HIGH_PRIORITY_CLASS processes, and a base priority of 16 for REALTIME_PRIORITY_CLASS processes.

THREAD_PRIORITY_LOWEST
-2

Priority 2 points below the priority class.

THREAD_PRIORITY_NORMAL
0

Normal priority for the priority class.

THREAD_PRIORITY_TIME_CRITICAL
15

Base-priority level of 15 for IDLE_PRIORITY_CLASS, BELOW_NORMAL_PRIORITY_CLASS, NORMAL_PRIORITY_CLASS, ABOVE_NORMAL_PRIORITY_CLASS, or HIGH_PRIORITY_CLASS processes, and a base-priority level of 31 for REALTIME_PRIORITY_CLASS processes.

 

If the thread has the REALTIME_PRIORITY_CLASS base class, this function can also return one of the following values: -7, -6, -5, -4, -3, 3, 4, 5, or 6. For more information, see Scheduling Priorities.

Remarks

Every thread has a base-priority level determined by the thread's priority value and the priority class of its process. The operating 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 will scheduling of threads at a lower level take place.

For a table that shows the base-priority levels for each combination of priority class and thread priority value, refer to the SetPriorityClass function.

Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps.

Windows Phone 8.1:Windows Phone Store apps may call this function but it has no effect.

Requirements

Minimum supported client

Windows XP [desktop apps | UWP apps]

Minimum supported server

Windows Server 2003 [desktop apps | UWP apps]

Minimum supported phone

Windows Phone 8.1

Header

WinBase.h on Windows XP, Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 and Windows Server 2008 R2 (include Windows.h);
Processthreadsapi.h on Windows 8, Windows Server 2012 and Windows Phone 8.1

Library

Kernel32.lib;
WindowsPhoneCore.lib on Windows Phone 8.1

DLL

Kernel32.dll;
KernelBase.dll on Windows Phone 8.1

See also

GetPriorityClass
OpenThread
Process and Thread Functions
Scheduling Priorities
SetPriorityClass
SetThreadPriority
Threads