WaitForMultipleObjects-Funktion (synchapi.h)

  • Artikel

Wartet, bis sich eines oder alle angegebenen Objekte im Signalzustand befinden oder das Timeoutintervall verstrichen ist.

Verwenden Sie die WaitForMultipleObjectsEx-Funktion , um einen warnbaren Wartezustand zu erhalten.

Syntax

DWORD WaitForMultipleObjects(
  [in] DWORD        nCount,
  [in] const HANDLE *lpHandles,
  [in] BOOL         bWaitAll,
  [in] DWORD        dwMilliseconds
);

Parameter

[in] nCount

Die Anzahl der Objekthandles im Array, auf das von lpHandles verwiesen wird. Die maximale Anzahl von Objekthandles ist MAXIMUM_WAIT_OBJECTS. Dieser Parameter darf nicht 0 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 für Objekte unterschiedlicher Typen enthalten. Es darf nicht mehrere Kopien desselben Handle enthalten.

Wenn eines dieser Handles geschlossen wird, während die Wartezeit noch aussteht, ist das Verhalten der Funktion nicht definiert.

Die Handles müssen über das Synchronzugriffsrecht 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 signalisiert wird. 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 ohne Zero angegeben wird, wartet die Funktion, bis die angegebenen Objekte signalisiert werden oder das Intervall verstreicht. Wenn dwMilliseconds null ist, tritt die Funktion nicht in den Wartezustand ein, wenn die angegebenen Objekte nicht signalisiert werden. Es wird immer sofort zurückgegeben. Wenn dwMillisecondsUNENDLICH ist, wird die Funktion nur zurückgegeben, wenn die angegebenen Objekte signalisiert 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.

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
WAIT_OBJECT_0 bis (WAIT_OBJECT_0 + nCount– 1)
 Wenn bWaitAllTRUE ist, gibt ein Rückgabewert innerhalb des angegebenen Bereichs an, dass der Zustand aller angegebenen Objekte signalisiert wird.

Wenn bWaitAllFALSE 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 mehrere Objekte signalisiert wurden, ist dies der Arrayindex des signalierten Objekts mit dem kleinsten Indexwert aller signalisierten Objekte.
WAIT_ABANDONED_0 bis (WAIT_ABANDONED_0 + nCount– 1)
 Wenn bWaitAllTRUE ist, gibt ein Rückgabewert innerhalb des angegebenen Bereichs an, dass der Zustand aller angegebenen Objekte signalisiert wird und mindestens eines der Objekte ein verlassenes Mutex-Objekt ist.

Wenn bWaitAllFALSE ist, gibt der Rückgabewert abzüglich 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 zu persistenten Zustanden schützt, sollten Sie ihn auf Konsistenz überprüfen.
WAIT_TIMEOUT
0x00000102L
 Das Verstrichene Timeoutintervall und die vom bWaitAll-Parameter angegebenen Bedingungen sind nicht erfüllt.
WAIT_FAILED
(DWORD)0xFFFFFFFF
 Die Funktion ist fehlgeschlagen. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Die WaitForMultipleObjects-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 wurden oder das Timeoutintervall verstrichen ist.

Wenn bWaitAllTRUE 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 die Zustände aller Objekte auf signalisiert wurden. Beispielsweise kann ein Mutex signalisiert werden, aber der Thread erhält erst dann den Besitz, wenn die Zustände der anderen Objekte ebenfalls auf signalisiert sind. In der Zwischenzeit kann ein anderer Thread den Besitz des Mutex erhalten, wodurch sein Zustand auf nicht signalisiert festgelegt wird.

Wenn bWaitAllFALSE ist, überprüft diese Funktion die Handles im Array in der Reihenfolge ab 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 die Rückgabe der Funktion bewirkt hat. Beispielsweise wird die Anzahl eines Semaphorobjekts um eins verringert. Weitere Informationen finden Sie in der Dokumentation zu den einzelnen Synchronisierungsobjekten.

Verwenden Sie eine der folgenden Methoden, um auf mehr als MAXIMUM_WAIT_OBJECTS Handles zu warten:

  • Erstellen Sie einen Thread, um auf MAXIMUM_WAIT_OBJECTS Handles zu warten, und warten Sie dann auf diesen Thread und die anderen Handles. Verwenden Sie diese Technik, um die Handles in Gruppen von MAXIMUM_WAIT_OBJECTS zu unterteilen.
  • Rufen Sie RegisterWaitForSingleObject oder SetThreadpoolWait auf, um auf jedes Handle zu warten. Der Threadpool wartet effizient auf den Handles und weist einen Workerthread zu, nachdem das Objekt signalisiert wurde oder das Timeoutintervall abläuft.
Die WaitForMultipleObjects-Funktion kann Handles eines der folgenden Objekttypen im lpHandles-Array angeben:
  • Änderungsbenachrichtigung
  • Konsoleneingabe
  • Ereignis
  • Benachrichtigung zu Speicherressourcen
  • Mutex
  • Prozess
  • Semaphore
  • Thread
  • Wartebarer Timer
Gehen Sie vorsichtig vor, wenn Sie die Wartefunktionen und den Code aufrufen, der Direkt oder indirekt Fenster erstellt. Wenn ein Thread Fenster erstellt, muss er Nachrichten verarbeiten. Nachrichtenübertragungen werden an alle Fenster im System gesendet. Ein Thread, der eine Wartefunktion ohne Timeoutintervall verwendet, kann dazu führen, dass das System zum Deadlocking wird. Zwei Beispiele für Code, der indirekt Fenster erstellt, sind DDE und die CoInitialize-Funktion . Wenn Sie über einen Thread verfügen, der Fenster erstellt, verwenden Sie daher MsgWaitForMultipleObjects oder MsgWaitForMultipleObjectsEx anstelle von WaitForMultipleObjects.

Beispiele

Ein Beispiel finden Sie unter Warten auf mehrere Objekte.

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 (einschließlich Windows.h)
Bibliothek Kernel32.lib
DLL Kernel32.dll

Siehe auch

WAIT_ABANDONED_0

Synchronisierungsfunktionen

Wartefunktionen