RtWaitForMultipleObjects

RtWaitForMultipleObjects allows a thread to wait on one of multiple objects to be signaled.

Syntax

DWORD RtWaitForMultipleObjects(
    DWORD dwCount,
    CONST HANDLE *lpHandles,
    BOOL bWaitAll,
    DWORD dwMilliseconds
);

Parameters

dwCount

Specifies the number of object handles in the array pointed to by lpHandles. The maximum number of object handles is MAX_WFMO (64).

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.

bWaitAll

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.

dwMilliseconds

Specifies the time-out interval, in milliseconds. The function returns if the interval elapses, even if the condition specified by the fWaitAll parameter are not met. If dwMilliseconds is zero, the function tests the states of the specified objects and returns immediately. If dwMilliseconds is INFINITE, the function's time-out interval never elapses.

Return Values

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

RtWaitForMultipleObjects 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:

• Any one of the specified object is in the signaled state
• The time-out interval elapses

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.

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

• Event
• Mutex
• Process
• Semaphore
• Thread

If the nCount is equal to or less than 16, the API’s latency will be roughly the same as in previous versions. If nCount is greater than 16, the latency will increase linearly (i.e., for 32 objects the latency will be about twice that of 16).

See Also:

CreateThread

RtOpenProcess

RtCreateEvent

RtCreateMutex

RtCreateProcess

RtCreateSemaphore

RtOpenEvent

RtOpenMutex

RtOpenSemaphore

RtWaitForSingleObject