Função FltCancellableWaitForMultipleObjects (fltkernel.h)
O FltCancellableWaitForMultipleObjects executa uma operação de espera cancelável (uma espera que pode ser encerrada) em um ou mais objetos dispatcher.
Sintaxe
NTSTATUS FLTAPI FltCancellableWaitForMultipleObjects(
[in] ULONG Count,
[in] PVOID [] ObjectArray,
[in] WAIT_TYPE WaitType,
[in, optional] PLARGE_INTEGER Timeout,
[in, optional] PKWAIT_BLOCK WaitBlockArray,
[in] PFLT_CALLBACK_DATA CallbackData
);
Parâmetros
[in] Count
O número de objetos a serem aguardados.
[in] ObjectArray
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.
[in] WaitType
Uma enumeração com o valor de WaitAll, que indica que todos os objetos especificados devem atingir um estado sinalizado antes que a espera seja atendida; ou WaitAny, que indica que qualquer um dos objetos deve atingir um estado sinalizado antes que a espera seja atendida.
[in, optional] Timeout
Um ponteiro para um valor de tempo limite opcional. Esse parâmetro especifica o tempo absoluto ou relativo em 100 unidades nanossegundos em que a espera deve ser concluída.
Se o Tempo Limite apontar para um valor zero (ou seja, *Tempo limite == 0), a rotina retornará sem esperar. Se o chamador fornecer um ponteiro NULL (ou seja, Timeout == NULL), a rotina aguardará indefinidamente até que qualquer um ou todos os objetos do dispatcher sejam definidos como o estado sinalizado.
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 o 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 igual a zero (ou seja, *Tempo limite == 0) permite testar um conjunto de condições de espera e executar condicionalmente quaisquer ações adicionais se a espera puder ser atendida imediatamente, como na aquisição de um mutex.
[in, optional] WaitBlockArray
Se a Contagem <= THREAD_WAIT_OBJECTS, WaitBlockArray poderá ser NULL. Caso contrário, esse parâmetro deve apontar para um buffer de memória de sizeof(KWAIT_BLOCK) * Count bytes. A rotina usa esse buffer para manter registros enquanto executa a operação de espera.
[in] CallbackData
Um ponteiro para a estrutura de FLT_CALLBACK_DATA que representa a operação de E/S emitida pelo usuário e que pode ser cancelada pelo usuário. Esse parâmetro é opcional e pode ser NULL. O chamador deve garantir que a operação de E/S permanecerá válida durante essa rotina e que a E/S não deve ter um conjunto de rotina de cancelamento (por exemplo, a função fltSetCancelCompletion não deve ter sido chamada na operação de E/S). Observe que o
Valor de retorno
FltCancellableWaitForMultipleObjects pode retornar um dos seguintes valores:
O valor retornado indica apenas o status da espera.
Observe que a macro NT_SUCCESS retorna FALSE ("falha") para os valores de status STATUS_CANCELLED e STATUS_THREAD_IS_TERMINATING e VERDADEIRO ("êxito") para todos os outros valores de status.
Observações
O
A rotina foi projetada para dar suporte às diretrizes de conclusão/cancelamento de E/S de . O objetivo dessas diretrizes é permitir que os usuários encerrem rapidamente os aplicativos. Isso, por sua vez, requer que os aplicativos tenham a capacidade de encerrar rapidamente threads que estão executando e/S e quaisquer operações de E/S atuais. Essa rotina fornece uma maneira de os threads do usuário bloquearem (ou seja, aguardar) no kernel para conclusão de E/S, objetos dispatcher ou variáveis de sincronização de uma maneira que permita que a espera seja prontamente cancelada. Essa rotina também permite que a espera do thread seja encerrada se o thread for encerrado por um usuário ou um aplicativo.
Por exemplo, um redirecionador pode precisar criar uma ou mais operações de E/S secundárias para processar uma E/S no modo de usuário e aguardar de forma síncrona a conclusão das solicitações secundárias. Uma maneira de fazer isso é configurar um evento que será sinalizado pela rotina de conclusão das operações de E/S secundárias e aguardar a sinalização do evento. Em seguida, para executar uma operação de espera cancelável, FltCancellableWaitForMultipleObjects é chamado de passar os eventos associados às operações de E/S secundárias e a operação de E/S do modo de usuário original. A espera do thread para que o evento seja sinalizado será cancelada se ocorrer um evento de encerramento pendente ou se a operação de E/S do modo de usuário original for cancelada.
Observe que encerrar a espera não cancela automaticamente nenhuma operação de E/S emitida pelo chamador , que deve ser tratada separadamente pelo chamador.
Cada objeto thread tem uma matriz interna de blocos de espera que você pode usar para aguardar vários objetos simultaneamente. Sempre que possível, você deve usar a matriz interna de blocos de espera 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 você deve aguardar 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. Você não precisa inicializar o buffer e os drivers podem tratá-lo como uma estrutura opaca. Você pode liberar o buffer assim que a rotina for retornada.
Se a contagem for maior que MAXIMUM_WAIT_OBJECTS ou se WaitBlockArray for NULL e Contagem for maior que THREAD_WAIT_OBJECTS, o sistema emitirá 0xC de Verificação de Bugs: MAXIMUM_WAIT_OBJECTS_EXCEEDED.
Uma consideração especial se aplica quando um ou mais dos elementos no parâmetro ObjectArray passados para FltCancellableWaitForMultipleObjects refere-se a um mutex. Se o objeto dispatcher que é aguardado for um mutex, a entrega do APC será a mesma que para todos os outros objetos dispatcher durante a espera. No entanto, uma vez FltCancellableWaitForMultipleObjects 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.
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.
A rotina de
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Windows Vista |
| da Plataforma de Destino |
Universal |
| cabeçalho | fltkernel.h (inclua Ntifs.h, Fltkernel.h) |
| biblioteca | Fltmgr.lib |
| IRQL | Consulte a seção Comentários. |
Consulte também
FltCancellableWaitForSingleObject