Função KeReleaseMutex (wdm.h)

Artigo
02/29/2024

A rotina KeReleaseMutex libera um objeto mutex e especifica se o chamador deve chamar uma das rotinas KeWaitXxx assim que KeReleaseMutex retornar o controle.

Sintaxe

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

Parâmetros

[in, out] Mutex

Um ponteiro para um objeto mutex inicializado para o qual o chamador fornece o armazenamento.

[in] Wait

Especifica se a chamada para KeReleaseMutex deve ser seguida imediatamente por uma chamada para uma das rotinas KeWaitXxx . Se TRUE, a chamada KeReleaseMutex deverá ser seguida por uma chamada para KeWaitForMultipleObjects, KeWaitForMutexObject ou KeWaitForSingleObject. Para obter mais informações, consulte a seção Comentários a seguir.

Retornar valor

Se o valor retornado for zero, o objeto mutex foi liberado e alcançou um estado de sinalizado.

Comentários

Para melhorar o desempenho, use mutexes rápidos ou mutexes protegidos. Para obter mais informações, consulte Alternativas a objetos Mutex.

Se o objeto mutex atingir um estado sinalizado, será feita uma tentativa de atender a uma espera pelo objeto mutex.

Um objeto mutex só pode ser liberado pelo thread que contém o mutex no momento. Se for feita uma tentativa de liberar um mutex que o thread não contém ou se um mutex tiver sido adquirido em IRQL = DISPATCH_LEVEL e o thread não estiver em execução no DISPATCH_LEVEL (e vice-versa), a rotina gerará uma exceção de STATUS_ABANDONED ou STATUS_MUTEX_NOT_OWNED.

Quando um objeto mutex atinge um estado sinalizado, ele é removido da lista de mutexes que são mantidos por esse thread. Se essa lista não contiver mais entradas, a prioridade original para o thread será restaurada.

A rotina KeReleaseMutex pode gerar temporariamente o IRQL. Se o parâmetro Wait for FALSE, a rotina, antes de retornar, restaurará o IRQL para o valor original que ele tinha no início da chamada.

Se Wait = TRUE, a rotina retornará sem reduzir o IRQL. Nesse caso, a chamada KeReleaseMutex deve ser seguida imediatamente por uma chamada KeWaitXxx . Ao definir Wait = TRUE, o chamador pode impedir que uma opção de contexto desnecessária ocorra entre a chamada KeReleaseMutex e a chamada KeWaitXxx . A rotina KeWaitXxx , antes de retornar, restaura o IRQL para seu valor original no início da chamada KeReleaseMutex . Embora o IRQL desabilite as opções de contexto entre as duas chamadas, essas chamadas não podem ser usadas de forma confiável como o início e o fim de uma operação atômica. Por exemplo, entre essas duas chamadas, um thread que está sendo executado ao mesmo tempo em outro processador pode alterar o estado do objeto de evento ou do destino da espera.

Se o chamador estiver em execução em IRQL = DISPATCH_LEVEL ou em um contexto de thread arbitrário, o parâmetro Timeout para KeWaitXxx deverá ser zero.

Se um mutex for adquirido recursivamente, o thread de retenção deverá chamar KeReleaseMutex tantas vezes quanto adquiriu o mutex para defini-lo para o estado sinalizado.

Para obter mais informações sobre objetos mutex, consulte Objetos Mutex.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Disponível a partir do Windows 2000.
Plataforma de Destino	Universal
Cabeçalho	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL
Regras de conformidade da DDI	HwStorPortProhibitedDIs(storport), IrqlKeDispatchLte(wdm)