Função WaitOnAddress (synchapi.h)

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.

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

Confira também

WakeByAddressAll

WakeByAddressSingle

APIs Vertdll disponíveis em enclaves de VBS