Funzione KeSetCoalescableTimer (wdm.h)
La routine KeSetCoalescableTimer imposta l'ora di scadenza iniziale e il periodo di un oggetto timer e specifica quanto ritardo può essere tollerato negli orari di scadenza.
Sintassi
BOOLEAN KeSetCoalescableTimer(
[in, out] PKTIMER Timer,
[in] LARGE_INTEGER DueTime,
[in] ULONG Period,
[in] ULONG TolerableDelay,
[in, optional] PKDPC Dpc
);
Parametri
[in, out] Timer
Puntatore a un oggetto timer. Questo parametro punta a una struttura KTIMER , ovvero una struttura di sistema opaca che rappresenta l'oggetto timer. Questo oggetto deve essere stato inizializzato in precedenza dalla routine KeInitializeTimerEx o KeInitializeTimer.
[in] DueTime
Specifica un tempo assoluto o relativo in corrispondenza del quale il timer deve scadere. Se il valore del parametro DueTime è negativo, l'ora di scadenza è relativa all'ora di sistema corrente. In caso contrario, l'ora di scadenza è assoluta. L'ora di scadenza è espressa in unità temporali di sistema, ovvero intervalli di 100 nanosecondi. I tempi di scadenza assoluti tengono traccia delle modifiche apportate all'orologio di sistema. Le ore di scadenza relative non sono interessate dalle modifiche dell'orologio di sistema.
[in] Period
Specifica l'intervallo tra le scadenze del timer periodico in millisecondi. Il valore di questo parametro non deve superare MAXLONG. Questo parametro è facoltativo e può essere impostato su zero per indicare che il timer non èperiodic.
[in] TolerableDelay
Specifica una tolleranza, in millisecondi, per il periodo timer specificato da Period e per l'intervallo di tempo iniziale specificato da DueTime . Per un timer periodico, l'intervallo di tempo tra due scadenze timer successive sarà compreso nell'intervallo compreso tra (PeriodTolerableDelay) e (Period - + TolerableDelay). L'ora di scadenza iniziale sarà compreso nell'intervallo da DueTimea (DueTime + TolerableDelay). Il valore TolerableDelay non può essere negativo.
[in, optional] Dpc
Puntatore a un oggetto DPC. Questo parametro punta a una struttura KDPC , ovvero una struttura di sistema opaca che rappresenta l'oggetto DPC. Questo oggetto deve essere stato inizializzato in precedenza dalla routine KeInitializeDpc . Questo parametro è facoltativo e può essere specificato come NULL se il chiamante non richiede un DPC.
Valore restituito
KeSetCoalescableTimer restituisce TRUE se l'oggetto timer era già nella coda timer di sistema. In caso contrario, restituisce FALSE.
Commenti
Questa routine esegue le operazioni seguenti:
Imposta il timer su uno stato non segnalato.
Associa il timer al DPC, se è specificato un DPC.
Annulla il timer se è già attivo.
Rende attivo il timer e imposta il periodo di tempo e periodo di tempo del timer sui valori specificati. Il timer può scadere immediatamente se il tempo di scadenza specificato è già passato.
La routine KeSetTimerEx è simile a KeSetCoalescableTimer , ma non accetta un parametro TolerableDelay . Il parametro TolerableDelay di KeSetCoalescableTimer consente al chiamante di specificare una tolleranza per il periodo timer. Una chiamata a KeSetCoalescableTimer con TolerableDelay = 0 è uguale a una chiamata a KeSetTimerEx. In molte istanze gli sviluppatori possono modificare facilmente i driver esistenti sostituendo le chiamate a KeSetTimerEx con chiamate a KeSetCoalescableTimer.
Se due chiamate KeSetCoalescableTimer specificano lo stesso oggetto timer e la seconda chiamata viene eseguita prima della scadenza della prima chiamata, la seconda chiamata annulla implicitamente il timer dalla prima chiamata. Tuttavia, se una scadenza timer dalla prima chiamata ha già abilitato l'esecuzione di un DPC, il DPC potrebbe essere eseguito dopo l'annullamento del timer. La seconda chiamata sostituisce l'ora di scadenza in sospeso dalla prima chiamata con una nuova ora di scadenza e attiva di nuovo il timer.
Se il parametro Period è diverso da zero, il timer è periodico. Per un timer periodico, la scadenza del primo timer si verifica al momento indicato dal parametro DueTime . Le scadenze successive sono separate dall'intervallo specificato da Period. Se Period = 0, il timer non èperiodic e scade al momento indicato da DueTime.
Se il parametro Dpc non è NULL, la routine crea un'associazione tra l'oggetto DPC specificato e l'oggetto timer. Dopo la scadenza del timer, il servizio timer rimuove l'oggetto timer dalla coda timer di sistema e imposta questo oggetto su uno stato segnalato. Se un oggetto DPC è associato all'oggetto timer, il servizio timer inserisce l'oggetto DPC nella coda DPC di sistema per l'esecuzione non appena consentite le condizioni.
Solo un'istanza di un particolare oggetto DPC può trovarsi nella coda DPC del sistema alla volta. Per evitare potenziali condizioni di gara, evitare di passare lo stesso oggetto DPC alle routine KeSetCoalescableTimer e KeInsertQueueDpc .
Evitare di modificare l'importanza o il processore di destinazione di un DPC associato a un timer attivo. Annullare il timer o assicurarsi che il timer sia scaduto prima di chiamare una routine come KeSetImportanceDpc o KeSetTargetProcessorDpcEx per modificare le impostazioni DPC. Ad esempio, se un driver aggiorna il processore di destinazione di un DPC mentre un timer consente all'esecuzione del DPC, il DPC potrebbe essere eseguito in un processore arbitrario.
Un timer periodico viene riavviato automaticamente non appena scade. Pertanto, in un sistema multiprocessore, il DPC per un timer periodico potrebbe essere in esecuzione su due o più processori contemporaneamente.
I driver devono annullare tutti i timer attivi nelle routine di scaricamento . Chiamare la routine KeCancelTimer per annullare un timer. Se un DPC è associato a un timer periodico o che potrebbe essere scaduto di recente, un driver deve attendere (ad esempio, chiamando la routine KeFlushQueuedDpcs ) per liberare il DPC e i relativi dati associati fino al termine di tutte le esecuzioni DPC in sospeso su tutti i processori.
KeSetCoalescableTimer usa il parametro TolerableDelay per eseguire il coalescing timer. Vale a dire, la routine regola i tempi di scadenza per il timer in modo da coincidere con i tempi di scadenza di altri timer software. Il carbone del timer consente di aumentare la lunghezza dei periodi di inattività in modo che il sistema operativo possa ridurre il consumo di energia e migliorare l'efficienza energetica.
Per usare in modo efficace il coalescing timer, un chiamante deve specificare un valore TolerableDelay di almeno 32 millisecondi. Questo valore equivale a due intervalli di orologio di sistema predefiniti di 15,6 millisecondi. Se è possibile, usare un valore TolerableDelay più grande, ad esempio 100 millisecondi.
Provare a specificare i valori Period e TolerableDelay in più di 50 millisecondi. I valori di periodo tipici sono 50, 100, 250, 500 e 1000 millisecondi. I valori TolerableDelay tipici sono 50, 100, 150 e 250 millisecondi.
In genere, un timer con un valore Period di grandi dimensioni può usare un valore TolerableDelay proporzionalmente grande. Ad esempio, un timer con Period = 500 millisecondi potrebbe usare TolerableDelay = 50 millisecondi, ma un timer con Period = 10 secondi potrebbe usare TolerableDelay = 1 secondo.
I tempi di scadenza vengono misurati rispetto all'orologio di sistema e l'accuratezza con cui il sistema operativo può rilevare quando scade un timer è limitato dalla granularità dell'orologio di sistema. Per altre informazioni, vedere Accuratezza timer.
Per altre informazioni sugli oggetti timer, vedere Oggetti timer e schede di rete. Per altre informazioni sul coalescing timer, vedere il white paper di Coalescing timer di Windows nel sito Web WHDC.
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Disponibile a partire da Windows 7. |
| Piattaforma di destinazione | Universale |
| Intestazione | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| Libreria | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | <= DISPATCH_LEVEL |