Функция KeSetCoalescableTimer (wdm.h)

Статья
02/27/2024

Подпрограмма KeSetCoalescableTimer задает начальное время истечения срока действия и период объекта таймера и указывает, сколько задержки можно допускать в течение срока действия.

Синтаксис

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

Параметры

[in, out] Timer

Указатель на объект таймера. Этот параметр указывает на структуру KTIMER , которая представляет собой непрозрачную системную структуру, представляющую объект таймера. Этот объект должен быть ранее инициализирован подпрограммой KeInitializeTimerEx или KeInitializeTimer .

[in] DueTime

Указывает абсолютное или относительное время, в которое истекает срок действия таймера. Если значение параметра DueTime отрицательное, время истечения срока действия будет относительно текущего системного времени. В противном случае срок действия будет абсолютным. Время истечения срока действия выражается в системных единицах времени, которые представляют собой 100-наносекундные интервалы. Абсолютное время истечения срока действия отслеживает любые изменения, внесенные в системные часы. Изменения системных часов не влияют на относительный срок действия.

[in] Period

Указывает интервал между периодическими истечением срока действия таймера в миллисекундах. Значение этого параметра не должно превышать MAXLONG. Этот параметр является необязательным и может быть равен нулю, чтобы указать, что таймер непериодический.

[in] TolerableDelay

Задает допуск (в миллисекундах) для периода таймера, заданного параметром Period , и начального интервала времени, заданного DueTime . Для периодического таймера интервал времени между двумя последовательными сроками действия таймера будет находиться в диапазоне от (Period - TolerableDelay) до (Period + TolerableDelay). Начальное время истечения срока действия будет находиться в диапазоне от DueTime до (DueTime + TolerableDelay). Значение TolerableDelay не может быть отрицательным.

[in, optional] Dpc

Указатель на объект DPC. Этот параметр указывает на структуру KDPC , которая представляет собой непрозрачную системную структуру, представляющую объект DPC. Этот объект должен быть ранее инициализирован подпрограммой KeInitializeDpc . Этот параметр является необязательным и может быть указан как NULL , если вызывающий объект не требует DPC.

Возвращаемое значение

KeSetCoalescableTimer возвращает значение TRUE , если объект таймера уже находился в очереди системного таймера. В противном случае возвращается значение FALSE.

Устанавливает таймер в состояние без сигнала.
Связывает таймер с DPC, если указан DPC.
Отменяет таймер, если он уже активен.
Делает таймер активным и задает для времени выполнения и периода таймера указанные значения. Срок действия таймера может истечь немедленно, если уже прошло указанное время.

Подпрограмма KeSetTimerEx похожа на KeSetCoalescableTimer, но не принимает параметр TolerableDelay . Параметр TolerableDelayобъекта KeSetCoalescableTimer позволяет вызывающей стороны указать допустимость для периода таймера. Вызов KeSetCoalescableTimer с tolerableDelay = 0 совпадает с вызовом KeSetTimerEx. Во многих случаях разработчики могут легко изменять существующие драйверы, заменяя вызовы KeSetTimerEx вызовами KeSetCoalescableTimer.

Если два вызова KeSetCoalescableTimer указывают один и тот же объект таймера, а второй вызов происходит до истечения срока действия DueTime , указанного для первого вызова, второй вызов неявно отменяет таймер из первого вызова. Однако если истечение срока действия таймера после первого вызова уже включило выполнение DPC, DPC может запуститься после отмены таймера. Второй вызов заменяет отложенное время истечения срока действия первого вызова новым временем истечения срока действия и снова активирует таймер.

Если параметр Period не равен нулю, таймер является периодическим. Для периодического таймера первый срок действия таймера происходит во время, указанное параметром DueTime . Более поздние сроки действия разделяются интервалом, заданным параметром Period. Если аргумент Period = 0, таймер непериодический и истекает в момент, указанный dueTime.

Если параметр Dpc не равен NULL, подпрограмма создает связь между указанным объектом DPC и объектом таймера. По истечении срока действия таймера служба таймера удаляет объект таймера из очереди системного таймера и присваивает этому объекту состояние сигнала. Если объект DPC связан с объектом таймера, служба таймера вставляет объект DPC в системную очередь DPC для запуска, как только позволяют условия.

В системной очереди DPC одновременно может находиться только один экземпляр определенного объекта DPC. Чтобы избежать потенциальных условий гонки, избегайте передачи одного и того же объекта DPC в подпрограммы KeSetCoalescableTimer и KeInsertQueueDpc .

Избегайте изменения важности или целевого процессора DPC, связанного с активным таймером. Отмените таймер или убедитесь, что срок действия таймера истек перед вызовом подпрограммы, например KeSetImportanceDpc или KeSetTargetProcessorDpcEx , для изменения параметров DPC. Например, если драйвер обновляет целевой процессор DPC, а таймер разрешает запуск DPC, DPC может выполняться на произвольном процессоре.

Периодический таймер автоматически перезапускается по истечении срока его действия. Таким образом, в многопроцессорной системе DPC для периодического таймера может работать на двух или более процессорах одновременно.

Драйверы должны отменить все активные таймеры в подпрограммах выгрузки . Вызовите подпрограмму KeCancelTimer , чтобы отменить таймер. Если DPC связан с таймером, который является периодическим или срок действия которого недавно истек, драйвер должен подождать (например, вызвав подпрограмму KeFlushQueuedDpcs ), чтобы освободить DPC и связанные с ним данные до тех пор, пока не будут завершены все ожидающие выполнения DPC на всех процессорах.

KeSetCoalescableTimer использует параметр TolerableDelay для объединения таймеров. То есть подпрограмма корректирует срок действия таймера так, чтобы он совпадал с временем окончания срока действия других программных таймеров. Объединение таймеров помогает увеличить продолжительность периодов простоя, чтобы операционная система может снизить энергопотребление и повысить энергоэффективность.

Чтобы эффективно использовать объединение таймеров, вызывающий объект должен указать допустимое значение Tolay не менее 32 миллисекунд. Это значение равно двум стандартным интервалам системных часов в 15,6 миллисекундах. Если это возможно, используйте большее значение TolerableDelay , например 100 миллисекунд.

Попробуйте указать значения Period и TolerableDelay в кратных 50 миллисекундах. Типичные значения period : 50, 100, 250, 500 и 1000 миллисекунд. Типичные значения TolerableDelay : 50, 100, 150 и 250 миллисекунд.

Как правило, таймер с большим значением Period может использовать пропорционально большое значение TolerableDelay . Например, таймер с периодом = 500 миллисекунд может использовать TolerableDelay = 50 миллисекунд, но таймер с периодом = 10 секунд может использовать TolerableDelay = 1 секунду.

Время истечения срока действия измеряется относительно системных часов, а точность, с которой операционная система может определить время истечения срока действия таймера, ограничена степенью детализации системных часов. Дополнительные сведения см. в разделе Точность таймера.

Дополнительные сведения об объектах таймера см. в разделе Объекты таймера и DPC. Дополнительные сведения о объединии таймеров см. в техническом документе о развертывании таймеров Windows на веб-сайте WHDC.

Требования

Требование	Значение
Минимальная версия клиента	Доступно начиная с Windows 7.
Целевая платформа	Универсальное
Верхняя часть	wdm.h (включая Wdm.h, Ntddk.h, Ntifs.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL