Função KeWaitForSingleObject (wdm.h)

Artigo
03/08/2023

A rotina KeWaitForSingleObject coloca o thread atual em um estado de espera até que o objeto dispatcher fornecido seja definido como um estado sinalizado ou (opcionalmente) até o tempo limite de espera.

Sintaxe

NTSTATUS
KeWaitForSingleObject (
    PVOID Object,
    KWAIT_REASON WaitReason,
    KPROCESSOR_MODE WaitMode,
    BOOLEAN Alertable,
    PLARGE_INTEGER Timeout
    );

Parâmetros

[in] Object

Ponteiro para um objeto dispatcher inicializado (evento, mutex, semáforo, thread ou temporizador) para o qual o chamador fornece o armazenamento. O objeto dispatcher deve residir na memória do sistema nãopagada. Para obter mais informações, consulte Comentários.

[in] WaitReason

Especifica o motivo da espera. Um driver deve definir esse valor como Executivo, a menos que ele esteja trabalhando em nome de um usuário e esteja em execução no contexto de um thread de usuário, nesse caso, ele deve definir esse valor como UserRequest.

[in] WaitMode

Especifica se o chamador aguarda em KernelMode ou UserMode. Drivers intermediários e de nível mais baixo devem especificar KernelMode. Se o Objeto fornecido for um mutex, o chamador deverá especificar KernelMode.

[in] Alertable

Especifica um valor booliano que será TRUE se a espera for alertável e FALSE caso contrário.

[in, optional] Timeout

Ponteiro para um valor de tempo limite que especifica o tempo absoluto ou relativo, em unidades de 100 nanossegundos, em que a espera deve ser concluída.

Um valor positivo especifica uma hora absoluta em relação a 1º de janeiro de 1601. Um valor negativo especifica um intervalo relativo à hora atual. Os tempos de expiração absolutos acompanham as alterações na hora do sistema; os tempos de expiração relativos não são afetados pelas alterações de tempo do sistema.

Se Timeout = 0, a rotina retornará sem esperar. Se o chamador fornecer um ponteiro NULL , a rotina aguardará indefinidamente até que o objeto dispatcher seja definido como o estado sinalizado. Para obter mais informações, consulte a seção Comentários a seguir.

Retornar valor

KeWaitForSingleObject pode retornar um dos seguintes.

A macro NT_SUCCESS reconhece todos esses valores status como valores de "êxito".

Código de retorno	Descrição
STATUS_SUCCESS	O objeto dispatcher especificado pelo parâmetro Object atendeu à espera.
STATUS_ALERTED	A espera foi interrompida para entregar um alerta ao thread de chamada.
STATUS_USER_APC	A espera foi interrompida para entregar uma APC (chamada de procedimento assíncrona) ao thread de chamada.
STATUS_TIMEOUT	Ocorreu um tempo limite antes de o objeto ser definido como um estado sinalizado. Esse valor pode ser retornado quando o conjunto especificado de condições de espera não pode ser atendido imediatamente e Timeout é definido como zero.

Comentários

O estado atual do Objeto especificado é examinado para determinar se a espera pode ser atendida imediatamente. Nesse caso, os efeitos colaterais necessários são executados no objeto . Caso contrário, o thread atual será colocado em um estado de espera e um novo thread será selecionado para execução no processador atual.

O parâmetro Alertable determina quando o thread pode ser alertado e seu estado de espera, consequentemente, anulado. Para obter informações adicionais, consulte Esperas e APCs.

Uma consideração especial se aplica quando o parâmetro Object passado para KeWaitForSingleObject é um mutex. Se o objeto dispatcher aguardado for um mutex, a entrega do APC será a mesma que para todos os outros objetos dispatcher durante a espera. No entanto, depois que KeWaitForSingleObject retornar com STATUS_SUCCESS e o thread realmente armazenar o mutex, somente APCs especiais no modo kernel serão entregues. A entrega de todas as outras APCs, no modo kernel e no modo de usuário, está desabilitada. Essa restrição na entrega de APCs persiste até que o mutex seja liberado.

O objeto dispatcher apontado pelo parâmetro Object deve residir na memória do sistema nãopagada.

Se o parâmetro WaitMode for UserMode, a pilha de kernel poderá ser trocada durante a espera. Consequentemente, um chamador nunca deve tentar passar parâmetros na pilha ao chamar KeWaitForSingleObject usando o argumento UserMode . Se você alocar o evento na pilha, deverá definir o parâmetro WaitMode como KernelMode.

É especialmente importante marcar o valor retornado de KeWaitForSingleObject quando o parâmetro WaitMode for UserMode ou Alertable for TRUE, pois KeWaitForSingleObject pode retornar mais cedo com um status de STATUS_USER_APC ou STATUS_ALERTED.

Todas as esperas de longo prazo que podem ser anuladas por um usuário devem ser esperas usermode e Alertable devem ser definidas como FALSE.

Sempre que possível, Alertable deve ser definido como FALSE e WaitMode deve ser definido como KernelMode, a fim de reduzir a complexidade do driver. A exceção principal para isso é quando a espera é uma espera de longo prazo.

Se um ponteiro NULL for fornecido para Timeout, o thread de chamada permanecerá em um estado de espera até que o Objeto seja sinalizado.

Um valor de tempo limite zero permite o teste de um conjunto de condições de espera e para o desempenho condicional de quaisquer efeitos colaterais se a espera puder ser atendida imediatamente, como na aquisição de um mutex.

Os intervalos de tempo limite são medidos em relação ao relógio do sistema e a precisão com que o sistema operacional pode detectar o fim de um intervalo de tempo limite é limitada pela granularidade do relógio do sistema. Para obter mais informações, consulte Precisão do temporizador.

Um mutex pode ser adquirido recursivamente apenas em tempos MINLONG. Se esse limite for excedido, a rotina gerará uma exceção STATUS_MUTANT_LIMIT_EXCEEDED.

Os chamadores de KeWaitForSingleObject devem estar em execução em IRQL <= DISPATCH_LEVEL. No entanto, se Timeout = NULL ou Timeout != 0, o chamador deverá estar em execução em IRQL <= APC_LEVEL e em um contexto de thread nonarbitrary. Se Timeout != NULL e Timeout = 0, o chamador deverá estar em execução em IRQL <= DISPATCH_LEVEL.

KeWaitForMutexObject é uma macro que se converte em KeWaitForSingleObject, que pode ser usada.

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

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

Requisitos

Requisito	Valor
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	CompleteRequestStatusCheck(wdm), HwStorPortProhibitedDIs(storport), IoAllocateIrpSignalEventInCompletionTimeout(wdm), IoBuildDeviceControlWait(wdm), IoBuildDeviceControlWaitTimeout(wdm), IoBuildFsdIrpSignalEventInCompletionTimeout(wdm), IoBuildSynchronousFsdRequestWait(wdm), IoBuildSynchronousFsdRequestWaitTimeout(wdm), IrpProcessingComplete(wdm), IrqlKeWaitForMutexObject(wdm), LowerDriverReturn(wdm), MarkIrpPending2(wdm), PendedCompletedRequest(wdm), PendedCompletedRequest2(wdm), PendedCompletedRequest3(wdm), PendedCompletedRequestEx(wdm), RemoveLockForwardDeviceControl(wdm), RemoveLockForwardDeviceControlInternal(wdm), RemoveLockForwardRead(wdm), RemoveLockForwardWrite(wdm), SpNoWait(storport), StartDeviceWait(wdm), StartDeviceWait2(wdm), StartDeviceWait3(wdm), StartDeviceWait4(wdm)