DeleteTimerQueueTimer-Funktion (threadpoollegacyapiset.h)

Artikel
03/02/2024

Entfernt einen Timer aus der Zeitgeberwarteschlange und wartet optional darauf, dass die derzeit ausgeführten Timer-Rückruffunktionen abgeschlossen sind, bevor der Timer gelöscht wird.

Syntax

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

Parameter

[in, optional] TimerQueue

Ein Handle für die Timerwarteschlange. Dieses Handle wird von der CreateTimerQueue-Funktion zurückgegeben.

Wenn der Timer mit der Standardtimerwarteschlange erstellt wurde, sollte dieser Parameter NULL sein.

[in] Timer

Ein Handle für den Timer-Warteschlangen-Timer. Dieses Handle wird von der CreateTimerQueueTimer-Funktion zurückgegeben.

[in, optional] CompletionEvent

Ein Handle für das Ereignisobjekt, das signalisiert werden soll, wenn das System den Timer abgebrochen hat und alle Rückruffunktionen abgeschlossen sind. Dieser Parameter kann NULL sein.

Wenn dieser Parameter INVALID_HANDLE_VALUE ist, wartet die Funktion, bis alle ausgeführten Timer-Rückruffunktionen abgeschlossen sind, bevor sie zurückgegeben wird.

Wenn dieser Parameter NULL ist, markiert die Funktion den Timer für das Löschen und gibt sofort zurück. Wenn der Timer bereits abgelaufen ist, wird die Timer-Rückruffunktion bis zum Abschluss ausgeführt. Es wird jedoch keine Benachrichtigung gesendet, wenn die Timer-Rückruffunktion abgeschlossen wurde. Die meisten Aufrufer sollten diese Option nicht verwenden und warten, bis die Rückruffunktionen des Timers ausgeführt werden, damit sie alle erforderlichen Bereinigungen ausführen können.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf. Wenn der Fehlercode ERROR_IO_PENDING ist, ist es nicht erforderlich, diese Funktion erneut aufzurufen. Bei jedem anderen Fehler sollten Sie den Aufruf wiederholen.

Hinweise

Diese Funktion kann nicht aufgerufen werden, während der Thread einen Identitätswechsel verwendet. Das resultierende Verhalten ist nicht definiert.

Sie können CompletionEvent auf INVALID_HANDLE_VALUE festlegen, wenn Sie diese Funktion aus dem Timer-Rückruf eines anderen Timers aufrufen, solange die Rückruffunktion nicht im Timerthread ausgeführt wird. Ein Deadlock kann jedoch auftreten, wenn zwei Rückruffunktionen versuchen, einen blockierenden DeleteTimerQueueTimer-Aufruf auf den Timern der anderen zu blockieren. Darüber hinaus können Sie keinen blockierenden Löschaufruf für einen Timer ausführen, der dem Rückruf zugeordnet ist.

Seien Sie vorsichtig, wenn Sie einen blockierenden DeleteTimerQueueTimer-Aufruf für einen persistenten Thread ausführen. Wenn der zu löschende Timer mit WT_EXECUTEINPERSISTENTTHREAD erstellt wurde, kann ein Deadlock auftreten.

Wenn ausstehende Rückruffunktionen vorhanden sind und CompletionEventNULL ist, schlägt die Funktion fehl, und der Fehlercode wird auf ERROR_IO_PENDING festgelegt. Dies gibt an, dass es ausstehende Rückruffunktionen gibt. Diese Rückrufe werden entweder ausgeführt oder befinden sich gerade in der Ausführung. Der Timer wird bereinigt, wenn die Rückruffunktion ausgeführt wird.

Um alle Zeitgeber in einer Timerwarteschlange abzubrechen, rufen Sie die DeleteTimerQueueEx-Funktion auf.

Um eine Anwendung zu kompilieren, die diese Funktion verwendet, definieren Sie _WIN32_WINNT als 0x0500 oder höher. Weitere Informationen finden Sie unter Verwenden der Windows-Header.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	threadpoollegacyapiset.h
Bibliothek	Kernel32.lib
DLL	Kernel32.dll