KeSetCoalescableTimer, fonction (wdm.h)

Article
03/16/2023

La routine KeSetCoalescableTimer définit le délai d’expiration et la période d’expiration initiaux d’un objet minuteur et spécifie le délai qui peut ê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 .

[in] DueTime

Spécifie une heure absolue ou relative à laquelle le minuteur doit expirer. Si la valeur du paramètre DueTime est négative, le délai d’expiration est relatif à l’heure système actuelle. Sinon, le délai 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 délais d’expiration absolus suivent toutes les modifications apportées à l’horloge système. Les temps 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 ponctuel.

[in] TolerableDelay

Spécifie une tolérance, en millisecondes, pour la période du minuteur spécifiée par Period et pour l’intervalle de temps initial spécifié par DueTime . Pour un minuteur périodique, l’intervalle de temps entre deux expirations de minuteur successives est compris entre (Period - IntolérableDelay) et (Period + IntolérableDelay). L’heure d’expiration initiale est comprise entre DueTime et (DueTime + Tolé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é comme NULL si l’appelant n’a pas besoin d’un DPC.

Valeur retournée

KeSetCoalescableTimer retourne TRUE si l’objet du minuteur se trouvait 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 au 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’é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 TolerableDelay de KeSetCoalescableTimer permet à l’appelant de spécifier une tolérance pour la période du minuteur. Un appel à KeSetCoalescableTimer avec TolerableDelay = 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 l’expiration du DueTime spécifié pour le premier appel, 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, la 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 un nouveau délai d’expiration et active à nouveau le minuteur.

Si le paramètre Period est 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 point. Si Period = 0, le minuteur est non périodique et expire à l’heure indiquée par DueTime.

Si le paramètre Dpc n’est pas NULL, la routine crée une association entre l’objet DPC spécifié et l’objet minuteur. Une fois le minuteur expiré, le service de 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 qu’il s’exécute dès que les conditions le permettent.

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 routines KeSetCoalescableTimer et KeInsertQueueDpc .

É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 alors qu’un minuteur permet à la DPC de s’exécuter, la 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 au moins deux processeurs en même temps.

Les pilotes doivent annuler tous les minuteurs actifs dans leurs routines de déchargement . Appelez la routine KeCancelTimer pour annuler un minuteur. Si un DPC est associé à un minuteur périodique ou qui a peut-être récemment expiré, un pilote doit attendre (par exemple, en appelant la routine KeFlushQueuedDpcs ) 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 qu’ils coïncident avec les heures 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 plus grande, 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 50, 100, 250, 500 et 1 000 millisecondes. Les valeurs IntolérableDelay standard sont 50, 100, 150 et 250 millisecondes.

En règle générale, un minuteur avec une valeur Period élevée peut utiliser une valeur IntolérableDelay proportionnellement grande. Par exemple, un minuteur avec Period = 500 millisecondes peut utiliser IntolérableDelay = 50 millisecondes, mais un minuteur avec Period = 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 l’expiration d’un minuteur est limitée 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 DPC. Pour plus d’informations sur la fusion du minuteur, consultez le livre blanc sur la coalescation du minuteur Windows sur le site web de WHDC.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible à partir de Windows 7.
Plateforme cible	Universal
En-tête	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL