WaitOnAddress function (synchapi.h)

Article
02/06/2024

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 at Address differs from the value at CompareAddress, 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 calling WakeByAddressSingle or WakeByAddressAll or the timeout elapses, whichever comes first.

[in] CompareAddress

A pointer to the location of the previously observed value at Address. The function returns when the value at Address differs from the value at CompareAddress.

[in] AddressSize

The size of the value, in bytes. This parameter can be 1, 2, 4, or 8.

[in, optional] dwMilliseconds

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

Return value

TRUE if the wait succeeded. If the operation fails, the function returns FALSE. If the wait fails, call GetLastError to obtain extended error information. In particular, if the operation times out, GetLastError returns ERROR_TIMEOUT.

Remarks

Microsoft Store app developers may need to obtain synchronization.lib by installing the Windows Software Development Kit (SDK).

The WaitOnAddress 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 the Sleep function inside a while loop because WaitOnAddress 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 call WakeByAddressSingle to wake a single waiting thread or WakeByAddressAll to wake all waiting threads. If WakeByAddressSingle is called, other waiting threads continue to wait.

Note: WaitOnAddress is guaranteed to return when the address is signaled, but it is also allowed to return for other reasons. For this reason, after WaitOnAddress returns the caller should compare the new value with the original undesired value to confirm that the value has actually changed. For example, the following circumstances can result in waking the thread early:

Low memory conditions
A previous wake on the same address was abandoned
Executing code on a checked build of the operating system

Examples

The following example shows how to use 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;
}

Requirements

Requirement	Value
Minimum supported client	Windows 8 [desktop apps \| UWP apps]
Minimum supported server	Windows Server 2012 [desktop apps \| UWP apps]
Target Platform	Windows
Header	synchapi.h (include Windows.h)
Library	Synchronization.lib
DLL	API-MS-Win-Core-Synch-l1-2-0.dll

Share via