WaitForSingleObject函数用法

 

  等待函数可使线程自愿进入等待状态，直到一个特定的内核对象变为已通知状态为止。这些等待函数中最常用的是WaitForSingleObject:

  DWORD WaitForSingleObject(HANDLE hObject, DWORD dwMilliseconds);

当线程调用该函数时，第一个参数hObject标识一个能够支持被通知/未通知的内核对象。第二个参数dwMilliseconds.允许该线程指明，为了等待该对象变为已通知状态，它将等待多长时间。调用下面这个函数将告诉系统，调用函数准备等待到h P r o c e s s句柄标识的进程终止运行为止：

 

WaitForSingleObject(hProcess, INFINITE);

第二个参数告诉系统，调用线程愿意永远等待下去（无限时间量），直到该进程终止运行。

通常情况下， I N F I N I T E是作为第二个参数传递给Wa i t F o r S i n g l e O b j e c t的，不过也可以传递任何一个值（以毫秒计算）。顺便说一下， I N F I N I T E已经定义为0 x F F F F F F F F（或-1）。当然，传递I N F I N I T E有些危险。如果对象永远不变为已通知状态，那么调用线程永远不会被唤醒，它将永远处于死锁状态，

不过，它不会浪费宝贵的C P U时间。

下面是如何用一个超时值而不是I N F I N I T E来调用Wa i t F o r S i n g l e O b j e c t的例子：

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;

}

上面这个代码告诉系统，在特定的进程终止运行之前，或者在5 0 0 0 m s时间结束之前，调用线程不应该变为可调度状态。因此，如果进程终止运行，那么这个

 

函数调用将在不到5 0 0 0 m s的时间内返回，如果进程尚未终止运行，那么它在大约5 0 0 0 m s时间内返回。注意，不能为d w M i l l i s e c o n d传递0。如果传递了0

 

，Wa i t F o r S i n g l e O b j e c t函数将总是立即返回。

Wa i t F o r S i n g l e O b j e c t的返回值能够指明调用线程为什么再次变为可调度状态。如果线程等待的对象变为已通知状态，那么返回值是WA I T _ O B J E C T _ 0

 

。如果设置的超时已经到期，则返回值是WA I T _ T I M E O U T。如果将一个错误的值（如一个无效句柄）传递给Wa i t F o r S i n g l eO b j e c t，那么返回值将是WA I 

 

T _ FA I L E D（若要了解详细信息，可调用G e t L a s t E r r o r）。

 

下面这个函数Wa i t F o r M u l t i p l e O b j e c t s与Wa i t F o r S i n g l e O b j e c t函数很相似，区别在于它允许调用线程同时查看若干个内核对象的已通知状态：

 

 

DWORD WaitForMultipleObjects(DWORD dwCount,

   CONST HANDLE* phObjects, 

   BOOL fWaitAll, 

   DWORD dwMilliseconds);

d w C o u n t参数用于指明想要让函数查看的内核对象的数量。这个值必须在1与M A X I M U M _WA I T _ O B J E C T S（在Wi n d o w s头文件中定义为6 4）之间。p h O 

 

b j e c t s参数是指向内核对象句柄的数组的指针。

可以以两种不同的方式来使用Wa i t F o r M u l t i p l e O b j e c t s函数。一种方式是让线程进入等待状态，直到指定内核对象中的任何一个变为已通知状态。另一种

 

方式是让线程进入等待状态，直到所有指定的内核对象都变为已通知状态。f Wa i tAl l参数告诉该函数，你想要让它使用何种方式。如果为该参数传递T R U E，那

 

么在所有对象变为已通知状态之前，该函数将不允许调用线程运行。

 

d w M i l l i s e c o n d s参数的作用与它在Wa i t F o r S i n g l e O b j e c t中的作用完全相同。如果在等待的时候规定的时间到了，那么该函数无论如何都会返回。同样

 

，通常为该参数传递I N F I N I T E，但是在编写代码时应该小心，以避免出现死锁情况。

 

Wa i t F o r M u l t i p l e O b j e c t s函数的返回值告诉调用线程，为什么它会被重新调度。可能的返回值是WA I T _ FA I L E D和WA I T _ T I M E O U T，这两个值的作用

 

是很清楚的。如果为f Wa i tAl l参数传递T R U E，同时所有对象均变为已通知状态，那么返回值是WA I T _ O B J E C T _ 0。如果为f Wa i t A l l传递FA L S E，那么一旦

 

任何一个对象变为已通知状态，该函数便返回。在这种情况下，你可能想要知道哪个对象变为已通知状态。返回值是WA I T _ O B J E C T _ 0与（WA I T _ O B J E C 

 

T _ 0 + d w C o u n t - 1）之间的一个值。换句话说，如果返回值不是WA I T _ T I M E O U T，也不是WA I T _ FA I L E D，那么应该从返回值中减去WA I T _ O B J E C T _ 0

 

。产生的数字是作为第二个参数传递给Wa i t F o r M u l t i p l e O b j e c t s的句柄数组中的索引。该索引说明哪个对象变为已通知状态。下面是说明这一情况的一些

 

示例代码：

 

 

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;

}

 

如果为f Wa i t A l l参数传递FA L S E，Wa i t F o r M u l t i p l e O b j e c t s就从索引0开始向上对句柄数组进行扫描，同时已通知的第一个对象终止等待状态。这可能产

 

生一些你不希望有的结果。例如，通过将3个进程句柄传递给该函数，你的线程就会等待3个子进程终止运行。如果数组中索引为0的进程终止运行，Wa i t F o r M 

 

u l t i p l e O b j e c t s就会返回。这时该线程就可以做它需要的任何事情，然后循环反复，等待另一个进程终止运行。如果该线程传递相同的3个句柄，该函数立即

 

再次返回WA I T _ O B J E C T _ 0。除非删除已经收到通知的句柄，否则代码就无法正确地运行。