Skip to main content

XTaskQueueTerminate

保留中のすべての項目をキャンセルし、新しい項目がキューに登録されないようにすることで、タスク キューを終了します。

構文

パラメーター

queue   _In_
Type: XTaskQueueHandle
終了するキューです。 wait   _In_
Type: bool
終了処理の完了を待機するには true を指定します。 callbackContext   _In_opt_
Type: void*
コールバックに渡す省略可能なコンテキスト ポインターです。 callback   _In_opt_
Type: XTaskQueueTerminatedCallback*
キューの終了時に呼び出される省略可能なコールバックです。

戻り値

Type: HRESULT HRESULT の成功またはエラー コード。

解説

この関数は、時間依存スレッドで呼び出しても安全ではありません。詳細については、Time-sensitive threads を参照してください。
XTaskQueueCloseHandle は、タスク キュー オブジェクトの内部参照カウントを単純にデクリメントするだけです。まだキューにコールバックが残っている場合、それらのコールバックはキュー オブジェクトに対する参照を保持しており、引き続き呼び出される可能性があります。これはアプリケーションのシャットダウン時に問題となる可能性があります。アプリケーションをシャットダウンする際は、クリーンアップ後に意図しないコールバックが実行されないようにする必要があります。XTaskQueue は、キューの制御された終了を実行するために XTaskQueueTerminate API を提供します。 タスク キューを終了すると、次の処理が実行されます:
  1. 両方のポートのすべてのコールバックが、canceled パラメーターが true に設定された状態で呼び出されます。
  2. ワーク ポートで保留中のすべてのコールバックがディスパッチされます。ワーク ポートに新しいコールバックを送信すると E_ABORT で失敗します。
  3. 完了ポートで保留中のすべてのコールバックがディスパッチされます。完了ポートに新しいコールバックを送信すると E_ABORT で失敗します。
このプロセスが完了すると、wait が true の場合は XTaskQueueTerminate が戻ります。wait が false の場合、終了は非同期に行われます。終了コールバックを指定した場合、終了処理の最後に完了スレッドから呼び出されます。
  • XTaskQueueTerminate はキュー ハンドルを閉じません。終了処理後も XTaskQueueCloseHandle を呼び出す必要があります。
  • XTaskQueueDispatch を呼び出してキュー コールバックを処理しているスレッドで XTaskQueueTerminate を呼び出す場合は、wait パラメーターに true を渡さないでください。渡すとデッドロックが発生する可能性があります。
次の例では、以前に作成したタスク キューを終了する方法を示します。
SubmitCallback は、XTaskQueueSubmitCallback 関数のコード例で定義されているヘルパー関数です。
タスク キューは UI スレッドと統合できます。通常は、完了ポートにキューされたコールバックを UI スレッドで実行させたいでしょう。この例では、作業にはスレッド プールを使用しますが、完了ポートのコールバックは Win32 のウィンドウ プロシージャーに統合します。また、他のスレッド モデルと統合する場合の、タスク キューの正しい終了方法も示しています。

要件

ヘッダー: XTaskQueue.h ライブラリ: xgameruntime.lib サポートされているプラットフォーム: Windows、XBOX One 本体、XBOX Series 本体

概念ドキュメント

関連項目

XTaskQueue members
非同期プログラミング モデル
非同期タスク キューの設計
最終更新日 2026年8月24日