WaitForMultipleObjectsEx-Funktion (synchapi.h)
Wartet, bis sich eines oder alle der angegebenen Objekte im signalierten Zustand befinden, eine E/A-Vervollständigungsroutine oder ein asynchroner Prozeduraufruf (APC) in die Warteschlange des Threads eingereiht wird oder das Timeoutintervall verstrichen ist.
Syntax
DWORD WaitForMultipleObjectsEx(
[in] DWORD nCount,
[in] const HANDLE *lpHandles,
[in] BOOL bWaitAll,
[in] DWORD dwMilliseconds,
[in] BOOL bAlertable
);
Parameter
[in] nCount
Die Anzahl der Objekthandles, auf die im Array gewartet werden soll, auf das von lpHandles verwiesen wird. Die maximale Anzahl von Objekthandles ist MAXIMUM_WAIT_OBJECTS. Dieser Parameter darf nicht 0 (null) sein.
[in] lpHandles
Ein Array von Objekthandles. Eine Liste der Objekttypen, deren Handles angegeben werden können, finden Sie im folgenden Abschnitt Hinweise. Das Array kann Handles von Objekten unterschiedlicher Typen enthalten. Es darf nicht mehrere Kopien desselben Handles enthalten.
Wenn eines dieser Handles geschlossen wird, während die Wartezeit noch aussteht, ist das Verhalten der Funktion undefiniert.
Die Handles müssen über das Synchronize-Zugriffsrecht verfügen. Weitere Informationen finden Sie unter Standardzugriffsrechte.
[in] bWaitAll
Wenn dieser Parameter TRUE ist, gibt die Funktion zurück, wenn der Zustand aller Objekte im lpHandles-Array auf signalisiert festgelegt ist. Bei FALSE gibt die Funktion zurück, wenn der Zustand eines der Objekte auf signalisiert festgelegt ist. Im letzteren Fall gibt der Rückgabewert das Objekt an, dessen Zustand die Funktion zurückgegeben hat.
[in] dwMilliseconds
Das Timeoutintervall in Millisekunden. Wenn ein Wert ungleich null angegeben wird, wartet die Funktion, bis die angegebenen Objekte signalisiert werden, eine E/A-Vervollständigungsroutine oder APC in die Warteschlange eingereiht wird oder das Intervall verfällt. Wenn dwMilliseconds null ist, wechselt die Funktion nicht in den Wartezustand, wenn die Kriterien nicht erfüllt sind. es wird immer sofort zurückgegeben. Wenn dwMillisecondsinfinite ist, gibt die Funktion nur zurück, wenn die angegebenen Objekte signalisiert oder eine E/A-Vervollständigungsroutine oder APC in die Warteschlange eingereiht werden.
Windows XP, Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 und Windows Server 2008 R2: Der Wert dwMilliseconds enthält die Zeit, die in Zuständen mit niedriger Energie verbracht wurde. Beispielsweise wird das Timeout während des Ruhezustands des Computers immer wieder heruntergezählt.
Windows 8, Windows Server 2012, Windows 8.1, Windows Server 2012 R2, Windows 10 und Windows Server 2016: Der Wert dwMilliseconds enthält keine Zeit, die mit Zuständen mit niedriger Energie verbracht wurde. Beispielsweise wird das Timeout nicht heruntergezählt, während sich der Computer im Ruhezustand befindet.
[in] bAlertable
Wenn dieser Parameter TRUE ist und sich der Thread im Wartezustand befindet, gibt die Funktion zurück, wenn das System eine E/A-Vervollständigungsroutine oder APC in die Warteschlange stellt und der Thread die Routine oder Funktion ausführt. Andernfalls gibt die Funktion nicht zurück, und die Vervollständigungsroutine oder APC-Funktion wird nicht ausgeführt.
Eine Vervollständigungsroutine wird in die Warteschlange gestellt, wenn die ReadFileEx - oder WriteFileEx-Funktion , in der sie angegeben wurde, abgeschlossen wurde. Die Wait-Funktion gibt zurück, und die Vervollständigungsroutine wird nur aufgerufen, wenn bAlertableTRUE ist und der aufrufende Thread der Thread ist, der den Lese- oder Schreibvorgang initiiert hat. Beim Aufrufen von QueueUserAPC wird ein APC in eine Warteschlange gestellt.
Rückgabewert
Wenn die Funktion erfolgreich ist, gibt der Rückgabewert das Ereignis an, durch das die Funktion zurückgegeben wurde. Dieses Argument einen der folgenden Werte annehmen. (Beachten Sie, dass WAIT_OBJECT_0 als 0 und WAIT_ABANDONED_0 als 0x00000080L definiert ist.)
| Rückgabecode/-wert | BESCHREIBUNG |
|---|---|
|
Wenn bWaitAllTRUE ist, gibt ein Rückgabewert in diesem Bereich an, dass der Zustand aller angegebenen Objekte signalisiert wird.
Wenn bWaitAllAUF FALSE festgelegt ist, gibt der Rückgabewert minus WAIT_OBJECT_0 den lpHandles-Arrayindex des Objekts an, das die Wartezeit erfüllt hat. Wenn während des Aufrufs mehr als ein Objekt signalisiert wurde, ist dies der Arrayindex des signalierten Objekts mit dem kleinsten Indexwert aller signalisierten Objekte. |
|
Wenn bWaitAllTRUE ist, gibt ein Rückgabewert in diesem Bereich an, dass der Zustand aller angegebenen Objekte signalisiert wird, und mindestens eines der Objekte ist ein verlassenes Mutex-Objekt.
Wenn bWaitAllFALSE ist, gibt der Rückgabewert minus WAIT_ABANDONED_0 den lpHandles-Arrayindex eines verlassenen Mutex-Objekts an, das die Wartezeit erfüllt hat. Der Besitz des Mutex-Objekts wird dem aufrufenden Thread gewährt, und der Mutex wird auf nicht signalisiert festgelegt. Wenn ein Mutex Informationen zum beständigen Zustand schützt, sollten Sie ihn auf Konsistenz überprüfen. |
|
Die Wartezeit wurde durch einen oder mehrere asynchrone Prozeduraufrufe (APC ) im Benutzermodus beendet, die im Thread in die Warteschlange eingereiht wurden. |
|
Das Timeoutintervall ist abgelaufen, die vom bWaitAll-Parameter angegebenen Bedingungen wurden nicht erfüllt, und es werden keine Abschlussroutinen in die Warteschlange eingereiht. |
|
Die Funktion ist fehlgeschlagen. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf. |
Hinweise
Die WaitForMultipleObjectsEx-Funktion bestimmt, ob die Wartekriterien erfüllt wurden. Wenn die Kriterien nicht erfüllt wurden, wechselt der aufrufende Thread in den Wartezustand, bis die Bedingungen der Wartekriterien erfüllt sind oder das Timeoutintervall verstrichen ist.
Wenn bWaitAllAUF TRUE festgelegt ist, wird der Wartevorgang der Funktion nur abgeschlossen, wenn der Status aller Objekte auf signalisiert festgelegt wurde. Die Funktion ändert die Zustände der angegebenen Objekte erst, wenn der Status aller Objekte auf signalisiert festgelegt wurde. Beispielsweise kann ein Mutex signalisiert werden, aber der Thread erhält erst dann den Besitz, wenn der Status der anderen Objekte ebenfalls auf signalisiert festgelegt ist. In der Zwischenzeit kann ein anderer Thread den Besitz des Mutex erhalten, wodurch sein Zustand auf nicht signalisiert festgelegt wird.
Wenn bWaitAllauf FALSE festgelegt ist, überprüft diese Funktion die Handles im Array, beginnend mit Index 0, bis eines der Objekte signalisiert wird. Wenn mehrere Objekte signalisiert werden, gibt die Funktion den Index des ersten Handles in dem Array zurück, dessen Objekt signalisiert wurde.
Die -Funktion ändert den Zustand einiger Typen von Synchronisierungsobjekten. Die Änderung erfolgt nur für das Objekt oder die Objekte, deren signalisierter Zustand dazu geführt hat, dass die Funktion zurückgegeben wurde. Beispielsweise wird die Anzahl eines Semaphorobjekts um eins verringert. Weitere Informationen finden Sie in der Dokumentation zu den einzelnen Synchronisierungsobjekten.
Um auf mehr als MAXIMUM_WAIT_OBJECTS Handles zu warten, verwenden Sie eine der folgenden Methoden:
- Erstellen Sie einen Thread, der auf MAXIMUM_WAIT_OBJECTS Handles wartet, und warten Sie dann auf diesen Thread und die anderen Handles. Verwenden Sie diese Technik, um die Handles in Gruppen von MAXIMUM_WAIT_OBJECTS aufzuteilen.
- Rufen Sie RegisterWaitForSingleObject oder SetThreadpoolWait auf, um auf jedes Handle zu warten. Der Threadpool wartet effizient auf die Handles und weist einen Workerthread zu, nachdem das Objekt signalisiert wurde oder das Timeoutintervall abläuft.
- Änderungsbenachrichtigung
- Konsoleneingabe
- Ereignis
- Benachrichtigung zur Speicherressource
- Mutex
- Prozess
- Semaphore
- Thread
- Wartebarer Timer
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Windows XP [Desktop-Apps | UWP-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2003 [Desktop-Apps | UWP-Apps] |
| Zielplattform | Windows |
| Kopfzeile | synchapi.h (enthalten Windows.h unter Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2) |
| Bibliothek | Kernel32.lib |
| DLL | Kernel32.dll |
Siehe auch
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für