Waiting on kernel objects

Waiting on a single kernel object

The handle_wait function is a wrapper around the WaitForSingleObject function. It waits on an arbitrary waitable kernel object with an optional timeout.

bool handle_wait(HANDLE handle, DWORD dwMilliseconds = INFINITE) noexcept;

It returns true if the wait was successful or false if the wait timed out. It fails fast for any other condition, such as an invalid handle or an abandoned mutex.

Individual synchronization objects typically expose methods for waiting.

• To wait on an event, use the unique_event.wait() method.
• To wait on a mutex and automatically release the mutex at scope exit, use the unique_mutex.acquire method.
• To wait on a semaphore and automatically release a token at scope exit, use the unique_semaphore.acquire method.

Waiting on multiple objects

The unique_handle classes (which includes unique_event, unique_mutex, and unique_semaphore) are the same size as a kernel handle. This permits you to call WaitForMultipleObjects and MsgWaitForMultipleObjects with conformant arrays of those objects:

std::vector<wil::unique_handle> handles;
WaitForMultipleObjects(handles.size(), handles.data()->addressof(), TRUE, TIMEOUT);

wil::unique_handle handles[2];
WaitForMultipleObjects(ARRAYSIZE(handles), handles[0].addressof(), TRUE, TIMEOUT);

// WRONG! The "&" operator closes the handle.
WaitForMultipleObjects(handles.size(), &handles[0], TRUE, TIMEOUT);