Função RegisterWaitForSingleObject (winbase.h)

Direciona um thread de espera no pool de threads aguardar no objeto. O thread de espera enfileira a função de retorno de chamada especificada para o pool de threads quando ocorre um destes procedimentos:

• O objeto especificado está no estado sinalizado.
• O intervalo de tempo limite decorrido.

Sintaxe

BOOL RegisterWaitForSingleObject(
  [out]          PHANDLE             phNewWaitObject,
  [in]           HANDLE              hObject,
  [in]           WAITORTIMERCALLBACK Callback,
  [in, optional] PVOID               Context,
  [in]           ULONG               dwMilliseconds,
  [in]           ULONG               dwFlags
);

Parâmetros

[out] phNewWaitObject

Um ponteiro para uma variável que recebe um identificador de espera no retorno. Observe que um identificador de espera não pode ser usado em funções que exigem um identificador de objeto, como CloseHandle.

[in] hObject

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.

Não há suporte para o Mutex. Se um identificador para um mutex for passado, o pool de threads gerará uma exceção STATUS_THREADPOOL_HANDLE_EXCEPTION e ExceptionRecord.ExceptionInformation[0] será igual a STATUS_INVALID_PARAMETER_3.

Se esse identificador estiver 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] Callback

Um ponteiro para a função definida pelo aplicativo do tipo WAITORTIMERCALLBACK a ser executado quando hObject estiver no estado sinalizado ou dwMilliseconds decorridos. Para obter mais informações, consulte WaitOrTimerCallback.

[in, optional] Context

Um único valor que é passado para a função de retorno de chamada.

[in] dwMilliseconds

O intervalo de tempo limite, em milissegundos. A função retornará se o intervalo decorrido, mesmo que o estado do objeto não esteja atribuído. Se dwMilliseconds for zero, a função testará o estado do objeto e retornará imediatamente. Se dwMilliseconds for INFINITE, o intervalo de tempo limite da função nunca será decorrido.

[in] dwFlags

Esse parâmetro pode ser um ou mais dos valores a seguir.

Para obter informações sobre como usar esses valores com objetos que permanecem sinalizados, consulte a seção Comentários.

Valor de retorno

Se a função for bem-sucedida, o valor retornado não será zero.

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame
GetLastError .

Observações

Novos threads de espera são criados automaticamente quando necessário. A operação de espera é executada por um thread de espera do pool de threads. A rotina de retorno de chamada é executada por um thread de trabalho quando o estado do objeto é sinalizado ou o intervalo de tempo limite decorrido. Se dwFlags não for WT_EXECUTEONLYONCE, o temporizador será redefinido sempre que o evento for sinalizado ou o intervalo de tempo limite decorrido.

Quando a espera for concluída, você deverá chamar a função UnregisterWait ou UnregisterWaitEx para cancelar a operação de espera. (Até mesmo as operações de espera que usam WT_EXECUTEONLYONCE devem ser canceladas.) Não faça uma chamada de bloqueio para nenhuma dessas funções de dentro da função de retorno de chamada.

Observe que você não deve pulsar um objeto de evento passado para RegisterWaitForSingleObject, pois o thread de espera pode não detectar que o evento é sinalizado antes de ser redefinido. Você não deve registrar um objeto que permaneça sinalizado (como um evento de redefinição manual ou um processo encerrado), a menos que você defina o sinalizador WT_EXECUTEONLYONCE ou WT_EXECUTEINWAITTHREAD. Para outros sinalizadores, a função de retorno de chamada pode ser chamada muitas vezes antes que o evento seja redefinido.

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 condição de espera fosse atendida. Por exemplo, a contagem de um objeto semáforo é reduzida em um.

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

• Alterar notificação
• Entrada do console
• Acontecimento
• Notificação de recurso de memória
• Processo
• Semáforo
• Fio
• Temporizador aguardável

Por padrão, o pool de threads tem no máximo 500 threads. Para elevar esse limite, use a macro WT_SET_MAX_THREADPOOL_THREAD definida no WinNT.h.

#define WT_SET_MAX_THREADPOOL_THREADS(Flags,Limit) \
    ((Flags)|=(Limit)<<16)

Use essa macro ao especificar o parâmetro dwFlags. Os parâmetros de macro são os sinalizadores desejados e o novo limite (até (2<<16)-1 threads). No entanto, observe que seu aplicativo pode melhorar seu desempenho mantendo o número de threads de trabalho baixo.

O item de trabalho e todas as funções que ele chama devem ser seguros para o pool de threads. Portanto, você não pode chamar uma chamada assíncrona que requer um thread persistente, como a função RegNotifyChangeKeyValue, do ambiente de retorno de chamada padrão. Em vez disso, defina o máximo do pool de threads igual ao mínimo do pool de threads usando as funções SetThreadpoolThreadMaximum e SetThreadpoolThreadMinimum ou crie seu próprio thread usando a função CreateThread. (Para a API original do pool de threads, especifique WT_EXECUTEINPERSISTENTTHREAD usando a função QueueUserWorkItem.)

Para compilar um aplicativo que usa essa função, defina _WIN32_WINNT como 0x0500 ou posterior. Para obter mais informações, consulte Usando os cabeçalhos do Windows.

Requisitos

Consulte também

Funções de sincronização

de pool de threads

UnregisterWait

UnregisterWaitEx

Funções de espera

WaitOrTimerCallback