Función WaitForMultipleObjectsEx (synchapi.h)

  • Artículo

Espera hasta que uno o todos los objetos especificados estén en el estado señalado, una rutina de finalización de E/S o una llamada de procedimiento asincrónico (APC) se pone en cola en el subproceso o el intervalo de tiempo de espera transcurrido.

Sintaxis

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

Parámetros

[in] nCount

Número de identificadores de objeto que se van a esperar en la matriz a la 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 de objetos de diferentes 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 el estado de todos los objetos de la matriz lpHandles se establece en señalizado. Si es FALSE, la función devuelve cuando el estado de cualquiera de los objetos se establece en señalizado. En el último caso, el valor devuelto indica el objeto cuyo estado hizo que la función devolva.

[in] dwMilliseconds

El intervalo de tiempo de espera en milisegundos. Si se especifica un valor distinto de cero, la función espera hasta que se señalizan los objetos especificados, se pone en cola una rutina de finalización de E/S o APC, o el intervalo transcurre. Si dwMilliseconds es cero, la función no especifica un estado de espera si no se cumplen los criterios; siempre devuelve inmediatamente. Si dwMilliseconds es INFINITE, la función solo devolverá cuando se señalen los objetos especificados o se pone en cola una rutina de finalización de E/S o APC.

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

Windows 8, Windows Server 2012, Windows 8.1, Windows Server 2012 R2, Windows 10 y Windows Server 2016: El valor dwMilliseconds no incluye el tiempo invertido en estados de bajo consumo. Por ejemplo, el tiempo de espera no sigue contando mientras el equipo está suspendido.

[in] bAlertable

Si este parámetro es TRUE y el subproceso está en estado de espera, la función devuelve cuando el sistema pone en cola una rutina de finalización de E/S o APC, y el subproceso ejecuta la rutina o función. De lo contrario, la función no devuelve y no se ejecuta la rutina de finalización ni la función APC.

Una rutina de finalización se pone en cola cuando se ha completado la función ReadFileEx o WriteFileEx en la que se especificó. La función wait devuelve y solo se llama a la rutina de finalización si bAlertable es TRUE y el subproceso que realiza la llamada es el subproceso que inició la operación de lectura o escritura. Una instancia de APC se pone en cola cuando se llama a QueueUserAPC.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto indica el evento que provocó que la función se devolva. 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 0x000000080L).

Código o valor devuelto Descripción
WAIT_OBJECT_0 a (WAIT_OBJECT_0 + nCount– 1)
 Si bWaitAll es TRUE, un valor devuelto en este intervalo indica que se señala el estado de todos los objetos especificados.

Si bWaitAll es FALSE, el valor devuelto menos WAIT_OBJECT_0 indica el índice de matriz lpHandles del objeto que cumplió la espera. Si se señala más de un objeto durante la llamada, este es el índice de matriz del objeto señalado con el valor de índice más pequeño de todos los objetos señalados.
WAIT_ABANDONED_0 a (WAIT_ABANDONED_0 + nCount– 1)
 Si bWaitAll es TRUE, un valor devuelto en este intervalo indica que se señala el estado de todos los objetos especificados y al menos uno de los objetos es un objeto de exclusión mutua abandonado.

Si bWaitAll es FALSE, el valor devuelto menos WAIT_ABANDONED_0 indica el índice de la matriz lpHandles de un objeto de exclusión mutua abandonado que cumplió la espera. La propiedad del objeto de exclusión mutua se concede al subproceso que realiza la llamada y la exclusión mutua se establece en sin signo.

Si una exclusión mutua protegía la información de estado persistente, debe comprobar si hay coherencia.
WAIT_IO_COMPLETION
0x000000C0L
 La espera finalizó con una o varias llamadas de procedimiento asincrónico en modo de usuario (APC) en cola al subproceso.
WAIT_TIMEOUT
0x00000102L
 El intervalo de tiempo de espera transcurrido, no se cumplen las condiciones especificadas por el parámetro bWaitAll y no se ponen en cola rutinas de finalización.
WAIT_FAILED
(DWORD)0xFFFFFFFF
 Error en la función. Para obtener información de error extendida, llame a GetLastError.

Comentarios

La función WaitForMultipleObjectsEx determina si se han cumplido los criterios de espera. Si no se han cumplido los criterios, el subproceso que realiza la llamada entra en estado de espera hasta que se cumplan 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 demás 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 sin signo.

Cuando bWaitAll es FALSE, esta función comprueba los identificadores de la matriz en orden a partir del índice 0, hasta que se señala a 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 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 en 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.
La función WaitForMultipleObjectsEx puede especificar identificadores de cualquiera de los siguientes tipos de objeto en la matriz lpHandles :
  • Notificación de cambio
  • Entrada de consola
  • Evento
  • Notificación de recursos de memoria
  • Mutex
  • Proceso
  • Semaphore
  • Thread
  • Temporizador que se puede esperar
Tenga cuidado al llamar a las funciones de espera y el código que crea ventanas directa o indirectamente. Si un subproceso crea ventanas, debe procesar mensajes. Las difusión de mensajes se envían a todas las ventanas del sistema. Un subproceso que usa una función de espera sin intervalo de tiempo de espera puede hacer que el sistema se interbloquee. Dos ejemplos de código que crea indirectamente ventanas son DDE y la función CoInitialize . Por lo tanto, si tiene un subproceso que crea ventanas, use MsgWaitForMultipleObjects o MsgWaitForMultipleObjectsEx, en lugar de WaitForMultipleObjectsEx.

Requisitos

Requisito Value
Cliente mínimo compatible Windows XP [aplicaciones de escritorio | aplicaciones para UWP]
Servidor mínimo compatible Windows Server 2003 [aplicaciones de escritorio | aplicaciones para UWP]
Plataforma de destino Windows
Encabezado synchapi.h (incluye Windows.h en Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
Library Kernel32.lib
Archivo DLL Kernel32.dll

Vea también

Funciones de sincronización

Funciones wait