WaitOnAddress 函式 (synchapi.h)

等候位於指定位址的值變更。

語法

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

參數

[in] Address

要等候的位址。如果 Address 上的值與 CompareAddress 的值不同，函式會立即傳回。如果值相同，則函式不會傳回，直到相同進程中的另一個線程發出呼叫 WakeByAddressSingle 或 WakeByAddressAll 或逾時之前，位址上的值已變更的訊號，否則會先傳回。

[in] CompareAddress

位於 Address 之先前觀察到值位置的指標。當 Address 的值與 CompareAddress 的值不同時，函式會傳回。

[in] AddressSize

值的大小，以位元組為單位。這個參數可以是 1、 2、 4或 8。

[in, optional] dwMilliseconds

作業逾時之前要等候的毫秒數。如果此參數為 INFINITE，線程會無限期等候。

傳回值

TRUE 如果等候成功，則為。如果工作失敗，函式會傳 FALSE回。如果等候失敗，請呼叫 GetLastError 以取得擴充的錯誤資訊。特別是，如果作業逾時， GetLastError 會 傳回ERROR_TIMEOUT。

備註

安裝 Windows 軟體開發套件 (SDK) 可能需要取得 synchronization.lib Microsoft Store 應用程式開發人員。

WaitOnAddress 函式可供線程使用，以等候特定值從某些非想要的值變更為任何其他值。 WaitOnAddress 比在迴圈中使用 whileSleep 函式更有效率，因為 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
標頭	synchapi.h (包含 Windows.h)
程式庫	Synchronization.lib
Dll	API-MS-Win-Core-Synch-l1-2-0.dll