Función SleepEx (synchapi.h)

Artículo
03/08/2023

Suspende el subproceso actual hasta que se cumpla la condición especificada. La ejecución se reanuda cuando se produce una de las siguientes acciones:

Se llama a una función de devolución de llamada de finalización de E/S.
Una llamada a procedimiento asincrónico (APC) se pone en cola en el subproceso.
El intervalo de tiempo de espera transcurre.

Sintaxis

DWORD SleepEx(
  [in] DWORD dwMilliseconds,
  [in] BOOL  bAlertable
);

Parámetros

[in] dwMilliseconds

Intervalo de tiempo para el que se va a suspender la ejecución, en milisegundos.

Un valor de cero hace que el subproceso relinque el resto de su intervalo de tiempo a cualquier otro subproceso que esté listo para ejecutarse. Si no hay ningún otro subproceso listo para ejecutarse, la función se devuelve inmediatamente y el subproceso continúa la ejecución. Windows XP: Un valor de cero hace que el subproceso renuncie al resto de su segmento de tiempo a cualquier otro subproceso de igual prioridad que esté listo para ejecutarse. Si no hay ningún otro subproceso de igual prioridad listo para ejecutarse, la función devuelve inmediatamente y el subproceso continúa la ejecución. Este comportamiento cambió a partir de Windows Server 2003.

Un valor de INFINITE indica que la suspensión no debe agotar el tiempo de espera.

[in] bAlertable

Si este parámetro es FALSE, la función no devuelve hasta que haya transcurrido el período de tiempo de espera. Si se produce una devolución de llamada de finalización de E/S, la función no devuelve inmediatamente y la función de finalización de E/S no se ejecuta. Si un APC se pone en cola en el subproceso, la función no devuelve inmediatamente y la función de APC no se ejecuta.

Si el parámetro es TRUE y el subproceso que llamó a esta función es el mismo subproceso que llamó a la función de E/S extendida (ReadFileEx o WriteFileEx), la función devuelve cuando ha transcurrido el período de tiempo de espera o cuando se produce una función de devolución de llamada de finalización de E/S. Si se produce una devolución de llamada de finalización de E/S, se llama a la función de finalización de E/S. Si un APC se pone en cola en el subproceso (QueueUserAPC), la función devuelve cuando ha transcurrido el período de tiempo de espera o cuando se llama a la función APC.

Valor devuelto

El valor devuelto es cero si el intervalo de tiempo especificado expiró.

El valor devuelto se WAIT_IO_COMPLETION si la función devuelta debido a una o varias funciones de devolución de llamada de finalización de E/S. Esto solo puede ocurrir si bAlertable es TRUE y si el subproceso que llamó a la función SleepEx es el mismo subproceso que llamó a la función de E/S extendida.

Comentarios

Esta función hace que un subproceso renuncie al resto de su segmento de tiempo y deje de ejecutarse para un intervalo basado en el valor de dwMilliseconds. Una vez transcurrido el intervalo de suspensión, el subproceso está listo para ejecutarse. Tenga en cuenta que no se garantiza que un subproceso listo se ejecute inmediatamente. Por lo tanto, el subproceso no se ejecutará hasta que transcurre algún tiempo arbitrario después de que transcurre el intervalo de suspensión, en función de la frecuencia de "tic" del sistema y el factor de carga de otros procesos. El reloj del sistema "tics" a una velocidad constante. Para aumentar la precisión del intervalo de suspensión, llame a la función timeGetDevCaps para determinar la resolución mínima admitida del temporizador y la función timeBeginPeriod para establecer la resolución del temporizador en su mínimo. Tenga cuidado al llamar a timeBeginPeriod, ya que las llamadas frecuentes pueden afectar significativamente al reloj del sistema, el uso de energía del sistema y el programador. Si llama a timeBeginPeriod, llámelo una vez al principio de la aplicación y asegúrese de llamar a la función timeEndPeriod al final de la aplicación. Si especifica 0 milisegundos, el subproceso renunciará al resto de su segmento de tiempo, pero permanecerá listo. Para obtener más información, consulte Programación de prioridades.

Esta función se puede usar con las funciones ReadFileEx o WriteFileEx para suspender un subproceso hasta que se haya completado una operación de E/S. Estas funciones especifican una rutina de finalización que se va a ejecutar cuando se ha completado la operación de E/S. Para que se ejecute la rutina de finalización, el subproceso que llamó a la función de E/S debe estar en un estado de espera alertable cuando se produce la función de devolución de llamada de finalización. Un subproceso entra en un estado de espera alertable llamando a SleepEx, MsgWaitForMultipleObjectsEx, WaitForSingleObjectEx o WaitForMultipleObjectsEx, con el parámetro bAlertable de la función establecido en TRUE.

Tenga cuidado al usar SleepEx en los escenarios siguientes:

Código que crea ventanas directa o indirectamente (por ejemplo, DDE y COM CoInitialize). Si un subproceso crea ventanas, debe procesar los mensajes. Las difusiones de mensajes se envían a todas las ventanas del sistema. Si tiene un subproceso que usa SleepEx con retraso infinito, el sistema interbloqueo.
Subprocesos que están bajo control de simultaneidad. Por ejemplo, un puerto de finalización de E/S o un grupo de subprocesos limita el número de subprocesos asociados que se pueden ejecutar. Si el número máximo de subprocesos ya se está ejecutando, no se puede ejecutar ningún subproceso asociado adicional hasta que finalice un subproceso en ejecución. Si un subproceso usa SleepEx con un intervalo de cero para esperar a que uno de los subprocesos asociados adicionales realice algún trabajo, el proceso podría interbloquear.

Para estos escenarios, use MsgWaitForMultipleObjects o MsgWaitForMultipleObjectsEx, en lugar de SleepEx.

Windows Phone 8.1: esta función es compatible con las aplicaciones de Windows Phone Store en Windows Phone 8.1 y versiones posteriores.

Windows 8.1 y Windows Server 2012 R2: esta función es compatible con las aplicaciones de la Tienda Windows en Windows 8.1, Windows Server 2012 R2 y versiones posteriores.

Requisitos


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 Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
Library	Kernel32.lib; WindowsPhoneCore.lib en Windows Phone 8.1
Archivo DLL	KernelBase.dll en Windows Phone 8.1; Kernel32.dll