KeReleaseSemaphore-Funktion (wdm.h)

  • Artikel

Die KeReleaseSemaphore-Routine gibt das angegebene Semaphorobjekt frei.

Syntax

LONG KeReleaseSemaphore(
  [in, out] PRKSEMAPHORE Semaphore,
  [in]      KPRIORITY    Increment,
  [in]      LONG         Adjustment,
  [in]      BOOLEAN      Wait
);

Parameter

[in, out] Semaphore

Ein Zeiger auf ein initialisiertes Semaphorobjekt, für das der Aufrufer den Speicher bereitstellt.

[in] Increment

Gibt den Prioritätsinkrement an, der angewendet werden soll, wenn das Loslassen des Semaphors dazu führt, dass eine Wartezeit erfüllt wird.

[in] Adjustment

Gibt einen Wert an, der der aktuellen Semaphoranzahl hinzugefügt werden soll. Dieser Wert muss positiv sein.

[in] Wait

Gibt an, ob dem Aufruf von KeReleaseSemaphore sofort ein Aufruf einer der KeWaitXxx-Routinen folgen soll. Bei TRUE muss auf den KeReleaseSemaphor-Aufruf ein Aufruf von KeWaitForMultipleObjects, KeWaitForMutexObject oder KeWaitForSingleObject folgen. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

Rückgabewert

Wenn der Rückgabewert 0 ist, wird der vorherige Zustand des Semaphorobjekts nicht signalisiert.

Hinweise

KeReleaseSemaphore bietet eine Laufzeitprioritätssteigerung für wartete Threads. Wenn dieser Aufruf den Semaphor auf den signalisierten Zustand festlegt, wird die Semaphoranzahl um den angegebenen Wert erweitert. Der Aufrufer kann auch angeben, ob er eine der KeWaitXxx-Routinen aufruft, sobald KeReleaseSemaphore die Steuerung zurückgibt.

Durch das Loslassen eines Semaphorobjekts wird die Semaphoranzahl um den Wert des Adjustment-Parameters erweitert. Wenn der resultierende Wert größer als der Grenzwert des Semaphorobjekts ist, wird die Anzahl nicht angepasst, und eine Ausnahme, STATUS_SEMAPHORE_LIMIT_EXCEEDED, wird ausgelöst.

Durch die Erweiterung der Anzahl des Semaphorobjekts erreicht der Semaphor einen Signalzustand, und es wird versucht, so viele Wartezeiten wie möglich auf dem Semaphorobjekt zu erfüllen.

Die KeReleaseSemaphore-Routine könnte den IRQL vorübergehend erhöhen. Wenn der Wait-Parameter FALSE ist, stellt die Routine den IRQL wieder auf den ursprünglichen Wert zurück, der zu Beginn des Aufrufs vorhanden war.

Wenn Wait = TRUE ausgeführt wird, wird die Routine zurückgegeben, ohne den IRQL zu senken. In diesem Fall muss dem KeReleaseSemaphore-Aufruf sofort ein KeWaitXxx-Aufruf folgen. Durch Festlegen von Wait = TRUE kann der Aufrufer verhindern, dass zwischen dem KeReleaseSemaphore-Aufruf und dem KeWaitXxx-Aufruf ein unnötiger Kontextwechsel stattfindet. Die KeWaitXxx-Routine stellt den IRQL zu Beginn des KeReleaseSemaphor-Aufrufs wieder auf seinen ursprünglichen Wert zurück. Obwohl das IRQL Kontextwechsel zwischen den beiden Aufrufen deaktiviert, können diese Aufrufe nicht zuverlässig als Start und Ende eines atomaren Vorgangs verwendet werden. Zwischen diesen beiden Aufrufen kann beispielsweise ein Thread, der gleichzeitig auf einem anderen Prozessor ausgeführt wird, den Zustand des Semaphorobjekts oder des Ziels der Wartezeit ändern.

Warnung

Eine auslagerungsfähige Thread- oder auslagerungsfähige Treiberroutine, die bei IRQL = PASSIVE_LEVEL ausgeführt wird, sollte niemals KeReleaseSemaphore aufrufen, wenn der Wait-Parameter auf TRUE festgelegt ist. Ein solcher Aufruf verursacht einen schwerwiegenden Seitenfehler, wenn die aufrufende Funktion zwischen den Aufrufen von KeReleaseSemaphore und KeWaitXxx ausgelagert wird.

Weitere Informationen zu Semaphorobjekten finden Sie unter Semaphor-Objekte.

Aufrufer von KeReleaseSemaphore müssen unter IRQL <= DISPATCH_LEVEL ausgeführt werden, sofern Wait auf FALSE festgelegt ist. Andernfalls muss der Aufrufer unter IRQL = PASSIVE_LEVEL ausgeführt werden.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Verfügbar ab Windows 2000.
Zielplattform Universell
Header wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
Bibliothek NtosKrnl.lib
DLL NtosKrnl.exe
IRQL Weitere Informationen finden Sie im Abschnitt mit den Hinweisen.
DDI-Complianceregeln HwStorPortProhibitedDDIs(storport)

Weitere Informationen

KeInitializeSemaphor

KeReadStateSemaphor

KeWaitForMultipleObjects

KeWaitForSingleObject