Returns when the specified object is signaled or timeout occurs.
[ enWait = ] WaitForSingleObject ( hObject [,lTimeout] )
The WaitForSingleObject property syntax has the following parts:
|
Name |
Type |
Description |
|
enWait |
Val enumAWaitForReturn |
A number specifying the event that caused the function to return. |
|
hObject |
Val AHandle |
Handle of the object to wait for. |
|
lTimeout |
[Val] Long |
The time-out interval in milliseconds. This is optional. The default is -1 (infinite); that is, the function's time-out interval never elapses. See below also. See below also. |
enumAWaitForReturn can be one of the following values:
|
Name |
Value |
Description |
|
awaitFailed |
-1 |
The function failed. |
|
awaitObject0 |
0 |
The state of the specified object is signaled. |
|
awaitAbandoned0 |
0x80 (128) |
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. |
|
awaitTimeout |
0x102 (258) |
The time-out interval elapsed and the object's state is nonsignaled. |
The WaitForSingleObject function returns when one of the following occurs:
The specified object is in the signaled state.
The time-out interval elapses.
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.
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 states of the objects not selected are unaffected.
The WaitForSingleObject function can specify handles of any of the following objects:
Event
Mutex
Semaphore
Thread
Other Windows handles may be used such as: Change notification, Console input, Job, Process, Timer-queue timer or Waitable timer.
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.
Waiting on an invalid handle causes WaitForSingleObject to return waitFailed.
The lTimeOut default value is -1, infinite time-out. The function returns if the interval elapses, even if the object's state is nonsignaled. If lTimeout is zero, the function tests the object's state and returns immediately. If lTimeout is -1 (infinite), the function's time-out interval never elapses.
The following statement will return when the semaphore handle object is signaled or 700 milliseconds elapses first:
if WaitForSingleObject(sem.Handle, 700)=awaitObject0
print "thread terminated"
endif
AEvent, AMutex, ASemaphore, CreateThread, WaitForMultipleObjects, WaitForEvent