Função SleepEx (synchapi.h)

Artigo
08/26/2023

Suspende o thread atual até que a condição especificada seja atendida. A execução é retomada quando ocorre um dos seguintes procedimentos:

Uma função de retorno de chamada de conclusão de E/S é chamada.
Uma APC (chamada de procedimento assíncrono) é enfileirada para o thread.
O intervalo de tempo limite passa.

Sintaxe

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

Parâmetros

[in] dwMilliseconds

O intervalo de tempo para o qual a execução deve ser suspensa, em milissegundos.

Um valor zero faz com que o thread libere o restante de sua fatia de tempo para qualquer outro thread que esteja pronto para ser executado. Se não houver outros threads prontos para serem executados, a função retornará imediatamente e o thread continuará a execução. Windows XP: Um valor zero faz com que o thread libere o restante de sua fatia de tempo para qualquer outro thread de prioridade igual que esteja pronto para ser executado. Se não houver outros threads de prioridade igual prontos para serem executados, a função retornará imediatamente e o thread continuará a execução. Esse comportamento mudou a partir do Windows Server 2003.

Um valor infinite indica que a suspensão não deve ter tempo limite.

[in] bAlertable

Se esse parâmetro for FALSE, a função não retornará até que o período de tempo limite tenha decorrido. Se ocorrer um retorno de chamada de conclusão de E/S, a função não retornará imediatamente e a função de conclusão de E/S não será executada. Se um APC estiver na fila para o thread, a função não retornará imediatamente e a função APC não será executada.

Se o parâmetro for TRUE e o thread que chamou essa função for o mesmo thread que chamou a função de E/S estendida (ReadFileEx ou WriteFileEx), a função retornará quando o período de tempo limite tiver decorrido ou quando ocorrer uma função de retorno de chamada de conclusão de E/S. Se ocorrer um retorno de chamada de conclusão de E/S, a função de conclusão de E/S será chamada. Se um APC estiver na fila para o thread (QueueUserAPC), a função retornará quando o período de tempo limite tiver decorrido ou quando a função APC for chamada.

Valor retornado

O valor retornado será zero se o intervalo de tempo especificado tiver expirado.

O valor retornado será WAIT_IO_COMPLETION se a função retornada devido a uma ou mais funções de retorno de chamada de conclusão de E/S. Isso só poderá acontecer se bAlertable for TRUE e se o thread que chamou a função SleepEx for o mesmo thread que chamou a função de E/S estendida.

Comentários

Essa função faz com que um thread abra mão do restante de sua fatia de tempo e se torne indisplicável para um intervalo com base no valor de dwMilliseconds. Depois que o intervalo de suspensão tiver passado, o thread estará pronto para ser executado. Observe que não há garantia de que um thread pronto seja executado imediatamente. Consequentemente, o thread não será executado até que algum tempo arbitrário após o intervalo de suspensão se desfaça, com base na frequência de "escala" do sistema e no fator de carga de outros processos. O relógio do sistema "marca" a uma taxa constante. Para aumentar a precisão do intervalo de suspensão, chame a função timeGetDevCaps para determinar a resolução mínima de temporizador com suporte e a função timeBeginPeriod para definir a resolução do temporizador com o mínimo. Tenha cuidado ao chamar timeBeginPeriod, pois chamadas frequentes podem afetar significativamente o relógio do sistema, o uso de energia do sistema e o agendador. Se você chamar timeBeginPeriod, chame-o uma vez no início do aplicativo e chame a função timeEndPeriod no final do aplicativo. Se você especificar 0 milissegundos, o thread abrirá mão do restante de sua fatia de tempo, mas permanecerá pronto. Para obter mais informações, consulte Agendando prioridades.

Essa função pode ser usada com as funções ReadFileEx ou WriteFileEx para suspender um thread até que uma operação de E/S seja concluída. Essas funções especificam uma rotina de conclusão que deve ser executada quando a operação de E/S for concluída. Para que a rotina de conclusão seja executada, o thread que chamou a função de E/S deve estar em um estado de espera alertável quando a função de retorno de chamada de conclusão ocorrer. Um thread entra em um estado de espera alertável chamando SleepEx, MsgWaitForMultipleObjectsEx, WaitForSingleObjectEx ou WaitForMultipleObjectsEx, com o parâmetro bAlertable da função definido como TRUE.

Tenha cuidado ao usar SleepEx nos seguintes cenários:

Código que cria janelas direta ou indiretamente (por exemplo, DDE e COInitialize COM). Se um thread criar janelas, ele deverá processar mensagens. As transmissões de mensagens são enviadas para todas as janelas do sistema. Se você tiver um thread que usa SleepEx com atraso infinito, o sistema terá deadlock.
Threads que estão sob controle de simultaneidade. Por exemplo, uma porta de conclusão de E/S ou um pool de threads limita o número de threads associados que podem ser executados. Se o número máximo de threads já estiver em execução, nenhum thread associado adicional poderá ser executado até que um thread em execução seja concluído. Se um thread usar SleepEx com um intervalo de zero para aguardar que um dos threads associados adicionais realize algum trabalho, o processo poderá ficar em deadlock.

Para esses cenários, use MsgWaitForMultipleObjects ou MsgWaitForMultipleObjectsEx, em vez de SleepEx.

Windows Phone 8.1: essa função tem suporte para aplicativos Windows Phone Store no Windows Phone 8.1 e posterior.

Windows 8.1 e Windows Server 2012 R2: essa função tem suporte para aplicativos da Windows Store em Windows 8.1, Windows Server 2012 R2 e posterior.

Requisitos


Cliente mínimo com suporte	Windows XP [aplicativos da área de trabalho \| aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2003 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	synchapi.h (inclua Windows.h no Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
Biblioteca	Kernel32.lib; WindowsPhoneCore.lib no Windows Phone 8.1
DLL	KernelBase.dll no Windows Phone 8.1; Kernel32.dll