RegisterWaitForSingleObject-Funktion (winbase.h)

Artikel
08/27/2023

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
WT_EXECUTEDEFAULT 0x00000000	Standardmäßig wird die Rückruffunktion in eine Warteschlange für einen Nicht-E/A-Workerthread eingereiht.
WT_EXECUTEINIOTHREAD 0x00000001	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.
WT_EXECUTEINPERSISTENTTHREAD 0x00000080	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.
WT_EXECUTEINWAITTHREAD 0x00000004	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.
WT_EXECUTELONGFUNCTION 0x00000010	Die Rückruffunktion kann eine lange Wartezeit ausführen. Dieses Flag hilft dem System bei der Entscheidung, ob es einen neuen Thread erstellen soll.
WT_EXECUTEONLYONCE 0x00000008	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.
WT_TRANSFER_IMPERSONATION 0x00000100	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

Weitere Informationen finden Sie unter Synchronisierungsobjekte.

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)&lt;&lt;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