Função ZwWaitForSingleObject (ntifs.h)

Artigo
02/29/2024

A rotina ZwWaitForSingleObject aguarda até que o objeto especificado atinja um estado de Signaled. Um tempo limite opcional também pode ser especificado.

Sintaxe

NTSYSAPI NTSTATUS ZwWaitForSingleObject(
  [in]           HANDLE         Handle,
  [in]           BOOLEAN        Alertable,
  [in, optional] PLARGE_INTEGER Timeout
);

Parâmetros

[in] Handle

Um identificador para o objeto .

[in] Alertable

Um valor booliano que especifica se a espera é alertável.

[in, optional] Timeout

Um ponteiro opcional para um valor de tempo limite que especifica o tempo absoluto ou relativo em que a espera deve ser concluída. Um valor negativo especifica um intervalo relativo à hora atual. O valor deve ser expresso em unidades de 100 nanossegundos. Os tempos de expiração absolutos acompanham as alterações na hora do sistema. Os tempos relativos de expiração não são afetados pelas alterações de tempo do sistema.

Retornar valor

ZwWaitForSingleObject pode retornar um dos seguintes códigos de status possíveis:

Código de retorno	Descrição
STATUS_ACCESS_DENIED	O chamador não tinha os privilégios necessários para o evento especificado pelo parâmetro Handle .
STATUS_ALERTED	A espera foi anulada para entregar um alerta ao thread atual.
STATUS_INVALID_HANDLE	O parâmetro Handle fornecido era inválido.
STATUS_SUCCESS	O objeto especificado atendeu à espera.
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 puder ser atendido imediatamente e o parâmetro Timeout for definido como zero.
STATUS_USER_APC	A espera foi anulada para entregar um APC de usuário ao thread atual.

Observe que a macro NT_SUCCESS reconhece os valores STATUS_ALERTED, STATUS_SUCCESS, STATUS_TIMEOUT e STATUS_USER_APC status como valores de "êxito".

Comentários

ZwWaitForSingleObject aguarda até que o objeto especificado atinja um estado de Signaled. Um tempo limite opcional também pode ser especificado. ZwWaitForSingleObject examina o estado atual do objeto especificado para determinar se a espera pode ser atendida imediatamente. Nesse caso, as ações são executadas. 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.

Se um parâmetro Timeout não for especificado, a espera não será atendida até que o objeto atinja um estado de Signaled. Se um parâmetro Timeout for especificado e o objeto não tiver atingido um estado de Signaled quando o tempo limite expirar, a espera será atendida automaticamente. Se um valor de Tempo limite explícito de zero for especificado, nenhuma espera ocorrerá se a espera não puder ser atendida imediatamente. 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. A espera também pode ser especificada como alertável.

O parâmetro Alertable especifica se o thread pode ser alertado e seu estado de espera, consequentemente, anulado. Se o valor desse parâmetro for FALSE, o thread não poderá ser alertado. A única exceção a essa regra é a de um thread de terminação. Em determinadas circunstâncias, um thread de encerramento pode ser alertado enquanto ele está em processo de encerramento. Um thread é automaticamente tornado alertável, por exemplo, quando encerrado por um usuário com um CTRL+C.

Se o valor de Alertablefor TRUE e uma das seguintes condições estiver presente, o thread será alertado:

Se a origem do alerta for uma rotina interna e não documentada do modo kernel usada para alertar threads.
A origem do alerta é um APC no modo de usuário.

No primeiro desses dois casos, a espera do thread é satisfeita com uma status de conclusão de STATUS_ALERTED. No segundo caso, ele está satisfeito com uma status de conclusão de STATUS_USER_APC.

O thread deve ser alertável para que um APC no modo de usuário seja entregue. Esse não é o caso para APCs no modo kernel. Um APC no modo kernel pode ser entregue e executado mesmo que o thread não seja alertado. Depois que a execução do APC for concluída, a espera do thread será retomada. Um thread nunca é alertado, nem sua espera é anulada, pela entrega de um APC no modo kernel.

A entrega de APCs no modo kernel para um thread de espera não depende se o thread pode ser alertado. Se o APC do modo kernel for um APC especial no modo kernel, a APC será entregue, desde que o IRQL seja menor que APC_LEVEL. Se o APC do modo kernel for um APC normal no modo kernel, o APC será entregue desde que as três condições a seguir sejam mantidas: (1) o IRQL é menor que APC_LEVEL, (2) nenhum APC de kernel está em andamento e (3) o thread não está em uma seção crítica.

Se o identificador passado para ZwWaitForSingleObject se referir a um mutex, a entrega do APC será a mesma que para todos os outros objetos dispatcher durante a espera. No entanto, uma vez que ZwWaitForSingleObject retorna com STATUS_SUCCESS e o thread realmente contém o mutex, apenas 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.

É especialmente importante marcar o valor retornado de ZwWaitForSingleObject quando o parâmetro Alertable for TRUE, pois ZwWaitForSingleObject pode retornar antecipadamente com um status de STATUS_USER_APC ou STATUS_ALERTED.

Todas as esperas de longo prazo poderão ser anuladas por um usuário se o parâmetro Alertable estiver definido como FALSE.

Para obter informações adicionais, consulte Os threads de espera recebem alertas e APCs?

Os chamadores de ZwWaitForSingleObject devem estar em execução no IRQL menor ou igual a DISPATCH_LEVEL. Normalmente, o chamador deve estar em execução no IRQL PASSIVE_LEVEL e em um contexto de thread nonarbitrary. Uma chamada durante a execução no IRQL DISPATCH_LEVEL será válida se e somente se o chamador especificar um parâmetro Timeout de zero. Ou seja, um driver não deve esperar por um intervalo diferente de zero em IRQL igual a DISPATCH_LEVEL.

Os intervalos de tempo limite são medidos em relação ao relógio do sistema e a precisão da medida de tempo limite é limitada pela granularidade do relógio do sistema. Para obter mais informações, consulte Precisão do temporizador.

Se a chamada para a função ZwWaitForSingleObject ocorrer no modo de usuário, você deverá usar o nome "NtWaitForSingleObject" em vez de "ZwWaitForSingleObject".

Para chamadas de drivers no modo kernel, as versões NtXxx e ZwXxx de uma rotina dos Serviços do Sistema Nativo do Windows podem se comportar de forma diferente na maneira como lidam e interpretam parâmetros de entrada. Para obter mais informações sobre a relação entre as versões NtXxx e ZwXxx de uma rotina, consulte Usando versões Nt e Zw das rotinas dos Serviços de Sistema Nativo.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP
Plataforma de Destino	Universal
Cabeçalho	ntifs.h (inclua Ntifs.h, FltKernel.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Regras de conformidade de DDI	HwStorPortProhibitedDIs(storport), SpNoWait(storport)