The SignalObjectAndWait function allows the caller to atomically signal an object and wait on another object.
DWORD SignalObjectAndWait(
HANDLE hObjectToSignal, // handle to object to signal
HANDLE hObjectToWaitOn, // handle to object to wait for
DWORD dwMilliseconds, // time-out interval in milliseconds
BOOL bAlertable // alertable flag
);
Windows NT: If the handle is a semaphore, SEMAPHORE_MODIFY_STATE access is required. If the handle is an event, EVENT_MODIFY_STATE access is required. If the handle is a mutex, SYNCHRONIZE access is assumed, because only the owner of a mutex may release it. For more information, see Standard Access Rights.
A completion routine is queued when the ReadFileEx or WriteFileEx function in which it was specified has completed. The wait function returns and the completion routine is called only if bAlertable is TRUE, and the calling thread is the thread that initiated the read or write operation. An APC is queued when you call QueueUserAPC.
If the function succeeds, the return value indicates the event that caused the function to return. This value can be one of the following:
Value | Meaning |
---|---|
WAIT_ABANDONED | The specified object is a mutex object that was not released by the thread that owned the mutex object before the owning thread terminated. Ownership of the mutex object is granted to the calling thread, and the mutex is set to nonsignaled. |
WAIT_IO_COMPLETION | One or more I/O completion routines or user-mode APCs are queued for execution. |
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. |
If the function fails, the return value is 0xFFFFFFFF. To get extended error information, call GetLastError.
A completion routine is queued for execution when the ReadFileEx or WriteFileEx function in which it was specified has been completed. The wait function returns and the completion routine is executed only if bAlertable is TRUE, and the calling thread is the thread that initiated the read or write operation.
The SignalObjectAndWait function can wait for the following objects:
For more information, see Synchronization Objects.
Use caution when using 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. Two examples of code that indirectly creates windows are DDE and COM CoInitialize. Therefore, if you have a thread that creates windows, use MsgWaitForMultipleObjects or MsgWaitForMultipleObjectsEx, rather than SignalObjectAndWait.
Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winbase.h.
Import Library: Use kernel32.lib.
Synchronization Overview, Synchronization Functions, CancelWaitableTimer, CreateEvent, CreateMutex, CreateProcess, CreateThread, CreateRemoteThread, CreateSemaphore, CreateWaitableTimer, FindFirstChangeNotification, MsgWaitForMultipleObjects, MsgWaitForMultipleObjectsEx, OpenEvent, OpenMutex, OpenProcess, OpenSemaphore, OpenWaitableTimer, PulseEvent, QueueUserAPC, ReadFileEx, ResetEvent, SetEvent, SetWaitableTimer, WriteFileEx