Share via

Função WaitForSingleObject (synchapi.h)

  • Artigo

Aguarda até que o objeto especificado esteja no estado sinalizado ou o intervalo de tempo limite se especifique.

Para inserir um estado de espera alertável, use a função WaitForSingleObjectEx . Para aguardar vários objetos, use WaitForMultipleObjects.

Sintaxe

DWORD WaitForSingleObject(
  [in] HANDLE hHandle,
  [in] DWORD  dwMilliseconds
);

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 direito de acesso SYNCHRONIZE . Para obter mais informações, consulte Direitos de acesso padrão.

[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 ou o intervalo se especifique. Se dwMilliseconds for zero, a função não entrará em um estado de espera se o objeto não for sinalizado; ele sempre retorna imediatamente. Se dwMilliseconds for INFINITE, a função retornará somente quando o objeto for sinalizado.

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.

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.

Valor/código retornado 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 término do thread proprietário. A propriedade do objeto mutex é concedida ao thread de chamada e o estado mutex é definido como não atribuído.

Se o mutex estava protegendo informações de estado persistente, você deve marcar-lo para consistência.
WAIT_OBJECT_0
0x00000000L
 O estado do objeto especificado é sinalizado.
WAIT_TIMEOUT
0x00000102L
 O intervalo de tempo limite passou 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.

Comentários

A função WaitForSingleObject verifica o estado atual do objeto especificado. Se o estado do objeto não estiver atribuído, o thread de chamada entrará no estado de espera até que o objeto seja sinalizado ou o intervalo de tempo limite desatribua.

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 de semáforo é reduzida em um.

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

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

Exemplos

Para obter um exemplo, consulte Usando objetos Mutex.

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