Função PulseEvent (winbase.h)

Artigo
03/13/2024

Define o objeto de evento especificado para o estado sinalizado e o redefine para o estado não atribuído depois de liberar o número apropriado de threads em espera.

Nota Essa função não é confiável e não deve ser usada. Ele existe principalmente para compatibilidade com versões anteriores. Para obter mais informações, consulte Comentários.

Sintaxe

BOOL PulseEvent(
  [in] HANDLE hEvent
);

Parâmetros

[in] hEvent

Um identificador para o objeto de evento. A função CreateEvent ou OpenEvent retorna esse identificador.

O identificador deve ter o direito de acesso EVENT_MODIFY_STATE. Para obter mais informações, consulte Segurança do objeto de sincronização e direitos de acesso.

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

Um thread que aguarda um objeto de sincronização pode ser removido momentaneamente do estado de espera por um APC no modo kernel e, em seguida, retornado ao estado de espera após a conclusão do APC. Se a chamada para PulseEvent ocorrer durante o tempo em que o thread foi removido do estado de espera, o thread não será liberado porque PulseEvent libera apenas os threads que estão aguardando no momento em que é chamado. Portanto, PulseEvent não é confiável e não deve ser usado por novos aplicativos. Em vez disso, use variáveis de condição.

Para um objeto de evento de redefinição manual, todos os threads em espera que podem ser liberados imediatamente são liberados. Em seguida, a função redefine o estado do objeto de evento para não atribuído e retorna.

Para um objeto de evento de redefinição automática, a função redefine o estado para não atribuído e retorna depois de liberar um único thread de espera, mesmo que vários threads estejam aguardando.

Se nenhum thread estiver aguardando ou se nenhum thread puder ser liberado imediatamente, PulseEvent simplesmente definirá o estado do objeto de evento como não atribuído e retornará.

Observe que, para um thread que usa as funções de espera de vários objetos aguardar que todos os objetos especificados sejam sinalizados, PulseEvent pode definir o estado do objeto de evento como sinalizado e redefini-lo para não atribuído sem fazer com que a função de espera retorne. Isso ocorrerá se nem todos os objetos especificados forem sinalizados simultaneamente.

Tenha extrema cautela ao usar SignalObjectAndWait e PulseEvent com o Windows 7, pois 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.

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