XAsyncBlock
非同期呼び出しの有効期間を表します。
構文
typedef struct XAsyncBlock {
XTaskQueueHandle queue;
void* context;
XAsyncCompletionRoutine* callback;
unsigned internal[sizeof ( void* ) * 4];
} XAsyncBlock
メンバー
queue
型: XTaskQueueHandle
省略可能。 非同期呼び出しのタスク キューのハンドル。必要に応じて、callback に完了コールバックを指定できます。 null に設定された場合、非同期呼び出しでプロセス タスク キューの使用が試みられます。 プロセス タスク キューも null に設定されている場合は、非同期呼び出しが失敗し、E_NO_TASK_QUEUE を返します。
context
型: void*
省略可能。 完了コールバックに渡される情報へのポインター。
callback
型: XAsyncCompletionRoutine*
呼び出しの完了時に呼び出されるオプションのコールバック。
internal
型: 符号なし char[sizeof(void*) * 4]
内部で使用するために予約されています。
解説
XAsyncBlock 構造体は、非同期呼び出しの有効期間を表します。 最初に、XAsyncBlock を使用して非同期呼び出しを行います。必要に応じて、非同期呼び出しの完了コールバックも指定できます。 その後、その特定の呼び出しの起動ハンドルとして XAsyncBlock を使用できます。 非同期呼び出しを行うと、その呼び出しがタスク キューに送信されて実行待機状態になります。 タスク キューを使用すると、非同期呼び出しを実行するスレッドと完了コールバックを呼び出すスレッド (完了コールバックが指定されている場合) を決定できます。 タスク キューを作成しなくても、非同期呼び出しを行うことはできます。
queue にタスク キューが指定されていない場合、既定ではプロセス タスク キューが使用されます。 通常は、プロセス タスク キューによって非同期呼び出しがシステム スレッド プールにディスパッチされ、非同期呼び出しを開始したスレッドがアラート可能になると、そのスレッドで完了コールバックが呼び出されます。 タスク キューのディスパッチ モードの詳細については、「非同期タスク キューの設計」を参照してください。
注意
非同期呼び出しを起動した後は、その非同期呼び出しの XAsyncBlock に設定されているどのパラメーターも変更しないでください。
完了コールバック
必要に応じて、callback にコールバック関数へのポインターを指定して、非同期呼び出しの完了コールバックを行うことができます。 完了コールバックは、非同期呼び出しの完了後に実行されるコールバック関数です。 コンテキスト固有のデータを完了コールバックに渡すには、完了コールバックの情報を表す context にポインターを指定します。
callback に完了コールバックを指定しない場合は、XAsyncGetStatus 関数を使用して非同期呼び出しが完了しているかどうかを定期的に確認できます。非同期呼び出しが完了していれば、必要に応じて XAsyncGetResult および XAsyncGetResultSize を使用して、完了したタスクから結果を取得できます。
完了コールバックの詳細については、「XAsyncCompletionRoutine」を参照してください。
XAsyncBlock の実装
XAsyncProvider を使用して、XAsyncBlock を使用した独自の非同期機能を実装できます。実装した非同期機能は XTaskQueue 関数を使用して呼び出すことができます。 非同期呼び出しは、XAsyncRun を呼び出して起動することもできます。このヘルパー関数は、内部で XAsyncProvider を使用して、同じくヘルパー関数である XAsyncWork で指定されたコールバック関数を実行し、追跡します。
XAsyncProvider と XAsyncBlock を使用して独自の非同期機能を実装する方法の詳細については、「非同期プログラミング モデル」を参照してください。
非同期呼び出しの有効期間中は、XAsyncBlock がメモリ内に維持されたままでなければなりません。 ただし、XAsyncBlock が動的に割り当てられる場合は、非同期呼び出しの完了コールバック内で削除しても問題はありません。
要件
ヘッダー: XAsync.h
サポートされているプラットフォーム: Windows、Xbox One ファミリー本体、Xbox Series 本体