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。
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 |