SignalObjectAndWait-Funktion (synchapi.h)

  • Artikel

Signalisiert ein Objekt und wartet auf ein anderes Objekt als einzelnen Vorgang.

Syntax

DWORD SignalObjectAndWait(
  [in] HANDLE hObjectToSignal,
  [in] HANDLE hObjectToWaitOn,
  [in] DWORD  dwMilliseconds,
  [in] BOOL   bAlertable
);

Parameter

[in] hObjectToSignal

Ein Handle für das zu signalisierende Objekt. Dieses Objekt kann ein Semaphor, ein Mutex oder ein Ereignis sein.

Wenn es sich bei dem Handle um ein Semaphor handelt, ist das SEMAPHORE_MODIFY_STATE Zugriffsrecht erforderlich. Wenn es sich bei dem Handle um ein Ereignis handelt, ist das EVENT_MODIFY_STATE-Zugriffsrecht erforderlich. Wenn es sich beim Handle um einen Mutex handelt und der Aufrufer den Mutex nicht besitzt, schlägt die Funktion mit ERROR_NOT_OWNER fehl.

[in] hObjectToWaitOn

Ein Handle für das Objekt, auf das gewartet werden soll. Das Synchronize-Zugriffsrecht ist erforderlich. Weitere Informationen finden Sie unter Synchronisierungsobjektsicherheit und Zugriffsrechte. Eine Liste der Objekttypen, deren Handles Sie angeben können, finden Sie im Abschnitt Hinweise.

[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 und keine APC-Objekte (Completion or asynchron procedure call, asynchrone Prozeduraufrufe) in die Warteschlange eingereiht sind. Wenn dwMilliseconds 0 ist, testet die Funktion den Zustand des Objekts, sucht nach Vervollständigungsroutinen oder APCs in der Warteschlange und gibt sofort zurück. Wenn dwMillisecondsUNENDLICH ist, verstreicht das Timeoutintervall der Funktion nie.

[in] bAlertable

Wenn dieser Parameter TRUE ist, gibt die Funktion zurück, wenn das System eine E/A-Vervollständigungsroutine oder APC-Funktion in die Warteschlange stellt und der Thread die Funktion aufruft. Bei FALSE gibt die Funktion nicht zurück, und der Thread ruft weder die Vervollständigungsroutine noch die APC-Funktion auf.

Eine Vervollständigungsroutine wird in die Warteschlange eingereiht, wenn der Funktionsaufruf abgeschlossen ist, der die APC in die Warteschlange gestellt hat. Diese Funktion gibt zurück, und die Vervollständigungsroutine wird nur aufgerufen, wenn bAlertableTRUE ist, und der aufrufende Thread der Thread ist, der den APC in die Warteschlange gestellt hat.

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.

Rückgabecode/-wert BESCHREIBUNG
WAIT_ABANDONED
0x00000080L
 Das angegebene Objekt ist ein Mutex-Objekt, das nicht von dem Thread freigegeben wurde, dem das Mutex-Objekt gehört, bevor der besitzereigene Thread beendet wurde. Der Besitz des Mutex-Objekts wird dem aufrufenden Thread gewährt, und der Mutex wird auf nicht signalisiert festgelegt.

Wenn der Mutex Informationen zu persistenten Zustanden schützt, sollten Sie ihn auf Konsistenz überprüfen.
WAIT_IO_COMPLETION
0x000000C0L
 Die Wartezeit wurde durch einen oder mehrere asynchrone Prozeduraufrufe im Benutzermodus beendet, die in die Warteschlange des Threads eingereiht wurden.
WAIT_OBJECT_0
0x00000000L
 Der Zustand des angegebenen Objekts wird signalisiert.
WAIT_TIMEOUT
0x00000102L
 Das Timeoutintervall ist verstrichen, und der Zustand des Objekts ist nicht signalisiert.
WAIT_FAILED
(DWORD)0xFFFFFFFF
 Die Funktion ist fehlgeschlagen. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Die SignalObjectAndWait-Funktion bietet eine effizientere Möglichkeit, ein Objekt zu signalisieren und dann auf ein anderes zu warten, im Vergleich zu separaten Funktionsaufrufen wie SetEvent gefolgt von WaitForSingleObject.

Die SignalObjectAndWait-Funktion kann auf die folgenden Objekte warten:

  • Änderungsbenachrichtigung
  • Konsoleneingabe
  • Ereignis
  • Benachrichtigung zu Speicherressourcen
  • Mutex
  • Prozess
  • Semaphore
  • Thread
  • Wartebarer Timer
Weitere Informationen finden Sie unter Synchronisierungsobjekte.

Ein Thread kann die SignalObjectAndWait-Funktion verwenden, um sicherzustellen, dass sich ein Workerthread in einem Wartezustand befindet, bevor ein Objekt signalisiert wird. Beispielsweise können ein Thread und ein Workerthread Handles für Ereignisobjekte verwenden, um ihre Arbeit zu synchronisieren. Der Thread führt Code wie den folgenden aus:

  dwRet = WaitForSingleObject(hEventWorkerDone, INFINITE);
  if( WAIT_OBJECT_0 == dwRet)
    SetEvent(hEventMoreWorkToDo);

Der Workerthread führt Code wie den folgenden aus:

  dwRet = SignalObjectAndWait(hEventWorkerDone,
                              hEventMoreWorkToDo,
                              INFINITE, 
                              FALSE);

Beachten Sie, dass das "Signal" und "Warten" nicht garantiert als atomarer Vorgang ausgeführt werden. Threads, die auf anderen Prozessoren ausgeführt werden, können den Signalzustand des ersten Objekts beobachten, bevor der Thread, der SignalObjectAndWait aufruft, seine Wartezeit für das zweite Objekt beginnt.

Gehen Sie äußerst vorsichtig vor, wenn Sie SignalObjectAndWait und PulseEvent mit Windows 7 verwenden, da die Verwendung dieser APIs zwischen mehreren Threads zu einem Deadlock einer Anwendung führen kann. Threads, die von SignalObjectAndWait signalisiert werden, rufen PulseEvent auf, um das wartende Objekt des SignalObjectAndWait-Aufrufs zu signalisieren . Unter bestimmten Umständen kann der Aufrufer von SignalObjectAndWait den Signalzustand des wartenden Objekts nicht rechtzeitig empfangen, was zu einem Deadlock führt.

Gehen Sie vorsichtig vor, wenn Sie die Wartefunktionen und den Code verwenden, 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 COM CoInitialize. Wenn Sie also über einen Thread verfügen, der Fenster erstellt, müssen Sie SignalObjectAndWait aus einem anderen Thread aufrufen. Wenn dies nicht möglich ist, können Sie MsgWaitForMultipleObjects oder MsgWaitForMultipleObjectsEx verwenden, aber die Funktionalität ist nicht gleichwertig.

Um eine Anwendung zu kompilieren, die diese Funktion verwendet, definieren Sie _WIN32_WINNT als 0x0400 oder höher. Weitere Informationen finden Sie unter Verwenden der Windows-Header.

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

MsgWaitForMultipleObjects

MsgWaitForMultipleObjectsEx

Synchronisierungsfunktionen

Wartefunktionen