RegisterWaitForSingleObject-Funktion (winbase.h)
Weist einen Wartethread im Threadpool an, auf das -Objekt zu warten. Der Wartethread führt die angegebene Rückruffunktion in die Warteschlange für den Threadpool aus, wenn eine der folgenden Aktionen auftritt:
- Das angegebene Objekt befindet sich im signalierten Zustand.
- Das Timeoutintervall verstreicht.
Syntax
BOOL RegisterWaitForSingleObject(
[out] PHANDLE phNewWaitObject,
[in] HANDLE hObject,
[in] WAITORTIMERCALLBACK Callback,
[in, optional] PVOID Context,
[in] ULONG dwMilliseconds,
[in] ULONG dwFlags
);
Parameter
[out] phNewWaitObject
Ein Zeiger auf eine Variable, die bei der Rückgabe ein Wartehandle empfängt. Beachten Sie, dass ein Wartehandle nicht in Funktionen verwendet werden kann, die ein Objekthandle erfordern, z. B. CloseHandle.
[in] hObject
Ein Handle für das -Objekt. Eine Liste der Objekttypen, deren Handles angegeben werden können, finden Sie im folgenden Abschnitt Hinweise.
Wenn dieses Handle geschlossen wird, während die Wartezeit noch aussteht, ist das Verhalten der Funktion undefiniert.
Die Handles müssen über das Synchronzugriffsrecht verfügen. Weitere Informationen finden Sie unter Standardzugriffsrechte.
[in] Callback
Ein Zeiger auf die anwendungsdefinierte Funktion vom Typ WAITORTIMERCALLBACK , die ausgeführt werden soll, wenn sich hObject im signalisierten Zustand befindet oder dwMilliseconds verstreicht. Weitere Informationen finden Sie unter WaitOrTimerCallback.
[in, optional] Context
Ein einzelner Wert, der an die Rückruffunktion übergeben wird.
[in] dwMilliseconds
Das Timeoutintervall in Millisekunden. Die Funktion gibt zurück, wenn das Intervall verstrichen ist, auch wenn der Zustand des Objekts nicht signalisiert ist. Wenn dwMilliseconds null ist, testet die Funktion den Zustand des Objekts und gibt sofort zurück. Wenn dwMillisecondsUNENDLICH ist, verstreicht das Timeoutintervall der Funktion nie.
[in] dwFlags
Dieser Parameter kann einen oder mehrere der folgenden Werte aufweisen.
Informationen zur Verwendung dieser Werte mit Objekten, die signalisiert bleiben, finden Sie im Abschnitt Hinweise.
| Wert | Bedeutung |
|---|---|
|
Standardmäßig wird die Rückruffunktion in eine Warteschlange für einen Nicht-E/A-Workerthread eingereiht. |
|
Dieses Flag wird nicht verwendet.
Windows Server 2003 und Windows XP: Die Rückruffunktion wird für einen E/A-Workerthread in die Warteschlange gestellt. 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 für einen Thread eingereiht, der nie beendet wird. Es wird nicht garantiert, dass derselbe Thread jedes Mal verwendet wird. Dieses Flag sollte nur für kurze Aufgaben verwendet werden, oder es kann sich auf andere Wartevorgä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 beständig ist, obwohl kein Workerthread beendet wird, wenn E/A-Anforderungen ausstehen. |
|
Die Rückruffunktion wird vom Wartethread selbst aufgerufen. Dieses Flag sollte nur für kurze Aufgaben verwendet werden, oder es kann sich auf andere Wartevorgänge auswirken.
Deadlocks können auftreten, wenn ein anderer Thread eine exklusive Sperre erhält und die Funktion UnregisterWait oder UnregisterWaitEx aufruft, während die Rückruffunktion versucht, dieselbe Sperre abzurufen. |
|
Die Rückruffunktion kann eine lange Wartezeit ausführen. Dieses Flag hilft dem System bei der Entscheidung, ob es einen neuen Thread erstellen soll. |
|
Der Thread wartet nicht mehr auf dem Handle, nachdem die Rückruffunktion einmal aufgerufen wurde. Andernfalls wird der Timer jedes Mal zurückgesetzt, wenn der Wartevorgang abgeschlossen ist, bis der Wartevorgang abgebrochen wird. |
|
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. Rufen Sie zum Abrufen erweiterter Fehlerinformationen auf.
GetLastError.
Hinweise
Neue Wartethreads werden bei Bedarf automatisch erstellt. Der Wartevorgang wird von einem Wartethread aus dem Threadpool ausgeführt. Die Rückrufroutine wird von einem Workerthread ausgeführt, wenn der Zustand des Objekts signalisiert wird oder das Timeoutintervall verstreicht. Wenn dwFlags nicht WT_EXECUTEONLYONCE ist, wird der Timer jedes Mal zurückgesetzt, wenn das Ereignis signalisiert wird oder das Timeoutintervall verstreicht.
Wenn die Wartezeit abgeschlossen ist, müssen Sie die Funktion UnregisterWait oder UnregisterWaitEx aufrufen, um den Wartevorgang abzubrechen. (Auch Wartevorgänge, die WT_EXECUTEONLYONCE verwenden, müssen abgebrochen werden.) Führen Sie keinen blockierenden Aufruf für eine dieser Funktionen aus der Rückruffunktion aus.
Beachten Sie, dass Sie ein An RegisterWaitForSingleObject übergebenes Ereignisobjekt nicht impulsieren sollten, da der Wartethread möglicherweise nicht erkennt, dass das Ereignis vor dem Zurücksetzen signalisiert wird. Sie sollten kein Objekt registrieren, das signalisiert bleibt (z. B. ein manuelles Zurücksetzungsereignis oder ein beendeter Prozess), es sei denn, Sie legen das WT_EXECUTEONLYONCE - oder WT_EXECUTEINWAITTHREAD-Flag fest. Bei anderen Flags wird die Rückruffunktion möglicherweise zu oft aufgerufen, bevor das Ereignis zurückgesetzt wird.
Die Funktion ändert den Zustand einiger Typen von Synchronisierungsobjekten. Die Änderung erfolgt nur für das Objekt, dessen signalisierter Zustand die Wartebedingung erfüllt hat. Beispielsweise wird die Anzahl eines Semaphorobjekts um eins verringert.
Die Funktion RegisterWaitForSingleObject kann auf die folgenden Objekte warten:
- Änderungsbenachrichtigung
- Konsoleneingabe
- Ereignis
- Benachrichtigung zu Speicherressourcen
- Mutex
- Prozess
- Semaphore
- Thread
- Wartebarer Timer
Standardmäßig verfügt der Threadpool über maximal 500 Threads. Verwenden Sie zum Erhöhen dieses Grenzwerts das in WinNT.h definierte WT_SET_MAX_THREADPOOL_THREAD Makro.
#define WT_SET_MAX_THREADPOOL_THREADS(Flags,Limit) \
((Flags)|=(Limit)<<16)
Verwenden Sie dieses Makro, wenn Sie den dwFlags-Parameter angeben. Die Makroparameter sind die gewünschten Flags und das neue Limit (bis zu (2<<16)-1 Threads). Beachten Sie jedoch, dass Ihre Anwendung die Leistung verbessern kann, indem sie die Anzahl der Workerthreads niedrig hält.
Das Arbeitselement und alle aufgerufenen Funktionen müssen threadpoolsicher sein. Aus diesem Grund können Sie keinen asynchronen Aufruf, der einen persistenten Thread erfordert, z. B. die RegNotifyChangeKeyValue-Funktion , aus der Standardrückrufumgebung aufrufen. Legen Sie stattdessen mit den Funktionen SetThreadpoolThreadpoolThreadMaximum und SetThreadpoolThreadMinimum das Maximum des Threadpools fest, oder erstellen Sie ihren eigenen Thread mit der CreateThread-Funktion . (Geben Sie für die ursprüngliche Threadpool-API WT_EXECUTEINPERSISTENTTHREAD mithilfe der QueueUserWorkItem-Funktion an.)
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 | winbase.h (einschließlich Windows.h) |
| Bibliothek | Kernel32.lib |
| DLL | Kernel32.dll |
Siehe auch
Aufheben der RegistrierungWait