KeReleaseMutex-Funktion (wdm.h)

Artikel
02/27/2024

Die KeReleaseMutex-Routine gibt ein Mutex-Objekt frei und gibt an, ob der Aufrufer eine der KeWaitXxx-Routinen aufrufen soll, sobald KeReleaseMutex die Steuerung zurückgibt.

Syntax

LONG KeReleaseMutex(
  [in, out] PRKMUTEX Mutex,
  [in]      BOOLEAN  Wait
);

Parameter

[in, out] Mutex

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

[in] Wait

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

Rückgabewert

Wenn der Rückgabewert 0 (null) ist, wurde das Mutex-Objekt freigegeben und erhielt einen Signalzustand.

Hinweise

Verwenden Sie schnelle Mutexe oder geschützte Mutexe, um eine bessere Leistung zu erzielen. Weitere Informationen finden Sie unter Alternativen zu Mutex-Objekten.

Wenn das Mutex-Objekt einen Signalzustand erreicht, wird versucht, eine Wartezeit auf das Mutex-Objekt zu erfüllen.

Ein Mutex-Objekt kann nur durch den Thread freigegeben werden, der derzeit den Mutex enthält. Wenn versucht wird, einen Mutex freizugeben, den der Thread nicht enthält, oder wenn ein Mutex bei IRQL = DISPATCH_LEVEL abgerufen wurde und der Thread nicht mit DISPATCH_LEVEL ausgeführt wird (und umgekehrt), löst die Routine eine STATUS_ABANDONED oder STATUS_MUTEX_NOT_OWNED Ausnahme aus.

Wenn ein Mutex-Objekt einen Signalzustand erreicht, wird es aus der Liste der Mutexe entfernt, die von diesem Thread gespeichert werden. Wenn diese Liste keine weiteren Einträge enthält, wird die ursprüngliche Priorität für den Thread wiederhergestellt.

Die KeReleaseMutex-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 KeReleaseMutex-Aufruf sofort ein KeWaitXxx-Aufruf folgen. Durch Festlegen von Wait = TRUE kann der Aufrufer verhindern, dass zwischen dem KeReleaseMutex-Aufruf und dem KeWaitXxx-Aufruf ein unnötiger Kontextwechsel auftritt. Die KeWaitXxx-Routine stellt den IRQL am Anfang des KeReleaseMutex-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.

Wenn ein Mutex rekursiv abgerufen wird, muss der haltende Thread KeReleaseMutex so oft aufrufen, wie er den Mutex abgerufen hat, um ihn auf den signalierten Zustand festzulegen.

Weitere Informationen zu Mutex-Objekten finden Sie unter Mutex-Objekte.

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	<= DISPATCH_LEVEL
DDI-Complianceregeln	HwStorPortProhibitedDIs(storport), IrqlKeDispatchLte(wdm)