KeSetCoalescableTimer-Funktion (wdm.h)

Artikel
02/27/2024

Die KeSetCoalescableTimer-Routine legt die anfängliche Ablaufzeit und den Zeitraum eines Timerobjekts fest und gibt an, wie viel Verzögerung in den Ablaufzeiten toleriert werden kann.

Syntax

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

Parameter

[in, out] Timer

Ein Zeiger auf ein Timerobjekt. Dieser Parameter verweist auf eine KTIMER-Struktur , bei der es sich um eine undurchsichtige Systemstruktur handelt, die das Timerobjekt darstellt. Dieses Objekt muss zuvor von der KeInitializeTimerEx - oder KeInitializeTimer-Routine initialisiert worden sein.

[in] DueTime

Gibt einen absoluten oder relativen Zeitpunkt an, zu dem der Timer abläuft. Wenn der Wert des DueTime-Parameters negativ ist, ist die Ablaufzeit relativ zur aktuellen Systemzeit. Andernfalls ist die Ablaufzeit absolut. Die Ablaufzeit wird in Systemzeiteinheiten ausgedrückt, die 100-Nanosekunden-Intervalle sind. Absolute Ablaufzeiten verfolgen alle Änderungen, die an der Systemuhr vorgenommen werden. Relative Ablaufzeiten werden von Systemuhränderungen nicht beeinflusst.

[in] Period

Gibt das Intervall zwischen periodischen Timerablaufen in Millisekunden an. Der Wert dieses Parameters darf MAXLONG nicht überschreiten. Dieser Parameter ist optional und kann auf null festgelegt werden, um anzugeben, dass der Timer nichtperiodisch ist.

[in] TolerableDelay

Gibt eine Toleranz in Millisekunden für den Zeitgeberzeitraum an, der von Period angegeben wird, und für das anfängliche Zeitintervall, das DueTime angibt. Bei einem periodischen Timer liegt das Zeitintervall zwischen zwei aufeinander folgenden Timerablaufzeiten im Bereich von (Period - TolerableDelay) bis (Period + TolerableDelay). Die anfängliche Ablaufzeit liegt im Bereich von DueTime bis (DueTime + TolerableDelay). Der TolerableDelay-Wert darf nicht negativ sein.

[in, optional] Dpc

Ein Zeiger auf ein DPC-Objekt. Dieser Parameter verweist auf eine KDPC-Struktur , bei der es sich um eine undurchsichtige Systemstruktur handelt, die das DPC-Objekt darstellt. Dieses Objekt muss zuvor von der KeInitializeDpc-Routine initialisiert worden sein. Dieser Parameter ist optional und kann als NULL angegeben werden, wenn der Aufrufer keinen DPC erfordert.

Rückgabewert

KeSetCoalescableTimer gibt TRUE zurück, wenn sich das Timerobjekt bereits in der Systemtimerwarteschlange befand. Andernfalls wird FALSE zurückgegeben.

Hinweise

Diese Routine führt Folgendes aus:

Legt den Timer auf einen nicht signalisierenden Zustand fest.
Ordnet den Timer dem DPC zu, wenn ein DPC angegeben wird.
Bricht den Timer ab, wenn er bereits aktiv ist.
Aktiviert den Timer und legt die fällige Zeit und den Zeitraum des Timers auf die angegebenen Werte fest. Der Timer kann sofort ablaufen, wenn die angegebene Fälligkeitszeit bereits abgelaufen ist.

Die KeSetTimerEx-Routine ähnelt KeSetCoalescableTimer , akzeptiert jedoch keinen TolerableDelay-Parameter . Mit dem TolerableDelay-Parameter von KeSetCoalescableTimer kann der Aufrufer eine Toleranz für den Zeitgeberzeitraum angeben. Ein Aufruf von KeSetCoalescableTimer mit TolerableDelay = 0 ist identisch mit einem Aufruf von KeSetTimerEx. In vielen Fällen können Entwickler vorhandene Treiber einfach ändern, indem Aufrufe von KeSetTimerEx durch Aufrufe von KeSetCoalescableTimer ersetzt werden.

Wenn zwei KeSetCoalescableTimer-Aufrufe das gleiche Timerobjekt angeben und der zweite Aufruf erfolgt, bevor die für den ersten Aufruf angegebene DueTime abläuft, wird der Timer des ersten Aufrufs implizit abgebrochen. Wenn jedoch ein Timerablauf seit dem ersten Aufruf bereits die Ausführung eines DPC aktiviert hat, kann der DPC ausgeführt werden, nachdem der Timer abgebrochen wurde. Der zweite Aufruf ersetzt die ausstehende Ablaufzeit des ersten Aufrufs durch eine neue Ablaufzeit und aktiviert den Timer erneut.

