Skip to main content
非同期 API とは、すぐに戻り、非同期タスクを開始し、そのタスクが完了した後に結果を返す API のことです。 従来、ゲームは完了コールバックを使用するときに、どのスレッドが非同期タスクを実行し、どのスレッドが結果を返すかをほとんど制御できませんでした。一部のゲームは、スレッド同期の必要性を回避するために、ヒープの一部が単一のスレッドからのみアクセスされるように設計されています。完了コールバックがゲームが制御するスレッドから呼び出されない場合、非同期タスクの結果で共有状態を更新するにはスレッド同期が必要になります。 PlayFab Services SDK は、PFAuthenticationLoginWithCustomIDAsyncPFDataGetFilesAsyncPFProfilesGetProfileAsync などの非同期 API 呼び出しを行う際に、開発者に直接的なスレッド制御を提供する非同期 C API を公開しています。 以下は、PFProfilesGetProfileAsync を呼び出す基本的な例です:
この呼び出しパターンを理解するには、XAsyncBlockXTaskQueueHandle の使い方を理解する必要があります。 XAsyncBlock は、非同期タスクと完了コールバックに関するすべての情報を保持します。 XTaskQueueHandle を使用すると、どのスレッドが非同期タスクを実行し、どのスレッドが XAsyncBlock の完了コールバックを呼び出すかを決定できます。

XAsyncBlock

XAsyncBlock を詳しく見てみましょう。これは以下のように定義された構造体です:
XAsyncBlock には以下が含まれます:
  • queue - 作業を実行する場所に関する情報を表すハンドルである XTaskQueueHandle。このパラメーターが設定されていない場合、デフォルトのキューが使用されます。
  • context - コールバック関数にデータを渡すことができます。
  • callback - 非同期処理が完了した後に呼び出されるオプションのコールバック関数。コールバックを指定しない場合、XAsyncGetStatusXAsyncBlock の完了を待ってから結果を取得できます。
作成する非同期呼び出しごとに、ヒープ上に新しい XAsyncBlock を作成する必要があります。XAsyncBlock は、XAsyncBlock の完了コールバックが呼び出されるまで存続する必要があり、その後は削除できます。
重要: XAsyncBlock は、非同期タスクが完了するまでメモリ内に保持されている必要があります。動的に割り当てられている場合、XAsyncBlock の完了コールバック内で削除できます。

非同期タスクの待機

非同期タスクが完了したかどうかは、2つの異なる方法で確認できます:
  • XAsyncBlock の完了コールバックが呼び出される。
  • XAsyncGetStatus を true で呼び出して完了するまで待機する。
XAsyncGetStatus では、XAsyncBlock の完了コールバックが実行された後に非同期タスクが完了と見なされますが、XAsyncBlock の完了コールバックはオプションです。 非同期タスクが完了すると、結果を取得できます。

非同期タスクの結果を取得する

結果を取得するために、ほとんどの非同期 API 関数には、非同期呼び出しの結果を受け取るための対応する Result 関数があります。 サンプルコードでは、PFProfilesGetProfileAsync に対応する PFProfilesGetProfileGetResult 関数があります。この関数を使用して関数の結果を取得し、それに応じて動作させることができます。 結果の取得に関する詳細については、各非同期 API 関数のドキュメントを参照してください。

XTaskQueueHandle

XTaskQueueHandle を使用すると、どのスレッドが非同期タスクを実行し、どのスレッドが XAsyncBlock の完了コールバックを呼び出すかを決定できます。 ディスパッチモードを設定することにより、これらの操作を実行するスレッドを制御できます。利用可能なディスパッチモードは3つあります:
  • Manual - 手動キューは自動的にディスパッチされません。任意のスレッドでディスパッチするかは開発者次第です。これを使用して、非同期呼び出しの作業側またはコールバック側を特定のスレッドに割り当てることができます。
  • Thread Pool - スレッドプールを使用してディスパッチします。スレッドプールは呼び出しを並列で実行し、スレッドプールのスレッドが利用可能になると、順次キューから実行する呼び出しを取り出します。Thread Pool は最も使いやすいですが、使用されるスレッドの制御は最小限になります。
  • Serialized Thread Pool - スレッドプールを使用してディスパッチします。スレッドプールは呼び出しを直列で実行し、単一のスレッドプールスレッドが利用可能になると、順次キューから実行する呼び出しを取り出します。
  • Immediate - キューに入れられた作業を、送信されたスレッドで即座にディスパッチします。
新しい XTaskQueueHandle を作成するには、XTaskQueueCreate を呼び出す必要があります。例:
この関数は2つの XTaskQueueDispatchMode パラメーターを取ります。XTaskQueueDispatchMode には、3つの可能な値があります:
workDispatchMode は、非同期作業を処理するスレッドのディスパッチモードを決定します。completionDispatchMode は、非同期操作の完了を処理するスレッドのディスパッチモードを決定します。 XTaskQueueHandle を作成したら、それを XAsyncBlock に追加するだけで、作業関数と完了関数のスレッドを制御できます。XTaskQueueHandle の使用を終えたとき (通常はゲームが終了するとき)、XTaskQueueCloseHandle で閉じることができます:
呼び出しサンプル:

XTaskQueueHandle の手動ディスパッチ

XTaskQueueHandle の作業キューまたは完了キューに手動キューディスパッチモードを使用した場合、手動でディスパッチする必要があります。作業キューと完了キューの両方を以下のように手動でディスパッチするように設定した XTaskQueueHandle を作成したとします:
XTaskQueueDispatchMode::Manual が割り当てられた作業をディスパッチするには、XTaskQueueDispatch 関数を呼び出します。
呼び出しサンプル:
  • queue - 作業をディスパッチするキュー。
  • port - XTaskQueuePort 列挙型のインスタンス。
  • timeoutInMs - ミリ秒単位のタイムアウトを表す uint32_t。
XTaskQueuePort 列挙型で定義される2つのコールバックタイプがあります:

XTaskQueueDispatch を呼び出すタイミング

キューが新しいアイテムを受信したことを確認するには、XTaskQueueRegisterMonitor を呼び出してイベントハンドラーを設定し、作業または完了をディスパッチする準備ができたことをコードに通知することができます。
XTaskQueueRegisterMonitor は以下のパラメーターを受け取ります:
  • queue - コールバックを送信する非同期キュー。
  • callbackContext - 送信コールバックに渡されるデータへのポインター。
  • callback - 新しいコールバックがキューに送信されたときに呼び出される関数。
  • token - コールバックを削除するために XTaskQueueUnregisterMonitor の後続の呼び出しで使用されるトークン。
例として、XTaskQueueRegisterMonitor の呼び出しは次のとおりです:
対応する XTaskQueueMonitorCallback コールバックは、次のように実装できます:
そしてバックグラウンドスレッドでは、この条件変数を待って XTaskQueueDispatch を呼び出すことができます。

リファレンス

API リファレンスドキュメント
最終更新日 2026年8月25日