Compartilhar via

Função WaitOnAddress (synchapi.h)

  • Artigo

Aguarda o valor no endereço especificado ser alterado.

Sintaxe

BOOL WaitOnAddress(
  [in]           volatile VOID *Address,
  [in]           PVOID         CompareAddress,
  [in]           SIZE_T        AddressSize,
  [in, optional] DWORD         dwMilliseconds
);

Parâmetros

[in] Address

O endereço no qual aguardar. Se o valor em Address for diferente do valor em CompareAddress, a função retornará imediatamente. Se os valores forem os mesmos, a função não retornará até que outro thread no mesmo processo sinalize que o valor em Address foi alterado chamando WakeByAddressSingle ou WakeByAddressAll ou o tempo limite passa, o que ocorrer primeiro.

[in] CompareAddress

Um ponteiro para o local do valor observado anteriormente em Address. A função retorna quando o valor em Address difere do valor em CompareAddress.

[in] AddressSize

O tamanho do valor, em bytes. Esse parâmetro pode ser 1, 2, 4ou 8.

[in, optional] dwMilliseconds

O número de milissegundos a aguardar antes que a operação limite. Se esse parâmetro for INFINITE, o thread aguardará indefinidamente.

Retornar valor

TRUE se a espera foi bem-sucedida. Se a operação falhar, a função retornará FALSE. Se a espera falhar, chame GetLastError para obter informações de erro estendidas. Em particular, se a operação atingir o tempo limite, GetLastError retornará ERROR_TIMEOUT.

Comentários

Talvez os desenvolvedores de aplicativos da Microsoft Store precisem obter synchronization.lib instalando o Software Development Kit do Windows (SDK do Windows) (SDK).

A função WaitOnAddress pode ser usada por um thread para aguardar que um valor específico seja alterado de algum valor indesejado para qualquer outro valor. WaitOnAddress é mais eficiente do que usar a função Sleep dentro de um while loop porque WaitOnAddress não interfere no agendador de threads. WaitOnAddress também é mais simples de usar do que um objeto de evento porque não é necessário criar e inicializar um evento e, em seguida, verificar se ele está sincronizado corretamente com o valor. WaitOnAddress não é afetado por condições de memória insuficiente, além de potencialmente acordar o thread mais cedo, conforme observado abaixo.

Qualquer thread dentro do mesmo processo que altera o valor no endereço no qual os threads estão aguardando deve chamar WakeByAddressSingle para ativar um único thread de espera ou WakeByAddressAll para ativar todos os threads em espera. Se WakeByAddressSingle for chamado, outros threads de espera continuarão aguardando.

Observação:WaitOnAddress tem a garantia de retornar quando o endereço é sinalizado, mas também tem permissão para retornar por outros motivos. Por esse motivo, depois que WaitOnAddress retornar, o chamador deverá comparar o novo valor com o valor original indesejado para confirmar se o valor realmente foi alterado. Por exemplo, as seguintes circunstâncias podem resultar na ativação antecipada do thread:
  • Condições de memória insuficiente
  • Uma ativação anterior no mesmo endereço foi abandonada
  • Executando código em um build verificado do sistema operacional
 

Exemplos

O exemplo a seguir mostra como usar WaitOnAddress.

ULONG g_TargetValue; // global, accessible to all threads
ULONG CapturedValue;
ULONG UndesiredValue;

UndesiredValue = 0;
CapturedValue = g_TargetValue;
while (CapturedValue == UndesiredValue) {
      WaitOnAddress(&g_TargetValue, &UndesiredValue, sizeof(ULONG), INFINITE);
      CapturedValue = g_TargetValue;
}

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows 8 [aplicativos da área de trabalho | Aplicativos UWP]
Servidor mínimo com suporte Windows Server 2012 [aplicativos da área de trabalho | Aplicativos UWP]
Plataforma de Destino Windows
Cabeçalho synchapi.h (inclua Windows.h)
Biblioteca Synchronization.lib
DLL API-MS-Win-Core-Synch-l1-2-0.dll

Confira também

WakeByAddressAll

WakeByAddressSingle

APIs Vertdll disponíveis em enclaves de VBS