KeSetCoalescableTimer 함수(wdm.h)

아티클
03/16/2023

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을 초과하면 안 됩니다. 이 매개 변수는 선택 사항이며 타이머가 비협조적임을 나타내기 위해 0으로 설정할 수 있습니다.

[in] TolerableDelay

Period에서 지정하는 타이머 기간 및 DueTime에서 지정하는 초기 시간 간격에 대한 허용 오차(밀리초)를 지정합니다. 주기적인 타이머의 경우 두 연속 타이머 만료 사이의 시간 간격은 (PeriodTolerableDelay)에서 (Period + - TolerableDelay)의 범위에 있습니다. 초기 만료 시간은 DueTime 에서 (DueTime + TolerableDelay) 범위입니다. TolerableDelay 값은 음수일 수 없습니다.

[in, optional] Dpc

DPC 개체에 대한 포인터입니다. 이 매개 변수는 DPC 개체를 나타내는 불투명한 시스템 구조체인 KDPC 구조를 가리킵니다. 이 개체는 이전에 KeInitializeDpc 루틴에 의해 초기화되어야 합니다. 이 매개 변수는 선택 사항이며 호출자에게 DPC가 필요하지 않은 경우 NULL 로 지정할 수 있습니다.

반환 값

KeSetCoalescableTimer는 타이머 개체가 시스템 타이머 큐에 이미 있는 경우 TRUE 를 반환합니다. 그렇지 않으면 FALSE를 반환합니다.

설명

이 루틴은 다음을 수행합니다.

타이머를 신호가 없는 상태로 설정합니다.
DPC가 지정된 경우 타이머를 DPC에 연결합니다.
타이머가 이미 활성 상태이면 취소합니다.
타이머를 활성화하고 타이머의 기한 및 기간을 지정된 값으로 설정합니다. 지정된 기한이 이미 경과한 경우 타이머가 즉시 만료될 수 있습니다.

KeSetTimerEx 루틴은 KeSetCoalescableTimer과 유사하지만 TolerableDelay 매개 변수를 허용하지 않습니다. KeSetCoalescableTimer의 TolerableDelay 매개 변수를 사용하면 호출자가 타이머 기간에 대한 허용 오차를 지정할 수 있습니다. TolerableDelay = 0이 있는 KeSetCoalescableTimer에 대한 호출은 KeSetTimerEx 호출과 동일합니다. 대부분의 경우 개발자는 KeSetTimerEx 호출을 KeSetCoalescableTimer 호출로 바꾸어 기존 드라이버를 쉽게 수정할 수 있습니다.

두 개의 KeSetCoalescableTimer 호출이 동일한 타이머 개체를 지정하고 첫 번째 호출에 대해 지정된 DueTime 이 만료되기 전에 두 번째 호출이 발생하는 경우 두 번째 호출은 첫 번째 호출에서 타이머를 암시적으로 취소합니다. 그러나 첫 번째 호출에서 타이머 만료가 이미 DPC를 실행할 수 있도록 설정한 경우 타이머가 취소된 후 DPC가 실행될 수 있습니다. 두 번째 호출은 첫 번째 호출의 보류 중인 만료 시간을 새 만료 시간으로 바꾸고 타이머를 다시 활성화합니다.

Period 매개 변수가 0이 아닌 경우 타이머는 주기적입니다. 주기적인 타이머의 경우 DueTime 매개 변수로 표시된 시간에 첫 번째 타이머 만료가 발생합니다. 이후 만료는 Period로 지정된 간격으로 구분됩니다. Period = 0이면 타이머가 비페리오딕이며 DueTime으로 표시된 시점에 만료됩니다.

Dpc 매개 변수가 NULL이 아닌 경우 루틴은 지정된 DPC 개체와 타이머 개체 간의 연결을 만듭니다. 타이머가 만료되면 타이머 서비스는 시스템 타이머 큐에서 타이머 개체를 제거하고 이 개체를 신호 상태로 설정합니다. DPC 개체가 타이머 개체와 연결된 경우 타이머 서비스는 조건이 허용하는 즉시 실행되도록 DPC 개체를 시스템 DPC 큐에 삽입합니다.

