SetThreadpoolWaitEx function

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.

Syntax

BOOL WINAPI SetThreadpoolWaitEx(
  _Inout_    PTP_WAIT  pwa,
  _In_opt_   HANDLE    h,
  _In_opt_   PFILETIME pftTimeout,
  _Reserved_ PVOID     Reserved
);

Parameters

pwa [in, out]

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

h [in, optional]

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.

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.

pftTimeout [in, optional]

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.

Reserved

Reserved.

Return value

TRUE, if the timer was previously active and was canceled; otherwise, FALSE. This return value can be used to maintain reference counts to synchronize between completion and cancellation of a non-periodic timer operation. If FALSE is returned, a callback may be in progress or about to commence. If FALSE is returned, a subsequent WaitForThreadpool or WaitForThreadpoolEx Callback operation will complete after that callback is completed. A subsequent SetThreadpool or SetThreadpoolEx operation that is not later canceled will result in an additional callback.”

Remarks

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

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

Requirements

See also

CloseThreadpoolWait

CreateThreadpoolWait

Thread Pools

WaitForThreadpoolWaitCallbacks