SignalObjectAndWait-Funktion (synchapi.h)
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 |
|---|---|
|
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. |
|
Die Wartezeit wurde durch einen oder mehrere asynchrone Prozeduraufrufe im Benutzermodus beendet, die in die Warteschlange des Threads eingereiht wurden. |
|
Der Zustand des angegebenen Objekts wird signalisiert. |
|
Das Timeoutintervall ist verstrichen, und der Zustand des Objekts ist nicht signalisiert. |
|
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
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 |