Função WaitForMultipleObjectsEx (synchapi.h)

Aguarda até que um ou todos os objetos especificados estejam no estado sinalizado, uma rotina de conclusão de E/S ou APC (chamada de procedimento assíncrono) seja enfileirada para o thread ou o intervalo de tempo limite decorrido.

Sintaxe

DWORD WaitForMultipleObjectsEx(
  [in] DWORD        nCount,
  [in] const HANDLE *lpHandles,
  [in] BOOL         bWaitAll,
  [in] DWORD        dwMilliseconds,
  [in] BOOL         bAlertable
);

Parâmetros

[in] nCount

O número de identificadores de objeto a aguardar na matriz apontada por lpHandles. O número máximo de identificadores de objeto é MAXIMUM_WAIT_OBJECTS. Esse parâmetro não pode ser zero.

[in] lpHandles

Uma matriz de identificadores de objeto. Para obter uma lista dos tipos de objeto cujos identificadores podem ser especificados, consulte a seção Comentários a seguir. A matriz pode conter identificadores de objetos de diferentes tipos. Ele pode não conter várias cópias do mesmo identificador.

Se um desses identificadores for fechado enquanto a espera ainda estiver pendente, o comportamento da função será indefinido.

Os identificadores devem ter o direito de acesso SYNCHRONIZE . Para obter mais informações, consulte Direitos de acesso padrão.

[in] bWaitAll

Se esse parâmetro for TRUE, a função retornará quando o estado de todos os objetos na matriz lpHandles for definido como sinalizado. Se FALSE, a função retornará quando o estado de qualquer um dos objetos for definido como sinalizado. No último caso, o valor retornado indica o objeto cujo estado fez com que a função retornasse.

[in] dwMilliseconds

O intervalo de tempo limite em milissegundos. Se um valor diferente de zero for especificado, a função aguardará até que os objetos especificados sejam sinalizados, uma rotina de conclusão de E/S ou APC seja enfileirada ou o intervalo se especifique. Se dwMilliseconds for zero, a função não entrará em um estado de espera se os critérios não forem atendidos; ele sempre retorna imediatamente. Se dwMilliseconds for INFINITE, a função retornará somente quando os objetos especificados forem sinalizados ou uma rotina de conclusão de E/S ou APC estiver na fila.

Windows XP, Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 e Windows Server 2008 R2: o valor dwMilliseconds inclui o tempo gasto em estados de baixa potência. Por exemplo, o tempo limite continua em contagem regressiva enquanto o computador está adormecido.

Windows 8, Windows Server 2012, Windows 8.1, Windows Server 2012 R2, Windows 10 e Windows Server 2016: o valor dwMilliseconds não inclui o tempo gasto em estados de baixa potência. Por exemplo, o tempo limite não continua em contagem regressiva enquanto o computador está adormecido.

[in] bAlertable

Se esse parâmetro for TRUE e o thread estiver no estado de espera, a função retornará quando o sistema enfileirar uma rotina de conclusão de E/S ou APC e o thread executar a rotina ou a função. Caso contrário, a função não retornará e a rotina de conclusão ou a função APC não será executada.

Uma rotina de conclusão é enfileirada quando a função ReadFileEx ou WriteFileEx na qual ela foi especificada foi concluída. A função de espera retorna e a rotina de conclusão é chamada somente se bAlertable for TRUE e o thread de chamada for o thread que iniciou a operação de leitura ou gravação. Um APC é enfileirado quando você chama QueueUserAPC.

Retornar valor

Se a função for bem-sucedida, o valor retornado indicará o evento que causou o retorno da função. Pode ser um dos seguintes valores. (Observe que WAIT_OBJECT_0 é definido como 0 e WAIT_ABANDONED_0 é definido como 0x00000080L.)

Valor/código retornado Descrição
WAIT_OBJECT_0 para (WAIT_OBJECT_0 + nCount – 1)
Se bWaitAll for TRUE, um valor retornado nesse intervalo indicará que o estado de todos os objetos especificados é sinalizado.

Se bWaitAll for FALSE, o valor retornado menos WAIT_OBJECT_0 indicará o índice da matriz lpHandles do objeto que atendeu à espera. Se mais de um objeto tiver sido sinalizado durante a chamada, esse será o índice de matriz do objeto sinalizado com o menor valor de índice de todos os objetos sinalizados.

