WaitMultipleObjects

The WaitMultipleObjects function determines whether one or more objects specified by handles are in a signaled state, waits for one or all of the objects to enter the signaled state, and then returns.

DWORD WaitMultipleObjects(
  _In_  DWORD          nCount,
  _In_  const HANDLE   *lpHandles,
  _In_  BOOL           bWaitAll,
  _In_  DWORD          dwMilliseconds
);

Parameters

nCount: DWORD
The number of handle and event array elements to be tested.
lpHandles: const HANDLE *
A pointer to an array of object handles. The array can contain handles to various types of objects. It cannot contain duplicate handles.
bWaitAll: BOOL
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: DWORD
The time-out interval in milliseconds. If this parameter is zero, the function will test the state of the objects and return immediately. If the parameter is INFINITE, the function will wait indefinitely.

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: If bWaitAll is FALSE, the return value indicates the index of the object in the lpHandles array that caused the function to return.
WAIT_OBJECT_0: If bWaitAll is TRUE, the return value indicates that all objects in the array are signaled.
WAIT_OBJECT_0 + nCount: If bWaitAll is FALSE, the return value indicates that the object specified by lpHandles[nCount] is signaled.
WAIT_TIMEOUT: If the time-out interval elapsed before the condition was met.
WAIT_FAILED: The function failed. To get extended error information, call GetLastError.

Remarks

The WaitMultipleObjects function is used to wait for the completion of multiple operations. It allows a thread to efficiently wait for one or more synchronization objects (like events, mutexes, semaphores) to become signaled.

The nCount parameter must not be greater than 64. If you need to wait for more than 64 objects, you must create a separate thread to wait for a subset of the handles.

Handles in lpHandles can refer to different types of synchronization objects, but all objects must belong to the same process.

Requirements

Header: synchapi.h (include windows.h)

Library: Kernel32.lib

DLL: Kernel32.dll

Example

Here's a simplified C++ example demonstrating the usage of WaitMultipleObjects:

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

int main() {
    HANDLE hEvent1 = CreateEvent(NULL, FALSE, FALSE, NULL);
    HANDLE hEvent2 = CreateEvent(NULL, FALSE, FALSE, NULL);

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

    HANDLE handles[2] = { hEvent1, hEvent2 };

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

    // Wait for either event to be signaled, with a 5-second timeout
    DWORD waitResult = WaitMultipleObjects(2, handles, FALSE, 5000);

    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 << "The time-out interval elapsed." << std::endl;
            break;
        default:
            std::cerr << "Wait function failed. Error: " << GetLastError() << std::endl;
            break;
    }

    CloseHandle(hEvent1);
    CloseHandle(hEvent2);

    return 0;
}

Win32 API Reference