CreateTimerQueueTimer-Funktion (threadpoollegacyapiset.h)
Erstellt einen Timer-Warteschlangen-Timer. Dieser Timer läuft zum angegebenen Fälligkeitszeitpunkt ab, dann nach jedem angegebenen Zeitraum. Wenn der Timer abläuft, wird die Rückruffunktion aufgerufen.
Syntax
BOOL CreateTimerQueueTimer(
[out] PHANDLE phNewTimer,
[in, optional] HANDLE TimerQueue,
[in] WAITORTIMERCALLBACK Callback,
[in, optional] PVOID Parameter,
[in] DWORD DueTime,
[in] DWORD Period,
[in] ULONG Flags
);
Parameter
[out] phNewTimer
Ein Zeiger auf einen Puffer, der bei der Rückgabe ein Handle zum Timer-Warteschlangen-Timer empfängt. Wenn dieses Handle abgelaufen ist und nicht mehr benötigt wird, geben Sie es durch Aufrufen von DeleteTimerQueueTimer frei.
[in, optional] TimerQueue
Ein Handle für die Zeitgeberwarteschlange. Dieses Handle wird von der CreateTimerQueue-Funktion zurückgegeben.
Wenn dieser Parameter NULL ist, wird der Timer der Standardtimerwarteschlange zugeordnet.
[in] Callback
Ein Zeiger auf die anwendungsdefinierte Funktion vom Typ WAITORTIMERCALLBACK , die ausgeführt werden soll, wenn der Timer abläuft. Weitere Informationen finden Sie unter WaitOrTimerCallback.
[in, optional] Parameter
Ein einzelner Parameterwert, der an die Rückruffunktion übergeben wird.
[in] DueTime
Die Zeitspanne in Millisekunden relativ zur aktuellen Zeit, die verstreichen muss, bevor der Timer zum ersten Mal signalisiert wird.
[in] Period
Der Zeitraum des Timers in Millisekunden. Wenn dieser Parameter null ist, wird der Timer einmal signalisiert. Wenn dieser Parameter größer als 0 (null) ist, ist der Timer periodisch. Ein periodischer Timer reaktiviert automatisch jedes Mal, wenn der Zeitraum verstrichen ist, bis der Timer abgebrochen wird.
[in] Flags
Bei diesem Parameter kann es sich um einen oder mehrere der folgenden Werte aus WinNT.h handeln.
| Wert | Bedeutung |
|---|---|
|
Standardmäßig wird die Rückruffunktion in eine Warteschlange für einen Nicht-E/A-Workerthread eingereiht. |
|
Die Rückruffunktion wird vom Timerthread selbst aufgerufen. Dieses Flag sollte nur für kurze Aufgaben verwendet werden, oder es kann sich auf andere Zeitgebervorgänge auswirken.
Die Rückruffunktion wird als APC in die Warteschlange gestellt. Es sollten keine warnbaren Wartevorgänge ausgeführt werden. |
|
Dieses Flag wird nicht verwendet.
Windows Server 2003 und Windows XP: Die Rückruffunktion wird in die Warteschlange eines E/A-Workerthreads eingereiht. Dieses Flag sollte verwendet werden, wenn die Funktion in einem Thread ausgeführt werden soll, der in einem warnbaren Zustand wartet. E/A-Workerthreads wurden ab Windows Vista und Windows Server 2008 entfernt. |
|
Die Rückruffunktion wird in eine Warteschlange mit einem Thread eingereiht, der nie beendet wird. Es wird nicht garantiert, dass jedes Mal derselbe Thread verwendet wird. Dieses Flag sollte nur für kurze Aufgaben verwendet werden, oder es kann sich auf andere Zeitgebervorgänge auswirken.
Dieses Flag muss festgelegt werden, wenn der Thread Funktionen aufruft, die APCs verwenden. Weitere Informationen finden Sie unter Asynchrone Prozeduraufrufe. Beachten Sie, dass derzeit kein Workerthread wirklich persistent ist, obwohl kein Workerthread beendet wird, wenn E/A-Anforderungen ausstehen. |
|
Die Rückruffunktion kann eine lange Wartezeit ausführen. Dieses Flag hilft dem System zu entscheiden, ob ein neuer Thread erstellt werden soll. |
|
Der Timer wird nur einmal auf den Signalzustand festgelegt. Wenn dieses Flag festgelegt ist, muss der Period-Parameter null sein. |
|
Rückruffunktionen verwenden das aktuelle Zugriffstoken, unabhängig davon, ob es sich um ein Prozess- oder Identitätswechseltoken handelt. Wenn dieses Flag nicht angegeben ist, werden Rückruffunktionen nur mit dem Prozesstoken ausgeführt.
Windows XP: Dieses Flag wird erst unter Windows XP mit SP2 und Windows Server 2003 unterstützt. |
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.
Hinweise
Wenn die Parameter DueTime und Period ungleich null sind, wird der Timer zuerst zur Fälligkeit und dann in regelmäßigen Abständen signalisiert. Der Rückruf wird bei jedem Ablauf des Zeitraums aufgerufen, unabhängig davon, ob die Ausführung des vorherigen Rückrufs abgeschlossen wurde. Rückruffunktionen werden im Threadpool in die Warteschlange eingereiht. Diese Threads unterliegen Planungsverzögerungen, sodass der Zeitpunkt je nach den anderen Vorgängen in der Anwendung oder im System variieren kann.
Die Zeit, die das System im Ruhezustand oder Ruhezustand verbringt, zählt nicht zum Ablauf des Timers. Der Timer wird signalisiert, wenn die kumulative Menge der verstrichenen Zeit, die das System im Wachzustand verbringt, mit der Fälligkeit des Zeitgebers übereinstimmt.
Windows Server 2003 und Windows XP: Die Zeit, die das System im Ruhezustand oder Ruhezustand verbringt, zählt bis zum Ablauf des Timers. Wenn der Timer abläuft, während sich das System im Ruhezustand befindet, wird der Timer sofort signalisiert, wenn das System aktiviert wird.
Um einen Timer abzubrechen, rufen Sie die DeleteTimerQueueTimer-Funktion auf. Um alle Zeitgeber in einer Zeitgeberwarteschlange abzubrechen, rufen Sie die DeleteTimerQueueEx-Funktion auf.
Standardmäßig verfügt der Threadpool über maximal 500 Threads. Verwenden Sie zum Erhöhen dieses Grenzwerts das in WinNT.h definierte makro WT_SET_MAX_THREADPOOL_THREAD .
#define WT_SET_MAX_THREADPOOL_THREADS(Flags,Limit) \
((Flags)|=(Limit)<<16)
Verwenden Sie dieses Makro, wenn Sie den Flags-Parameter angeben. Die Makroparameter sind die gewünschten Flags und der neue Grenzwert (bis zu (2<<16)-1 Threads). Beachten Sie jedoch, dass Ihre Anwendung die Leistung verbessern kann, indem die Anzahl der Workerthreads niedrig gehalten wird.
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.
Beispiele
Ein Beispiel, das CreateTimerQueueTimer verwendet, finden Sie unter Verwenden von Timerwarteschlangen.
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 |