Performance Functions (Win32 API)

The Win32 API provides a rich set of functions for monitoring and managing the performance of your Windows applications and the system as a whole. These functions allow you to gather information about CPU usage, memory utilization, disk I/O, network activity, and more.

Performance Monitoring

These functions are used to query performance counters and system statistics.

Performance Data Helpers (PDH)

The Performance Data Helper (PDH) library provides a higher-level interface for accessing performance data, simplifying the process of querying and displaying performance counter information.

Function Details

QueryPerformanceCounter

Retrieves the current value of the high-resolution performance counter.

BOOL QueryPerformanceCounter(
  LARGE_INTEGER *lpPerformanceCount
);

Parameters:

Name Type Description
lpPerformanceCount LARGE_INTEGER* A pointer to a LARGE_INTEGER structure that receives the current counter value.
This function provides a highly accurate time measurement, suitable for performance timing and benchmarking.

QueryPerformanceFrequency

Retrieves the current frequency of the performance counter.

BOOL QueryPerformanceFrequency(
  LARGE_INTEGER *lpFrequency
);

Parameters:

Name Type Description
lpFrequency LARGE_INTEGER* A pointer to a LARGE_INTEGER structure that receives the counter's frequency. This value is in counts per second.
Use this function to determine the units of QueryPerformanceCounter for accurate time interval calculations.

GetProcessTimes

Retrieves timing information for the specified process.

BOOL GetProcessTimes(
  HANDLE hProcess,
  LPFILETIME lpCreationTime,
  LPFILETIME lpExitTime,
  LPFILETIME lpKernelTime,
  LPFILETIME lpUserTime
);

Parameters:

Name Type Description
hProcess HANDLE A handle to the process.
lpCreationTime LPFILETIME A pointer to a FILETIME structure that receives the creation time of the process.
lpExitTime LPFILETIME A pointer to a FILETIME structure that receives the exit time of the process.
lpKernelTime LPFILETIME A pointer to a FILETIME structure that receives the amount of time the process has spent executing in kernel mode.
lpUserTime LPFILETIME A pointer to a FILETIME structure that receives the amount of time the process has spent executing in user mode.

GetThreadTimes

Retrieves timing information for the specified thread.

BOOL GetThreadTimes(
  HANDLE hThread,
  LPFILETIME lpCreationTime,
  LPFILETIME lpExitTime,
  LPFILETIME lpKernelTime,
  LPFILETIME lpUserTime
);

Parameters:

Name Type Description
hThread HANDLE A handle to the thread.
lpCreationTime LPFILETIME A pointer to a FILETIME structure that receives the creation time of the thread.
lpExitTime LPFILETIME A pointer to a FILETIME structure that receives the exit time of the thread.
lpKernelTime LPFILETIME A pointer to a FILETIME structure that receives the amount of time the thread has spent executing in kernel mode.
lpUserTime LPFILETIME A pointer to a FILETIME structure that receives the amount of time the thread has spent executing in user mode.

GetSystemTimes

Retrieves current performance-counter values for system-wide kernel, user, and idle time.

BOOL GetSystemTimes(
  LPFILETIME lpIdleTime,
  LPFILETIME lpKernelTime,
  LPFILETIME lpUserTime
);

Parameters:

Name Type Description
lpIdleTime LPFILETIME A pointer to a FILETIME structure that receives the amount of time the system has spent executing in idle.
lpKernelTime LPFILETIME A pointer to a FILETIME structure that receives the amount of time the system has spent executing in kernel mode.
lpUserTime LPFILETIME A pointer to a FILETIME structure that receives the amount of time the system has spent executing in user mode.
This function returns cumulative times. To measure intervals, call the function twice and calculate the difference.

GlobalMemoryStatusEx

Retrieves information about the current memory availability for the system.

BOOL GlobalMemoryStatusEx(
  LPMEMORYSTATUSEX lpBuffer
);

Parameters:

Name Type Description
lpBuffer LPMEMORYSTATUSEX A pointer to a MEMORYSTATUSEX structure that receives information about the current memory status.

