PulseEvent-Funktion (winbase.h)

Artikel
03/03/2024

Legt das angegebene Ereignisobjekt auf den signalierten Zustand fest und setzt es dann auf den nicht signalierten Zustand zurück, nachdem die entsprechende Anzahl von wartenden Threads freigegeben wurde.

Hinweis Diese Funktion ist unzuverlässig und sollte nicht verwendet werden. Es besteht hauptsächlich aus Gründen der Abwärtskompatibilität. Weitere Informationen finden Sie in den Hinweisen.

Syntax

BOOL PulseEvent(
  [in] HANDLE hEvent
);

Parameter

[in] hEvent

Ein Handle für das Ereignisobjekt. Die CreateEvent- oder OpenEvent-Funktion gibt dieses Handle zurück.

Das Handle muss über das zugriffsrecht EVENT_MODIFY_STATE verfügen. Weitere Informationen finden Sie unter Synchronisierungsobjektsicherheit und Zugriffsrechte.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Ein Thread, der auf ein Synchronisierungsobjekt wartet, kann von einem Kernelmodus-APC vorübergehend aus dem Wartezustand entfernt und nach Abschluss des APC in den Wartezustand zurückgegeben werden. Wenn der Aufruf von PulseEvent während des Zeitpunkts auftritt, zu dem der Thread aus dem Wartezustand entfernt wurde, wird der Thread nicht freigegeben, da PulseEvent nur die Threads freigibt, die zum Zeitpunkt des Aufrufs warten. PulseEvent ist daher unzuverlässig und sollte nicht von neuen Anwendungen verwendet werden. Verwenden Sie stattdessen Bedingungsvariablen.

Für ein Ereignisobjekt mit manuellem Zurücksetzen werden alle wartenden Threads freigegeben, die sofort freigegeben werden können. Die Funktion setzt dann den Zustand des Ereignisobjekts auf nicht signalisiert zurück und gibt zurück.

Bei einem Ereignisobjekt mit automatischem Zurücksetzen setzt die Funktion den Zustand auf nicht signalisiert zurück und gibt nach dem Freigeben eines einzelnen wartenden Threads zurück, auch wenn mehrere Threads warten.

Wenn keine Threads warten oder kein Thread sofort freigegeben werden kann, legt PulseEvent einfach den Zustand des Ereignisobjekts auf nicht signalisiert fest und gibt zurück.

Beachten Sie, dass PulseEvent für einen Thread, der die Wartefunktionen mit mehreren Objekten verwendet, auf die Signalisierung aller angegebenen Objekte wartet, den Zustand des Ereignisobjekts auf signalisiert festlegen und auf nicht signalisiert zurücksetzen kann, ohne dass die Wartefunktion zurückgegeben wird. Dies geschieht, wenn nicht alle angegebenen Objekte gleichzeitig signalisiert werden.

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.

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