RtWaitForSingleObjectEx

RtWaitForSingleObjectEx allows a thread to wait on an object to be signaled with high granularity of time-out interval.

Syntax

DWORD RtWaitForSingleObjectEx(
    HANDLE hHandle,
    PULARGE_INTEGER lpWaitTimeOut
);

Parameters

hHandle

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

lpWaitTimeOut

The pointer to time-out interval, in 100 nanoseconds. The function returns if the interval elapses, even if the object's state is non-signaled. If lpWaitTimeOut is NULL, the function returns WAIT_FAILED with last error ERROR_INVALID_PARAMETER. If lpWaitTimeOut ->QuadPart is zero, the function tests the object's state and returns immediately. If both lpWaitTimeOut ->LowPart and lpWaitTimeOut ->HighPart are INFINITE, the function's time-out interval never elapses. Otherwise, lpWaitTimeOut ->QuadPart modules down to the multiple of RTX HAL Clock period. If the value becomes zero after module down, the time-out interval elapses to the next tick.

Return Values

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 values 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

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

RtWaitForSingleObjectEx can wait for the following objects:

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 is value for the life of the thread so it can be waited on to determine when the thread is completed..
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 processor has exited.

NOTE: RtWaitForSingleObjectEx can only be called from a RTSS process or RTDLL.

Requirements

Minimum Supported Version	RTX 2012 Update 1
Header	Rtapi.h
Library	Rtx_Rtss.lib (RTSS)