Compartilhar via

Função WaitForMultipleObjects (synchapi.h)

  • Artigo

Aguarda até que um ou todos os objetos especificados estejam no estado sinalizado ou o intervalo de tempo limite decorrido.

Para inserir um estado de espera alertável, use a função WaitForMultipleObjectsEx.

Sintaxe

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

Parâmetros

[in] nCount

O número de identificadores de objeto na matriz apontado 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 para 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 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 ou o intervalo decorrido. Se dwMilliseconds for zero, a função não entrará em um estado de espera se os objetos especificados não forem sinalizados; ele sempre retorna imediatamente. Se dwMilliseconds for INFINITE, a função retornará somente quando os objetos especificados forem sinalizados.

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.

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 TRUE, um valor retornado dentro do intervalo especificado 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 dentro do intervalo especificado 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 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_TIMEOUT
0x00000102L
 O intervalo de tempo limite decorrido e as condições especificadas pelo parâmetro bWaitAll não são atendidas.
WAIT_FAILED
(DWORD)0xFFFFFFFF
 A função falhou. Para obter informações de erro estendidas, chame GetLastError.

Observações

A função WaitForMultipleObjects 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 WaitForMultipleObjects 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 WaitForMultipleObjects.

Exemplos

Para obter um exemplo, consulte Aguardando vários objetos.

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)
biblioteca Kernel32.lib
de DLL Kernel32.dll

Consulte também

WAIT_ABANDONED_0

Funções de sincronização

Funções de espera