Função WaitForMultipleObjectsEx (synchapi.h)

  • Artigo

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 no 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. 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 acesso SYNCHRONIZE direito. Para obter mais informações, consulte Standard Access Rights.

[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 causou o retorno da função.

[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 decorrido. 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 dwMilliseconds valor inclui o tempo gasto em estados de baixa potência. Por exemplo, o tempo limite continua em contagem regressiva enquanto o computador está dormindo.

Windows 8 e mais recente, Windows Server 2012 e mais recente: o valor dwMilliseconds não inclui o tempo gasto em estados de baixa potência. Por exemplo, o tempo limite não mantém a contagem regressiva enquanto o computador está dormindo.

[in] bAlertable

Se esse parâmetro for VERDADEIRO e o thread estiver no estado de espera, a função retornará quando o sistema enfileira 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 foi especificada tiver sido concluída. A função de espera retorna e a rotina de conclusão é chamada somente se bAlertable é VERDADEIRO e o thread de chamada é o thread que iniciou a operação de leitura ou gravação. Um APC é enfileirado quando você chama QueueUserAPC.

Valor de retorno

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

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

Se bWaitAll for FALSE, o valor retornado menos WAIT_OBJECT_0 indicará o índice lpHandles matriz do objeto que satisfize a 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 VERDADEIRO, um valor retornado nesse intervalo indicará que o estado de todos os objetos especificados está 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 de um objeto mutex abandonado que satisfize a 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 verificar se há consistência.
WAIT_IO_COMPLETION
0x000000C0L
 A espera foi encerrada por um ou mais chamadas de procedimento assíncronas (APC) enfileiradas no 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.

Observações

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 sejam atendidas ou o intervalo de tempo limite decorrido.

Quando bWaitAll é verdadeiro, a operação de espera da função é concluída somente quando os estados de todos os objetos foram 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 a 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 para começar com o í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 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, em seguida, aguarde esse thread mais as outras alças. Use essa técnica para dividir as alças em grupos de MAXIMUM_WAIT_OBJECTS.
  • Chame RegisterWaitForSingleObject ou SetThreadpoolWait aguardar em cada identificador. O pool de threads aguarda com eficiência nas alças 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:
  • Alterar notificação
  • Entrada do console
  • Acontecimento
  • Notificação de recurso de memória
  • Mutex
  • Processo
  • Semáforo
  • Fio
  • Temporizador aguardável
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 janelas indiretamente 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
de cliente com suporte mínimo Windows XP [aplicativos da área de trabalho | Aplicativos UWP]
servidor com suporte mínimo Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP]
da 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
de DLL Kernel32.dll

Consulte também

Funções de sincronização

Funções de espera