SetThreadpoolWait function (threadpoolapiset.h)

Sets the wait object, replacing the previous wait object, if any. A worker thread calls the wait object's callback function after the handle becomes signaled or after the specified timeout expires.


void SetThreadpoolWait(
  [in, out]      PTP_WAIT  pwa,
  [in, optional] HANDLE    h,
  [in, optional] PFILETIME pftTimeout


[in, out] pwa

A pointer to a TP_WAIT structure that defines the wait object. The CreateThreadpoolWait function returns this pointer.

[in, optional] h

A handle.

If this parameter is NULL, the wait object will cease to queue new callbacks (but callbacks already queued will still occur).

If this parameter is not NULL, it must refer to a valid waitable object.

Mutex is not supported. If a handle to a mutex is passed in, the thread pool raises a STATUS_THREADPOOL_HANDLE_EXCEPTION exception and ExceptionRecord.ExceptionInformation[0] will be equal to STATUS_INVALID_PARAMETER_3.

If this handle is closed while the wait is still pending, the function's behavior is undefined. If the wait is still pending and the handle must be closed, use CloseThreadpoolWait to cancel the wait and then close the handle.

The wait is considered set if this parameter is non-NULL.

[in, optional] pftTimeout

A pointer to a FILETIME structure that specifies the absolute or relative time at which the wait operation should time out. If this parameter points to a positive value, it indicates the absolute time since January 1, 1601 (UTC), in 100-nanosecond intervals. If this parameter points to a negative value, 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 points to 0, the wait times out immediately. If this parameter is NULL, the wait will not time out.

Return value



A wait object can wait for only one handle. Setting the handle for a wait object replaces the previous handle, if any.

You must re-register the event with the wait object before signaling it each time to trigger the wait callback.

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


For an example, see Using the Thread Pool Functions.


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

See also




Thread Pools