WaitForSingleObject and WaitForMultipleObjects
Synchronization relies on one thread blocking until another thread has completed a task that uses some sort of shared resource. In Windows CE two blocking functions are commonly used:
WaitForSingleObject: Waits until a single kernel object becomes signaled, or a timeout occurs
WaitForMultipleObjects: Waits until one of several kernel objects becomes signaled, or a timeout occurs
Chapter 5 ("Processes and Threads") showed how WaitForSingleObject could be used to block until a thread or process terminates. However, WaitForSingleObject can also be used to block on a wide range of synchronization objects, such as mutexes, events, and semaphores.
| WaitForSingleObject | |
|---|---|
| HANDLE hHandle | Handle of kernel object to block on, for example, thread, process, mutex, event, or semaphore. |
| DWORD dwMilliseconds | Timeout value in milliseconds. The constant INFINITE specifies no timeout. |
| DWORD Return Value | WAIT_OBJECT_0 if the object is signaled. |
| WAIT_TIMEOUT if the wait timed out. | |
| WAIT_ABANDONED if a mutex object became abandoned (see section on mutex objects for abandoned mutex objects). | |
| WAIT_FAILED indicates failure, call GetLastError for detailed error information. |
WaitForSingleObject can be called with a "0" value for dwMilliseconds. In this case, the function does not block but returns WAIT_OBJECT_0 if the object is signaled, or WAIT_TIMEOUT if the object is not signaled. Calling the function in this way is used to determine if an object is signaled or non-signaled without blocking.
| WaitForMultipleObjects | |
|---|---|
| DWORD nCount | Number of kernel objects to wait on. |
| HANDLE *lpHandles | Array of kernel object handles to wait on. |
| BOOL fWaitAll | Must be FALSE. Windows CE does not support waiting on all object handles. |
| DWORD dwMilliseconds | Timeout value in milliseconds. The constant INFINITE specifies no timeout. |
| DWORD Return Value | WAIT_OBJECT_0 to (WAIT_OBJECT_0 + nCount −1) indicating which object in the lpHandles array became signaled. |
| WAIT_ABANDONED_0 to (WAIT_ABANDONED_0 + nCount −1) indicating which event object was abandoned. | |
| WAIT_TIMEOUT if the wait timed out. | |
| WAIT_FAILED indicates failure, call GetLastError for detailed error information. |
In Windows CE WaitForMultipleObjects will always return when the first kernel object becomes signaled, whereas in Windows NT/98/2000 WaitForMultipleObjects can be used to block until all the objects become signaled.
The array of object handles passed to WaitForMultipleObjects can include a mixture of different kernel objects, such as threads, processes, and so on. However, the same kernel object handle cannot appear more than once in the array.