Función SignalObjectAndWait (synchapi.h)
Señala un objeto y espera en otro objeto como una sola operación.
Sintaxis
DWORD SignalObjectAndWait(
[in] HANDLE hObjectToSignal,
[in] HANDLE hObjectToWaitOn,
[in] DWORD dwMilliseconds,
[in] BOOL bAlertable
);
Parámetros
[in] hObjectToSignal
Identificador del objeto que se va a indicar. Este objeto puede ser un semáforo, una exclusión mutua o un evento.
Si el identificador es un semáforo, se requiere el SEMAPHORE_MODIFY_STATE derecho de acceso. Si el identificador es un evento, se requiere el derecho de acceso EVENT_MODIFY_STATE . Si el identificador es una exclusión mutua y el autor de la llamada no posee la exclusión mutua, se produce un error en la función con ERROR_NOT_OWNER.
[in] hObjectToWaitOn
Identificador del objeto en el que se va a esperar. Se requiere el derecho de acceso SYNCHRONIZE ; para obtener más información, vea Seguridad de objetos de sincronización y derechos de acceso. Para obtener una lista de los tipos de objeto cuyos identificadores puede especificar, vea la sección Comentarios.
[in] dwMilliseconds
El intervalo de tiempo de espera en milisegundos. La función devuelve si transcurre el intervalo, incluso si el estado del objeto no está asignado y no se pone en cola ningún objeto de llamada a procedimiento asincrónico (APC). Si dwMilliseconds es cero, la función prueba el estado del objeto, comprueba si hay rutinas de finalización en cola o API y devuelve inmediatamente. Si dwMilliseconds es INFINITE, el intervalo de tiempo de espera de la función nunca transcurre.
[in] bAlertable
Si este parámetro es TRUE, la función devuelve cuando el sistema pone en cola una rutina de finalización de E/S o una función de APC, y el subproceso llama a la función. Si es FALSE, la función no devuelve y el subproceso no llama a la rutina de finalización ni a la función APC.
Una rutina de finalización se pone en cola cuando se ha completado la llamada de función que ha puesto en cola el APC. Esta función devuelve y se llama a la rutina de finalización solo si bAlertable es TRUE y el subproceso que realiza la llamada es el subproceso que pone en cola el APC.
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.
| Código o valor devuelto | Descripción |
|---|---|
|
El objeto especificado es un objeto de exclusión mutua que el subproceso que pertenece al objeto de exclusión mutua antes de que finalice el subproceso propietario. 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 la exclusión mutua protegía la información de estado persistente, debe comprobarla para comprobar la coherencia. |
|
La espera finalizó con una o varias llamadas de procedimiento asincrónico en modo de usuario (APC) en cola al subproceso. |
|
Se señala el estado del objeto especificado. |
|
El intervalo de tiempo de espera transcurrido y el estado del objeto no está asignado. |
|
Error en la función. Para obtener información de error extendida, llame a GetLastError. |
Comentarios
La función SignalObjectAndWait proporciona una manera más eficaz de señalar un objeto y, a continuación, esperar en otro en comparación con llamadas de función independientes, como SetEvent seguido de WaitForSingleObject.
La función SignalObjectAndWait puede esperar los siguientes objetos:
- Notificación de cambio
- Entrada de consola
- Evento
- Notificación de recursos de memoria
- Mutex
- Proceso
- Semaphore
- Thread
- Temporizador que se puede esperar
Un subproceso puede usar la función SignalObjectAndWait para asegurarse de que un subproceso de trabajo está en un estado de espera antes de señalar un objeto. Por ejemplo, un subproceso y un subproceso de trabajo pueden usar identificadores para los objetos de evento para sincronizar su trabajo. El subproceso ejecuta código como el siguiente:
dwRet = WaitForSingleObject(hEventWorkerDone, INFINITE);
if( WAIT_OBJECT_0 == dwRet)
SetEvent(hEventMoreWorkToDo);
El subproceso de trabajo ejecuta código como el siguiente:
dwRet = SignalObjectAndWait(hEventWorkerDone,
hEventMoreWorkToDo,
INFINITE,
FALSE);
Tenga en cuenta que no se garantiza que la "señal" y la "espera" se realicen como una operación atómica. Los subprocesos que se ejecutan en otros procesadores pueden observar el estado señalado del primer objeto antes de que el subproceso que llama a SignalObjectAndWait comience su espera en el segundo objeto.
Tenga extrema precaución al usar SignalObjectAndWait y PulseEvent con Windows 7, ya que el uso de estas API entre varios subprocesos puede hacer que una aplicación interbloquee. Los subprocesos señalados por SignalObjectAndWait llaman a PulseEvent para indicar el objeto en espera de la llamada SignalObjectAndWait . En algunas circunstancias, el autor de la llamada de SignalObjectAndWait no puede recibir el estado de señal del objeto en espera en tiempo, lo que provoca un interbloqueo.
Tenga cuidado al usar 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 crean ventanas indirectamente son DDE y COM CoInitialize. Por lo tanto, si tiene un subproceso que crea ventanas, asegúrese de llamar a SignalObjectAndWait desde un subproceso diferente. Si esto no es posible, puede usar MsgWaitForMultipleObjects o MsgWaitForMultipleObjectsEx, pero la funcionalidad no es equivalente.
Para compilar una aplicación que use esta función, defina _WIN32_WINNT como 0x0400 o posterior. Para obtener más información, vea Uso de los encabezados de Windows.
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 (incluya Windows.h) |
| Library | Kernel32.lib |
| Archivo DLL | Kernel32.dll |