Waits for the value at the specified address to change.

Syntax

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

Parameters

[in] Address

The address on which to wait. If the value atAddress differs from the value atCompareAddress, the function returns immediately. If the values are the same, the function does not return until another thread in the same process signals that the value at Address has changed by callingWakeByAddressSingle orWakeByAddressAll or the timeout elapses, whichever comes first.

[in] CompareAddress

A pointer to the location of the previously observed value atAddress. The function returns when the value atAddress differs from the value atCompareAddress.

[in] AddressSize

The size of the value, in bytes. This parameter can be1,2,4, or8.

[in, optional] dwMilliseconds

The number of milliseconds to wait before the operation times out. If this parameter isINFINITE, the thread waits indefinitely.

Return value

TRUE if the wait succeeded. If the operation fails, the function returnsFALSE. If the wait fails, callGetLastError to obtain extended error information. In particular, if the operation times out,GetLastError returnsERROR_TIMEOUT.

Remarks

Microsoft Store app developers may need to obtainsynchronization.lib by installing theWindows Software Development Kit (SDK).

TheWaitOnAddress function can be used by a thread to wait for a particular value to change from some undesired value to any other value.WaitOnAddress is more efficient than using theSleep function inside awhile loop becauseWaitOnAddress does not interfere with the thread scheduler.WaitOnAddress is also simpler to use than an event object because it is not necessary to create and initialize an event and then make sure it is synchronized correctly with the value.WaitOnAddress is not affected by low-memory conditions, other than potentially waking the thread early as noted below.

Any thread within the same process that changes the value at the address on which threads are waiting should callWakeByAddressSingle to wake a single waiting thread orWakeByAddressAll to wake all waiting threads. IfWakeByAddressSingle is called, other waiting threads continue to wait.

Examples

The following example shows how to useWaitOnAddress.

ULONG g_TargetValue; // global, accessible to all threadsULONG CapturedValue;ULONG UndesiredValue;UndesiredValue = 0;CapturedValue = g_TargetValue;while (CapturedValue == UndesiredValue) {      WaitOnAddress(&g_TargetValue, &UndesiredValue, sizeof(ULONG), INFINITE);      CapturedValue = g_TargetValue;}

Requirements

See also

WakeByAddressAll

WakeByAddressSingle

Vertdll APIs available in VBS enclaves