タスク キュー API の概要
タスク キューは、ワーク ポートと完了ポートの 2 つのキュー ポートで構成されています。これらのポートは同じオブジェクトにまとめられています。これは、非同期処理を実行するためのワーク ポートと、それをユーザーに通知するための完了ポートの両方が必要になることが多いためです。 タスク キューは以下のように説明できます。- 2 つのタスク キュー ポートが含まれます。
- 各タスク キュー ポートは独自のディスパッチ モードを持つことができ、これがキュー内の項目をディスパッチする方法を決定します。
- ディスパッチ モードは、システム スレッド プールによる完全自動ディスパッチから、明示的にタスクを取り出す必要がある完全手動ディスパッチまで、さまざまです。
- コールバックはキューのどちらのポートにも送信できます。
- キューはハンドルで表されます。ハンドルは複製することができ、その動作は基本的にキューの参照カウントを増やします。
- スレッド プール: スレッド プール キューにキューされたコールバックは、システム スレッド プールで実行されます。スレッド プールは、呼び出しを並列に呼び出し、スレッド プール スレッドが利用可能になるたびにキューから順番に呼び出しを取り出して実行します。
- シリアル化スレッド プール: コールバックはスレッド プールにキューされ実行されますが、すべてのスレッド プール スレッドで並列に実行される代わりに、次々と順番に実行されます。
- 手動: 手動キューにキューされたコールバックは、自動的にはディスパッチされません。任意のスレッドでディスパッチするのはあなた次第です。手動タスク キューを使用する場合は、Windows メッセージ キューもポンプ処理するようにする必要があります。
- 即時: 即時ディスパッチ モードはキューを行いません。コールバックを送信したスレッドで直ちに呼び出しを実行します。
XTaskQueueDuplicateHandle、XTaskQueueSubmitCallback、XTaskQueueSubmitDelayedCallback、および XTaskQueueCreateComposite はすべて、キュー ハンドルへの参照を追加します。つまり、すべてのコールバックが完了するまで、キューは実際には破棄されません。
タスク キュー ハンドルはプロセス単位のリソースであり、プロセス外にマーシャリングまたは使用することはできません。
使用パターン
タスク キューの典型的な使用パターンは次のとおりです。- タスク キュー ハンドルを作成し、各ポートのディスパッチ モードを指定します。
- 手動ディスパッチを使用する場合は、キューのディスパッチ関数を呼び出すためのアプリ固有のスレッドを確立します。
-
キューを Microsoft Game Development Kit (GDK) 呼び出しのパラメーターとして使用するか、
XTaskQueueCallbackを使用して直接送信します。 - 必要に応じて、アプリのシャットダウン時にタスク キューを終了します。
非同期タスク キューの「方法」トピック
このセクションでは、一般的な非同期タスク キューのシナリオの「方法」の例を提供します。このセクションの内容
スレッド プール タスク キューの作成 ワーク コールバックと完了コールバックの両方をシステム スレッド プールでディスパッチするタスク キューを作成する方法の例を示します。 コールバックの送信 タスク キューのワーク ポートまたは完了ポートにコールバックを送信する方法の例を示します。 タスク キュー ハンドルの複製 タスク キュー ハンドルを複製する方法の例を示します。長時間実行される作業がある場合は、その作業の期間中、タスク キュー ハンドルを複製したい場合があります。こうすると、XTaskQueueCloseHandle を呼び出す誰かが、まだキューを必要としている間にそれをクローズしてしまうことを防げます。
手動タスク キューの作成
手動でポンプ処理するタスク キューを作成する方法の例を示します。ワーク ポートと完了ポートの両方の呼び出しをディスパッチする 2 つの STL スレッドを作成します。
イベントを使用した手動キュー ディスパッチの制御
ディスパッチする項目があるときに、タスク キューを使用して条件変数にシグナルを送る方法の例を示します。
Windows メッセージ ループでタスク キューを使用する
ワークにはスレッド プールを使用しますが、完了ポート コールバックを Win32 の Window proc に統合する例を示します。この例では、他のスレッド モデルと統合する際のタスク キューの正しい終了方法も示しています。
プロセス タスク キューの使用
プロセス タスク キューを使用する方法の例を示します。既定のプロセス タスク キューは、ワークと完了の両方のディスパッチにスレッド プールを使用します。
複合タスク キューの作成
ワークにはスレッド プールを使用しますが、完了ポート コールバックを Win32 の WindowProc コールバック関数に統合する例を示します。この例では、他のスレッド モデルと統合する際のタスク キューの正しい終了方法も示しています。
遅延コールバックの使用
500 ミリ秒ごとに 10 個のコールバックを呼び出し、遅延コールバックを使用する方法の例を示します。XTaskQueueSubmitDelayedCallback API を使用して、タスク キューを使って未来にコールバックを送信します。このようにすることで、失敗した呼び出しを短い遅延の後に再試行したり、定期イベント用の安価なタイマーとして使用したりすることができます。
タスク キュー ウェイターの使用
タスク キュー ウェイターを使用する方法の例を示します。Win32 カーネル ハンドルをタスク キューに登録できます。ハンドルがシグナル状態になると、コールバックがキューに送信されます。