Función KeSetCoalescableTimer (wdm.h)

Artículo
03/16/2023

La rutina KeSetCoalescableTimer establece el tiempo de expiración inicial y el período de un objeto de temporizador y especifica cuánto retraso se puede tolerar en los tiempos de expiración.

Sintaxis

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

Puntero a un objeto de temporizador. Este parámetro apunta a una estructura KTIMER , que es una estructura del sistema opaca que representa el objeto de temporizador. Este objeto debe haber sido inicializado previamente por la rutina KeInitializeTimerEx o KeInitializeTimer .

[in] DueTime

Especifica un tiempo absoluto o relativo en el que el temporizador va a expirar. Si el valor del parámetro DueTime es negativo, la hora de expiración es relativa a la hora actual del sistema. De lo contrario, la hora de expiración es absoluta. La hora de expiración se expresa en unidades de tiempo del sistema, que son intervalos de 100 nanosegundos. Los tiempos de expiración absolutos realizan un seguimiento de los cambios realizados en el reloj del sistema. Los tiempos de expiración relativos no se ven afectados por los cambios del reloj del sistema.

[in] Period

Especifica el intervalo entre expiraciones periódicas del temporizador en milisegundos. El valor de este parámetro no debe superar MAXLONG. Este parámetro es opcional y se puede establecer en cero para indicar que el temporizador no esperiódico.

[in] TolerableDelay

Especifica una tolerancia, en milisegundos, para el período de temporizador que Period especifica y para el intervalo de tiempo inicial que especifica DueTime . Para un temporizador periódico, el intervalo de tiempo entre dos expiraciones sucesivas del temporizador estará en el intervalo desde (Period - TolerableDelay) hasta (Period + TolerableDelay). La hora de expiración inicial estará en el intervalo de DueTime a (DueTime + TolerableDelay). El valor TolerableDelay no puede ser negativo.

[in, optional] Dpc

Puntero a un objeto DPC. Este parámetro apunta a una estructura KDPC , que es una estructura del sistema opaca que representa el objeto DPC. Este objeto debe haber sido inicializado previamente por la rutina KeInitializeDpc . Este parámetro es opcional y se puede especificar como NULL si el autor de la llamada no requiere un DPC.

Valor devuelto

KeSetCoalescableTimer devuelve TRUE si el objeto de temporizador ya estaba en la cola del temporizador del sistema. De lo contrario, devuelve FALSE.

Comentarios

Esta rutina hace lo siguiente:

Establece el temporizador en un estado no señalado.
Asocia el temporizador al DPC, si se especifica un DPC.
Cancela el temporizador si ya está activo.
Activa el temporizador y establece el tiempo de vencimiento y el período del temporizador en los valores especificados. El temporizador puede expirar inmediatamente si ya ha transcurrido el tiempo de vencimiento especificado.

La rutina KeSetTimerEx es similar a KeSetCoalescableTimer , pero no acepta un parámetro TolerableDelay . El parámetro TolerableDelay de KeSetCoalescableTimer permite al autor de la llamada especificar una tolerancia para el período del temporizador. Una llamada a KeSetCoalescableTimer con TolerableDelay = 0 es la misma que una llamada a KeSetTimerEx. En muchos casos, los desarrolladores pueden modificar fácilmente los controladores existentes reemplazando las llamadas a KeSetTimerEx por llamadas a KeSetCoalescableTimer.

Si dos llamadas a KeSetCoalescableTimer especifican el mismo objeto de temporizador y la segunda llamada se produce antes de que expire el dueTime especificado para la primera llamada, la segunda llamada cancela implícitamente el temporizador de la primera llamada. Sin embargo, si una expiración del temporizador de la primera llamada ya ha habilitado un DPC para ejecutarse, el DPC podría ejecutarse después de cancelar el temporizador. La segunda llamada reemplaza la hora de expiración pendiente de la primera llamada por una nueva hora de expiración y vuelve a activar el temporizador.

