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-nanosecond units. The function returns if the interval elapses. 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 will wait indefinitely for the object to be signaled. Otherwise, lpWaitTimeOut ->QuadPart rounds down to the nearest multiple of the RTX64 HAL timer period. If the value becomes zero after rounding, the time-out interval elapses at the next tick of the HAL timer.

Return Value

To get extended error information, call GetLastError.

The return value indicates the event that caused the function to return. It can be one of the following values:

Value	Description
WAIT_ABANDONED 0x00000080L	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. If the mutex was protecting persistent state information, you should check it for consistency.
WAIT_OBJECT_0 0x00000000L	The state of the specified object is signaled.
WAIT_TIMEOUT 0x00000102L	The time-out interval elapsed, and the object's state is non-signaled.
WAIT_FAILED (DWORD) 0xFFFFFFFF	The function has failed. To get extended error information, call GetLastError.

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 valid until explicitly closed, so it can still be waited on after the thread terminates.
• Process
  The functions RtCreateProcess and RtOpenProcess return the process handle. This handle is valid until explicitly closed, so it can be waited on to determine when the process has exited.

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

NOTE: The signatures for RtWaitForSingleObjectEx and WaitForSingleObjectEx are different but will result in the same behavior when used in a real-time application.

See Also:

• CreateThread
• RtOpenProcess
• RtCreateEvent
• RtCreateMutex
• RtCreateProcess
• RtCreateSemaphore
• RtOpenEvent
• RtOpenMutex
• RtOpenSemaphore
• RtWaitForMultipleObjects
• Application timer expiration behavior