Wenn der Period-Parameter ungleich null ist, ist der Timer periodisch. Bei einem regelmäßigen Timer tritt der erste Timerablauf zu dem Zeitpunkt auf, der durch den DueTime-Parameter angegeben wird. Spätere Ablaufvorgänge werden durch das durch Period angegebene Intervall getrennt. Wenn Period = 0 ist, ist der Timer nichtperiodisch und läuft zu dem Zeitpunkt ab, der durch DueTime angegeben wird.

Wenn der Dpc-Parameter nicht NULL ist, erstellt die Routine eine Zuordnung zwischen dem angegebenen DPC-Objekt und dem Timerobjekt. Nach Ablauf des Zeitgebers entfernt der Zeitgeberdienst das Timerobjekt aus der Systemtimerwarteschlange und legt dieses Objekt auf einen signalierten Zustand fest. Wenn dem Timerobjekt ein DPC-Objekt zugeordnet ist, fügt der Zeitgeberdienst das DPC-Objekt in die DPC-Systemwarteschlange ein, um ausgeführt zu werden, sobald die Bedingungen dies zulassen.

Es kann jeweils nur ein instance eines bestimmten DPC-Objekts in der DPC-Warteschlange des Systems enthalten sein. Um potenzielle Racebedingungen zu vermeiden, vermeiden Sie es, dasselbe DPC-Objekt an die Routinen KeSetCoalescableTimer und KeInsertQueueDpc zu übergeben.

Vermeiden Sie es, die Wichtigkeit oder den Zielprozessor eines DPC zu ändern, der einem aktiven Timer zugeordnet ist. Brechen Sie entweder den Timer ab, oder stellen Sie sicher, dass der Timer abgelaufen ist, bevor Sie eine Routine wie KeSetImportanceDpc oder KeSetTargetProcessorDpcEx aufrufen, um die DPC-Einstellungen zu ändern. Wenn beispielsweise ein Treiber den Zielprozessor eines DPC aktualisiert, während ein Timer die Ausführung des DPC ermöglicht, kann der DPC auf einem beliebigen Prozessor ausgeführt werden.

Ein regelmäßiger Timer wird automatisch neu gestartet, sobald er abläuft. Daher kann der DPC für einen regelmäßigen Timer in einem Multiprozessorsystem auf zwei oder mehr Prozessoren gleichzeitig ausgeführt werden.

Treiber müssen alle aktiven Timer in ihren Entladeroutinen abbrechen. Rufen Sie die KeCancelTimer-Routine auf, um einen Timer abzubrechen. Wenn ein DPC einem regelmäßigen oder kürzlich abgelaufenen Timer zugeordnet ist, muss ein Treiber warten (z. B. durch Aufrufen der KeFlushQueuedDpcs-Routine ), um den DPC und die zugehörigen Daten freizusetzen, bis alle ausstehenden DPC-Ausführungen auf allen Prozessoren abgeschlossen sind.

KeSetCoalescableTimer verwendet den Parameter TolerableDelay , um timer-Zusammenführung durchzuführen. Das heißt, die Routine passt die Ablaufzeiten für den Timer an die Ablaufzeiten anderer Softwaretimer an. Timer-Zusammenführung trägt dazu bei, die Dauer der Leerlaufzeiten zu erhöhen, damit das Betriebssystem den Stromverbrauch senken und die Energieeffizienz verbessern kann.

Um die Timer-Zusammenführung effektiv zu verwenden, sollte ein Aufrufer einen TolerableDelay-Wert von mindestens 32 Millisekunden angeben. Dieser Wert entspricht zwei Standarduhrintervallen von 15,6 Millisekunden. Wenn möglich, verwenden Sie einen größeren TolerableDelay-Wert , z. B. 100 Millisekunden.

Versuchen Sie, die Werte Period und TolerableDelay in Vielfachen von 50 Millisekunden anzugeben. Typische Periodenwerte sind 50, 100, 250, 500 und 1000 Millisekunden. Typische TolerableDelay-Werte sind 50, 100, 150 und 250 Millisekunden.

In der Regel kann ein Timer mit einem großen Period-Wert einen proportional großen TolerableDelay-Wert verwenden. Beispielsweise kann ein Timer mit Period = 500 Millisekunden TolerableDelay = 50 Millisekunden verwenden, aber ein Timer mit Period = 10 Sekunden kann TolerableDelay = 1 Sekunde verwenden.

Ablaufzeiten werden relativ zur Systemuhr gemessen, und die Genauigkeit, mit der das Betriebssystem erkennen kann, wann ein Timer abläuft, wird durch die Granularität der Systemuhr begrenzt. Weitere Informationen finden Sie unter Timergenauigkeit.

Weitere Informationen zu Timerobjekten finden Sie unter Timerobjekte und DPCs. Weitere Informationen zum Zusammenfügen von Zeitgebern finden Sie im Whitepaper Windows Timer Coalescing auf der WHDC-Website.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar ab Windows 7.
Zielplattform	Universell
Header	wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL