WaitForSingleObject

WaitForSingleObject is a Windows API function in kernel32.dll that waits until the specified object becomes signaled or until a timeout interval elapses. It is used for basic synchronization between threads or processes and can wait on objects such as events, mutexes, semaphores, processes, threads, and timers.

The function signature is: DWORD WaitForSingleObject(HANDLE hHandle, DWORD dwMilliseconds);

Parameters:

- hHandle: a handle to an object whose state you want to wait on. The object must be waitable (e.g., event, mutex, semaphore, process, thread, timer).

- dwMilliseconds: the time-out interval, in milliseconds. Use INFINITE to wait indefinitely.

Return value:

- WAIT_OBJECT_0: the specified object is signaled.

- WAIT_TIMEOUT: the time-out interval elapsed and the object was not signaled.

- WAIT_ABANDONED: a mutex was abandoned by a thread that terminated without releasing it.

- WAIT_FAILED: an error occurred; call GetLastError for more information.

Notes:

- It is a blocking call that suspends the calling thread until the object is signaled or the timeout expires.

- For alertable waiting (to receive APCs), use WaitForSingleObjectEx with aAlertable set to TRUE, or use WaitForMultipleObjectsEx.

- Use with caution to avoid deadlocks; ensure handles are valid and released promptly.

See also:

WaitForMultipleObjects, WaitForSingleObjectEx, WaitForMultipleObjectsEx.