Función KeSetCoalescableTimer (wdm.h)
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 de KTIMER, que es una estructura del sistema opaca que representa el objeto de temporizador. El keInitializeTimerEx o la rutina de KeInitializeTimer debe inicializar este objeto.
[in] DueTime
Especifica un tiempo absoluto o relativo en el que el temporizador debe 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. El tiempo 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 esperiodic.
[in] TolerableDelay
Especifica una tolerancia, en milisegundos, para el período del temporizador que Período especifica y para el intervalo de tiempo inicial que dueTime especifica. Para un temporizador periódico, el intervalo de tiempo entre dos expiraciones sucesivas del temporizador estará en el intervalo de (Período - TolerableDelay) a (Período + TolerableDelay). La hora de expiración inicial estará en el intervalo comprendido entre DueTime (DueTime + TolerableDelay). El valor de TolerableDelay no puede ser negativo.
[in, optional] Dpc
Puntero a un objeto DPC. Este parámetro apunta a una estructura de KDPC, que es una estructura del sistema opaca que representa el objeto DPC. El rutina de KeInitializeDpc debe inicializar este objeto previamente. 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.
Observaciones
Esta rutina hace lo siguiente:
Establece el temporizador en un estado no señalizado.
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 igual 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 KeSetCoalescableTimer llamadas 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 se puede ejecutar después de que se cancele 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 Período. Si Período = 0, el temporizador no esperiodic y expira en el momento indicado por DueTime.
Si el parámetro Dpc no esNULL, la rutina crea una asociación entre el objeto DPC especificado y el objeto de temporizador. Una vez que expire 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 de 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 se ejecute el DPC, el DPC se puede ejecutar en un procesador arbitrario.
Un temporizador periódico se reinicia automáticamente en cuanto expira. Por lo tanto, en un sistema de varios procesadores, el DPC para un temporizador periódico podría ejecutarse en dos o más procesadores al mismo tiempo.
Los controladores deben cancelar los temporizadores activos en sus rutinas Descargar. 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 KeFlushQueuedDpcs rutina) 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. La 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 de forma eficaz, un autor de la llamada debe especificar un TolerableDelay valor 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 de tolerableDelay mayor, como 100 milisegundos.
Intente especificar los valores de Period y TolerableDelay en múltiplos de 50 milisegundos. Los valores típicos de período son 50, 100, 250, 500 y 1000 milisegundos. Los valores típicos de TolerableDelay son 50, 100, 150 y 250 milisegundos.
Normalmente, un temporizador con un valor período de grande puede usar un valor de tolerableDelay proporcionalmente grande. Por ejemplo, un temporizador con Período = 500 milisegundos podría usar TolerableDelay = 50 milisegundos, pero un temporizador con Período = 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 DPCs. Para obtener más información sobre la fusión del temporizador, consulta las notas del producto Timer Coalescing de Windows timer en el sitio web de WHDC.
Requisitos
| Requisito | Valor |
|---|---|
| cliente mínimo admitido | Disponible a partir de Windows 7. |
| de la plataforma de destino de | Universal |
| encabezado de | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| biblioteca de | NtosKrnl.lib |
| DLL de | NtosKrnl.exe |
| irQL | <= DISPATCH_LEVEL |