KeSetCoalescableTimer-Funktion (wdm.h)
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 eine absolute oder relative Uhrzeit an, zu der 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 Timerablauf 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 Period angibt, und für das anfängliche Zeitintervall, das DueTime- angibt. Bei einem periodischen Timer befindet sich das Zeitintervall zwischen zwei aufeinander folgenden Zeitgeberablaufen im Bereich von (Zeitraum - TolerableDelay) bis (Zeitraum + TolerableDelay). Die anfängliche Ablaufzeit liegt zwischen DueTime- und (DueTime + TolerableDelay). Der wert TolerableDelay kann 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 Systemzeitgeberwarteschlange befand. Andernfalls wird FALSE-zurückgegeben.
Bemerkungen
Diese Routine führt folgende Aktionen aus:
Legt den Timer auf einen nicht signalgesteuerten Zustand fest.
Ordnet den Timer dem DPC zu, wenn ein DPC angegeben ist.
Bricht den Timer ab, wenn er bereits aktiv ist.
Macht den Timer aktiv und legt die Fälligkeitszeit und den Zeitraum des Timers auf die angegebenen Werte fest. Der Timer kann sofort ablaufen, wenn die angegebene Fälligkeitszeit bereits vergangen 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 ganz einfach ändern, indem Aufrufe an KeSetTimerEx durch Aufrufe von KeSetCoalescableTimerersetzt werden.
Wenn zwei KeSetCoalescableTimer- Aufrufe dasselbe Timerobjekt angeben und der zweite Aufruf vor ablaufen der für den ersten Aufruf angegebenen DueTime- erfolgt, wird der zweite Aufruf implizit vom timer vom ersten Aufruf abgebrochen. Wenn jedoch ein Timerablauf vom ersten Aufruf bereits eine DPC-Ausführung aktiviert hat, kann der DPC ausgeführt werden, nachdem der Timer abgebrochen wurde. Der zweite Aufruf ersetzt die ausstehende Ablaufzeit vom ersten Aufruf durch eine neue Ablaufzeit und aktiviert den Timer erneut.
Wenn der Period Parameter ungleich Null ist, ist der Timer periodisch. Bei einem periodischen Timer erfolgt der erste Timerablauf zu dem Zeitpunkt, der durch den DueTime-parameter angegeben wird. Spätere Ablaufzeiten werden durch das Intervall getrennt, das durch Periodangegeben wird. Wenn Zeitraum = 0 ist, ist der Timer nichtperiodisch und läuft zum Zeitpunkt ab, der durch DueTime-angegeben wird.
Wenn der Dpc--Parameter nichtNULL-ist, erstellt die Routine eine Zuordnung zwischen dem angegebenen DPC-Objekt und dem Timerobjekt. Nach Ablauf des Timers entfernt der Zeitgeberdienst das Timerobjekt aus der Systemzeitgeberwarteschlange und legt dieses Objekt auf einen signalierten Zustand fest. Wenn ein DPC-Objekt dem Timerobjekt zugeordnet ist, fügt der Timerdienst das DPC-Objekt in die DPC-Systemwarteschlange ein, damit es ausgeführt wird, sobald bedingungen zulässig sind.
In der DPC-Warteschlange des Systems kann jeweils nur eine Instanz eines bestimmten DPC-Objekts vorhanden sein. Um potenzielle Racebedingungen zu vermeiden, vermeiden Sie, dasselbe DPC-Objekt an die KeSetCoalescableTimer und KeInsertQueueDpc Routinen zu übergeben.
Vermeiden Sie das Ändern der Wichtigkeit oder des Zielprozessors eines DPC, der einem aktiven Timer zugeordnet ist. Abbrechen Sie den Timer, 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 periodischer Timer wird automatisch neu gestartet, sobald er abläuft. Daher kann der DPC für einen regelmäßigen Timer in einem Multiprozessorsystem gleichzeitig auf zwei oder mehr Prozessoren ausgeführt werden.
Treiber müssen alle aktiven Timer in ihren Unload Routinen abbrechen. Rufen Sie die KeCancelTimer Routine auf, um einen Timer abzubrechen. Wenn ein DPC einem periodischen Zeitgeber zugeordnet ist oder der kürzlich abgelaufen ist, muss ein Treiber warten (z. B. durch Aufrufen der KeFlushQueuedDpcs Routine), um den DPC und die zugehörigen Daten freizuschalten, bis alle ausstehenden DPC-Ausführungen auf allen Prozessoren abgeschlossen sind.
KeSetCoalescableTimer verwendet die TolerableDelay--Parameter zum Ausführen der Zeitgeber-Zusammenlegung. Das heißt, die Routine passt die Ablaufzeiten für den Timer so an, dass sie mit den Ablaufzeiten anderer Softwaretimer übereinstimmen. Timer-Zusammenführung trägt dazu bei, die Länge der Leerlaufzeiten zu erhöhen, sodass das Betriebssystem den Stromverbrauch reduzieren und die Energieeffizienz verbessern kann.
Um zeitgeberkonsentiert zu verwenden, sollte ein Aufrufer eine 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 Zeitraum- Werte 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. Ein Timer mit Punkt = 500 Millisekunden kann z. B. TolerableDelay- = 50 Millisekunden verwenden, aber ein Timer mit Punkt = 10 Sekunden kann TolerableDelay = 1 Sekunde verwenden.
Die Ablaufzeiten werden relativ zur Systemuhr gemessen, und die Genauigkeit, mit der das Betriebssystem erkennen kann, wann ein Timer abläuft, ist durch die Granularität der Systemuhr begrenzt. Weitere Informationen finden Sie unter Zeitgebergenauigkeit.
Weitere Informationen zu Timerobjekten finden Sie unter timer Objects and DPCs. Weitere Informationen zum Zusammenwachsen von Zeitgebern finden Sie in der Windows Timer Coalescing Whitepaper auf der WHDC-Website.
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Verfügbar ab Windows 7. |
| Zielplattform- | Universal |
| Header- | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| Library | NtosKrnl.lib |
| DLL- | NtosKrnl.exe |
| IRQL- | <= DISPATCH_LEVEL |