Функция WaitOnAddress (synchapi.h)

Статья
02/05/2024

Ожидает изменения значения по указанному адресу.

Синтаксис

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

Параметры

[in] Address

Адрес, по которому требуется ждать. Если значение в поле Address отличается от значения в CompareAddress, функция возвращается немедленно. Если значения совпадают, функция не возвращается до тех пор, пока другой поток в том же процессе не сигнализирует об изменении значения в поле Address путем вызова WakeByAddressSingle или WakeByAddressAll или истечения времени ожидания, в зависимости от того, что наступит первым.

[in] CompareAddress

Указатель на расположение ранее наблюдаемого значения в поле Адрес. Функция возвращает, если значение адреса отличается от значения в CompareAddress.

[in] AddressSize

Размер значения в байтах. Этот параметр может иметь значение 1, 2, 4или 8.

[in, optional] dwMilliseconds

Время ожидания в миллисекундах до истечения времени ожидания операции. Если этот параметр имеет значение INFINITE, поток ожидает неограниченное время.

Возвращаемое значение

TRUE Значение , если ожидание выполнено успешно. Если операция завершается сбоем, функция возвращает .FALSE Если ожидание завершается сбоем, вызовите Метод GetLastError , чтобы получить расширенные сведения об ошибке. В частности, если время ожидания операции истекает, GetLastError возвращает ERROR_TIMEOUT.

Функция WaitOnAddress может использоваться потоком для ожидания изменения определенного значения с некоторого нежелательного значения на любое другое. WaitOnAddress эффективнее, чем использование функции Спящего режима в while цикле, так как WaitOnAddress не влияет на планировщик потоков. WaitOnAddress также проще использовать, чем объект события, так как нет необходимости создавать и инициализировать событие, а затем убедиться, что оно правильно синхронизировано со значением. На WaitOnAddress не влияют условия нехватки памяти, кроме потенциального пробуждения потока, как указано ниже.

Любой поток в рамках одного процесса, изменяющий значение по адресу, по которому ожидаются потоки, должен вызывать WakeByAddressSingle , чтобы разбудить один ожидающий поток, или WakeByAddressAll для пробуждения всех ожидающих потоков. Если вызывается WakeByAddressSingle , другие ожидающие потоки продолжают ждать.

Примечание.WaitOnAddress гарантированно возвращается при получении сигнала об адресе, но он также может вернуться по другим причинам. По этой причине после возврата WaitOnAddress вызывающий объект должен сравнить новое значение с исходным нежелательным значением, чтобы убедиться, что значение действительно изменилось. Например, следующие обстоятельства могут привести к пробуждению потока на раннем этапе:

Условия нехватки памяти
Предыдущее пробуждение по тому же адресу было прервано
Выполнение кода в проверенной сборке операционной системы

Примеры

В следующем примере показано, как использовать 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;
}

Требования

Требование	Значение
Минимальная версия клиента	Windows 8 [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2012 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	synchapi.h (включая Windows.h)
Библиотека	Synchronization.lib
DLL	API-MS-Win-Core-Synch-l1-2-0.dll

См. также раздел

WakeByAddressAll

WakeByAddressSingle

API-интерфейсы Vertdll, доступные в анклавах VBS

Поделиться через