Função RegisterWaitForSingleObject (winbase.h)
Direciona um thread de espera no pool de threads para aguardar o objeto . O thread de espera enfileira a função de retorno de chamada especificada para o pool de threads quando ocorre um dos seguintes:
- O objeto especificado está no estado sinalizado.
- O intervalo de tempo limite passa.
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.
Se esse identificador estiver fechado enquanto a espera ainda estiver pendente, o comportamento da função será indefinido.
Os identificadores devem ter o direito de acesso SYNCHRONIZE . Para obter mais informações, consulte Direitos de acesso padrão.
[in] Callback
Um ponteiro para a função definida pelo aplicativo do tipo WAITORTIMERCALLBACK a ser executada 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 decorrer, 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 usar um 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 | Significado |
|---|---|
|
Por padrão, a função de retorno de chamada é enfileirada em um thread de trabalho que não é de E/S. |
|
Esse sinalizador não é usado.
Windows Server 2003 e Windows XP: A função de retorno de chamada é enfileirada em um thread de trabalho de E/S. Esse sinalizador deve ser usado se a função deve ser executada em um thread que aguarda em um estado alertável. Os threads de trabalho de E/S foram removidos a partir do Windows Vista e do Windows Server 2008. |
|
A função de retorno de chamada é enfileirada em um thread que nunca termina. Ele não garante que o mesmo thread seja usado a cada vez. Esse sinalizador deve ser usado apenas para tarefas curtas ou pode afetar outras operações de espera.
Esse sinalizador deverá ser definido se o thread chamar funções que usam APCs. Para obter mais informações, consulte Chamadas de procedimento assíncrono. Observe que atualmente nenhum thread de trabalho é realmente persistente, embora nenhum thread de trabalho seja encerrado se houver solicitações de E/S pendentes. |
|
A função de retorno de chamada é invocada pelo thread de espera em si. Esse sinalizador deve ser usado apenas para tarefas curtas ou pode afetar outras operações de espera.
Deadlocks poderão ocorrer se algum outro thread adquirir um bloqueio exclusivo e chamar a função UnregisterWait ou UnregisterWaitEx enquanto a função de retorno de chamada estiver tentando adquirir o mesmo bloqueio. |
|
A função de retorno de chamada pode executar uma longa espera. Esse sinalizador ajuda o sistema a decidir se ele deve criar um thread. |
|
O thread não aguardará mais o identificador depois que a função de retorno de chamada tiver sido chamada uma vez. Caso contrário, o temporizador será redefinido sempre que a operação de espera for concluída até que a operação de espera seja cancelada. |
|
As funções de retorno de chamada usarão o token de acesso atual, seja um processo ou token de representação. Se esse sinalizador não for especificado, as funções de retorno de chamada serão executadas somente com o token de processo.
Windows XP: Esse sinalizador não tem suporte até o Windows XP com SP2 e Windows Server 2003. |
Valor retornado
Se a função for bem-sucedida, o valor retornado será diferente de zero.
Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame
GetLastError.
Comentários
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 passa. Se dwFlags não for WT_EXECUTEONLYONCE, o temporizador será redefinido sempre que o evento for sinalizado ou o intervalo de tempo limite decorrer.
Quando a espera for concluída, você deverá chamar a função UnregisterWait ou UnregisterWaitEx para cancelar a operação de espera. (Até mesmo 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 de semáforo é reduzida em um.
A função RegisterWaitForSingleObject 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
Por padrão, o pool de threads tem no máximo 500 threads. Para aumentar esse limite, use a macro WT_SET_MAX_THREADPOOL_THREAD definida em 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 exija 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 pool de threads mínimo usando as funções SetThreadpoolThreadMaximum e SetThreadpoolThreadMinimum ou crie seu próprio thread usando a função CreateThread . (Para a API do pool de threads original, 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
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows XP [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2003 [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | winbase.h (incluir Windows.h) |
| Biblioteca | Kernel32.lib |
| DLL | Kernel32.dll |
Confira também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de