Função WaitForSingleObjectEx (synchapi.h)

  • Artigo

Aguarda até que o objeto especificado esteja 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.

Para aguardar vários objetos, use oWaitForMultipleObjectsEx .

Sintaxe

DWORD WaitForSingleObjectEx(
  [in] HANDLE hHandle,
  [in] DWORD  dwMilliseconds,
  [in] BOOL   bAlertable
);

Parâmetros

[in] hHandle

Um identificador para o objeto. Para obter uma lista dos tipos de objeto cujos identificadores podem ser especificados, consulte a seção Comentários a seguir.

Se esse identificador estiver fechado enquanto a espera ainda estiver pendente, o comportamento da função será indefinido.

O identificador deve ter o acesso SYNCHRONIZE direito. Para obter mais informações, consulte Standard Access Rights.

[in] dwMilliseconds

O intervalo de tempo limite, em milissegundos. Se um valor diferente de zero for especificado, a função aguardará até que o objeto seja sinalizado, 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 o objeto for sinalizado 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 é verdadeiroe 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.

Código/valor de retorno Descrição
WAIT_ABANDONED
0x00000080L
 O objeto especificado é um objeto mutex que não foi liberado pelo thread que possuía o objeto mutex antes do thread proprietário ser encerrado. A propriedade do objeto mutex é concedida ao thread de chamada e o mutex é definido como não atribuído.

Se o 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_OBJECT_0
0x00000000L
 O estado do objeto especificado é sinalizado.
WAIT_TIMEOUT
0x00000102L
 O intervalo de tempo limite decorrido e o estado do objeto não está atribuído.
WAIT_FAILED
(DWORD)0xFFFFFFFF
 A função falhou. Para obter informações de erro estendidas, chame GetLastError.

Observações

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

A função modifica o estado de alguns tipos de objetos de sincronização. A modificação ocorre apenas para o objeto cujo estado sinalizado fez com que a função retornasse. Por exemplo, a contagem de um objeto semáforo é reduzida em um.

A função WaitForSingleObjectEx pode aguardar os seguintes objetos:

  • 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 WaitForSingleObjectEx.

Exemplos

Para obter um exemplo, consulte Servidor pipe nomeado usando rotinas de conclusão.

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