MEMORYSTATUSEX Structure

This structure contains information about the current memory status of the computer. Key members include:

  • dwLength: The size of the structure, in bytes.
  • dwMemoryLoad: A number between 0 and 100 that indicates the approximate percentage of physical memory currently in use.
  • ullTotalPhys: The total amount of physical memory, in bytes.
  • ullAvailPhys: The amount of physical memory currently available, in bytes.
  • ullTotalPageFile: The current size of the committed memory, in bytes. This value is less than or equal to ullTotalPhys + ullTotalVirtual.
  • ullAvailPageFile: The maximum amount of memory that can be committed, in bytes. This value is less than or equal to ullTotalPhys + ullTotalVirtual.

VirtualQueryEx

Obtains detailed information about a region of pages within the virtual address space of a specified process.

SIZE_T VirtualQueryEx(
  HANDLE                   hProcess,
  LPCVOID                  lpAddress,
  PMEMORY_BASIC_INFORMATION lpBuffer,
  SIZE_T                   dwLength
);

Parameters:

Name Type Description
hProcess HANDLE A handle to the process.
lpAddress LPCVOID The base address of the region of pages to be queried.
lpBuffer PMEMORY_BASIC_INFORMATION A pointer to a MEMORY_BASIC_INFORMATION structure that receives information about the specified memory region.
dwLength SIZE_T The size of the buffer pointed to by lpBuffer, in bytes.

PdhOpenQuery

Creates a query that can be used to collect performance data.

PDH_STATUS PdhOpenQuery(
  LPCSTR      szDataSource,
  DWORD_PTR   dwUserData,
  PDH_HQUERY *phQuery
);

Parameters:

Name Type Description
szDataSource LPCSTR Optional. Name of the performance data source. If NULL, the function retrieves data from the local computer.
dwUserData DWORD_PTR User-defined value. This value is passed to any application-defined callback functions.
phQuery PDH_HQUERY* Pointer to a handle. The function initializes this handle to a query object.

PdhAddCounter

Adds a performance counter to the specified query.

PDH_STATUS PdhAddCounterA(
  PDH_HQUERY hQuery,
  LPCSTR     szCounterPath,
  DWORD_PTR  dwUserData,
  PDH_HCOUNTER *phCounter
);

Parameters:

Name Type Description
hQuery PDH_HQUERY Handle to the query object.
szCounterPath LPCSTR The path of the counter to add. Example: \Processor(_Total)\% Processor Time.
dwUserData DWORD_PTR User-defined value.
phCounter PDH_HCOUNTER* Pointer to a handle. The function initializes this handle to the performance counter.

PdhCollectQueryData

Collects data for all counters in the specified query.

PDH_STATUS PdhCollectQueryData(
  PDH_HQUERY hQuery
);

Parameters:

Name Type Description
hQuery PDH_HQUERY Handle to the query object.
Call this function periodically to update performance counter values.

PdhGetFormattedCounterValue

Retrieves the current data for a specified counter and formats it as a displayable value.

PDH_STATUS PdhGetFormattedCounterValue(
  PDH_HCOUNTER          hCounter,
  DWORD                 dwFormat,
  LPDWORD               lpdwType,
  PPDH_FMT_COUNTERVALUE pValue
);

Parameters:

Name Type Description
hCounter PDH_HCOUNTER Handle to the counter object.
dwFormat DWORD The desired format for the counter value. Common values include PDH_FMT_LONG, PDH_FMT_DOUBLE, PDH_FMT_LARGE.
lpdwType LPDWORD Optional. Pointer to a DWORD that receives the counter type.
pValue PPDH_FMT_COUNTERVALUE Pointer to a PDH_FMT_COUNTERVALUE structure that receives the formatted counter value.

PdhCloseQuery

Closes the specified performance data query and frees associated resources.

PDH_STATUS PdhCloseQuery(
  PDH_HQUERY hQuery
);

Parameters:

Name Type Description
hQuery PDH_HQUERY Handle to the query object.
Always call this function when you are finished with a query to prevent resource leaks.