WAIT_ABANDONED_0 para (WAIT_ABANDONED_0 + nCount – 1)
Se bWaitAll for TRUE, um valor retornado nesse intervalo indicará que o estado de todos os objetos especificados é sinalizado e pelo menos um dos objetos é um objeto mutex abandonado.

Se bWaitAll for FALSE, o valor retornado menos WAIT_ABANDONED_0 indicará o índice de matriz lpHandles de um objeto mutex abandonado que atendeu à espera. A propriedade do objeto mutex é concedida ao thread de chamada e o mutex é definido como não atribuído.

Se um mutex estava protegendo informações de estado persistente, você deve marcar-lo para consistência.

WAIT_IO_COMPLETION
0x000000C0L
A espera foi encerrada por uma ou mais APC (chamadas de procedimento assíncronas ) no modo de usuário enfileiradas para o thread.
WAIT_TIMEOUT
0x00000102L
O intervalo de tempo limite decorrido, as condições especificadas pelo parâmetro bWaitAll não foram atendidas e nenhuma rotina de conclusão é enfileirada.
WAIT_FAILED
(DWORD)0xFFFFFFFF
A função falhou. Para obter informações de erro estendidas, chame GetLastError.

Comentários

A função WaitForMultipleObjectsEx determina se os critérios de espera foram atendidos. Se os critérios não tiverem sido atendidos, o thread de chamada entrará no estado de espera até que as condições dos critérios de espera tenham sido atendidas ou o intervalo de tempo limite se escorra.

Quando bWaitAll for TRUE, a operação de espera da função será concluída somente quando os estados de todos os objetos tiverem sido definidos como sinalizados. A função não modifica os estados dos objetos especificados até que os estados de todos os objetos tenham sido definidos como sinalizados. Por exemplo, um mutex pode ser sinalizado, mas o thread não obtém propriedade até que os estados dos outros objetos também sejam definidos como sinalizados. Enquanto isso, algum outro thread pode obter a propriedade do mutex, definindo assim seu estado como não atribuído.

Quando bWaitAll é FALSE, essa função verifica os identificadores na matriz a partir do índice 0, até que um dos objetos seja sinalizado. Se vários objetos forem sinalizados, a função retornará o índice do primeiro identificador na matriz cujo objeto foi sinalizado.

A função modifica o estado de alguns tipos de objetos de sincronização. A modificação ocorre apenas para o objeto ou objetos cujo estado sinalizado fez com que a função retornasse. Por exemplo, a contagem de um objeto de semáforo é reduzida em um. Para obter mais informações, consulte a documentação dos objetos de sincronização individuais.

Para aguardar mais de MAXIMUM_WAIT_OBJECTS identificadores, use um dos seguintes métodos:

  • Crie um thread para aguardar MAXIMUM_WAIT_OBJECTS identificadores e aguarde esse thread mais os outros identificadores. Use essa técnica para dividir os identificadores em grupos de MAXIMUM_WAIT_OBJECTS.
  • Chame RegisterWaitForSingleObject ou SetThreadpoolWait para aguardar cada identificador. O pool de threads aguarda com eficiência nos identificadores e atribui um thread de trabalho depois que o objeto é sinalizado ou o intervalo de tempo limite expira.
A função WaitForMultipleObjectsEx pode especificar identificadores de qualquer um dos seguintes tipos de objeto na matriz lpHandles :
  • Notificação de alteração
  • Entrada do console
  • Evento
  • Notificação de recursos de memória
  • Mutex
  • Processar
  • Sinal
  • Thread
  • Temporizador de espera
Tenha cuidado ao chamar as funções de espera e o código que cria janelas direta ou indiretamente. Se um thread criar janelas, ele deverá processar mensagens. As transmissões de mensagens são enviadas para todas as janelas do sistema. Um thread que usa uma função de espera sem intervalo de tempo limite pode fazer com que o sistema fique em deadlock. Dois exemplos de código que criam indiretamente janelas são DDE e a função CoInitialize . Portanto, se você tiver um thread que cria janelas, use MsgWaitForMultipleObjects ou MsgWaitForMultipleObjectsEx, em vez de WaitForMultipleObjectsEx.

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows XP [aplicativos da área de trabalho | aplicativos UWP]
Servidor mínimo com suporte Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP]
Plataforma de Destino Windows
Cabeçalho synchapi.h (inclua Windows.h no Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
Biblioteca Kernel32.lib
DLL Kernel32.dll

Confira também

Funções de sincronização

Funções de espera