Função SignalObjectAndWait (synchapi.h)
Sinaliza um objeto e aguarda em outro objeto como uma única operação.
Sintaxe
DWORD SignalObjectAndWait(
[in] HANDLE hObjectToSignal,
[in] HANDLE hObjectToWaitOn,
[in] DWORD dwMilliseconds,
[in] BOOL bAlertable
);
Parâmetros
[in] hObjectToSignal
Um identificador para o objeto a ser sinalizado. Esse objeto pode ser um semáforo, um mutex ou um evento.
Se o identificador for um semáforo, o direito de acesso SEMAPHORE_MODIFY_STATE será necessário. Se o identificador for um evento, o EVENT_MODIFY_STATE direito de acesso será necessário. Se o identificador for um mutex e o chamador não tiver o mutex, a função falhará com ERROR_NOT_OWNER.
[in] hObjectToWaitOn
Um identificador para o objeto a aguardar. O direito de acesso SYNCHRONIZE é necessário; para obter mais informações, consulte Segurança do objeto de sincronização e direitos de acesso. Para obter uma lista dos tipos de objeto cujos identificadores você pode especificar, consulte a seção Comentários.
[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 e nenhum objeto de APC (chamada de procedimento assíncrono) ou de conclusão seja enfileirado. Se dwMilliseconds for zero, a função testará o estado do objeto, verificará se há APCs ou rotinas de conclusão enfileiradas e retorna imediatamente. Se dwMilliseconds for INFINITE, o intervalo de tempo limite da função nunca será decorrido.
[in] bAlertable
Se esse parâmetro for TRUE, a função retornará quando o sistema enfileirar uma rotina de conclusão de E/S ou uma função APC e o thread chamar a função. Se FALSE, a função não retornará e o thread não chamará a rotina de conclusão ou a função APC.
Uma rotina de conclusão é enfileirada quando a chamada de função que enfileirava o APC é concluída. Essa função retorna e a rotina de conclusão é chamada somente se bAlertable for TRUE e o thread de chamada for o thread que enfileirava o APC.
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 |
|---|---|
|
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 marcar-lo para consistência. |
|
A espera foi encerrada por uma ou mais chamadas de procedimento assíncronas do modo de usuário (APC) enfileiradas no thread. |
|
O estado do objeto especificado é sinalizado. |
|
O intervalo de tempo limite decorrido e o estado do objeto não está atribuído. |
|
A função falhou. Para obter informações de erro estendidas, chame GetLastError. |
Comentários
A função SignalObjectAndWait fornece uma maneira mais eficiente de sinalizar um objeto e aguardar em outro em comparação com chamadas de função separadas, como SetEvent , seguida por WaitForSingleObject.
A função SignalObjectAndWait pode aguardar os seguintes objetos:
- Alterar notificação
- Entrada do console
- Evento
- Notificação de recurso de memória
- Mutex
- Processar
- Sinal
- Thread
- Temporizador de espera
Um thread pode usar a função SignalObjectAndWait para garantir que um thread de trabalho esteja em um estado de espera antes de sinalizar um objeto. Por exemplo, um thread e um thread de trabalho podem usar identificadores para objetos de evento para sincronizar seu trabalho. O thread executa código como o seguinte:
dwRet = WaitForSingleObject(hEventWorkerDone, INFINITE);
if( WAIT_OBJECT_0 == dwRet)
SetEvent(hEventMoreWorkToDo);
O thread de trabalho executa código como o seguinte:
dwRet = SignalObjectAndWait(hEventWorkerDone,
hEventMoreWorkToDo,
INFINITE,
FALSE);
Observe que não há garantia de que o "sinal" e a "espera" sejam executados como uma operação atômica. Os threads em execução em outros processadores podem observar o estado sinalizado do primeiro objeto antes que o thread que chama SignalObjectAndWait inicie sua espera no segundo objeto.
Tenha extrema cautela ao usar SignalObjectAndWait e PulseEvent com o Windows 7, já que usar essas APIs entre vários threads pode causar deadlock em um aplicativo. Threads sinalizados por SignalObjectAndWait chamam PulseEvent para sinalizar o objeto de espera da chamada SignalObjectAndWait . Em algumas circunstâncias, o chamador de SignalObjectAndWait não pode receber o estado de sinal do objeto de espera a tempo, causando um deadlock.
Tenha cuidado ao usar as funções de espera e o código que criam 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 COM CoInitialize. Portanto, se você tiver um thread que cria janelas, chame SignalObjectAndWait de um thread diferente. Se isso não for possível, você poderá usar MsgWaitForMultipleObjects ou MsgWaitForMultipleObjectsEx, mas a funcionalidade não é equivalente.
Para compilar um aplicativo que usa essa função, defina _WIN32_WINNT como 0x0400 ou posterior. Para obter mais informações, consulte Usando os cabeçalhos do Windows.
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) |
| Biblioteca | Kernel32.lib |
| DLL | Kernel32.dll |