WaitForSingleObject (Compact 2013)

  • Article

3/28/2014

This function returns when the specified object is in the signaled state or when the time-out interval elapses.

Syntax

DWORD WaitForSingleObject(
  HANDLE hHandle,
  DWORD dwMilliseconds
);

Parameters

  • hHandle
    [in] Handle to the object. For a list of the object types whose handles can be specified, see the Remarks section.
  • dwMilliseconds
    [in] Specifies the time-out interval, in milliseconds. The function returns if the interval elapses, even if the object's state is nonsignaled. If dwMilliseconds is zero, the function tests the object's state and returns immediately. If dwMilliseconds is INFINITE, the function's time-out interval never elapses.

Return Value

If the function succeeds, the return value indicates the event that caused the function to return. The following table shows possible values.

Value

Description

WAIT_FAILED

Indicates failure for one of the following reasons:

  • There is insufficient memory in the system.
  • Two threads are waiting on the same interrupt event.
  • The current thread is being terminated.
  • The underlying object represented by hHandle has been deleted.
  • The handle is invalid.

WAIT_OBJECT_0

The state of the specified object is signaled.

WAIT_TIMEOUT

The time-out interval elapsed, and the object's state is nonsignaled.

To get extended error information, call GetLastError.

Remarks

Two threads cannot wait on a single interrupt event.

If an event handle is closed after WaitForSingleObject is called, it will never be signaled and only return after timeout has expired.

The WaitForSingleObject function checks the current state of the specified object. If the object's state is nonsignaled, the calling thread enters an efficient wait state. The thread consumes very little processor time while waiting for the object state to become signaled or the time-out interval to elapse. The time-out value needs to be a positive number between zero and 0x7FFFFFFF. The maximum time-out value not equal to infinity is 0x7FFFFFFF. The infinite time-out value is 0xFFFFFFFF. Any time-out value between 0x7FFFFFFF and 0xFFFFFFFF - that is, values from 0x80000000 through 0xFFFFFFFE - is equivalent to 0x7FFFFFFF. If you need a bigger time-out value than the maximum of 0x7FFFFFFF, use the value for infinity (0xFFFFFFFF).

Before returning, a wait function modifies the state of some types of synchronization objects. Modification occurs only for the object whose signaled state caused the function to return. For example, the count of a semaphore object is decreased by one. The WaitForSingleObject function can wait for any of the following objects:

  • Event
  • Mutex
  • Semaphore
  • Process
  • Thread

Use caution when calling the wait functions and code that directly or indirectly creates windows. If a thread creates any windows, it must process messages. Message broadcasts are sent to all windows in the system. A thread that uses a wait function with no time-out interval may cause the system to become deadlocked. For example, the Dynamic Data Exchange (DDE) protocol and the COM function CoInitialize both indirectly create windows that can cause a deadlock. Therefore, if you have a thread that creates windows, use MsgWaitForMultipleObjects or MsgWaitForMultipleObjectsEx, rather than WaitForSingleObject.

Each object type, such as memory maps, semaphores, events, message queues, mutexes, and watchdog timers, has its own separate namespace. Empty strings, "", are handled as named objects. On Windows desktop-based platforms, synchronization objects all share the same namespace.

Requirements

Header

winbase.h

Library

coredll.lib

See Also

Reference

Synchronization Functions
WaitForMultipleObjects
CreateEvent
PulseEvent
ResetEvent
SetEvent
Sleep

Other Resources

MsgWaitForMultipleObjects
MsgWaitForMultipleObjectsEx
CreateFile