WaitForMultipleObjects - Windows Win32 API

Function

DWORD WaitForMultipleObjects(
DWORD nCount,
CONST HANDLE *lpHandles,
BOOL bWaitAll,
DWORD dwMilliseconds
);

Description

This function determines if any or all of the objects specified in the array of handles are in a signaled state or if the time-out interval elapses. The objects can be any of the following types: an event, a semaphore, a mutex, a process, or a thread.

The function returns an index into the array of handles that identifies the object that satisfied the wait condition. If the function returns because the time-out interval elapsed, it returns WAIT_TIMEOUT.

Parameters

Parameter	Description
`nCount`	The number of handles in the array pointed to by `lpHandles`.
`lpHandles`	A pointer to an array of handles. For a list of object types whose handles can be used by this function, see the Remarks section. The array can contain handles to different types of objects.
`bWaitAll`	If this parameter is `TRUE`, the function returns when the state of all objects in the array is signaled. If this parameter is `FALSE`, the function returns as soon as the state of any one of the objects is signaled.
`dwMilliseconds`	The time-out interval in milliseconds. If this parameter is zero, the function will always return immediately. If this parameter is `INFINITE`, the time-out interval is indefinite; the function will not return until signaled.

Return Value

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

0 to nCount-1: The value indicates that the handle at the specified index in the lpHandles array is signaled.
WAIT_OBJECT_0 + nCount: The time-out interval elapsed and bWaitAll was FALSE.
WAIT_ABANDONED: The value indicates that the specified object is a mutex and the process that owned the mutex has terminated without releasing it. The return value is WAIT_ABANDONED + (index of mutex handle in lpHandles).
WAIT_TIMEOUT: The time-out interval elapsed.

If the function fails, the return value is WAIT_FAILED. To get extended error information, call GetLastError.

Remarks

The lpHandles array can contain handles to the following types of objects:

Event objects
Semaphore objects
Mutex objects
Process objects
Thread objects

You can wait for up to 64 handles simultaneously.

Example

Waiting for two events

This example demonstrates how to wait for either of two events to become signaled.


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

int main() {
    HANDLE hEvent1 = CreateEvent(NULL, FALSE, FALSE, L"MyEvent1");
    HANDLE hEvent2 = CreateEvent(NULL, FALSE, FALSE, L"MyEvent2");

    if (hEvent1 == NULL || hEvent2 == NULL) {
        std::cerr << "Failed to create events. Error: " << GetLastError() << std::endl;
        return 1;
    }

    HANDLE hHandles[2] = { hEvent1, hEvent2 };
    DWORD dwWaitResult;

    std::cout << "Waiting for Event1 or Event2 to be signaled..." << std::endl;

    // Wait indefinitely for either event to be signaled
    dwWaitResult = WaitForMultipleObjects(
        2,              // number of handles
        hHandles,       // array of handles
        FALSE,          // wait for any one object
        INFINITE);      // infinite timeout

    switch (dwWaitResult) {
        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 << "The time-out interval elapsed." << std::endl;
            break;
        case WAIT_FAILED:
            std::cerr << "WaitForMultipleObjects failed. Error: " << GetLastError() << std::endl;
            break;
        default:
            std::cerr << "Unexpected return value: " << dwWaitResult << std::endl;
            break;
    }

    CloseHandle(hEvent1);
    CloseHandle(hEvent2);

    return 0;
}