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

另請參閱

WakeByAddressAll

WakeByAddressSingle

VBS 記憶體保護區中可用的 Vertdll API