KePulseEvent-Funktion (ntddk.h)

Artikel
02/26/2024

Die KePulseEvent-Routine legt ein Ereignisobjekt atomar auf einen Signalzustand fest, versucht, so viele Wartezeiten wie möglich zu erfüllen, und setzt dann das Ereignisobjekt auf einen nicht signalierten Zustand zurück.

Syntax

LONG KePulseEvent(
  [in, out] PRKEVENT  Event,
  [in]      KPRIORITY Increment,
  [in]      BOOLEAN   Wait
);

Parameter

[in, out] Event

Ein Zeiger auf ein Verteilerobjekt vom Typ KEVENT.

[in] Increment

Gibt einen Boost an, der auf die Priorität von Threads angewendet werden soll, die als Ergebnis des Pulsierens des Ereignisses angegeben werden. In der Regel auf 0 festgelegt, kann aber auf 1 festgelegt werden.

[in] Wait

Gibt einen booleschen Wert an, der angibt, ob dem Aufruf von KePulseEvent sofort ein Aufruf einer der KeWaitXxx-Routinen folgt. Wenn TRUE, folgt auf den KePulseEvent-Aufruf unmittelbar ein Aufruf von KeWaitForMultipleObjects, KeWaitForMutexObject oder KeWaitForSingleObject. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

Rückgabewert

Der vorherige Signalzustand des Ereignisobjekts.

Hinweise

Weitere Informationen zu Ereignisobjekten finden Sie unter Ereignisobjekte.

Die KePulseEvent-Routine kann die IRQL vorübergehend auslösen. Wenn der Wait-ParameterFALSE ist, stellt die Routine, bevor sie zurückgibt, den IRQL auf den ursprünglichen Wert zurück, den sie zu Beginn des Aufrufs hatte.

Wenn Wait = TRUE, gibt die Routine zurück, ohne die IRQL zu senken. In diesem Fall muss dem KePulseEvent-Aufruf unmittelbar ein KeWaitXxx-Aufruf folgen. Durch Festlegen von Wait = TRUE kann der Aufrufer verhindern, dass zwischen dem KePulseEvent-Aufruf und dem KeWaitXxx-Aufruf ein unnötiger Kontextwechsel auftritt. Die KeWaitXxx-Routine stellt den IRQL am Anfang des KePulseEvent-Aufrufs wieder auf seinen ursprünglichen Wert zurück. Obwohl die IRQL Kontextwechsel zwischen den beiden Aufrufen deaktiviert, können diese Aufrufe nicht zuverlässig als Start und Ende eines atomischen Vorgangs verwendet werden. Zwischen diesen beiden Aufrufen kann z. B. ein Thread, der gleichzeitig auf einem anderen Prozessor ausgeführt wird, den Zustand des Ereignisobjekts oder des Ziels des Wartevorgangs ändern.

Wenn der Aufrufer unter IRQL = DISPATCH_LEVEL oder in einem beliebigen Threadkontext ausgeführt wird, muss der Timeout-Parameter für KeWaitXxx null sein.

Warnung

Wenn ein Thread, der auf Event wartet, derzeit einen Kernel-APC ausführt, wird beim Aufrufen von KePulseEvent die Wartezeit dieses Threads nicht erfüllt. Nach Abschluss des Kernel-APC verbleibt der Thread im Wartezustand.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar ab Windows 2000.
Zielplattform	Universell
Header	ntddk.h (include Ntddk.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL
DDI-Complianceregeln	HwStorPortProhibitedDIs(storport), IrqlKeDispatchLte(wdm)