WaitForSingleObject

The WaitForSingleObject function determines whether the calling thread has waiting access to an object. If the conditions are not met, the calling thread enters the wait state until the conditions are met or the time-out interval elapses.

DWORD WaitForSingleObject( HANDLE hHandle, DWORD dwMilliseconds );

Parameters

Parameter Description
hHandle A handle to the object. For a list of objects that have single-wait sync-event characteristics, see Synchronization Object Types.
dwMilliseconds The time-out interval in milliseconds. If this parameter is zero, the function returns immediately. If this parameter is INFINITE, the function will not return until the object's signaled state is received.

Return Value

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:

  • WAIT_OBJECT_0: The state of the specified object is signaled.
  • WAIT_TIMEOUT: The time-out interval elapsed.
  • WAIT_ABANDONED: The specified object is a mutex, and the thread that owned the mutex has terminated without releasing it. The mutex is now abandoned and signaled.

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

Remarks

This function places the current thread in a wait state until one of the following occurs:

  • The specified object is in the signaled state.
  • The time-out interval elapses.

The WaitForSingleObject function checks the "signaled state" of the object specified by hHandle. If the object is signaled, the function returns immediately. If the object is not signaled, the thread enters a wait state. If the thread enters a wait state, it remains in that state until the time-out interval expires or the object's signaled state is received.

Note: If dwMilliseconds is INFINITE, the function will wait indefinitely for the object to be signaled.

You can use WaitForSingleObject to wait for various synchronization objects, including events, mutexes, semaphores, and processes.

See Also