Función WaitForMultipleObjects (synchapi.h)

Espera hasta que uno o todos los objetos especificados estén en estado señalado o el intervalo de tiempo de espera transcurrido.

Para especificar un estado de espera alertable, use la función WaitForMultipleObjectsEx.

Sintaxis

DWORD WaitForMultipleObjects(
  [in] DWORD        nCount,
  [in] const HANDLE *lpHandles,
  [in] BOOL         bWaitAll,
  [in] DWORD        dwMilliseconds
);

Parámetros

[in] nCount

Número de identificadores de objeto de la matriz a las que apunta lpHandles. El número máximo de identificadores de objeto es MAXIMUM_WAIT_OBJECTS. Este parámetro no puede ser cero.

[in] lpHandles

Matriz de identificadores de objeto. Para obtener una lista de los tipos de objeto cuyos identificadores se pueden especificar, vea la siguiente sección Comentarios. La matriz puede contener identificadores para objetos de distintos tipos. Puede que no contenga varias copias del mismo identificador.

Si se cierra uno de estos identificadores mientras la espera sigue pendiente, el comportamiento de la función no está definido.

Los identificadores deben tener el derecho de acceso SYNCHRONIZE. Para obtener más información, consulte Derechos de acceso estándar.

[in] bWaitAll

Si este parámetro es TRUE, la función devuelve cuando se señala el estado de todos los objetos de la matriz lpHandles. Si FALSE, la función devuelve cuando el estado de cualquiera de los objetos se establece en señalizado. En este último caso, el valor devuelto indica el objeto cuyo estado hizo que la función devolva.

[in] dwMilliseconds

Intervalo de tiempo de espera, en milisegundos. Si se especifica un valor distinto de cero, la función espera hasta que se señalen los objetos especificados o el intervalo transcurrido. Si dwMilliseconds es cero, la función no entra en un estado de espera si los objetos especificados no están señalados; siempre devuelve inmediatamente. Si dwMilliseconds es INFINITE, la función solo devolverá cuando se señalen los objetos especificados.

Windows XP, Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 y Windows Server 2008 R2: El dwMilliseconds valor incluye el tiempo invertido en estados de baja potencia. Por ejemplo, el tiempo de espera sigue contando mientras el equipo está dormido.

Windows 8 y versiones más recientes, Windows Server 2012 y versiones posteriores: El dwMilliseconds valor no incluye el tiempo invertido en estados de baja potencia. Por ejemplo, el tiempo de espera no sigue contando mientras el equipo está dormido.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto indica el evento que provocó que se devuelva la función. Puede ser uno de los siguientes valores. (Tenga en cuenta que WAIT_OBJECT_0 se define como 0 y WAIT_ABANDONED_0 se define como 0x00000080L).

Observaciones

La función waitForMultipleObjects determina si se han cumplido los criterios de espera. Si no se han cumplido los criterios, el subproceso de llamada entra en el estado de espera hasta que se cumplen las condiciones de los criterios de espera o el intervalo de tiempo de espera transcurrido.

Cuando bWaitAll es TRUE, la operación de espera de la función solo se completa cuando los estados de todos los objetos se han establecido en señalizado. La función no modifica los estados de los objetos especificados hasta que los estados de todos los objetos se han establecido en señalizado. Por ejemplo, se puede señalar una exclusión mutua, pero el subproceso no obtiene la propiedad hasta que los estados de los otros objetos también se establecen en señalizado. Mientras tanto, algún otro subproceso puede obtener la propiedad de la exclusión mutua, estableciendo así su estado en no asignado.

Cuando bWaitAll es FALSE, esta función comprueba los identificadores de la matriz en orden a partir del índice 0, hasta que se señale uno de los objetos. Si se señalizan varios objetos, la función devuelve el índice del primer identificador de la matriz cuyo objeto se señalizó.

La función modifica el estado de algunos tipos de objetos de sincronización. La modificación solo se produce para el objeto o los objetos cuyo estado señalado hizo que la función devolva. Por ejemplo, el recuento de un objeto de semáforo se reduce en uno. Para obtener más información, consulte la documentación de los objetos de sincronización individuales.

Para esperar más de MAXIMUM_WAIT_OBJECTS identificadores, use uno de los métodos siguientes:

• Cree un subproceso para esperar a MAXIMUM_WAIT_OBJECTS identificadores y, a continuación, espere en ese subproceso más los demás identificadores. Use esta técnica para dividir los identificadores en grupos de MAXIMUM_WAIT_OBJECTS.
• Llame a RegisterWaitForSingleObject o SetThreadpoolWait para esperar en cada identificador. El grupo de subprocesos espera eficazmente en los identificadores y asigna un subproceso de trabajo después de que el objeto se señale o expire el intervalo de tiempo de espera.