ÿþ<html> <head> <meta http-equiv="Content-Type" content="text/html; charset=unicode" /> <meta http-equiv="Content-Language" content="en-us" /> <style> <!-- p.MsoNormal, li.MsoNormal {margin-top:0mm; margin-right:0mm; margin-bottom:10.0pt; margin-left:0mm; line-height:115%; font-size:12.0pt; font-family:"Times New Roman","serif";} a:link {color:blue; text-decoration:underline;} a:visited {color:purple; text-decoration:underline;} p {margin-right:0mm; margin-left:0mm; font-size:12.0pt; font-family:"Times New Roman","serif";} ol {margin-bottom:0mm;} --> </style> <title>The Windows thread synchronization tutorial: the wait functions, single-object, multiple-object, alertable, registered wait functions etc</title> <meta name="keywords" content="Windows system, system programming, processors time, performance, benchmarking, tutorials, tech, utility, tools, services" /> <meta name="description" content="The win32 thread synchronization programming - various wait functions for thread synchronization" /> </head> <body lang="EN-US" link="#0000FF" vlink="#800080" topmargin="20" leftmargin="20" rightmargin="20" bottommargin="20"> <div class="Section1"> <h3 align="center" style="margin-bottom:0mm;margin-bottom:0; text-align:center; margin-top:0"><font size="5" face="Byington"> <span style="line-height:115%;font-weight:400">Windows Thread Synchronization 3</span></font></h3> <p class="MsoNormal" style="margin-bottom:0mm;margin-bottom:0; margin-top:0">&nbsp;</p> <p class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt">&nbsp;</p> <p class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt" align="center"> <script type="text/javascript"><!-- google_ad_client = "pub-8089415323104206"; google_ad_slot = "0761177910"; google_ad_width = 728; google_ad_height = 90; //--> </script> &nbsp;<script type="text/javascript" src="http://pagead2.googlesyndication.com/pagead/show_ads.js"> </script></p> <p class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt">&nbsp;</p> <p class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt">&nbsp;</p> <p class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"><b> <font size="3" face="Arial"> <span style="font-size:12.0pt;line-height:115%; font-weight:bold">Wait Functions</span></font></b></p> <p class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"> <font size="3" face="Arial"><span style="font-size:12.0pt;line-height:115%">&nbsp;</span></font></p> <p class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"> <font size="3" face="Arial"><span style="font-size:12.0pt;line-height:115%"> The wait functions allow a thread <b><span style="font-weight:bold">to block its own execution</span></b>. The wait functions do not return until the specified criteria have been met. The type of wait function determines the set of criteria used. When a wait function is called, it checks whether the wait criteria have been met. If the criteria have not been met, the calling thread enters the <b><span style="font-weight:bold">wait state</span></b> until the conditions of the wait criteria have been met or the specified time-out interval elapses. There are four types of wait functions:</span></font></p> <p class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"> <font size="3" face="Arial"><span style="font-size:12.0pt;line-height:115%">&nbsp;</span></font></p> <ol style="margin-top:0mm" start="1" type="1"> <li class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"> <font size="3" face="Arial"> <span style="font-size:12.0pt;line-height: 115%">single-object</span></font></li> <li class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"> <font size="3" face="Arial"> <span style="font-size:12.0pt;line-height: 115%">multiple-object</span></font></li> <li class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"> <font size="3" face="Arial"> <span style="font-size:12.0pt;line-height: 115%">alertable</span></font></li> <li class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"> <font size="3" face="Arial"> <span style="font-size:12.0pt;line-height: 115%">registered</span></font></li> </ol> <p class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"> <font size="3" face="Arial"><span style="font-size:12.0pt;line-height:115%">&nbsp;</span></font></p> <p class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"><b> <font size="3" face="Arial"> <span style="font-size:12.0pt;line-height:115%; font-weight:bold">Single-object Wait Functions</span></font></b></p> <p class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"> <font size="3" face="Arial"><span style="font-size:12.0pt;line-height:115%">&nbsp;</span></font></p> <p class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"> <font size="3" face="Arial"><span style="font-size:12.0pt;line-height:115%"> The SignalObjectAndWait(), WaitForSingleObject(), and WaitForSingleObjectEx() functions require a handle to one synchronization object. These functions return when one of the following occurs:</span></font></p> <p class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"> <font size="3" face="Arial"><span style="font-size:12.0pt;line-height:115%">&nbsp;</span></font></p> <ol style="margin-top:0mm" start="1" type="1"> <li class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"> <font size="3" face="Arial"> <span style="font-size:12.0pt;line-height: 115%">The specified object is in the signaled state.</span></font></li> <li class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"> <font size="3" face="Arial"> <span style="font-size:12.0pt;line-height: 115%">The time-out interval elapses. The time-out interval can be set to INFINITE to specify that the wait will not time out.</span></font></li> </ol> <p class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"> <font size="3" face="Arial"><span style="font-size:12.0pt;line-height:115%">&nbsp;</span></font></p> <p class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"> <font size="3" face="Arial"><span style="font-size:12.0pt;line-height:115%"> The SignalObjectAndWait() function enables the calling thread to atomically (atomic operation - an operation that can&#39;t be interrupted is called) set the state of an object to signaled and wait for the state of another object to be set to signaled.</span></font></p> <p class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"> <font size="3" face="Arial"><span style="font-size:12.0pt;line-height:115%">&nbsp;</span></font></p> <p class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"><b> <font size="3" face="Arial"> <span style="font-size:12.0pt;line-height:115%; font-weight:bold">Multiple-object Wait Functions</span></font></b></p> <p class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"> <font size="3" face="Arial"><span style="font-size:12.0pt;line-height:115%">&nbsp;</span></font></p> <p class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"> <font size="3" face="Arial"><span style="font-size:12.0pt;line-height:115%"> The WaitForMultipleObjects(), WaitForMultipleObjectsEx(), MsgWaitForMultipleObjects(), and MsgWaitForMultipleObjectsEx() functions enable the calling thread to specify an array containing one or more synchronization object handles. These functions return when one of the following occurs:</span></font></p> <p class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"> <font size="3" face="Arial"><span style="font-size:12.0pt;line-height:115%">&nbsp;</span></font></p> <ol style="margin-top:0mm" start="1" type="1"> <li class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"> <font size="3" face="Arial"> <span style="font-size:12.0pt;line-height: 115%">The state of any one of the specified objects is set to signaled or the states of all objects have been set to signaled. You control whether one or all of the states will be used in the function call.</span></font></li> <li class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"> <font size="3" face="Arial"> <span style="font-size:12.0pt;line-height: 115%">The time-out interval elapses. The time-out interval can be set to INFINITE to specify that the wait will not time out.</span></font></li> </ol> <p class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"> <font size="3" face="Arial"><span style="font-size:12.0pt;line-height:115%">&nbsp;</span></font></p> <p class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"> <font size="3" face="Arial"><span style="font-size:12.0pt;line-height:115%"> The MsgWaitForMultipleObjects() and MsgWaitForMultipleObjectsEx() function allow you to specify input event objects in the object handle array. This is done when you specify the type of input to wait for in the thread&#39;s input queue. For example, a thread could use MsgWaitForMultipleObjects() to block its execution until the state of a specified object has been set to signaled and there is mouse input available in the thread&#39;s input queue. The thread can use the GetMessage() or PeekMessage() function to retrieve the input. When waiting for the states of all objects to be set to signaled, these multiple-object functions do not modify the states of the specified objects until the states of all objects have been set signaled. For example, the state of a mutex object can be signaled, but the calling thread does not get ownership until the states of the other objects specified in the array have also been set to signaled. In the meantime, some other thread may get ownership of the mutex object, thereby setting its state to nonsignaled. When waiting for the state of a single object to be set to signaled, these multiple-object functions check the handles in the array in order starting with index 0, until one of the objects is signaled. If multiple objects become signaled, the function returns the index of the first handle in the array whose object was signaled.</span></font></p> <p class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"> <font size="3" face="Arial"><span style="font-size:12.0pt;line-height:115%">&nbsp;</span></font></p> <p class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"><b> <font size="3" face="Arial"> <span style="font-size:12.0pt;line-height:115%; font-weight:bold">Alertable Wait Functions</span></font></b></p> <p class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"> <font size="3" face="Arial"><span style="font-size:12.0pt;line-height:115%">&nbsp;</span></font></p> <p class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"> <font size="3" face="Arial"><span style="font-size:12.0pt;line-height:115%"> The MsgWaitForMultipleObjectsEx(), SignalObjectAndWait(), WaitForMultipleObjectsEx(), and WaitForSingleObjectEx() functions differ from the other wait functions in that they can optionally perform an <b><span style="font-weight:bold">alertable wait operation</span></b>. In an alertable wait operation, the function can return when the specified conditions are met, but it can also return if the system queues an I/O completion routine or an APC for execution by the waiting thread.</span></font></p> <p class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"> <font size="3" face="Arial"><span style="font-size:12.0pt;line-height:115%">&nbsp;</span></font></p> <p class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"><b> <font size="3" face="Arial"> <span style="font-size:12.0pt;line-height:115%; font-weight:bold">Registered Wait Functions</span></font></b></p> <p class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"> <font size="3" face="Arial"><span style="font-size:12.0pt;line-height:115%">&nbsp;</span></font></p> <p class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"> <font size="3" face="Arial"><span style="font-size:12.0pt;line-height:115%"> The RegisterWaitForSingleObject() function differs from the other wait functions in that the wait operation is performed by a thread from the thread pool. When the specified conditions are met, the callback function is executed by a worker thread from the thread pool. By default, a registered wait operation is a multiple-wait operation. The system resets the timer every time the event is signaled (or the time-out interval elapses) until you call the UnregisterWaitEx() function to cancel the operation. To specify that a wait operation should be executed only once, set the dwFlags parameter of RegisterWaitForSingleObject() to WT_EXECUTEONLYONCE.</span></font></p> <p class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"> <font size="3" face="Arial"><span style="font-size:12.0pt;line-height:115%">&nbsp;</span></font></p> <p class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"><b> <font size="3" face="Arial"> <span style="font-size:12.0pt;line-height:115%; font-weight:bold">Wait Functions and Time-out Intervals</span></font></b></p> <p class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"> <font size="3" face="Arial"><span style="font-size:12.0pt;line-height:115%">&nbsp;</span></font></p> <p class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"> <font size="3" face="Arial"><span style="font-size:12.0pt;line-height:115%"> The accuracy of the specified time-out interval depends on the resolution of the system clock. The system clock &quot;ticks&quot; at a constant rate. If the time-out interval is less than the resolution of the system clock, the wait may time out in less than the specified length of time. If the time-out interval is greater than one tick but less than two, the wait can be anywhere between one and two ticks, and so on. To increase the accuracy of the time-out interval for the wait functions, call the timeGetDevCaps() function to determine the supported minimum timer resolution and the timeBeginPeriod() function to set the timer resolution to its minimum. Use caution when calling timeBeginPeriod(), as frequent calls can significantly affect the system clock, system power usage, and the scheduler. If you call timeBeginPeriod(), call it one time early in the application and be sure to call the timeEndPeriod() function at the very end of the application.</span></font></p> <p class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"> <font size="3" face="Arial"><span style="font-size:12.0pt;line-height:115%">&nbsp;</span></font></p> <p class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"><b> <font size="3" face="Arial"> <span style="font-size:12.0pt;line-height:115%; font-weight:bold">Wait Functions and Synchronization Objects</span></font></b></p> <p class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"> <font size="3" face="Arial"><span style="font-size:12.0pt;line-height:115%">&nbsp;</span></font></p> <p class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"> <font size="3" face="Arial"><span style="font-size:12.0pt;line-height:115%"> The wait functions can modify the states of some types of synchronization objects. Modification occurs only for the object or objects whose signaled state caused the function to return. Wait functions can modify the states of synchronization objects as follows:</span></font></p> <p class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"> <font size="3" face="Arial"><span style="font-size:12.0pt;line-height:115%">&nbsp;</span></font></p> <ol style="margin-top:0mm" start="1" type="1"> <li class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"> <font size="3" face="Arial"> <span style="font-size:12.0pt;line-height: 115%">The count of a semaphore object decreases by one, and the state of the semaphore is set to nonsignaled if its count is zero.</span></font></li> <li class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"> <font size="3" face="Arial"> <span style="font-size:12.0pt;line-height: 115%">The states of mutex, auto-reset event, and change-notification objects are set to nonsignaled.</span></font></li> <li class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"> <font size="3" face="Arial"> <span style="font-size:12.0pt;line-height: 115%">The state of a synchronization timer is set to nonsignaled.</span></font></li> <li class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"> <font size="3" face="Arial"> <span style="font-size:12.0pt;line-height: 115%">The states of manual-reset event, manual-reset timer, process, thread, and console input objects are not affected by a wait function.</span></font></li> </ol> <p class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"> <font size="3" face="Arial"><span style="font-size:12.0pt;line-height:115%">&nbsp;</span></font></p> <p class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"><b> <font size="3" face="Arial"> <span style="font-size:12.0pt;line-height:115%; font-weight:bold">Wait Functions and Creating Windows</span></font></b></p> <p class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"> <font size="3" face="Arial"><span style="font-size:12.0pt;line-height:115%">&nbsp;</span></font></p> <p class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt"> <font size="3" face="Arial"><span style="font-size:12.0pt;line-height:115%"> You have to be careful 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. If you have a thread that uses a wait function with no time-out interval, the system will <b><span style="font-weight:bold">deadlock</span></b>. Two examples of code that indirectly creates windows are DDE and the CoInitialize() function. Therefore, if you have a thread that creates windows, use MsgWaitForMultipleObjects() or MsgWaitForMultipleObjectsEx(), rather than the other wait functions.</span></font></p> <p class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt">&nbsp;</p> <p class="MsoNormal" style="margin-bottom:0mm;margin-bottom:.0001pt">&nbsp;</p> <h3 align="center" style="margin-top: 0; margin-bottom: 0"> <script type="text/javascript"><!-- google_ad_client = "pub-8089415323104206"; google_ad_slot = "2156170134"; google_ad_width = 728; google_ad_height = 15; //--> </script> &nbsp;<script type="text/javascript" src="http://pagead2.googlesyndication.com/pagead/show_ads.js"> </script></h3> <p align="center" style="margin-top: 0; margin-bottom: 0">&nbsp;</p> <h3 align="center" style="margin-top: 0; margin-bottom: 0"> <font face="Byington"><span style="font-weight: 400">&lt; <a title="A Windows process and thread tutorial: atomicity and thread states" style="color: blue; text-decoration: underline" href="threadprocesssynchronizationapis11_1.html"> Thread Synchronization 2</a> | <a title="The Windows Win32 thread synchronization techniques programming tutorials with program examples and code samples" style="color: blue; text-decoration: underline" href="threadprocesssynchronizationapis11index.html"> Thread Synchronization Programming</a> | <a title="The Win32 programming tutorial using Visual Studio, C and C++ languages" style="color: blue; text-decoration: underline" href="index.html"> Win32 Programming</a> | <a title="The Windows process and thread synchronization tutorial: Event synchronization objects" style="color: blue; text-decoration: underline" href="threadprocesssynchronizationapis11_3.html"> Thread Synchronization 4</a> &gt;</span></font></h3> <p align="left" style="margin-top: 0; margin-bottom: 0">&nbsp;</p> <div align="center"> <script src="http://tag.contextweb.com/TagPublish/getjs.aspx?action=VIEWAD&cwrun=200&cwadformat=728X90&cwpid=527221&cwwidth=728&cwheight=90&cwpnet=1&cwtagid=82740"></script> </div> </div> </body> </html>