특정 DPC 개체의 instance 한 번에 하나의 시스템 DPC 큐에 있을 수 있습니다. 잠재적인 경합 상태를 방지하려면 동일한 DPC 개체를 KeSetCoalescableTimer 및 KeInsertQueueDpc 루틴 모두에 전달하지 않도록 합니다.

활성 타이머와 연결된 DPC의 중요도 또는 대상 프로세서를 변경하지 않습니다. 타이머를 취소하거나 KeSetImportanceDpc 또는 KeSetTargetProcessorDpcEx 와 같은 루틴을 호출하기 전에 타이머가 만료되었는지 확인하여 DPC 설정을 변경합니다. 예를 들어 드라이버가 DPC의 대상 프로세서를 업데이트하고 타이머가 DPC를 실행할 수 있게 하는 경우 DPC는 임의의 프로세서에서 실행될 수 있습니다.

정기 타이머는 만료되는 즉시 자동으로 다시 시작됩니다. 따라서 다중 프로세서 시스템에서는 주기적 타이머에 대한 DPC가 두 개 이상의 프로세서에서 동시에 실행될 수 있습니다.

드라이버는 언로드 루틴에서 활성 타이머를 취소해야 합니다. KeCancelTimer 루틴을 호출하여 타이머를 취소합니다. DPC가 주기적이거나 최근에 만료되었을 수 있는 타이머와 연결된 경우 드라이버는 모든 프로세서에서 보류 중인 모든 DPC 실행이 완료될 때까지 DPC 및 관련 데이터를 해제하기 위해 대기해야 합니다(예: KeFlushQueuedDpcs 루틴 호출).

KeSetCoalescableTimer 은 TolerableDelay 매개 변수를 사용하여 타이머 병합을 수행합니다. 즉, 루틴은 타이머가 다른 소프트웨어 타이머의 만료 시간과 일치하도록 만료 시간을 조정합니다. 타이머 병합은 운영 체제가 전력 소비를 줄이고 에너지 효율을 향상시킬 수 있도록 유휴 기간의 길이를 늘리는 데 도움이 됩니다.

타이머 병합을 효과적으로 사용하려면 호출자가 32밀리초 이상의 TolerableDelay 값을 지정해야 합니다. 이 값은 15.6밀리초의 두 기본 시스템 클록 간격과 같습니다. 가능한 경우 100밀리초와 같은 더 큰 TolerableDelay 값을 사용합니다.

Period 및 TolerableDelay 값을 50밀리초의 배수로 지정해 보세요. 일반적인 기간 값은 50, 100, 250, 500 및 1000밀리초입니다. 일반적인 TolerableDelay 값은 50, 100, 150 및 250밀리초입니다.

일반적으로 Period 값이 큰 타이머는 비례적으로 큰 TolerableDelay 값을 사용할 수 있습니다. 예를 들어 Period = 500밀리초의 타이머는 TolerableDelay = 50밀리초를 사용할 수 있지만 Period = 10초인 타이머는 TolerableDelay = 1초를 사용할 수 있습니다.

만료 시간은 시스템 클록을 기준으로 측정되며, 타이머가 만료되는 시기를 운영 체제에서 감지할 수 있는 정확도는 시스템 클록의 세분성에 의해 제한됩니다. 자세한 내용은 타이머 정확도를 참조하세요.

타이머 개체에 대한 자세한 내용은 타이머 개체 및 DPC를 참조하세요. 타이머 병합에 대한 자세한 내용은 WHDC 웹 사이트의 Windows 타이머 병합 백서를 참조하세요.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows 7부터 사용할 수 있습니다.
대상 플랫폼	유니버설
헤더	wdm.h(Wdm.h, Ntddk.h, Ntifs.h 포함)
라이브러리	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL