Função KeWaitForSingleObject (wdm.h)

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é que a espera limite.

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 verdadeiro 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 um tempo absoluto 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 *Tempo limite = 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.

Valor de retorno

KeWaitForSingleObject pode retornar um dos seguintes.

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

Observações

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 alertável 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 retorna com STATUS_SUCCESS e o thread realmente contém o mutex, somente APCs especiais no modo kernel sã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 verificar 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 alertáveis 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 principal exceção a isso é quando a espera é uma espera de longo prazo.

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

Um valor de tempo limite de 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.

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 por tempo 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 o TEMPO LIMITE = NULL ou *Tempo limite != 0, o chamador deverá estar em execução em IRQL <= APC_LEVEL e em um contexto de thread não secundário. Se Tempo limite != NULL e *Tempo limite = 0, o chamador deverá estar em execução no 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 aos Objetos Mutex.

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

Requirements

Consulte também

ExInitializeFastMutex

KeBugCheckEx

KeInitializeEvent

KeInitializeMutex

KeInitializeSemaphore

KeInitializeTimer

KeWaitForMultipleObjects