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 を呼び出すことによって Address の値が変更されたことを通知するか、タイムアウトが経過するまで、どちらか早く戻りません。

[in] CompareAddress

Address で以前に観察された値の位置へのポインター。 Address の値が CompareAddress の値と異なる場合、関数は を返します。

[in] AddressSize

値のサイズ (バイト単位)。 このパラメーターには、1、24または を指定8できます。

[in, optional] dwMilliseconds

操作がタイムアウトするまでに待機するミリ秒数。このパラメーターが INFINITE の場合、スレッドは無期限に待機します。

戻り値

TRUE 待機に成功した場合は 。 操作が失敗した場合、関数は を返します FALSE。 待機が失敗した場合は、 GetLastError を 呼び出して拡張エラー情報を取得します。 特に、操作がタイムアウトした場合、GetLastError はERROR_TIMEOUTを返します。

注釈

Microsoft Store アプリ開発者は、Windows ソフトウェア開発キット (Windows SDK) (SDK) をインストールして取得synchronization.libする必要がある場合があります。

WaitOnAddress 関数は、スレッドが特定の値が望ましくない値から他の値に変更されるのを待機するために使用できます。 WaitOnAddress は、スレッド スケジューラに干渉しないため、ループ内で whileSleep 関数を使用するよりも効率的です。 WaitOnAddress は、イベントを作成して初期化し、値と正しく同期されていることを確認する必要がないため、イベント オブジェクトよりも簡単に使用できます。 WaitOnAddress は、メモリ不足の状態の影響を受けず、次に示すようにスレッドを早期にウェイクする可能性があります。

スレッドが待機しているアドレスの値を変更する同じプロセス内のすべてのスレッドは 、WakeByAddressSingle を呼び出して 1 つの待機スレッドをスリープ解除するか 、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 を含む)
Library Synchronization.lib
[DLL] API-MS-Win-Core-Synch-l1-2-0.dll

こちらもご覧ください

WakeByAddressAll

WakeByAddressSingle

VBS エンクレーブで使用できる Vertdll API