Windows Programming-waiting for Functions

Two wait functions are a single thread and multiple threads.

The waiting function enables the thread to voluntarily enter the waiting state until a specific kernel object changes to the notified State. (FangSH Note: If the kernel object does not change to a notification, the thread will wait forever .) The most common of these wait functions isWaitForSingleObject:

 DWORD WaitForSingleObject(HANDLEhObject,
  DWORD dwMilliseconds);

 

First ParameterHObjecT identifies a kernel object that can be notified/not notified (any of the objects listed earlier applies ). (FangSH Note: handle)

Second ParameterDwMillisecondsSpecifies the status of the waiting object to be notifiedWait time. (The interval is measured in milliseconds. INFINITE indicates that the hHandle status is notified until it is hHandle ). It is dangerous to pass INFINITE. If the object never changes to the notified State, the calling thread will never be awakened and it will always be in the Deadlock State. However, it will not waste valuable CPU time.

The following example shows how to use a timeout value instead of INFINITE to call WaitForSingleObject:

 DWORD dw = WaitForSingleObject(hProcess,5000);
switch(dw)
{
case WAIT_OBJECT_0:
// The process terminated.
     break;

case WAIT_TIMEOUT:
// The process did not terminate within 5000 milliseconds.
     break;

case WAIT_FAILED:
// Bad call to function (invalid handle?)
     break;
}

 

The code above tells the system that the calling thread should not change to a schedulable State before a specific process is terminated or before the end of Ms. Therefore, if the process terminates, the function call will return within Ms. If the process has not terminated, it will return within about Ms. Note: Do not pass 0 for d wMillisecond. If 0 is passed, the WaitForSingleObject function will always return immediately.

 

The return value of WaitForSingleObject can indicate why the call thread becomes schedulable again..

The returned value isWAIT_OBJECT_0.

If the set timeout has expired, the returned value isWa I T _ TIMEOUT.

If an error value (such as an invalid handle) is passed to Wa itForSingleObject, the returned value isWA IT_FAILED(For more information, call GetLastError ).

 

WaitForMultipleObjectsCall the thread to view the notified status of several kernel objects at the same time:

 DWORD WaitForMultipleObjects(DWORDdwCount,
  CONST HANDLE* phObjects,
  BOOL fWaitAll,
  DWORD dwMilliseconds);

 

DwCountThe parameter specifies the kernel object that you want the function to view.Quantity. This value must be 1 and MAXIMUM _ wa I T_OBJECTS (defined64.

PhObjectsThe parameter is the pointer to the array of the kernel object handle.

 

The WaitForMultipleObjects function can be used in two different ways..

One wayIs to let the thread enter the waiting state until the specified Kernel ObjectAnyChanged to notified status.

Another methodIs to let the thread enter the waiting statusAll specifiedThe kernel objects of are changed to the notified status.

 

FWaitAllThe parameter tells the function how you want it to be used. If this parameter is passedTRUEBefore all objects are notified, this function will not allow the calling thread to run.

DwMillisecondsThe function of a parameter is identical to that of WaitForSingleObject. If the specified time is reached while waiting, the function will return at any time. Similarly, INFINITE is usually passed for this parameter, but be careful when writing the code to avoid deadlocks.

 

The Return Value of the WaitForSingleObject function tells the calling thread why it is rescheduled.

The possible return values are WA IT_FAILED and WAIT_TIMEOUT. The functions of these two values are clear.

 

If the fWaitAll parameter is setTRUEAnd all objects are in the notified State. The returned value is WAIT_OBJECT_0.

If fWaitAll is passedFA LSEIf any object changes to the notified State, this function returns.

In this case, you may want to know which object has changed to the notified State. The returned value is a value between WAIT_OBJECT_0 and (WA IT_OBJECT_0 + dwCount-1.

In other words, if the returned value is not WA IT_TIMEOUT or WAIT_FA ILED, WAIT_OBJECT_0 should be subtracted from the returned value. The resulting number is the index in the handle array passed to WaitForMultipleObjects as the second parameter. This index indicates which object has changed to the notified status. The following is some sample code to illustrate this situation:

 HANDLE h[3];
h[0] = hProcess1;
h[1] = hProcess2;
h[2] = hProcess3;
DWORD dw = WaitForMultipleObjects(3,h, FALSE, 5000);
switch(dw)
{
case WAIT_FAILED:
// Bad call to function (invalid handle?)
     break;

case WAIT_TIMEOUT:
// None of the objects became signaled within 5000 milliseconds.
     break;

case WAIT_OBJECT_0 + 0:
// The process identified by h[0] (hProcess1) terminated.
     break;

case WAIT_OBJECT_0 + 1:
// The process identified by h[1] (hProcess2) terminated.
     break;

case WAIT_OBJECT_0 + 2:
// The process identified by h[2] (hProcess3) terminated.
     break;
}

 

If the fWaitAll parameter is passed with the fa lse, WaitForSingleObjects scans the handle array from index 0 and the first notified object ends the waiting state. This may produce some results that you don't want. For example, by passing three process handles to the function, your thread will wait for the three sub-processes to terminate. If the process with the index 0 in the array stops running, WaitForSingleObject will return. At this time, the thread can do anything it needs, and then loop repeatedly, waiting for another process to stop running. If the thread passes the same three handles, the function immediately returns WAIT_OBJECT_0 again. The Code cannot run correctly unless you delete the handle that has received the notification.

 

 

FangSH 2010-12-29