Funzione NdisSetCoalescableTimerObject (ndis.h)

La funzione NdisSetCoalescableTimerObject imposta un oggetto timer che il sistema operativo coordina con altri timer, in genere per ridurre il consumo di energia, quando la scadenza esatta del timer non è importante per l'operazione driver.

Sintassi

BOOLEAN NdisSetCoalescableTimerObject(
  [in]           NDIS_HANDLE   TimerObject,
  [in]           LARGE_INTEGER DueTime,
  [in, optional] LONG          MillisecondsPeriod,
  [in, optional] PVOID         FunctionContext,
  [in, optional] ULONG         Tolerance
);

Parametri

[in] TimerObject

Handle per un oggetto timer fornito da NDIS quando un driver chiama Funzione NdisAllocateTimerObject .

[in] DueTime

Ora assoluta o relativa alla scadenza del timer. 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 viene espressa nelle unità temporali di sistema (intervalli di 100 nanosecondi). I tempi di scadenza assoluti tengono traccia delle modifiche apportate all'ora di sistema; le ore di scadenza relative non sono interessate dalle modifiche all'ora di sistema.

[in, optional] MillisecondsPeriod

Intervallo di tempo periodico facoltativo, in millisecondi, trascorso tra ogni istanza quando il timer viene attivato e la chiamata successiva alla funzione NetTimerCallback , a meno che il timer non venga annullato. Il valore di questo parametro deve essere minore o uguale a MAXLONG. Questo parametro può essere impostato su zero per indicare che il timer non è periodico.

[in, optional] FunctionContext

Puntatore a un'area di contesto fornita dal chiamante che NDIS passa alla funzione NetTimerCallback associata quando viene attivato un timer. Se questo parametro è NULL, NDIS usa il valore predefinito specificato nell'oggetto NDIS_TIMER_CHARACTERISTICS struttura.

[in, optional] Tolerance

La tolleranza, in millisecondi, tra il periodo timer specificato da MillisecondsPeriod e l'intervallo di tempo iniziale specificato da DueTime . Un timer periodico scade per la prima volta nell'intervallo di tempo tra ( Tolleranza DueTime) e (TolleranzaDueTime - + ). L'intervallo di tempo tra due scadenze successive di un timer periodico sarà compreso nell'intervallo di ( MillisecondsPeriodTolerance ) e (TolleranzamillisecondiPeriod - + ).

Valore restituito

NdisSetCoalescableTimerObject restituisce TRUE se l'oggetto timer era già nella coda timer di sistema; in caso contrario, restituisce FALSE.

Commenti

Un oggetto timer impostato da questa funzione opera allo stesso modo di un timer impostato da NdisSetTimerObject, con un valore di tolleranza aggiuntivo aggiunto al parametro di scadenza DueTime . Il sistema operativo usa questo valore di tolleranza aggiuntivo per modificare l'ora di scadenza del timer per coincidere con la scadenza di altri timer software. A questo scopo, il sistema operativo può ridurre il consumo di energia e migliorare l'efficienza energetica.

NdisSetTimerObject funziona in modo analogo a NdisSetCoalescableTimerObject quando La tolleranza è impostata su zero.

Dopo che un driver chiama NdisSetCoalescableTimerObject, l'oggetto timer viene accodato fino alla scadenza di un intervallo compreso nell'intervallo di (Tolleranza DueTime ) e (TolleranzaDueTime - + ). Dopo la scadenza dell'intervallo, il sistema operativo rimuove l'oggetto timer dalla coda e la funzione NetTimerCallback fornita dal chiamante viene eseguita una sola volta in IRQL = DISPATCH_LEVEL non appena un processore diventa disponibile.

Se nel parametro MillisecondsPeriod viene specificato un valore diverso da zero, l'oggetto timer viene accodato di nuovo fino a quando un intervallo nell'intervallo di ( MillisecondsPeriodTolerance ) e ( MillisecondsPeriod + - Tolerance ) scade. Dopo la scadenza di questo intervallo, l'oggetto timer viene nuovamente inviato alla coda e la funzione NetTimerCallback fornita dal chiamante viene eseguita una sola volta in IRQL = DISPATCH_LEVEL non appena un processore diventa disponibile.

Per usare in modo efficace il coalescing timer, un chiamante deve specificare un valore di tolleranza di almeno 32 millisecondi. Questo valore equivale a circa due intervalli di orologio di sistema predefiniti di 15,6 millisecondi. Usare un valore di tolleranza più grande se è possibile eseguire questa operazione, ad esempio 100 millisecondi.

È consigliabile impostare MillisecondsPeriod e Tolerance su più di 50 millisecondi. I valori tipici millisecondiPeriod sono 50, 100, 250, 500 e 1000 millisecondi. I valori di tolleranza tipici sono 50, 100, 150 e 250 millisecondi.

In genere, un timer con un valore millisecondiPeriod di grandi dimensioni può usare un valore di tolleranza proporzionalemente elevato. Ad esempio, un timer con MillisecondsPeriod = 500 millisecondi potrebbe usare Tolerance = 50 millisecondi. Ma un timer con MillisecondsPeriod = 10 secondi potrebbe usare Tolleranza = 1 secondo.

Per altre informazioni sul comportamento timer, vedere KeSetTimerEx.

Per annullare un timer, chiamare la funzione NdisCancelTimerObject .

Requisiti

Vedi anche

KeSetTimerEx

NDIS_TIMER_CHARACTERISTICS

NdisAllocateTimerObject

NdisCancelTimerObject

NdisSetTimerObject

NetTimerCallback