QueryThreadCycleTime function (realtimeapiset.h)

Article
02/22/2024

Retrieves the cycle time for the specified thread.

Syntax

BOOL QueryThreadCycleTime(
  [in]  HANDLE   ThreadHandle,
  [out] PULONG64 CycleTime
);

Parameters

[in] ThreadHandle

A handle to the thread. The handle must have the PROCESS_QUERY_INFORMATION or PROCESS_QUERY_LIMITED_INFORMATION access right. For more information, see Process Security and Access Rights.

[out] CycleTime

The number of CPU clock cycles used by the thread. This value includes cycles spent in both user mode and kernel mode.

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

To enumerate the threads of the process, use the Thread32First and Thread32Next functions. To get the thread handle for a thread identifier, use the OpenThread function.

Do not attempt to convert the CPU clock cycles returned by QueryThreadCycleTime to elapsed time. This function uses timer services provided by the CPU, which can vary in implementation. For example, some CPUs will vary the frequency of the timer when changing the frequency at which the CPU runs and others will leave it at a fixed rate. The behavior of each CPU is described in the documentation provided by the CPU vendor.

To compile an application that uses this function, define _WIN32_WINNT as 0x0600 or later.

Requirements

Requirement	Value
Minimum supported client	Windows Vista [desktop apps only]
Minimum supported server	Windows Server 2008 [desktop apps only]
Target Platform	Windows
Header	realtimeapiset.h (include Windows.h on Windows 7, Windows Server 2008 Windows Server 2008 R2)
Library	Kernel32.lib
DLL	Kernel32.dll