Função SetWaitableTimer (synchapi.h)

Artigo
06/17/2023

Ativa o temporizador de espera especificado. Quando o tempo de conclusão chega, o temporizador é sinalizado e o thread que define o temporizador chama a rotina de conclusão opcional.

Sintaxe

BOOL SetWaitableTimer(
  [in]           HANDLE              hTimer,
  [in]           const LARGE_INTEGER *lpDueTime,
  [in]           LONG                lPeriod,
  [in, optional] PTIMERAPCROUTINE    pfnCompletionRoutine,
  [in, optional] LPVOID              lpArgToCompletionRoutine,
  [in]           BOOL                fResume
);

Parâmetros

[in] hTimer

Um identificador para o objeto de temporizador. A função CreateWaitableTimer ou OpenWaitableTimer retorna esse identificador .

O identificador deve ter o acesso de TIMER_MODIFY_STATE correto. Para obter mais informações, consulte Segurança do objeto de sincronização e direitos de acesso.

[in] lpDueTime

O tempo após o qual o estado do temporizador deve ser definido como sinalizado, em intervalos de 100 nanossegundos. Use o formato descrito pela estrutura FILETIME . Valores positivos indicam tempo absoluto. Certifique-se de usar um tempo absoluto baseado em UTC, pois o sistema usa o tempo baseado em UTC internamente. Valores negativos indicam tempo relativo. A precisão real do temporizador depende da capacidade do hardware. Para obter mais informações sobre a hora baseada em UTC, consulte Tempo do sistema.

[in] lPeriod

O período do temporizador, em milissegundos. Se lPeriod for zero, o temporizador será sinalizado uma vez. Se lPeriod for maior que zero, o temporizador será periódico. Um temporizador periódico reativa automaticamente cada vez que o período passa, até que o temporizador seja cancelado usando a função CancelWaitableTimer ou redefinido usando SetWaitableTimer. Se lPeriod for menor que zero, a função falhará.

[in, optional] pfnCompletionRoutine

Um ponteiro para uma rotina de conclusão opcional. A rotina de conclusão é a função definida pelo aplicativo do tipo PTIMERAPCROUTINE a ser executada quando o temporizador é sinalizado. Para obter mais informações sobre a função de retorno de chamada do temporizador, consulte TimerAPCProc. Para obter mais informações sobre APCs e threads do pool de threads, consulte Comentários.

[in, optional] lpArgToCompletionRoutine

Um ponteiro para uma estrutura que é passada para a rotina de conclusão.

[in] fResume

Se esse parâmetro for TRUE, restaurará um sistema no modo de conservação de energia suspenso quando o estado do temporizador estiver definido como sinalizado. Caso contrário, o sistema não será restaurado. Se o sistema não der suporte a uma restauração, a chamada será bem-sucedida, mas GetLastErrorretornará ERROR_NOT_SUPPORTED.

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero.

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.

Comentários

Os temporizadores são inicialmente inativos. Para ativar um temporizador, chame SetWaitableTimer. Se o temporizador já estiver ativo quando você chamar SetWaitableTimer, o temporizador será interrompido e ele será reativado. Parar o temporizador dessa maneira não define o estado do temporizador como sinalizado, portanto, os threads bloqueados em uma operação de espera no temporizador permanecem bloqueados. No entanto, ele cancela todas as rotinas de conclusão pendentes.

Quando o tempo de conclusão especificado chega, o temporizador fica inativo e o APC opcional é enfileirado para o thread que define o temporizador se não houver nenhum APC pendente já enfileirado. O estado do temporizador é definido como sinalizado, o temporizador é reativado usando o período especificado e o thread que define o temporizador chama a rotina de conclusão quando entra em um estado de espera alertável. Para obter mais informações, consulte QueueUserAPC. Observe que as APCs não funcionam tão bem quanto outros mecanismos de sinalização para threads de pool de threads porque o sistema controla o tempo de vida dos threads do pool de threads, portanto, é possível que um thread seja encerrado antes que a notificação seja entregue. Em vez de usar o parâmetro pfnCompletionRoutine ou outro mecanismo de sinalização baseado em APC, use um objeto de espera, como um temporizador criado com CreateThreadpoolTimer. Para E/S, use um objeto de conclusão de E/S criado com CreateThreadpoolIo ou uma estrutura OVERLAPPED baseada em hEvent em que o evento pode ser passado para a função SetThreadpoolWait.

Se o thread que define o temporizador for encerrado e houver uma rotina de conclusão associada, o temporizador será cancelado. No entanto, o estado do temporizador permanece inalterado. Se não houver rotina de conclusão, encerrar o thread não terá efeito no temporizador.

Quando um temporizador de redefinição manual é definido como o estado sinalizado, ele permanece nesse estado até SetWaitableTimer ser chamado para redefinir o temporizador. Como resultado, um temporizador periódico de redefinição manual é definido como o estado sinalizado quando o tempo de conclusão inicial chega e permanece sinalizado até que seja redefinido. Quando um temporizador de sincronização é definido como o estado sinalizado, ele permanece nesse estado até que um thread conclua uma operação de espera no objeto de temporizador.

Se o tempo do sistema for ajustado, o tempo de conclusão de qualquer temporizador absoluto pendente será ajustado.

Para compilar um aplicativo que usa essa função, defina _WIN32_WINNT como 0x0400 ou posterior. Para obter mais informações, consulte Usando os cabeçalhos do Windows.

Para usar um temporizador para agendar um evento para uma janela, use a função SetTimer .

AS APIs que lidam com temporizadores usam vários relógios de hardware diferentes. Esses relógios podem ter resoluções significativamente diferentes do esperado: alguns podem ser medidos em milissegundos (para aqueles que usam um chip de temporizador baseado em RTC), para aqueles medidos em nanossegundos (para aqueles que usam contadores ACPI ou TSC). Você pode alterar a resolução da API com uma chamada para as funções timeBeginPeriod e timeEndPeriod . A precisão com que você pode alterar a resolução depende de qual relógio de hardware a API específica usa. Para obter mais informações, marcar sua documentação de hardware.

Exemplos

Para obter um exemplo que usa SetWaitableTimer, consulte Usando objetos timer de espera.

Requisitos

Requisito	Valor
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 Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll