Função KeReleaseSemaphore (wdm.h)

A rotina KeReleaseSemaphore libera o objeto semáforo especificado.

Sintaxe

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

Parâmetros

[in, out] Semaphore

Um ponteiro para um objeto de semáforo inicializado para o qual o chamador fornece o armazenamento.

[in] Increment

Especifica o incremento de prioridade a ser aplicado se a liberação do semáforo fizer com que uma espera seja atendida.

[in] Adjustment

Especifica um valor a ser adicionado à contagem de semáforos atual. Esse valor deve ser positivo.

[in] Wait

Especifica se a chamada para KeReleaseSemaphore deve ser seguida imediatamente por uma chamada para uma das rotinas KeWaitXxx . Se TRUE, a chamada KeReleaseSemaphore 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 estado anterior do objeto semáforo não será sinalizado.

Comentários

KeReleaseSemaphore fornece um aumento de prioridade em tempo de execução para threads de espera. Se essa chamada definir o semáforo como o estado sinalizado, a contagem de semáforos será aumentada pelo valor especificado. O chamador também pode especificar se ele chamará uma das rotinas KeWaitXxx assim que KeReleaseSemaphore retornar o controle.

A liberação de um objeto semáforo faz com que a contagem de semáforos seja aumentada pelo valor do parâmetro Adjustment . Se o valor resultante for maior que o limite do objeto semáforo, a contagem não será ajustada e uma exceção, STATUS_SEMAPHORE_LIMIT_EXCEEDED, será gerada.

Aumentar a contagem de objetos de semáforo faz com que o semáforo atinja um estado sinalizado e uma tentativa é feita para satisfazer o maior número possível de esperas no objeto semáforo.

A rotina KeReleaseSemaphore 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 keReleaseSemaphore deve ser imediatamente seguida por uma chamada KeWaitXxx . Ao definir Wait = TRUE, o chamador pode impedir que uma opção de contexto desnecessária ocorra entre a chamada KeReleaseSemaphore e a chamada KeWaitXxx . A rotina KeWaitXxx , antes de retornar, restaura o IRQL para seu valor original no início da chamada KeReleaseSemaphore . 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á em execução ao mesmo tempo em outro processador pode alterar o estado do objeto semáforo ou do destino da espera.

Aviso

Um thread paginável ou uma rotina de driver paginável que é executado em IRQL = PASSIVE_LEVEL nunca deve chamar KeReleaseSemaphore com o parâmetro Wait definido como TRUE. Essa chamada causará uma falha fatal na página se a função de chamada for paginada entre as chamadas para KeReleaseSemaphore e KeWaitXxx.

Para obter mais informações sobre objetos semáforos, consulte Objetos semáforos.

Os chamadores de KeReleaseSemaphore devem estar em execução em IRQL <= DISPATCH_LEVEL desde que Wait esteja definido como FALSE. Caso contrário, o chamador deverá estar em execução em IRQL = PASSIVE_LEVEL.

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	Consulte a seção Observações.
Regras de conformidade de DDI	HwStorPortProhibitedDDIs(storport)

Confira também

KeInitializeSemaphore

KeReadStateSemaphore

KeWaitForMultipleObjects

KeWaitForSingleObject