RtQueryThreadPerfIdealProcessor

RtQueryThreadPerfIdealProcessor queries the thread’s current Class ID, the performance ideal processor, the current performance capability of affinity logical processor, and the performance capability of each logical processor based on hardware feedback.

Syntax

BOOL RtQueryThreadPerfIdealProcessor(
    Handle hThread,
    PULONG pClassID,
    PULONG pIdealProcessorNumber,
    PULONG pCurrentPerfCap,
    ULONG  SystemPerfCaps[]

);

Parameters

hThread

A handle to the thread object.

pClassID

A pointer to a ULONG to store the current Class ID of the specified thread. The thread Class ID is feedbacked by hardware based on thread characteristic; i.e., the instruction set the thread executes on the logical processor.

pIdealProcessorNumber

A pointer to a ULONG to store the performance ideal processor number (in RTSS) based on the thread’s current Class ID.

pCurrentPerfCap

A pointer to a ULONG to store the thread affinity processor’s current performance capability when executing the instruction set of the Class ID. Performance capability is a value (0 ... 255) specifying the relative performance level of a logical processor. Higher values indicate higher performance.

SystemPerfCaps[]

A ULONG array to store current performance capabilities of a Class ID on each active logical processor, including Windows logical processors and RTSS logical processors.

Return Value

Returns TRUE if the function succeeds. Returns FALSE if the function fails. GetLastError returns ERROR_NOT_SUPPORTED if Intel Thread Director is not supported, ERROR_INVALID_PARAMETER if there are invalid parameters, or ERROR_INVALID_HANDLE if the handle passed is null or invalid. 

Remarks

Thread Class IDs (0, 1, 2, …) represent a software thread's characteristics; i.e., the assembly instruction set (e.g., AVX2) the thread executes. With Intel Thread Director Technology (IDT), the logical processor feedbacks the Class ID of the thread running on it with enough history. RTX64 updates switching out the thread’s Class ID during thread switches and resets the logical processor’s thread director history. RTX64 also updates the thread’s Class ID when RtQueryThreadPerfIdealProcessor is called if the caller is the current thread on the current logical processor. The logical processor may not feedback a Class ID if it does not have enough information to provide a reliable Class ID. In this case, RTX64 will not overwrite the thread’s last known Class ID. Thread Class ID is initialized to 0 at create time.

The values returned by the parameters pIdealProcessorNumber, pCurrentPerfCap, and SystemPerfCaps[] are based on the thread’s current Class ID.

RTX64 does not dynamically migrate RTSS threads during thread scheduling. It is recommended that RTSS processes call RtQueryThreadPerfIdealProcessor to identify their ideal processors for those performance critical threads. If necessary, call SetThreadIdealProcessor or SetThreadAffinityMask to affinity the thread to the performance ideal processor. SetThreadIdealProcessor or SetThreadAffinityMask cannot migrate Interrupt Service Thread (IST), Timer Service Thread (TST), and NPX used thread at run-time. You may need to affine those threads to their performance ideal processors at create time.

See Also:

SetThreadIdealProcessor

SetThreadAffinityMask