Função KeSetCoalescableTimer (wdm.h)

Artigo
03/16/2023

A rotina KeSetCoalescableTimer define o tempo de expiração inicial e o período de um objeto de temporizador e especifica quanto atraso pode ser tolerado nos tempos de expiração.

Sintaxe

BOOLEAN KeSetCoalescableTimer(
  [in, out]      PKTIMER       Timer,
  [in]           LARGE_INTEGER DueTime,
  [in]           ULONG         Period,
  [in]           ULONG         TolerableDelay,
  [in, optional] PKDPC         Dpc
);

Parâmetros

[in, out] Timer

Um ponteiro para um objeto de temporizador. Esse parâmetro aponta para uma estrutura KTIMER , que é uma estrutura opaca do sistema que representa o objeto de temporizador. Esse objeto deve ter sido inicializado anteriormente pela rotina KeInitializeTimerEx ou KeInitializeTimer .

[in] DueTime

Especifica um tempo absoluto ou relativo no qual o temporizador deve expirar. Se o valor do parâmetro DueTime for negativo, o tempo de expiração será relativo à hora atual do sistema. Caso contrário, o tempo de expiração será absoluto. O tempo de expiração é expresso em unidades de tempo do sistema, que são intervalos de 100 nanossegundos. Os tempos de expiração absolutos acompanham as alterações feitas no relógio do sistema. Os tempos relativos de expiração não são afetados pelas alterações do relógio do sistema.

[in] Period

Especifica o intervalo entre expirações periódicas de temporizador em milissegundos. O valor desse parâmetro não deve exceder MAXLONG. Esse parâmetro é opcional e pode ser definido como zero para indicar que o temporizador não é periódico.

[in] TolerableDelay

Especifica uma tolerância, em milissegundos, para o período de temporizador que Period especifica e para o intervalo de tempo inicial especificado por DueTime . Para um temporizador periódico, o intervalo de tempo entre duas expirações sucessivas de temporizador estará no intervalo de (Period - TolerableDelay) a (Period + TolerableDelay). O tempo de expiração inicial estará no intervalo de DueTime a (DueTime + TolerableDelay). O valor TolerableDelay não pode ser negativo.

[in, optional] Dpc

Um ponteiro para um objeto DPC. Esse parâmetro aponta para uma estrutura KDPC , que é uma estrutura de sistema opaca que representa o objeto DPC. Esse objeto deve ter sido inicializado anteriormente pela rotina KeInitializeDpc . Esse parâmetro é opcional e pode ser especificado como NULL se o chamador não exigir um DPC.

Retornar valor

KeSetCoalescableTimer retornará TRUE se o objeto de temporizador já estiver na fila do temporizador do sistema. Caso contrário, retornará FALSE.

Comentários

Essa rotina faz o seguinte:

Define o temporizador como um estado não sinalizado.
Associa o temporizador ao DPC, se um DPC for especificado.
Cancela o temporizador se ele já estiver ativo.
Torna o temporizador ativo e define o tempo e o período de vencimento do temporizador para os valores especificados. O temporizador poderá expirar imediatamente se o tempo de conclusão especificado já tiver passado.

A rotina KeSetTimerEx é semelhante a KeSetCoalescableTimer , mas não aceita um parâmetro TolerableDelay . O parâmetro TolerableDelay de KeSetCoalescableTimer permite que o chamador especifique uma tolerância para o período de temporizador. Uma chamada para KeSetCoalescableTimer com TolerableDelay = 0 é a mesma que uma chamada para KeSetTimerEx. Em muitos casos, os desenvolvedores podem modificar facilmente os drivers existentes substituindo chamadas para KeSetTimerEx por chamadas para KeSetCoalescableTimer.

Se duas chamadas KeSetCoalescableTimer especificarem o mesmo objeto de temporizador e a segunda chamada ocorrer antes do DueTime especificado para a primeira chamada expirar, a segunda chamada cancelará implicitamente o temporizador da primeira chamada. No entanto, se uma expiração do temporizador da primeira chamada já tiver habilitado um DPC para execução, o DPC poderá ser executado depois que o temporizador for cancelado. A segunda chamada substitui o tempo de expiração pendente da primeira chamada por um novo tempo de expiração e ativa o temporizador novamente.

