Função KeWaitForMultipleObjects (wdm.h)
O KeWaitForMultipleObjects rotina coloca o thread atual em um estado de espera alertável ou não inerte até que qualquer um ou todos os vários objetos dispatcher sejam definidos como um estado sinalizado ou (opcionalmente) até o tempo limite de espera.
Sintaxe
NTSTATUS
KeWaitForMultipleObjects (
ULONG Count,
PVOID Object[],
WaitType,
KWAIT_REASON WaitReason,
KPROCESSOR_MODE WaitMode,
BOOLEAN Alertable,
PLARGE_INTEGER Timeout,
PKWAIT_BLOCK WaitBlockArray
);
Parâmetros
[in] Count
O número de objetos a serem aguardados. Esse parâmetro especifica o número de elementos na matriz apontada pelo parâmetro Object.
[in] Object
Um ponteiro para uma matriz de ponteiros para objetos dispatcher (eventos, mutexes, semáforos, threads e temporizadores) para os quais o chamador fornece o armazenamento. Tanto a matriz de ponteiro quanto os objetos dispatcher devem residir na memória do sistema nãopagada. Para obter mais informações, consulte Comentários.
[in] WaitType
O tipo de operação de espera a ser executada. Especifique WaitAll, indicando que todos os objetos especificados devem atingir um estado sinalizado antes que a espera seja atendida; ou WaitAny, indicando que qualquer um dos objetos deve atingir um estado sinalizado antes que a espera seja atendida.
[in] WaitReason
O motivo da espera. Os drivers devem definir esse valor como Executiva ou, se o driver estiver trabalhando em nome de um usuário e estiver em execução no contexto de um thread de usuário, para UserRequest.
[in] WaitMode
Se o chamador aguarda em KernelMode ou UserMode. Drivers intermediários e de nível mais baixo devem especificar kernelMode. Se o conjunto de objetos aguardados incluir um mutex, o chamador deverá especificar kernelMode.
[in] Alertable
Um valor booliano que indica se o thread pode ser alertado enquanto está no estado de espera.
[in, optional] Timeout
Um 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 qualquer um ou todos os objetos do dispatcher sejam definidos como o estado sinalizado. Para obter mais informações, consulte a seção Comentários a seguir.
[out, optional] WaitBlockArray
Um ponteiro para uma matriz de KWAIT_BLOCK alocada pelo chamador. Se Contagem<= THREAD_WAIT_OBJECTS, WaitBlockArray poderá ser NULL. Caso contrário, esse parâmetro deve apontar para um buffer de memória de tamanhos de(KWAIT_BLOCK) * Contagem bytes. A rotina usa esse buffer para manter registros enquanto executa a operação de espera. O buffer WaitBlockArray deve residir na memória do sistema nãopagada. Para obter mais informações, consulte Comentários.
Valor de retorno
KeWaitForMultipleObjects pode retornar um dos seguintes:
| Código de retorno | Descrição |
|---|---|
| STATUS_SUCCESS | O chamador especificado WaitAll para o parâmetro WaitType e todos os objetos dispatcher na matriz Object foram definidos como o estado sinalizado. |
| 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íncrono) ao thread de chamada. |
| STATUS_TIMEOUT | Ocorreu um tempo limite antes que o conjunto especificado de condições de espera fosse atendido. Esse valor pode ser retornado quando um valor de tempo limite explícito de zero é especificado, mas o conjunto especificado de condições de espera não pode ser atendido imediatamente. |
| STATUS_WAIT_0STATUS_WAIT_63 | O chamador especificado WaitAny para WaitType e um dos objetos dispatcher na matriz objeto foi definido como o estado sinalizado. Os seis bits inferiores do valor retornado codificam o índice baseado em zero do objeto que satisfize a espera. |
| STATUS_ABANDONED_WAIT_0STATUS_ABANDONED_WAIT_63 | O chamador tentou esperar por um mutex que foi abandonado. Os seis bits inferiores do valor retornado codificam o índice baseado em zero do mutex na matriz objeto. |
Observe que a macro NT_SUCCESS reconhece todos esses valores de status como valores de "êxito".
Observações
Cada objeto thread tem uma matriz interna de blocos de espera que podem ser usados para aguardar que vários objetos sejam definidos simultaneamente. Sempre que possível, a matriz interna de blocos de espera deve ser usada em uma operação de espera múltipla porque nenhum armazenamento de bloco de espera adicional precisa ser alocado e desalocado posteriormente. No entanto, se o número de objetos que devem ser aguardados simultaneamente for maior do que o número de blocos de espera internos, use o parâmetro WaitBlockArray para especificar um conjunto alternativo de blocos de espera a serem usados na operação de espera. Os drivers só precisam alocar um buffer de memória suficientemente grande para waitBlockArray. O buffer não precisa ser inicializado; no entanto, ele deve ser alocado da memória do sistema nãopagada. Se o parâmetro WaitMode for UserMode, o buffer WaitBlockArray não deverá ser alocado na pilha local porque a pilha pode ser trocada por memória. Os drivers podem tratar esse buffer como uma estrutura opaca e podem liberá-lo após o retorno da rotina. Se Contagem> MAXIMUM_WAIT_OBJECTS ou se waitBlockArray estiver NULL e Contagem> THREAD_WAIT_OBJECTS, o sistema emitirá 0xC de Verificação de Bugs (MAXIMUM_WAIT_OBJECTS_EXCEEDED).
O estado atual de cada um dos objetos especificados é examinado para determinar se a espera pode ser atendida imediatamente. Se os efeitos colaterais necessários forem executados nos objetos, um valor apropriado será retornado.
Se a espera não puder ser atendida imediatamente e nenhum valor de tempo limite ou um valor de tempo limite diferente de zero tiver sido especificado, o thread atual será colocado em um estado de espera e um novo thread será selecionado para execução no processador atual. Se nenhum tempo limite for fornecido, o thread de chamada permanecerá em um estado de espera até que as condições especificadas por Object e WaitType sejam atendidas.
Se tempo limite for especificado, a espera será atendida automaticamente se nenhuma das condições de espera especificadas for atendida quando o intervalo especificado expirar.
Um valor de tempo limite de zero permite o teste de um conjunto de condições de espera, executando condicionalmente 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 de Precisão do Temporizador.
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.
A matriz apontada pelo parâmetro objetos deve residir na memória do sistema nãopagada. Normalmente, um driver aloca o armazenamento para a matriz objetos na pilha local. A matriz Objects pode ser alocada na pilha local, independentemente do valor do parâmetro WaitMode.
Os objetos dispatcher apontados pelos elementos na matriz objetos devem 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 KeWaitForMultipleObjects com o argumento UserMode. Se você alocar o evento na pilha, deverá definir o parâmetro WaitMode para kernelMode.
Uma consideração especial se aplica quando o parâmetro Object passado para KeWaitForMultipleObjects é 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, após KeWaitForMultipleObjects 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.
É especialmente importante verificar o valor retornado de KeWaitForMultipleObjects quando o parâmetro WaitMode é usermode ou alertável é TRUE, porque KeWaitForMultipleObjects 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ável devem ser definidas como FALSE.
Sempre que possível, alertável 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.
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 KeWaitForMultipleObjects podem estar em execução no IRQL <= DISPATCH_LEVEL. No entanto, se Timeout = NULL ou *Timeout != 0, o chamador deverá estar em execução no IRQL <= APC_LEVEL e em um contexto de thread nonarbitrary. (Se Timeout != NULL e *Timeout = 0, o chamador deverá estar em execução no IRQL <= DISPATCH_LEVEL.)
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Disponível a partir do Windows 2000. |
| da Plataforma de Destino | Universal |
| cabeçalho | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| biblioteca | NtosKrnl.lib |
| de DLL | NtosKrnl.exe |
| IRQL | Consulte a seção Comentários. |
| regras de conformidade de DDI | HwStorPortProhibitedDIs(storport), IrpProcessingComplete(wdm), IrqlKeWaitForMultipleObjects(wdm), SpNoWait(storport) |