Skip to main content

非同期操作と通知

低速または計算コストの高い操作に対して、PlayFab Lobby and Matchmaking SDK は非同期 API を公開します。非同期 API により、コストの高い操作や低速な操作をメイン スレッドから開始し、任意のスレッドでそれらの操作の完了をポーリングできます。同じポーリング メカニズムは、SDK の更新に関する非同期通知をタイトル コードに配信するためにも使用されます。このページでは、PlayFab Lobby and Matchmaking SDK の非同期 API パターンと、それらに対してプログラミングする際のベスト プラクティスの概要を説明します。

基本的な API パターン

PlayFab Lobby and Matchmaking SDK には、把握しておくべき非同期 API パターンが 2 種類あります:
  1. 非同期操作
  2. 非同期通知

非同期操作

SDK の非同期 API は簡単に使用できます。非同期操作を開始して完了する一般的なパターンは次のとおりです:
  1. 選択した非同期 API に対して通常のメソッド呼び出しを行います。よく使用される非同期操作には次のようなものがあります:
  2. API の HRESULT 戻り値を SUCCEEDED() または FAILED() マクロで確認します。この同期的に返される値は、操作が正常に開始されたかどうかを示します。
非同期 API 呼び出しからの同期戻り値は、操作が正常に 完了 したかどうかは示 しません。同期エラーと非同期エラーの詳細については、SDK の エラー処理ドキュメント を参照してください。
  1. PFMultiplayerStartProcessingLobbyStateChanges() または PFMultiplayerStartProcessingMatchmakingStateChanges によって提供される、関連する操作の「completion state change (完了状態変更)」を探すことで、非同期操作の完了をポーリングします。PFMultiplayerCreateAndJoinLobby() の関連する「completion state change」の例は PFLobbyCreateAndJoinLobbyCompletedStateChange です。「state changes」とは何か、およびそれらがどのように機能するかの詳細については、状態変更 セクションを参照してください。
  2. completion state change の result 値を確認して、操作が成功したか失敗したかを判断します。これらのエラー値の詳細については、SDK の エラー処理ドキュメント を参照してください。

非同期通知

一部の機能は、Lobby and Matchmaking SDK への変更を非同期通知として生成します。 一般的な通知には次のものがあります:
  1. ロビー更新通知
  2. ロビー切断通知
  3. マッチメイキング チケット ステータス変更通知
これらの非同期通知は、PFMultiplayerStartProcessingLobbyStateChanges() および PFMultiplayerStartProcessingMatchmakingStateChanges を通じて「state changes」として SDK から提供されます。 「state changes」とは何か、およびそれらがどのように機能するかの詳細については、状態変更 セクションを参照してください。

状態変更

Lobby and Matchmaking SDK の非同期 API モデルは、PFLobbyStateChange および PFMatchmakingStateChange 構造体を中心に構築されています。PFLobbyStateChanges はロビー サブシステムの変更を通知し、PFMatchmakingStateChanges はマッチメイキング サブシステムの変更を通知します。 これらの「state changes」は、SDK からのイベントの非同期通知です。これらの通知は内部でキューに入れられ、PFMultiplayerStartProcessingLobbyStateChanges() および PFMultiplayerStartProcessingMatchmakingStateChanges を呼び出すことで処理します。これらの関数は、(それぞれの API サブシステムの) すべてのキューに入れられた state changes をリストとして返します。反復処理して個別に処理できます。各 state change には、通知されている特定の state change を判別するために検査できる対応する stateChangeType フィールドがあります。どの state change が提供されているかがわかったら、一般的な PFLobbyStateChange または PFMatchmakingStateChange 構造体を、より具体的な state change 構造体の型にキャストして、そのイベントの特定のデータを検査できます。 通常、state change の処理は、各 state change をハンドラーに委任する単純な switch ステートメントとして実装されます。 PFMultiplayerStartProcessingLobbyStateChanges または PFMultiplayerStartProcessingMatchmakingStateChanges からの state changes のリストが処理されたら、それぞれ PFMultiplayerFinishProcessingMatchmakingStateChanges() または PFMultiplayerFinishProcessingMatchmakingStateChanges() に返す必要があります。

非同期操作コンテキスト

各非同期 API には void* asyncContext パラメーターが含まれます。この値はパススルー パラメーターで、PFMultiplayerStartProcessingLobbyStateChanges() または PFMultiplayerStartProcessingMatchmakingStateChanges() によって提供されると、この API 呼び出しの関連する completion state change に設定されます。 この値は、非同期 API 呼び出しに任意のポインター サイズのコンテキストを付加するメカニズムを提供します。これらのコンテキストは、次のような多くのシナリオで使用できます:
  1. タイトル固有のデータを SDK 呼び出しに関連付ける
  2. 共有識別子で複数の非同期操作を結び付ける
これらの非同期コンテキストは SDK の使用に必須ではありませんが、一部のタイトル ロジックを書きやすくするのに役立つ場合があります。

操作のキューイング

非同期 API を扱う際、より大規模な非同期フローの一部として複数の非同期操作を順次実行する必要があることがよくあります。 Lobby and Matchmaking SDK での 1 つの例は、ロビーを作成し、そのロビーへの招待をフレンドに送信することです。直列化すると、このフローは次のようになります:
  1. PFMultiplayerCreateAndJoinLobby() を呼び出して PlayFab ロビーを作成して参加します。
  2. PFLobbyCreateAndJoinLobbyCompletedStateChange がロビーの作成と参加が正常に行われたことを反映するまで待ちます。
  3. 招待するフレンドごとに PFLobbySendInvite() を呼び出します。
  4. PFLobbySendInviteCompletedStateChange が招待が正常に送信されたことを反映するまで待ちます。
より複雑なフローやタイトル ロジックの場合、この直列化されたパターンが適切かもしれません。ただし、より単純なフローの場合、SDK はタイトル コードを簡略化することを意図した代替手段を提供します: SDK の多くの非同期 API は、前の操作が完全に完了する前の依存操作のキューイングをサポートしています。前の例から、ロビーが正常に作成されたことを確認する前でも、そのロビーへの招待を送信できます。 事実上、キューイングにより、非同期操作のコレクションをまとめてバンドルし、一度にすべてを開始し、エラー処理を単一の失敗地点に集約できます。

非同期作業の制御

ライブラリとタイトルのコア CPU ワークロード間の CPU 競合を避けるため、タイトルが非同期作業を実行する場所を制御する必要がある場合があります。 Lobby and Matchmaking SDK では、スレッド アフィニティの制御 によって非同期作業の実行方法を制御できます。

スレッド アフィニティの制御

既定では、非同期の SDK 作業は慎重に制御されたバックグラウンド スレッドで実行されます。一部のタイトルでは、CPU 競合を避けるために、これらのバックグラウンド スレッドが どこで スケジュールされるかを大まかに制御する必要があります。 これらのタイトルのために、Lobby and Matchmaking SDK は PFMultiplayerSetThreadAffinityMask() を提供しています。サポートされているプラットフォームでは、SDK のバックグラウンド スレッドで使用される CPU コアを制限できます。これにより、特定のコアを競合なしに独自の CPU ワークロード用に確保することが保証できます。
最終更新日 2026年8月13日