RtWaitForMultipleObjectsEx

RtWaitForMultipleObjectsExallows a thread to wait on one of multiple objects to be signaled with high granularity of time-out interval.

Syntax

DWORD RtWaitForMultipleObjectsEx(
    DWORD nCount,
    CONST HANDLE *lpHandles,
    BOOL fWaitAll,
    PULARGE_INTEGER lpWaitTimeOut
);

Parameters

nCount

Specifies the number of object handles in the array pointed to by lpHandles. The maximum number of object handles is MAX_WFMO, as defined in RTAPI.h.

lpHandles

Pointer to an array of object handles. For a list of the object types whose handles can be specified, see the following Remarks section. The array can contain handles to objects of different types. It may not contain the multiple copies of the same handle.

If one of these handles is closed while the wait is still pending, the function's behavior is undefined.

The handles must have SYNCHRONIZE access.

fWaitAll

Specifies the wait type. The function returns when the state of any one of the objects set to is signaled. The return value indicates the object whose state caused the function to return.

RTSS Environment: This parameter must be FALSE, indicating WAIT FOR ANY.

lpWaitTimeOut

The pointer to time-out interval, in 100-nanosecond units. The function returns if the interval elapses, even if the condition specified by the fWaitAll parameter are not met. If lpWaitTimeOut is NULL, the function returns WAIT_FAILED with last error ERROR_INVALID_PARAMETER. If lpWaitTimeOut ->QuadPart is zero, the function tests the states of the specified objects 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 RTX64 HAL Clock period. If the value becomes zero after module down, the time-out interval elapses to the next tick.

Return Value

The event that caused the function to return if the function succeeds

Possible return values are shown in this table:

Return Value

Meaning

WAIT_OBJECT_0 to (WAIT_OBJECT_0 + nCount - 1)

The return value minus WAIT_OBJECT_0 indicates the lpHandles array index of the object that satisfied the wait. If more than one object became signaled during the call, this is the array index of the signaled object with the smallest index value of all the signaled objects.

WAIT_ABANDONED_0 to (WAIT_ABANDONED_0 + nCount - 1)

The return value minus WAIT_ABANDONED_0 indicates the lpHandles array index of an abandoned mutex object that satisfied the wait.

WAIT_TIMEOUT

The time-out interval elapsed and the conditions specified by the fWaitAll parameter are not satisfied. If the function fails, the return value is WAIT_FAILED. To get extended error information, call GetLastError.

Remarks

RtWaitForMultipleObjectsEx determines whether the wait criteria have been met. If the criteria have not been met, the calling thread enters the wait state. It uses no processor time while waiting for the criteria to be met.

The function returns when one of these events occurs:

The 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. When fWaitAll is FALSE, and multiple objects are in the signaled state, the function chooses one of the objects to satisfy the wait; the states of the other objects are unaffected.

RtWaitForMultipleObjectsEx can specify handles of any of the following object types in the lpHandles array:

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

Requirements

Minimum Supported Version RTX64 2013 with Service Pack 1
Header RtssApi.h
Library Rtx_Rtss.lib

See Also: