Funzione KeReleaseMutex (wdm.h)

Articolo
03/05/2024

La routine KeReleaseMutex rilascia un oggetto mutex e specifica se il chiamante deve chiamare una delle routine KeWaitXxx non appena KeReleaseMutex restituisce il controllo.

Sintassi

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

Parametri

[in, out] Mutex

Puntatore a un oggetto mutex inizializzato per il quale il chiamante fornisce l'archiviazione.

[in] Wait

Specifica se la chiamata a KeReleaseMutex deve essere immediatamente seguita da una chiamata a una delle routine KeWaitXxx . Se TRUE, la chiamata KeReleaseMutex deve essere seguita da una chiamata a KeWaitForMultipleObjects, KeWaitForMutexObject o KeWaitForSingleObject. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.

Valore restituito

Se il valore restituito è zero, l'oggetto mutex è stato rilasciato e raggiunto uno stato segnalato.

Commenti

Per prestazioni migliori, usare mutex veloci o mutex sorvegliati. Per altre informazioni, vedere Alternative agli oggetti Mutex.

Se l'oggetto mutex raggiunge uno stato segnalato, viene effettuato un tentativo di soddisfare un'attesa per l'oggetto mutex.

Un oggetto mutex può essere rilasciato solo dal thread che attualmente contiene il mutex. Se viene effettuato un tentativo di rilasciare un mutex che il thread non contiene o se è stato acquisito un mutex in IRQL = DISPATCH_LEVEL e il thread non è in esecuzione in DISPATCH_LEVEL (e viceversa), la routine genera un'eccezione STATUS_ABANDONED o STATUS_MUTEX_NOT_OWNED.

Quando un oggetto mutex raggiunge uno stato segnalato, viene rimosso dall'elenco dei mutex contenuti in tale thread. Se questo elenco non contiene più voci, viene ripristinata la priorità originale per il thread.

La routine KeReleaseMutex potrebbe generare temporaneamente irQL. Se il parametro Wait è FALSE, la routine, prima che venga restituita, ripristina irQL sul valore originale che aveva all'inizio della chiamata.

Se WaitTRUE, la routine restituisce = senza abbassare il valore IRQL. In questo caso, la chiamata KeReleaseMutex deve essere immediatamente seguita da una chiamata KeWaitXxx . Impostando Wait = TRUE, il chiamante può impedire che si verifichi un cambio di contesto non necessario tra la chiamata KeReleaseMutex e la chiamata KeWaitXxx . La routine KeWaitXxx , prima che venga restituita, ripristina il valore originale di IRQL all'inizio della chiamata a KeReleaseMutex . Anche se IRQL disabilita i commutatori di contesto tra le due chiamate, queste chiamate non possono essere usate in modo affidabile come inizio e fine di un'operazione atomica. Ad esempio, tra queste due chiamate, un thread in esecuzione contemporaneamente in un altro processore potrebbe modificare lo stato dell'oggetto evento o della destinazione dell'attesa.

Se il chiamante è in esecuzione in IRQL = DISPATCH_LEVEL o in un contesto di thread arbitrario, il parametro Timeout su KeWaitXxx deve essere zero.

Se un mutex viene acquisito in modo ricorsivo, il thread di controllo deve chiamare KeReleaseMutex quante volte ha acquisito il mutex per impostarlo sullo stato segnalato.

Per altre informazioni sugli oggetti mutex, vedere Oggetti Mutex.

Requisiti

Requisito	Valore
Client minimo supportato	Disponibile a partire da Windows 2000.
Piattaforma di destinazione	Universale
Intestazione	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Libreria	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL
Regole di conformità DDI	HwStorPortProhibitedDDDIs(storport), IrqlKeDispatchLte(wdm)