Funzione DeleteTimerQueueTimer (threadpoollegacyapiset.h)

Articolo
08/26/2023

Rimuove un timer dalla coda timer e, facoltativamente, attende il completamento delle funzioni di callback timer attualmente in esecuzione prima di eliminare il timer.

Sintassi

BOOL DeleteTimerQueueTimer(
  [in, optional] HANDLE TimerQueue,
  [in]           HANDLE Timer,
  [in, optional] HANDLE CompletionEvent
);

Parametri

[in, optional] TimerQueue

Handle per la coda timer. Questo handle viene restituito dalla funzione CreateTimerQueue .

Se il timer è stato creato usando la coda timer predefinita, questo parametro deve essere NULL.

[in] Timer

Handle per il timer della coda timer. Questo handle viene restituito dalla funzione CreateTimerQueueTimer .

[in, optional] CompletionEvent

Handle per l'oggetto evento da segnalare quando il sistema ha annullato il timer e tutte le funzioni di callback sono state completate. Questo parametro può essere NULL.

Se questo parametro è INVALID_HANDLE_VALUE, la funzione attende il completamento delle funzioni di callback timer in esecuzione prima di restituire.

Se questo parametro è NULL, la funzione contrassegna il timer per l'eliminazione e restituisce immediatamente. Se il timer è già scaduto, la funzione di callback timer verrà eseguita al completamento. Tuttavia, non è stata inviata alcuna notifica al completamento della funzione di callback timer. La maggior parte dei chiamanti non deve usare questa opzione e deve attendere il completamento delle funzioni di callback timer in modo che possano eseguire qualsiasi pulizia necessaria.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è diverso da zero.

Se la funzione ha esito negativo, il valore restituito è zero. Per informazioni dettagliate sull'errore, chiamare GetLastError. Se il codice di errore è ERROR_IO_PENDING, non è necessario chiamare nuovamente questa funzione. Per qualsiasi altro errore, è necessario ripetere la chiamata.

Commenti

Questa funzione non può essere chiamata mentre il thread usa la rappresentazione. Il comportamento risultante non è definito.

È possibile impostare CompletionEvent su INVALID_HANDLE_VALUE quando si chiama questa funzione dall'interno del callback timer di un altro timer, purché la funzione di callback non venga eseguita nel thread timer. Tuttavia, un deadlock può verificarsi se due funzioni di callback tentano un blocco di chiamate DeleteTimerQueueTimer sui timer degli altri. Inoltre, non è possibile effettuare una chiamata di eliminazione di blocco in un timer associato al callback.

Prestare attenzione quando si effettua una chiamata deleteTimerQueueTimer in un thread persistente. Se il timer eliminato è stato creato con WT_EXECUTEINPERSISTENTTHREAD, potrebbe verificarsi un deadlock.

Se sono presenti funzioni di callback in sospeso e CompletionEvent è NULL, la funzione avrà esito negativo e imposta il codice di errore su ERROR_IO_PENDING. Ciò indica che sono presenti funzioni di callback in sospeso. Tali callback verranno eseguiti o si trovano al centro dell'esecuzione. Il timer viene pulito al termine dell'esecuzione della funzione di callback.

Per annullare tutti i timer in una coda timer, chiamare la funzione DeleteTimerQueueEx .

Per compilare un'applicazione che usa questa funzione, definire _WIN32_WINNT come 0x0500 o versioni successive. Per altre informazioni, vedere Uso delle intestazioni di Windows.

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	threadpoollegacyapiset.h
Libreria	Kernel32.lib
DLL	Kernel32.dll