RtWaitForSingleObject

RtWaitForSingleObject allows a thread to wait on an object to be signaled.

Syntax

DWORD RtWaitForSingleObject(
    HANDLE Handle,
    DWORD Milliseconds
);

Parameters

hHandle

The object identifier. See the list of the object types whose handles can be specified in the Remarks section.

Milliseconds

The time-out interval, in milliseconds. The function returns if the interval elapses, even if the object's state is non-signaled. If Milliseconds is zero, the function tests the object's state and returns immediately. If Milliseconds is INFINITE, the function's time-out interval never elapses.

Return Value

The event that caused the function to return, if the function succeeds, WAIT_FAILED if the function fails

To get extended error information, call GetLastError.

Possible return value on success are:

Value	Description
WAIT_ABANDONED	The specified object is a mutex object that was not released by the thread that owned the mutex object before the owning thread terminated. Ownership of the mutex object is granted to the calling thread, and the mutex is set to non-signaled.
WAIT_OBJECT_0	The state of the specified object is signaled.
WAIT_TIMEOUT	The time-out interval elapsed, and the object's state is non-signaled.

Remarks

RtWaitForSingleObject checks the current state of the specified object. If the object's state is non-signaled, the calling thread enters an efficient wait state. The thread consumes very little processor time while waiting for the object state to become signaled or the time-out interval to elapse.

The function returns when one of these events occurs:

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

Before returning, a wait function modifies the state of some types of synchronization objects. Modification occurs only for the object or objects whose signaled state caused the function to return. For example, the count of a semaphore object is decreased by one.

RtWaitForSingleObject can wait for the following objects:

Object	Description
Semaphore	RtCreateSemaphore or RtOpenSemaphore returns the handle. A semaphore object maintains a count between zero and some maximum value. Its state is signaled when its count is greater than zero and non-signaled when its count is zero. If the current state is signaled, the wait function decreases the count by one.
Mutex	RtCreateMutex and RtOpenMutex return handles to the mutex object which becomes signaled when the mutex is unowned.
Event	The RtCreateEvent or RtOpenEvent function returns the handle that can be waited on. An event object's state is set explicitly to signaled by the RtSetEvent or RtPulseEvent function. A manual-reset event object's state must be reset explicitly to nonsignaled by the RtResetEvent function. For an auto-reset event object, the wait function resets the object's state to nonsignaled before returning.
Thread	The function CreateThread returns a handle. This handle can be waited on to determine when the thread is completed.. NOTE: This will fail in the Windows build configuration, as CreateThread will pass a Windows handle.
Process	The function RtCreateProcess and RtOpenProcess return the process handle, this handle is valid for the life of the process so it can be waited on to determine when the process has exited.

See Also:

• RtCreateEvent
• RtCreateMutex
• RtCreateSemaphore
• RtOpenEvent
• RtOpenMutex
• RtOpenSemaphore