WaitForSingleObject
La función WaitForSingleObject regresa cuando ocurre uno de los casos siguientes:
- El objeto especificado está en el estado señalado.
- Transcurre el intervalo de time-out.
Sintaxis
DWORD WaitForSingleObject(
HANDLE hHandle, // manipulador de objeto para el que esperar
DWORD dwMilliseconds // intervalo de time-out en milisegundos
);
Parámetros
- hHandle
- Identifica el objeto. Para una lista de los tipos de objetos cuyos manipuladores pueden ser especificados,
ver la sección de observaciones.
Windows NT: El manipulador debe tener acceso SYNCHRONIZE. Para más información, ver Máscaras de Acceso y Derechos de Acceso. - dwMilliseconds
- Especifica el intervalo de time-out, en milisegundos. La función regresa si transcurre el intervalo, incluso si es estado del objeto es no señalado. Si dwMilliseconds es cero, la función verifica el estado del objeto 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_ABANDONED | El objeto especificado es un objeto mutex que no fue liberado por el hilo que posee el objeto antes de que el hilo propietario terminase. La propiedad del objeto mutex se otorga al hilo que llama, y el mutex es asignado a no señalado. |
| WAIT_OBJECT_0 | El estado del objeto especificado es señalado. |
| WAIT_TIMEOUT | El intervalo de time-out ha transcurrido y el objeto especificado es no señalado. |
Observaciones
La función WaitForSingleObject verifica el estado actual del objeto especifiado. Si el estado del objeto es no señalado, el hilo que llama entra en un estado de espera eficiente. El hilo consume muy poco tiempo de procesador mientras espera a que el estado del objeto cambie a señalado o transcurra el intervalo time-out.
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 WaitForSingleObject puede esperar por los siguentes objetos:
| 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 lpHandle. 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 WaitForSingleObject.