XAsyncBlock
XAsyncBlock を詳しく見てみましょう。これは次のように定義される構造体です:- queue - 作業を実行する場所に関する情報を表すハンドルである XTaskQueueHandle。このパラメーターが設定されていない場合は、デフォルト キューが使用されます。
- context - コールバック関数にデータを渡すことができます。
- callback - 非同期処理が完了した後に呼び出されるオプションのコールバック関数。コールバックを指定しない場合は、XAsyncGetStatus で XAsyncBlock の完了を待機してから、結果を取得できます。
重要: XAsyncBlock は、非同期タスクが完了するまでメモリ内に残る必要があります。動的に割り当てられている場合は、XAsyncBlock の完了コールバック内で削除できます。
非同期タスクの待機
非同期タスクが完了したことを確認する方法は 2 つあります:- XAsyncBlock の完了コールバックが呼び出される。
- XAsyncGetStatus を true で呼び出して、完了するまで待機する。
非同期タスクの結果の取得
結果を取得するには、ほとんどの非同期 API 関数に、非同期呼び出しの結果を受け取るための対応する Result 関数があります。 サンプル コードでは、PFProfilesGetProfileAsync には対応する PFProfilesGetProfileGetResult 関数があります。この関数を使用して、関数の結果を取得し、それに応じて動作させることができます。 結果の取得に関する詳細については、各非同期 API 関数のドキュメントを参照してください。XTaskQueueHandle
XTaskQueueHandle を使用すると、どのスレッドが非同期タスクを実行し、どのスレッドが XAsyncBlock の完了コールバックを呼び出すかを決定できます。 ディスパッチ モードを設定することで、これらの操作を実行するスレッドを制御できます。利用可能なディスパッチ モードは 3 つあります:- Manual - 手動キューは自動的にはディスパッチされません。任意のスレッドでディスパッチするかは開発者次第です。これを使用して、非同期呼び出しの作業側またはコールバック側のいずれかを特定のスレッドに割り当てることができます。
- Thread Pool - スレッド プールを使用してディスパッチします。スレッド プールは、スレッド プール スレッドが利用可能になると順にキューから呼び出しを取り出し、並列に呼び出しを実行します。Thread Pool は最も使いやすいですが、使用されるスレッドの制御は最も少なくなります。
- Serialized Thread Pool - スレッド プールを使用してディスパッチします。スレッド プールは、単一のスレッド プール スレッドが利用可能になると順にキューから呼び出しを取り出し、直列に呼び出しを実行します。
- Immediate - キューに入れられた作業を、送信元のスレッドから即座にディスパッチします。
XTaskQueueHandle の手動ディスパッチ
XTaskQueueHandle の作業キューまたは完了キューに手動キュー ディスパッチ モードを使用した場合は、手動でディスパッチする必要があります。作業キューと完了キューの両方が手動ディスパッチに設定された XTaskQueueHandle が次のように作成されたとします:- queue - 作業をディスパッチするキュー。
- port - XTaskQueuePort 列挙型のインスタンス。
- timeoutInMs - タイムアウトのミリ秒を表す uint32_t。
XTaskQueueDispatch の呼び出しタイミング
キューが新しい項目を受け取ったタイミングを確認するには、XTaskQueueRegisterMonitor を呼び出してイベント ハンドラーを設定し、作業または完了のいずれかがディスパッチ準備できていることをコードに通知できます。- queue - コールバックを送信する非同期キュー。
- callbackContext - 送信コールバックに渡すべきデータへのポインター。
- callback - 新しいコールバックがキューに送信されたときに呼び出される関数。
- token - コールバックを削除するために XTaskQueueUnregisterMonitor の後の呼び出しで使用されるトークン。
