RegisterWaitForSingleObject

The RegisterWaitForSingleObject function directs a wait thread in the thread pool to wait on the object. The wait thread queues the specified callback function to the thread pool when one of the following occurs:

• The specified object is in the signaled state.
• The time-out interval elapses.

BOOL RegisterWaitForSingleObject( 
  PHANDLE phNewWaitObject,       // wait handle
  HANDLE hObject,                // handle to object
  WAITORTIMERCALLBACK Callback,  // timer callback function
  PVOID Context                  // callback function parameter
  ULONG dwMilliseconds,          // time-out interval
  ULONG dwFlags                  // options
); 

Parameters

phNewWaitObject

[out] Pointer to a variable that receives a wait handle on return. Note that a wait handle cannot be used in functions that require an object handle, such as CloseHandle.

hObject

[in] Handle to the object. For a list of the object types whose handles can be specified, see the following Remarks section.

If this handle is closed while the wait is still pending, the function's behavior is undefined.

Callback

[in] Pointer to the application-defined function of type WAITORTIMERCALLBACK to be executed when hObject is in the signaled state, or dwMilliseconds elapses. For more information, see WaitOrTimerCallback.

Context

[in] Specifies a single value that is passed to the callback function.

dwMilliseconds

[in] Specifies the time-out interval, in milliseconds. The function returns if the interval elapses, even if the object's state is nonsignaled. If dwMilliseconds is zero, the function tests the object's state and returns immediately. If dwMilliseconds is INFINITE, the function's time-out interval never elapses.

dwFlags

[in] Specifies how the operation is to be performed. This parameter can be one or more of the following values.

Value	Meaning
WT_EXECUTEDEFAULT	By default, the callback function is queued to a non-I/O worker thread.
WT_EXECUTEINWAITTHREAD	The callback function is invoked by the wait thread itself. This flag should be used only for short tasks or it could affect other wait operations. Deadlocks can occur if some other thread acquires an exclusive lock and calls the UnregisterWait or UnregisterWaitEx function while the callback function is trying to acquire the same lock.
WT_EXECUTEINIOTHREAD	The callback function is queued to an I/O worker thread. This flag should be used if the function should be executed in a thread that waits in an alertable state. The callback function is queued as an APC. Be sure to address reentrancy issues if the function performs an alertable wait operation.
WT_EXECUTEINPERSISTENTTHREAD	The callback function is queued to a thread that never terminates. This flag should be used only for short tasks or it could affect other wait operations. Note that currently no worker thread is persistent, although no worker thread will terminate if there are any pending I/O requests.
WT_EXECUTELONGFUNCTION	Specifies that the callback function can perform a long wait. This flag helps the system to decide if it should create a new thread.
WT_EXECUTEONLYONCE	The thread will no longer wait on the handle after the callback function has been called once. Otherwise, the timer is reset every time the wait operation completes until the wait operation is canceled.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. There are no error values defined for this function that can be retrieved by calling GetLastError.

Remarks

New wait threads are created automatically when required. The wait operation is performed by a wait thread from the thread pool. The callback routine is executed by a worker thread when the object's state becomes signaled or the time-out interval elapses. If dwFlags is not WT_EXECUTEONLYONCE, the timer is reset every time the event is signaled or the time-out interval elapses.

To cancel the wait operation, call the UnregisterWait or UnregisterWaitEx function. Do not make a blocking call to either of these functions from within the callback function.

Note that you should not pulse an event object passed to RegisterWaitForSingleObject, because the wait thread might not detect that the event is signaled before it is reset. You should not register a manual reset event unless you set the WT_EXECUTEONLYONCE or WT_EXECUTEINWAITTHREAD flag.

The function modifies the state of some types of synchronization objects. Modification occurs only for the object whose signaled state caused the wait condition to be satisfied. For example, the count of a semaphore object is decreased by one.

The RegisterWaitForSingleObject function can wait for the following objects:

• Change notification
• Console input
• Event
• Job
• Mutex
• Process
• Semaphore
• Thread
• Waitable timer

For more information, see Synchronization Objects.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Unsupported.
  Header: Declared in Winbase.h; include Windows.h.
  Library: Use Kernel32.lib.

See Also

Synchronization Overview, Synchronization Functions, UnregisterWait, UnregisterWaitEx, WaitForMultipleObjects, WaitOrTimerCallback, Thread Pooling