KeSetCoalescableTimer, fonction (wdm.h)
La routine KeSetCoalescableTimer définit le délai d’expiration initial et la période d’un objet minuteur et spécifie le délai pouvant être toléré dans les délais d’expiration.
Syntaxe
BOOLEAN KeSetCoalescableTimer(
[in, out] PKTIMER Timer,
[in] LARGE_INTEGER DueTime,
[in] ULONG Period,
[in] ULONG TolerableDelay,
[in, optional] PKDPC Dpc
);
Paramètres
[in, out] Timer
Pointeur vers un objet minuteur. Ce paramètre pointe vers une structure KTIMER, qui est une structure système opaque qui représente l’objet minuteur. Cet objet doit avoir été précédemment initialisé par la routine KeInitializeTimerEx ou KeInitializeTimer routine.
[in] DueTime
Spécifie une heure absolue ou relative à laquelle le minuteur doit expirer. Si la valeur du paramètre DueTime est négative, l’heure d’expiration est relative à l’heure système actuelle. Sinon, le temps d’expiration est absolu. Le temps d’expiration est exprimé en unités de temps système, qui sont des intervalles de 100 nanosecondes. Les heures d’expiration absolues suivent les modifications apportées à l’horloge système. Les délais d’expiration relatifs ne sont pas affectés par les modifications de l’horloge système.
[in] Period
Spécifie l’intervalle entre les expirations périodiques du minuteur en millisecondes. La valeur de ce paramètre ne doit pas dépasser MAXLONG. Ce paramètre est facultatif et peut être défini sur zéro pour indiquer que le minuteur n’est pas prédédicique.
[in] TolerableDelay
Spécifie une tolérance, en millisecondes, pour la période du minuteur qui Période spécifie et pour l’intervalle de temps initial qui DueTime spécifie. Pour un minuteur périodique, l’intervalle de temps entre deux expirations de minuteur successives est compris entre (Période - IntolérableDelay) à (Période + IntolérableDelay). L’heure d’expiration initiale est comprise entre DueTime et (DueTime + IntolérableDelay). La valeur IntolérableDelay ne peut pas être négative.
[in, optional] Dpc
Pointeur vers un objet DPC. Ce paramètre pointe vers une structure KDPC, qui est une structure système opaque qui représente l’objet DPC. Cet objet doit avoir été précédemment initialisé par la routine KeInitializeDpc. Ce paramètre est facultatif et peut être spécifié en tant que NULL si l’appelant ne nécessite pas de DPC.
Valeur de retour
KeSetCoalescableTimer retourne TRUE si l’objet minuteur était déjà dans la file d’attente du minuteur système. Sinon, elle retourne FALSE.
Remarques
Cette routine effectue les opérations suivantes :
Définit le minuteur à un état non signalé.
Associe le minuteur à la DPC, si un DPC est spécifié.
Annule le minuteur s’il est déjà actif.
Active le minuteur et définit l’heure et la période d’échéance du minuteur sur les valeurs spécifiées. Le minuteur peut expirer immédiatement si l’heure d’échéance spécifiée est déjà passée.
La routine KeSetTimerEx est similaire à KeSetCoalescableTimer, mais n’accepte pas de paramètre IntolérableDelay. Le paramètre IntolérableDelay de KeSetCoalescableTimer permet à l’appelant de spécifier une tolérance pour la période du minuteur. Un appel à KeSetCoalescableTimer avec IntolérableDelay = 0 est identique à un appel à KeSetTimerEx. Dans de nombreux cas, les développeurs peuvent facilement modifier les pilotes existants en remplaçant les appels à KeSetTimerEx par des appels à KeSetCoalescableTimer.
Si deux appels KeSetCoalescableTimer spécifient le même objet de minuteur et que le deuxième appel se produit avant que le DueTime spécifié pour le premier appel expire, le deuxième appel annule implicitement le minuteur du premier appel. Toutefois, si une expiration du minuteur à partir du premier appel a déjà activé l’exécution d’un DPC, le DPC peut s’exécuter après l’annulation du minuteur. Le deuxième appel remplace l’heure d’expiration en attente du premier appel par une nouvelle heure d’expiration et active à nouveau le minuteur.
Si le paramètre période n’est pas différent de zéro, le minuteur est périodique. Pour un minuteur périodique, la première expiration du minuteur se produit à l’heure indiquée par le paramètre DueTime. Les expirations ultérieures sont séparées par l’intervalle spécifié par Période. Si Période = 0, le minuteur n’est pas prédédicique et expire à l’heure indiquée par DueTime.
Si le paramètre Dpc n’est pasNULL, la routine crée une association entre l’objet DPC spécifié et l’objet minuteur. Une fois le minuteur expiré, le service du minuteur supprime l’objet minuteur de la file d’attente du minuteur système et définit cet objet à un état signalé. Si un objet DPC est associé à l’objet minuteur, le service du minuteur insère l’objet DPC dans la file d’attente DPC système pour s’exécuter dès que les conditions autorisent.
Une seule instance d’un objet DPC particulier peut se trouver dans la file d’attente DPC système à la fois. Pour éviter les conditions de course potentielles, évitez de transmettre le même objet DPC aux deux routines KeSetCoalescableTimer et KeInsertQueueDpc routines.
Évitez de modifier l’importance ou le processeur cible d’un DPC associé à un minuteur actif. Annulez le minuteur ou assurez-vous que le minuteur a expiré avant d’appeler une routine telle que KeSetImportanceDpc ou KeSetTargetProcessorDpcEx pour modifier les paramètres DPC. Par exemple, si un pilote met à jour le processeur cible d’un DPC pendant qu’un minuteur permet à la DPC d’s’exécuter, le DPC peut s’exécuter sur un processeur arbitraire.
Un minuteur périodique redémarre automatiquement dès qu’il expire. Par conséquent, dans un système multiprocesseur, le DPC d’un minuteur périodique peut s’exécuter sur deux processeurs ou plus en même temps.
Les pilotes doivent annuler les minuteurs actifs dans leurs routines Décharger. Appelez la routine KeCancelTimer pour annuler un minuteur. Si un DPC est associé à un minuteur périodique ou qui a récemment expiré, un pilote doit attendre (par exemple, en appelant les KeFlushQueuedDpcs routine) pour libérer la DPC et ses données associées jusqu’à ce que toutes les exécutions DPC en attente sur tous les processeurs se terminent.
KeSetCoalescableTimer utilise le paramètre IntolérableDelay pour effectuer la fusion du minuteur. Autrement dit, la routine ajuste les délais d’expiration du minuteur pour coïncider avec les délais d’expiration d’autres minuteurs logiciels. La fusion du minuteur permet d’augmenter la durée des périodes d’inactivité afin que le système d’exploitation puisse réduire la consommation d’énergie et améliorer l’efficacité énergétique.
Pour utiliser efficacement la fusion du minuteur, un appelant doit spécifier une valeur IntolérableDelay d’au moins 32 millisecondes. Cette valeur est égale à deux intervalles d’horloge système par défaut de 15,6 millisecondes. Si vous le pouvez, utilisez une valeur IntolérableDelay, telle que 100 millisecondes.
Essayez de spécifier les valeurs Period et IntolérableDelay en multiples de 50 millisecondes. Les valeurs de période standard sont de 50, 100, 250, 500 et 1 000 millisecondes. Les valeurs typiques IntolérableDelay sont de 50, 100, 150 et 250 millisecondes.
En règle générale, un minuteur avec une valeur de période volumineuse peut utiliser une valeur de IntolérableDelay proportionnellement importante. Par exemple, un minuteur avec Période = 500 millisecondes peut utiliser IntolérableDelay = 50 millisecondes, mais un minuteur avec Période = 10 secondes peut utiliser IntolérableDelay = 1 seconde.
Les temps d’expiration sont mesurés par rapport à l’horloge système et la précision avec laquelle le système d’exploitation peut détecter lorsqu’un minuteur expire est limité par la granularité de l’horloge système. Pour plus d’informations, consultez précision du minuteur.
Pour plus d’informations sur les objets du minuteur, consultez objets de minuteur et les contrôleurs de domaine. Pour plus d’informations sur la fusion du minuteur, consultez le Windows Timer Coalescing livre blanc sur le site web du WHDC.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Disponible à partir de Windows 7. |
| plateforme cible | Universel |
| d’en-tête | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| bibliothèque | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | <= DISPATCH_LEVEL |