RegisterWaitForSingleObject 関数 (winbase.h)

オブジェクトで待機するように スレッド プール 内の待機スレッドを指示します。 待機スレッドは、次のいずれかが発生したときに、指定されたコールバック関数をスレッド プールにキューに入れます。

• 指定されたオブジェクトはシグナル状態です。
• タイムアウト間隔が経過します。

構文

BOOL RegisterWaitForSingleObject(
  [out]          PHANDLE             phNewWaitObject,
  [in]           HANDLE              hObject,
  [in]           WAITORTIMERCALLBACK Callback,
  [in, optional] PVOID               Context,
  [in]           ULONG               dwMilliseconds,
  [in]           ULONG               dwFlags
);

パラメーター

[out] phNewWaitObject

戻り時に待機ハンドルを受け取る変数へのポインター。 CloseHandle などのオブジェクト ハンドルを必要とする関数では、待機ハンドルを使用できないことに注意してください。

[in] hObject

オブジェクトへのハンドル。 ハンドルを指定できるオブジェクトの種類の一覧については、次の「解説」セクションを参照してください。

待機がまだ保留中の間にこのハンドルが閉じている場合、関数の動作は未定義です。

ハンドルには SYNCHRONIZE アクセス権が必要です。 詳細については、「 Standard Access Rights」を参照してください。

[in] Callback

hObject がシグナル状態の場合、または dwMilliseconds が経過したときに実行される WAITORTIMERCALLBACK 型のアプリケーション定義関数へのポインター。 詳細については、「 WaitOrTimerCallback」を参照してください。

[in, optional] Context

コールバック関数に渡される 1 つの値。

[in] dwMilliseconds

タイムアウト間隔 (ミリ秒単位)。 関数は、オブジェクトの状態が非署名の場合でも、間隔が経過した場合に を返します。 dwMilliseconds が 0 の場合、関数はオブジェクトの状態をテストし、直ちにを返します。 dwMilliseconds が INFINITE の場合、関数のタイムアウト間隔は経過しません。

[in] dwFlags

このパラメーターには、次の 1 つ以上の値を指定できます。

シグナル状態のままのオブジェクトでこれらの値を使用する方法については、「解説」セクションを参照してください。

戻り値

関数が成功すると、戻り値は 0 以外になります。

関数が失敗した場合は、0 を返します。 拡張エラー情報を取得するには、 を呼び出します。
GetLastError。

注釈

新しい待機スレッドは、必要に応じて自動的に作成されます。 待機操作は、スレッド プールからの待機スレッドによって実行されます。 コールバック ルーチンは、オブジェクトの状態がシグナル状態になるか、タイムアウト間隔が経過したときにワーカー スレッドによって実行されます。 dwFlags がWT_EXECUTEONLYONCEされていない場合、イベントが通知されるかタイムアウト間隔が経過するたびにタイマーがリセットされます。

待機が完了したら、UnregisterWait または UnregisterWaitEx 関数を呼び出して待機操作を取り消す必要があります。 ( WT_EXECUTEONLYONCE を使用する待機操作も取り消す必要があります。コールバック関数内からこれらの関数に対してブロック呼び出しを行わないでください。

RegisterWaitForSingleObject に渡されたイベント オブジェクトは、リセット前に待機スレッドによって通知されないことがあるため、パルスを設定しないでください。 WT_EXECUTEONLYONCEまたは WT_EXECUTEINWAITTHREAD フラグを設定しない限り、シグナル状態のままのオブジェクト (手動リセット イベントや終了プロセスなど) を登録しないでください。 その他のフラグの場合、イベントがリセットされる前にコールバック関数が何度も呼び出されることがあります。

関数は、一部の種類の同期オブジェクトの状態を変更します。 変更は、待機条件が満たされる原因となったシグナル状態のオブジェクトに対してのみ行われます。 たとえば、セマフォ オブジェクトの数は 1 ずつ減少します。

RegisterWaitForSingleObject 関数は、次のオブジェクトを待機できます。

• 変更通知
• コンソール入力
• イベント
• メモリ リソース通知
• Mutex
• Process
• Semaphore
• スレッド
• 待機可能タイマー

既定では、スレッド プールのスレッド数は最大 500 です。 この制限を引き上げるには、WinNT.h で定義 されているWT_SET_MAX_THREADPOOL_THREAD マクロを使用します。

#define WT_SET_MAX_THREADPOOL_THREADS(Flags,Limit) \
    ((Flags)|=(Limit)<<16)

dwFlags パラメーターを指定する場合は、このマクロを使用します。 マクロ パラメーターは、目的のフラグと新しい制限 (最大 (2<<16)-1 スレッド) です。 ただし、ワーカー スレッドの数を少なめておくと、アプリケーションのパフォーマンスが向上する可能性があることに注意してください。

作業項目と呼び出すすべての関数は、スレッド プール セーフである必要があります。 そのため、既定のコールバック環境から RegNotifyChangeKeyValue 関数などの永続的なスレッドを必要とする非同期呼び出しを呼び出すことはできません。 代わりに、SetThreadpoolThreadMaximum 関数と SetThreadpoolThreadMinimum 関数を使用してスレッド プールの最大値をスレッド プールの最小値に設定するか、CreateThread 関数を使用して独自のスレッドを作成します。 (元のスレッド プール API の場合は、QueueUserWorkItem 関数を使用してWT_EXECUTEINPERSISTENTTHREADを指定します)。

この関数を使用するアプリケーションをコンパイルするには、 _WIN32_WINNT を 0x0500 以降として定義します。 詳細については、「 Windows ヘッダーの使用」を参照してください。

要件

関連項目

同期関数

スレッド プール

UnregisterWait

UnregisterWaitEx

待機関数

WaitOrTimerCallback