Si el parámetro Period es distinto de cero, el temporizador es periódico. Para un temporizador periódico, la primera expiración del temporizador se produce en el momento indicado por el parámetro DueTime . Las expiraciones posteriores están separadas por el intervalo especificado por Period. Si Period = 0, el temporizador no esperiódico y expira en el momento indicado por DueTime.

Si el parámetro Dpc no es NULL, la rutina crea una asociación entre el objeto DPC especificado y el objeto del temporizador. Una vez expirado el temporizador, el servicio de temporizador quita el objeto de temporizador de la cola del temporizador del sistema y establece este objeto en un estado señalado. Si un objeto DPC está asociado al objeto de temporizador, el servicio de temporizador inserta el objeto DPC en la cola DPC del sistema para que se ejecute tan pronto como se permitan las condiciones.

Solo una instancia de un objeto DPC determinado puede estar en la cola DPC del sistema a la vez. Para evitar posibles condiciones de carrera, evite pasar el mismo objeto DPC a las rutinas KeSetCoalescableTimer y KeInsertQueueDpc .

Evite cambiar la importancia o el procesador de destino de un DPC asociado a un temporizador activo. Cancele el temporizador o asegúrese de que el temporizador ha expirado antes de llamar a una rutina como KeSetImportanceDpc o KeSetTargetProcessorDpcEx para cambiar la configuración de DPC. Por ejemplo, si un controlador actualiza el procesador de destino de un DPC mientras un temporizador permite que el DPC se ejecute, el DPC podría ejecutarse en un procesador arbitrario.

Un temporizador periódico se reinicia automáticamente en cuanto expira. Por lo tanto, en un sistema multiprocesador, el DPC para un temporizador periódico podría estar ejecutándose en dos o más procesadores al mismo tiempo.

Los controladores deben cancelar los temporizadores activos en sus rutinas de descarga . Llame a la rutina KeCancelTimer para cancelar un temporizador. Si un DPC está asociado a un temporizador que es periódico o que podría haber expirado recientemente, un controlador debe esperar (por ejemplo, llamando a la rutina KeFlushQueuedDpcs ) para liberar el DPC y sus datos asociados hasta que finalicen todas las ejecuciones DPC pendientes en todos los procesadores.

KeSetCoalescableTimer usa el parámetro TolerableDelay para realizar la fusión del temporizador. Es decir, la rutina ajusta los tiempos de expiración para que el temporizador coincida con los tiempos de expiración de otros temporizadores de software. El fusión del temporizador ayuda a aumentar la duración de los períodos de inactividad para que el sistema operativo pueda reducir el consumo de energía y mejorar la eficiencia energética.

Para usar el temporizador fusionando eficazmente, un llamador debe especificar un valor TolerableDelay de al menos 32 milisegundos. Este valor es igual a dos intervalos de reloj del sistema predeterminados de 15,6 milisegundos. Si puede, use un valor TolerableDelay mayor, como 100 milisegundos.

Intente especificar los valores Period y TolerableDelay en múltiplos de 50 milisegundos. Los valores de período típicos son 50, 100, 250, 500 y 1000 milisegundos. Los valores de TolerableDelay típicos son 50, 100, 150 y 250 milisegundos.

Normalmente, un temporizador con un valor period grande puede usar un valor TolerableDelay proporcionalmente grande. Por ejemplo, un temporizador con Period = 500 milisegundos podría usar TolerableDelay = 50 milisegundos, pero un temporizador con Period = 10 segundos podría usar TolerableDelay = 1 segundo.

Los tiempos de expiración se miden en relación con el reloj del sistema y la precisión con la que el sistema operativo puede detectar cuándo expira un temporizador está limitado por la granularidad del reloj del sistema. Para obtener más información, vea Precisión del temporizador.

Para obtener más información sobre los objetos de temporizador, vea Objetos de temporizador y DPC. Para obtener más información sobre la fusión de temporizadores, consulta las notas del producto Fusión del temporizador de Windows en el sitio web de WHDC.

Requisitos

Requisito	Value
Cliente mínimo compatible	Disponible a partir de Windows 7.
Plataforma de destino	Universal
Encabezado	wdm.h (incluya Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
Archivo DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL