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 つ以上の値を指定できます。

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

値 意味
WT_EXECUTEDEFAULT
0x00000000
 既定では、コールバック関数は I/O 以外のワーカー スレッドにキューに入れられます。
WT_EXECUTEINIOTHREAD
0x00000001
 このフラグは使用されません。

Windows Server 2003 および Windows XP: コールバック関数は、I/O ワーカー スレッドにキューに入れられます。 このフラグは、警告可能な状態で待機するスレッドで関数を実行する必要がある場合に使用する必要があります。

I/O ワーカー スレッドは、Windows Vista および Windows Server 2008 以降で削除されました。
WT_EXECUTEINPERSISTENTTHREAD
0x00000080
 コールバック関数は、終了しないスレッドにキューに入れられます。 毎回同じスレッドが使用される保証はありません。 このフラグは、短いタスクにのみ使用するか、他の待機操作に影響する可能性があります。

スレッドが APC を使用する関数を呼び出す場合は、このフラグを設定する必要があります。 詳細については、「 非同期プロシージャ呼び出し」を参照してください。

現在、ワーカー スレッドは本当に永続的ではありませんが、保留中の I/O 要求がある場合、ワーカー スレッドは終了しません。
WT_EXECUTEINWAITTHREAD
0x00000004
 コールバック関数は、待機スレッド自体によって呼び出されます。 このフラグは、短いタスクにのみ使用するか、他の待機操作に影響する可能性があります。

コールバック関数が同じロックを取得しようとしているときに、他のスレッドが排他ロックを取得し 、UnregisterWait または UnregisterWaitEx 関数を呼び出すと、デッドロックが発生する可能性があります。
WT_EXECUTELONGFUNCTION
0x00000010
 コールバック関数は長い待機を実行できます。 このフラグは、システムが新しいスレッドを作成する必要があるかどうかを判断するのに役立ちます。
WT_EXECUTEONLYONCE
0x00000008
 コールバック関数が 1 回呼び出された後、スレッドはハンドルを待機しなくなります。 それ以外の場合、待機操作が取り消されるまで待機操作が完了するたびにタイマーがリセットされます。
WT_TRANSFER_IMPERSONATION
0x00000100
 コールバック関数は、プロセスまたは偽装トークンのいずれであっても、現在のアクセス トークンを使用します。 このフラグを指定しない場合、コールバック関数はプロセス トークンでのみ実行されます。

Windows XP: このフラグは、SP2 と Windows Server 2003 の Windows XP まではサポートされません。

戻り値

関数が成功すると、戻り値は 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 ヘッダーの使用」を参照してください。

要件

要件 値
サポートされている最小のクライアント Windows XP (デスクトップ アプリのみ)
サポートされている最小のサーバー Windows Server 2003 (デスクトップ アプリのみ)
対象プラットフォーム Windows
ヘッダー winbase.h (Windows.h を含む)
Library Kernel32.lib
[DLL] Kernel32.dll

関連項目

同期関数

スレッド プール

UnregisterWait

UnregisterWaitEx

待機関数

WaitOrTimerCallback