RegisterWaitForSingleObject function (winbase.h)

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.

Syntax

BOOL RegisterWaitForSingleObject(
  [out]          PHANDLE             phNewWaitObject,
  [in]           HANDLE              hObject,
  [in]           WAITORTIMERCALLBACK Callback,
  [in, optional] PVOID               Context,
  [in]           ULONG               dwMilliseconds,
  [in]           ULONG               dwFlags
);

Parameters

[out] phNewWaitObject

A 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.

[in] hObject

A handle to the object. For a list of the object types whose handles can be specified, see the following Remarks section.

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.

The handles must have the SYNCHRONIZE access right. For more information, see Standard Access Rights.

[in] Callback

A 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.

[in, optional] Context

A single value that is passed to the callback function.

[in] dwMilliseconds

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.

[in] dwFlags

This parameter can be one or more of the following values.

For information about using these values with objects that remain signaled, see the Remarks section.

Return value

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call
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.

When the wait is completed, you must call the UnregisterWait or UnregisterWaitEx function to cancel the wait operation. (Even wait operations that use WT_EXECUTEONLYONCE must be canceled.) 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 an object that remains signaled (such as a manual reset event or terminated process) unless you set the WT_EXECUTEONLYONCE or WT_EXECUTEINWAITTHREAD flag. For other flags, the callback function might be called too many times before the event is reset.

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
• Memory resource notification
• Process
• Semaphore
• Thread
• Waitable timer

By default, the thread pool has a maximum of 500 threads. To raise this limit, use the WT_SET_MAX_THREADPOOL_THREAD macro defined in WinNT.h.

#define WT_SET_MAX_THREADPOOL_THREADS(Flags,Limit) \
    ((Flags)|=(Limit)<<16)

Use this macro when specifying the dwFlags parameter. The macro parameters are the desired flags and the new limit (up to (2<<16)-1 threads). However, note that your application can improve its performance by keeping the number of worker threads low.

The work item and all functions it calls must be thread-pool safe. Therefore, you cannot call an asynchronous call that requires a persistent thread, such as the RegNotifyChangeKeyValue function, from the default callback environment. Instead, set the thread pool maximum equal to the thread pool minimum using the SetThreadpoolThreadMaximum and SetThreadpoolThreadMinimum functions, or create your own thread using the CreateThread function. (For the original thread pool API, specify WT_EXECUTEINPERSISTENTTHREAD using the QueueUserWorkItem function.)

To compile an application that uses this function, define _WIN32_WINNT as 0x0500 or later. For more information, see Using the Windows Headers.

Requirements

See also

Synchronization Functions

Thread Pooling

UnregisterWait

UnregisterWaitEx

Wait Functions

WaitOrTimerCallback