Funzione SetThreadpoolTimerEx (threadpoolapiset.h)

Articolo
03/09/2024

Imposta l'oggetto timer, sostituendo il timer precedente, se presente. Un thread di lavoro chiama il callback dell'oggetto timer dopo la scadenza del timeout specificato.

Sintassi

BOOL SetThreadpoolTimerEx(
  [in, out]      PTP_TIMER pti,
  [in, optional] PFILETIME pftDueTime,
  [in]           DWORD     msPeriod,
  [in, optional] DWORD     msWindowLength
);

Parametri

[in, out] pti

Puntatore a una struttura TP_TIMER che definisce l'oggetto timer da impostare. La funzione CreateThreadpoolTimer restituisce questo puntatore.

[in, optional] pftDueTime

Puntatore a una struttura FILETIME che specifica il tempo assoluto o relativo in corrispondenza del quale il timer deve scadere. Se questo parametro punta a un valore positivo, indica l'ora assoluta dal 1° gennaio 1601 (UTC), misurata in 100 unità nanosecondi. Se questo parametro punta a un valore negativo, indica la quantità di tempo di attesa rispetto all'ora corrente. Se questo parametro punta a zero, il timer scade immediatamente. Per altre informazioni sui valori temporali, vedere Tempi file.

Se questo parametro è NULL, l'oggetto timer smetterà di accodare nuovi callback (ma i callback già accodati si verificheranno ancora).

Il timer viene impostato se il parametro pftDueTime non è NULL.

[in] msPeriod

Periodo timer, in millisecondi. Se questo parametro è zero, il timer viene segnalato una volta. Se questo parametro è maggiore di zero, il timer è periodico. Un timer periodico reagisce automaticamente ogni volta che il periodo viene trascorso, fino a quando il timer non viene annullato.

[in, optional] msWindowLength

La quantità massima di tempo che il sistema può ritardare prima di chiamare il callback timer. Se questo parametro è impostato, il sistema può eseguire chiamate batch per risparmiare energia.

Valore restituito

Restituisce TRUE se il timer è stato impostato in precedenza ed è stato annullato. In caso contrario restituisce FALSE.

Se lo stato precedente del timer è stato "impostato" e la funzione restituisce FALSE, un callback è in corso o sta per iniziare. Vedere le osservazioni per ulteriori discussioni.

Commenti

L'impostazione del timer annulla il timer precedente, se presente.

In alcuni casi, le funzioni di callback potrebbero essere eseguite dopo che un'applicazione chiude il timer del threadpool. Per evitare questo comportamento, un'applicazione deve seguire i passaggi descritti in CloseThreadpoolTimer.

Se il tempo di scadenza specificato da pftDueTime è relativo, il tempo trascorso dal sistema nel sonno o nell'ibernazione non viene conteggiato verso la scadenza del timer. Il timer viene segnalato quando la quantità cumulativa di tempo trascorso il sistema passa nello stato di sveglia equivale al tempo relativo o al periodo di tempo relativo del timer. Se il tempo di scadenza specificato da pftDueTime è assoluto, il tempo trascorso dal sistema nel sonno o nell'ibernazione viene conteggiato verso la scadenza del timer. Se il timer scade mentre il sistema sta dormendo, il timer viene segnalato immediatamente quando il sistema viene riattivato.

Per compilare un'applicazione che usa questa funzione, definire _WIN32_WINNT come 0x0600 o versione successiva.

Esempio

Per un esempio, vedere Uso delle funzioni del pool di thread.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 8 [app desktop \| App UWP]
Server minimo supportato	Windows Server 2012 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	threadpoolapiset.h
Libreria	Kernel32.lib
DLL	Kernel32.dll