WaitMultipleObjects

The WaitMultipleObjects function determines whether one or more objects specified by the caller are in a signaled state; this function returns when one or all of the events are signaled. This is a versatile function that can be used to synchronize the execution of multiple threads or processes.

Syntax

DWORD WaitMultipleObjects(
  [in] DWORD           nCount,
  [in] const HANDLE    *lpHandles,
  [in] BOOL            bWaitAll,
  [in] DWORD           dwMilliseconds
);

Parameters

Parameter	Description
`nCount`	The number of handles in the array pointed to by `lpHandles`.
`lpHandles`	A pointer to an array of object handles. The array must contain at least one handle. The handles must have sufficient rights to test for the conditions. For more information, see Object Handle Requirements.
`bWaitAll`	If this parameter is `TRUE`, the function returns when all objects in the `lpHandles` array are signaled. If this parameter is `FALSE`, the function returns when any one of the objects is signaled.
`dwMilliseconds`	The time-out interval in milliseconds. If this parameter is zero, the function will test the status of the specified objects and return immediately. If this parameter is `INFINITE`, the function will wait indefinitely for any or all of the specified objects to be signaled.

Return Value

If the function succeeds, the return value indicates the event that caused the function to exit. It can be one of the following values:

If bWaitAll is TRUE:
- 0 to nCount - 1: The function returned because all the specified objects were signaled. The return value is the index of the first object in the array that was signaled.
- WAIT_OBJECT_0 + nCount: The time-out interval elapsed.
- WAIT_ABANDONED_0: The function returned because a mutex object in the array was abandoned. The return value is WAIT_ABANDONED_0 + i, where i is the index of the abandoned mutex.
If bWaitAll is FALSE:
- 0 to nCount - 1: The function returned because one of the specified objects was signaled. The return value is the index of the first object in the array that was signaled.
- WAIT_OBJECT_0 + nCount: The time-out interval elapsed.
- WAIT_ABANDONED_0: The function returned because a mutex object in the array was abandoned. The return value is WAIT_ABANDONED_0 + i, where i is the index of the abandoned mutex.

If the function fails, the return value is WAIT_TIMEOUT, and GetLastError returns information about the error.

Remarks

The lpHandles array can contain handles to various synchronization objects, including events, mutexes, semaphores, and process/thread handles.
The order of handles in the array matters when bWaitAll is FALSE, as the function returns the index of the *first* signaled object.
For mutexes, an abandoned mutex is one that was not released by the thread that owned it before that thread terminated.
The INFINITE constant is defined in winuser.h.

Example

#include <windows.h>
#include <iostream>

int main() {
    HANDLE hEvents[2];
    DWORD waitResult;

    // Create two events
    hEvents[0] = CreateEvent(NULL, FALSE, FALSE, TEXT("MyEvent1"));
    hEvents[1] = CreateEvent(NULL, FALSE, FALSE, TEXT("MyEvent2"));

    if (hEvents[0] == NULL || hEvents[1] == NULL) {
        std::cerr << "Error creating events: " << GetLastError() << std::endl;
        return 1;
    }

    std::cout << "Waiting for either event to be signaled..." << std::endl;

    // Wait for either event to be signaled (bWaitAll = FALSE)
    waitResult = WaitMultipleObjects(2, hEvents, FALSE, INFINITE);

    switch (waitResult) {
        case WAIT_OBJECT_0:
            std::cout << "Event 1 was signaled." << std::endl;
            break;
        case WAIT_OBJECT_0 + 1:
            std::cout << "Event 2 was signaled." << std::endl;
            break;
        case WAIT_TIMEOUT:
            std::cout << "Wait timed out." << std::endl;
            break;
        default:
            std::cerr << "Unexpected wait result: " << waitResult << std::endl;
            break;
    }

    CloseHandle(hEvents[0]);
    CloseHandle(hEvents[1]);

    return 0;
}