Se o parâmetro Period for diferente de zero, o temporizador será periódico. Para um temporizador periódico, a expiração do primeiro temporizador ocorre no momento indicado pelo parâmetro DueTime . Expirações posteriores são separadas pelo intervalo especificado por Period. Se Período = 0, o temporizador não será periódico e expirará no momento indicado por DueTime.

Se o parâmetro Dpc não for NULL, a rotina criará uma associação entre o objeto DPC especificado e o objeto timer. Depois que o temporizador expira, o serviço de temporizador remove o objeto de temporizador da fila do temporizador do sistema e define esse objeto como um estado sinalizado. Se um objeto DPC estiver associado ao objeto timer, o serviço de temporizador inserirá o objeto DPC na fila DPC do sistema para ser executado assim que as condições permitirem.

Apenas uma instância de um objeto DPC específico pode estar na fila DPC do sistema por vez. Para evitar possíveis condições de corrida, evite passar o mesmo objeto DPC para as rotinas KeSetCoalescableTimer e KeInsertQueueDpc .

Evite alterar a importância ou o processador de destino de um DPC associado a um temporizador ativo. Cancele o temporizador ou verifique se o temporizador expirou antes de chamar uma rotina como KeSetImportanceDpc ou KeSetTargetProcessorDpcEx para alterar as configurações de DPC. Por exemplo, se um driver atualizar o processador de destino de um DPC enquanto um temporizador permitir que o DPC seja executado, o DPC poderá ser executado em um processador arbitrário.

Um temporizador periódico é reiniciado automaticamente assim que expira. Portanto, em um sistema multiprocessador, o DPC para um temporizador periódico pode estar em execução em dois ou mais processadores ao mesmo tempo.

Os motoristas devem cancelar todos os temporizadores ativos em suas rotinas de descarregamento . Chame a rotina KeCancelTimer para cancelar um temporizador. Se um DPC estiver associado a um temporizador periódico ou que possa ter expirado recentemente, um driver deverá aguardar (por exemplo, chamando a rotina KeFlushQueuedDpcs ) para liberar o DPC e seus dados associados até que todas as execuções de DPC pendentes em todos os processadores sejam concluídas.

KeSetCoalescableTimer usa o parâmetro TolerableDelay para executar a união do temporizador. Ou seja, a rotina ajusta os tempos de expiração do temporizador para coincidir com os tempos de expiração de outros temporizadores de software. A união do temporizador ajuda a aumentar o comprimento dos períodos ociosos para que o sistema operacional possa reduzir o consumo de energia e melhorar a eficiência energética.

Para usar a união de temporizador com eficiência, um chamador deve especificar um valor TolerableDelay de pelo menos 32 milissegundos. Esse valor é igual a dois intervalos de relógio do sistema padrão de 15,6 milissegundos. Se puder, use um valor TolerableDelay maior, como 100 milissegundos.

Tente especificar os valores Period e TolerableDelay em múltiplos de 50 milissegundos. Os valores de Período típicos são 50, 100, 250, 500 e 1000 milissegundos. Os valores típicos de TolerableDelay são 50, 100, 150 e 250 milissegundos.

Normalmente, um temporizador com um valor de Período grande pode usar um valor TolerávelDelay proporcionalmente grande. Por exemplo, um temporizador com Period = 500 milissegundos pode usar TolerableDelay = 50 milissegundos, mas um temporizador com Period = 10 segundos pode usar TolerableDelay = 1 segundo.

Os tempos de expiração são medidos em relação ao relógio do sistema e a precisão com que o sistema operacional pode detectar quando um temporizador expira é limitada pela granularidade do relógio do sistema. Para obter mais informações, consulte Precisão do temporizador.

Para obter mais informações sobre objetos de temporizador, consulte Objetos do Temporizador e DPCs. Para obter mais informações sobre a união do temporizador, consulte o white paper Coalescing do Temporizador do Windows no site do WHDC.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Disponível a partir do Windows 7.
Plataforma de Destino	Universal
Cabeçalho	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL