WaitForMultipleObjects
La función WaitForMultipleObjects regresa cuando ocurre uno de los casos siguientes:
- O bien uno o todos los objetos especificados están en el estado señalado.
- Transcurre el intervalo de time-out.
Sintaxis
DWORD WaitForMultipleObjects(
DWORD nCount, // número de manipuladores en el array de manipuladores de objetos
CONST HANDLE *lpHandles, // puntero a un array de manipuladores de objetos
BOOL bWaitAll, // bandera de espera
DWORD dwMilliseconds // intervalo de time-out en milisegundos
);
Parámetros
- nCount
- Especifica el números de manipuladores de objetos en el array apuntado pro lpHandles. El número máximo de manipuladores de objetos es MAXIMUM_WAIT_OBJECTS.
- lpHandles
- Puntero a un array de manipuladores de objetos. Para ver una lista de tipos de objetos cuyos manipuladores
se pueden especificar, ver la sección de observaciones. El array puede contener manipuladores de objetos de
tipos diferentes.
Windows NT: Los manipuladores deben tener acceso SYNCHRONIZE. Para más información, ver Máscaras de Acceso y Derechos de Acceso. - bWaitAll
- Especifica el tipo de espera. Si es TRUE, la función regresa cuando el estado de todos los objetos en el array lpHandles está señalado. Si es FALSE, la función regresa cuando el estado de cualquiera de los objetos es a señalado. En el último caso, el valor de retorno indica el objeto cuyo estado ha hecho que ha hecho que la función retorne.
- dwMilliseconds
- Especifica el intervalo de time-out, en milisegundos. La función regresa si transcurre el intervalo, incluso si las condiciones especificadas por el parámetro bWaitAll no se cumplen. Si dwMilliseconds es cero, la función verifica los estados de los objetos especificados y regresa inmediatamente. Si dwMilliseconds es INFINITE, el intervalo de time-out de la función nunca se cumple.
Valor de retorno
Si la función tiene éxito, el valor de retorno indica el evento que ha provocado que la función regrese.
Si la función falla, el valor de retorno es WAIT_FAILED. Para obtener información adicional sobre el error, llamar a GetLastError.
El valor de retorno en caso de éxito es uno de los siguientes:
| Valor | Significado |
|---|---|
| WAIT_OBJECT_0 a (WAIT_OBJECT_0 + nCount - 1) | Si bWaitAll es TRUE, el valor de retorno indica que el estado de todos los objetos especificados es señalado. Si bWaitAll es FALSE, el valor de retorno menos WAIT_OBJECT_0 indica el índice del array lpHandles del objeto que ha satisfecho la espera. Si más de un objeto es señalado durante la llamada, este es el índice del array del objeto señalado con el valor de índice menor de todos los objetos señalados. |
| WAIT_ABANDONED_0 a (WAIT_ABANDONED_0 + nCount - 1) | Si bWaitAll es TRUE, el valor de retorno indica que el estado de todos los objetos especificados es señalado y al menos uno de los objetos es un objeto mutex abandonado. Si bWaitAll es FALSE, el valor de retorno menos WAIT_ABANDONED_0 indica el índice del array lpHandles de un objeto mutex abandonado que satisface la espera. |
| WAIT_TIMEOUT | El intervalo de time-out ha transcurrido y las condiciones especificadas por el parámetro bWaitAll no se han satisfecho. |
Observaciones
La función WaitForMultipleObjects determina si los criterios de espera se han cumplido. Si el criterio no se ha cumplido, el hilo que llama entra en un estado de espera eficiente, consumiendo muy poco tiempo de procesador mientras espera que los criterios se cumplan.
Cuando bWaitAll es TRUE, la operación de espera de la función se completa sólo cuando el estado de todos los objetos hayan sido señalados. La función no modifica los estados de los objetos especificados hasta que los estados de todos los objetos hayan sido asignados a señalado. Por ejemplo, un mutex puede estar señalado, pero el hilo no obtiene su propiedad hasta que los estados de los otros objetos hayan sido asignados a señalados también. En el intervalo, otros hilos pueden obtener la propiedad del mutex, y asignar su estado a no señalado.
Antes de retornar, una función de espera modifica el estado de algunos tipos de objetos de sincronización. La modificación se produce sólo para el objeto u objetos cuyo estado de señalización provoquen que la función retorne. Por ejemplo, el contador de un objeto semáforo se decrementa en uno.
La función WaitForMultipleObjects puede especificar manipuladores de cualquiera de los siguientes tipos de objeto en el array lpHandles:
| Objeto | Descripción |
|---|---|
| Notificación de cambio | La función FindFirstChangeNotification devuelve el manipulador. Se señala una notificación de cambio de estado de objeto cuando un tipo especificado de cambio se produce dentro de un directorio o árbol de direcorio especificado. |
| Entrada de consola | El manipulador es retornado por la función CreateFile cuando se especifica el valor CONIN$, o por la función GetStdHandle. El estado del objeto se señala cuando existe una entrada sin leer en el buffer de entrada de la consola, y está no señalado cuando el buffer de entrada está vacío. | Evento | La función CreateEvent o OpenEvent devuelve el manipulador. Un estado de objeto de evento se asigna explícitamente a señalado por la función SetEvent o PulseEvent. El estado de un objeto de evento de reset manual debe ser explícitamente reseteado a no señalado por la función ResetEvent. Para un objeto de evento auto-reset, la función de espera resetea el estado del objeto a no señalado antes de retornar. Los objetos de evento también se usan en operaciones overlapped, en cuyo caso el estado es asignado por el sistema. | Mutex | La función CreateMutex o OpenMutex devuelve el manipulador. El estado de un objeto mutex está señalado cuando no es propiedad de ningún hilo. La función de espera requiere la propiedad del mutex para el hilo que la llama, cambiando el estado del mutex a no señalado cunado la propiedad es otorgada. | Proceso | La función CreateProcess o OpenProcess devuelve el manipulador. El estado de un objeto proceso está señalado cuando el proceso termina. | Semáforo | La función CreateSemaphore o OpenSemaphore devuelve el manipulador. Un objeto semáforo mantiene un contador entre cero y algún valor máximo. Su estado está señalado cuando su contador es mayor que cero y no señalado cuando su contador es cero. Es el estado actual es señalado, la función de espera decrementa el contador en uno. | Hilo | La función CreateProcess, CreateThread o CreateRemoteThread devuelve el manipulador. El estado de un objeto hilo está señalado cuando el hilo termina. | Temporizador | La función CreateWaitableTimer o OpenWaitableTimer retorna el manipulador. El temporizador se activa mediante una llamada a la función SetWaitableTimer. El estado de un temporizador activo es señalado cuando alcanza su debido tiempo. Se puede desactivar el temporizador mediante una llamada a la función CancelWaitableTimer. |
En algunas circunstancias, se puede especificar un manipulador de un fichero, una tubería con nombre o un dispositivo de comunicaciones como un objeto de sincronización en lpHandles. Sin embargo, su uso para este propósito está desaconsejado.
Se debe ser cuidadoso cuando se usen funciones de espera y DDE. Si un hilo crea cualquier ventana, debe procesar mensajes. DDE envía mensajes a todas las ventanas en el sistema. Si se tiente un hilo que usa una función de espera sin intervalo de time-out, el sistema puede llegar a un punto muerto. De modo que, si se tiene un hilo que crea ventanas, se debe usar MsgWaitForMultipleObjects o MsgWaitForMultipleObjectsEx, en lugar de WaitForMultipleObjects.