Freigeben über


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
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)<<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

Synchronisierungsfunktionen

Pooling von Threads

Aufheben der RegistrierungWait

Aufheben der RegistrierungWaitEx

Wartefunktionen

Waitortimercallback