Export (0) Print
Expand All
Expand Minimize

SetThreadpoolTimer function

Sets the timer object. A worker thread calls the timer object's callback after the specified timeout expires.

Syntax


VOID WINAPI SetThreadpoolTimer(
  _Inout_   PTP_TIMER pti,
  _In_opt_  PFILETIME pftDueTime,
  _In_      DWORD msPeriod,
  _In_opt_  DWORD msWindowLength
);

Parameters

pti [in, out]

A pointer to a TP_TIMER structure that defines the timer object to set. The CreateThreadpoolTimer function returns this structure.

pftDueTime [in, optional]

A pointer to a FILETIME structure that specifies the absolute or relative time at which the timer should expire. If positive or zero, it indicates the absolute time since January 1, 1601 (UTC), measured in 100 nanosecond units. If negative, it indicates the amount of time to wait relative to the current time. For more information about time values, see File Times.

If this parameter is NULL, the timer object will cease to queue new callbacks (but callbacks already queued will still occur). Note that if this parameter is zero, the timer will expire immediately.

msPeriod [in]

The timer period, in milliseconds. If this parameter is zero, the timer is signaled once. If this parameter is greater than zero, the timer is periodic. A periodic timer automatically reactivates each time the period elapses, until the timer is canceled.

msWindowLength [in, optional]

The maximum amount of time the system can delay before calling the timer callback. If this parameter is set, the system can batch calls to conserve power.

Return value

This function does not return a value.

Remarks

In some cases, callback functions might run after an application closes the threadpool timer. To prevent this behavior, an application should call SetThreadpoolTimer with the pftDueTime parameter set to NULL and the msPeriod and msWindowLength parameters set to 0. For more information, see CloseThreadpoolTimer.

If the due time specified by pftDueTime is relative, the time that the system spends in sleep or hibernation does not count toward the expiration of the timer. The timer is signaled when the cumulative amount of elapsed time the system spends in the waking state equals the timer's relative due time or period. If the due time specified by pftDueTime is absolute, the time that the system spends in sleep or hibernation does count toward the expiration of the timer. If the timer expires while the system is sleeping, the timer is signaled immediately when the system wakes.

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

Examples

For an example, see Using the Thread Pool Functions.

Requirements

Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2008 [desktop apps only]

Header

WinBase.h on Windows Vista, Windows 7, Windows Server 2008, and Windows Server 2008 R2 (include Windows.h);
Threadpoolapiset.h on Windows 8 and Windows Server 2012

Library

Kernel32.lib

DLL

Kernel32.dll

See also

CloseThreadpoolTimer
CreateThreadpoolTimer
IsThreadpoolTimerSet
Thread Pools
WaitForThreadpoolTimerCallbacks

 

 

Community Additions

ADD
Show:
© 2014 Microsoft