非同期プログラミングモデル

Microsoft Game Development Kit (GDK) は、XBOX One ERA プログラミングモデルの一部として実装された非同期パターンに関してゲーム開発者から寄せられたフィードバックに対応する、新しい非同期 API のパターンを実装しています。この新しいパターンが、一般的なゲームアーキテクチャに統合しやすく、ゲーム開発者が求めている高度な制御を提供することを目標としています。このトピックでは、その設計パターンについて説明し、非同期パターンを実装するために使用できるライブラリの提案を紹介します。

概念モデル

Microsoft Game Development Kit (GDK) における非同期プログラミングは、大きく分けて 2 つの主要コンポーネント (タスクとタスクキュー) に分かれています。ライブラリにはさらに多くの機能がありますが、概念モデル全体はこれら 2 つの主要コンポーネントを利用しています。タスクとは、開始し、状態を確認し、必要に応じてキャンセルし、完了し、完了情報を返すことができる一連の非同期作業です。Microsoft Game Development Kit (GDK) モデルにおけるタスクは、ワークコールバックと完了コールバックの 2 つの本体で構成されます。これにより、完全並列処理や、並列処理と単一スレッド完了の組み合わせなど、より高度な制御が可能になります。タスクキューは、後で実行するためにワークコールバックと完了コールバックの両方をエンキューするコンテナーです。タスクキューには、ワークコールバックと完了コールバックを別々に扱う 2 つの内部キュー (ポートと呼びます) があります。これらはワークポートと完了ポートと呼ばれます。 図 1. タスクとタスクキューの図 タスクキューの各ポートは、作成時に個別に構成することで、異なるコールバック実行動作を作成できます。たとえば、ワークポートを非同期に構成し、完了ポートをメインスレッドでシリアルに実行するように構成することができます。マニュアル設定により、実行動作を完全に制御することもできます。ポート構成モードについては以下で説明しています。非同期タスクが開始されると、コールバックはただちにタスクキューにエンキューされるわけではありません。非同期プロバイダーが状態変化を処理し、作業がエンキューされてディスパッチされてから完了コールバックがエンキューされ、ディスパッチされるようにします。タスクキュー自身は、直接的にスレッド化を扱いません。代わりに、そのポートをディスパッチする外部呼び出しに依存します。外部呼び出しがスレッド化と並列実行の動作を決定します。タスクキュー自体は完全にスレッドセーフです。 図 2. 複数のスレッドにディスパッチされているポート 基本的にはこれだけです。タスクのコールバックはタスクキューのワークポートと完了ポートにエンキューされ、そのタスクキューがそれらのコールバックを何らかの方法でディスパッチします。API には、タスクキューの管理、コールバックの状態確認、作業データの追跡、カスタムタスク処理の作成など、豊富な機能が含まれています。 Microsoft Game Development Kit (GDK) の非同期 API 呼び出しは常にワークコールバックを内部的に実装し、完了コールバックは常にオプションです。Microsoft Game Development Kit (GDK) の非同期呼び出し以外で使用する場合は、ワークコールバックを指定する必要があります。

要件

ゲーム開発者は、API 呼び出しに関して次の要件を挙げています。

非同期呼び出しよりも同期呼び出しを優先する
ポーリング付きの非同期を提供する
コールバック付きの非同期を提供する
非同期処理を実行するスレッドを制御できるようにする
完了コールバックが実行されるスレッドを制御できるようにする

API の種類

Microsoft Game Development Kit (GDK) は、API 設計において非常に率直であることを目指しています。ゲーム開発者は、ハードウェアの使用を最大化するようにコードを細かく調整する専門家です。可能な限り制御を彼らに委ねます。API の実装は次のような種類に分類されます。

タイムセンシティブセーフ: タイムセンシティブセーフな API とは、タイムセンシティブなスレッドで呼び出せる API のことです。通常、この API は些細なものや非常に高速なものを意味しますが、鍵となる概念は、API のパフォーマンス特性が 一貫している ことです。これらは常に同期であり、非同期版が必要になることはありません。これらの API は「time-sensitive-safe」として文書化する必要があります。
タイムセンシティブセーフでない: これらの API はレンダースレッドから呼び出すのは安全ではありません。パフォーマンス特性は大きく変動する可能性があります。ほとんどの API はこのカテゴリに該当します。
非同期: これらの API は、Web サービス呼び出しなど、本質的に非同期です。このトピックで説明する非同期パターンを使用します。非同期 API は、XBOX One ERA プログラミングモデルほど Microsoft Game Development Kit (GDK) には多くありません。非同期 API は一般に長時間実行され、キャンセル可能です。特定の使用ケースを除き、非同期 API には not-time-critical-safe な同期版があります。非同期 API を呼び出す動作は常に time-critical-safe であるべきです。
通知: 通知は本質的に周期的であり、定義された終わりがありません。これらは非同期 API に関連していますが、周期的性質のため、開発者に対しては異なる見た目と振る舞いをすべきです。通知の登録は常に time-critical-safe であるべきです。

非同期 API パターン

Microsoft Game Development Kit (GDK) では、Microsoft Game Development Kit (GDK) コンポーネントが一貫した非同期サポートを提供するために使える、汎用的な非同期 API パターンを導入しています。その中核には OVERLAPPED に類似した構造体である XAsyncBlock があります。

typedef void CALLBACK XAsyncCompletionRoutine(struct XAsyncBlock* asyncBlock);

struct XAsyncBlock
{
    XTaskQueueHandle queue;
    void* context;
    XAsyncCompletionRoutine* callback;
    unsigned char internal[sizeof(void*) * 4];
};

XAsyncBlock は呼び出し元が提供する構造体です。呼び出し元は次の表に示すオプションフィールドをこの構造体に入力します。

フィールド	説明
queue	どのスレッドが非同期呼び出しを実行するかを制御できるタスクキューハンドル。このパラメーターが null の場合、プロセスタスクキューが使用されます。プロセスタスクキューが null に設定されている場合、呼び出しは E_NO_TASK_QUEUE で失敗します。
context	コールバック関数に渡されるオプションのコンテキストポインター。
callback	操作が完了したときに呼び出されるオプションのコールバック関数。

Internal フィールドはシステムが使用するため、変更してはなりません。この構造体のユーザーが設定可能なフィールドは、非同期操作中に変更してはいけません。XAsyncBlock は、非同期操作のライフタイムの間、メモリ上に残っている必要があります。XAsyncBlock が動的に割り当てられている場合、それを削除できる最も早い時点は完了コールバックです。 XAsyncBlock に加え、次のようにいくつかのヘルパー API が用意されています。

STDAPI XAsyncGetStatus(XAsyncBlock* asyncBlock, bool wait);

STDAPI XAsyncGetResultSize(XAsyncBlock* asyncBlock, size_t* bufferSize);

STDAPI_(void) XAsyncCancel(XAsyncBlock* asyncBlock);

typedef HRESULT CALLBACK XAsyncWork(XAsyncBlock* asyncBlock);

STDAPI XAsyncRun(XAsyncBlock* asyncBlock, XAsyncWork* work);

XAsyncGetStatus は非同期呼び出しの状態を返します。呼び出しが開始すると、この状態は E_PENDING になります。完了すると S_OK または特定のエラーに変わります。呼び出しがキャンセルされた場合は E_ABORT を返します。 XAsyncGetResultSize は、呼び出しの結果を取得するために必要なバッファーのサイズを返します。実際に結果を取得する API は非同期呼び出しごとにカスタマイズされています。 XAsyncCancel は呼び出しをキャンセルするために使用できます。キャンセルの動作はキャンセルされる操作次第で、同期的、非同期的、またはまったくキャンセルされない場合があります。操作がキャンセルされると、XAsyncGetResult、XAsyncGetResultSize、または XAsyncGetStatus は E_ABORT を返します。キャンセルされた呼び出しは、XAsyncBlock の XAsyncCompletionRoutine パラメーターにシグナルを送り、そのコールバックを呼び出します。 XAsyncRun は、任意のコードを非同期に実行できるヘルパーメソッドです。

非同期 API の使用方法

まず、次のコード例の同期 API を見てみましょう。

HRESULT XGameSaveGetRemainingQuota(XGameSaveProviderHandle provider,
int64_t* remainingQuota);

この API は Web サービスを呼び出して、まだ残っているセーブゲームストレージの量を判別します。非同期サポートを追加するために、次のように新しい API のペアを宣言します。

HRESULT XGameSaveGetRemainingQuotaAsync(XGameSaveProviderHandle
provider, XAsyncBlock* async);

HRESULT XGameSaveGetRemainingQuotaResult(XAsyncBlock* async,
int64_t* remainingQuota);

XGameSaveGetRemainingQuotaAsync は非同期呼び出しが開始された場合に S_OK を返します (この API は非同期専用なので E_PENDING を返す意味はありません)。XGameSaveGetRemainingQuotaResult は、呼び出しが完了するまで E_PENDING を返します。これを実際に使用する例を次に示します。

// providerHandle is a previously obtained XGameSaveProviderHandle.

XAsyncBlock* b = new XAsyncBlock;
ZeroMemory(b, sizeof(XAsyncBlock));
b->context = this;
b->queue = queue;
b->callback = [](XAsyncBlock* async)
{
    int64_t remainingQuota;
    if(SUCCEEDED(XGameSaveGetRemainingQuotaResult(async, &remainingQuota)))
    {
        printf("Remaining quota: %irn", remainingQuota);
    }
    delete async;
};
XGameSaveGetRemainingQuotaAsync(providerHandle, b);

XAsyncBlocks はすべて、非同期呼び出しがどこでどのように実行されるかを制御するタスクキュー (後述) を必要とします。指定されなかった場合は、プロセス全体のタスクキューが使用されます。 XAsyncBlock は非同期呼び出しの間、メモリ上に残る必要があることに注意してください。この例では、動的に割り当てられ、完了コールバックで削除されます。また、グローバル変数やメンバー変数として保存することもできます。同じ XAsyncBlock を同時に複数の非同期呼び出しに使用すると、動作は未定義になります。 XGameSaveGetRemainingQuotaResult は非同期呼び出しのサイクルを完了させます。非同期ブロック内の内部データを解放するので、ブロックを新しい呼び出しに使用できるようになります。それ以降の XGameSaveGetRemainingQuotaResult の呼び出しは失敗します。XGameSaveGetRemainingQuotaAsync と XGameSaveGetRemainingQuotaResult は非同期ブロック内でペアになっています。ある非同期呼び出しに対して別の Result API を混在させるとエラーが発生します。非同期呼び出しにデータペイロードがなく、HRESULT ステータスだけが重要な場合は、次のように非同期ブロックのみを受け取る Result メソッドを定義します。

HRESULT QueryUpdateStatusAsyncResult(_Inout_ XAsyncBlock* block);

作業ディスパッチの制御

先の呼び出しで、どのスレッドが非同期作業を行ったのでしょうか？どのスレッドが完了コールバックを呼び出したのでしょうか？それは XAsyncBlock に割り当てられたタスクキューによって決まります。タスクキューには 2 つの「ポート」、ワークポート と 完了ポート があります。各ポートには、そのポートにキューされたコールバックがどのように処理されるかを決定するディスパッチモードがあります。次のようにいくつかのディスパッチモードがあります。

スレッドプール: スレッドプールキューにキューされたコールバックは、システムスレッドプールで実行されます。スレッドプールは、呼び出しを並列に呼び出し、スレッドプールスレッドが利用可能になるたびにキューから順番に呼び出しを取り出して実行します。
シリアル化スレッドプール: コールバックはスレッドプールにキューされ実行されますが、一度に 1 つずつ実行されます。
手動: 手動キューにキューされたコールバックは、自動的にはディスパッチされません。開発者が任意のスレッドでディスパッチする必要があります。
即時: 即時ディスパッチモードはキューを行いません。コールバックを送信したスレッドで直ちに呼び出しを実行します。

既定のプロセスタスクキューが構成されているため、ワークポートと完了ポートの両方がシステムスレッドプール経由でディスパッチされます。このプロセスタスクキューは、XAsyncBlock にキューパラメーターが渡されない場合に使用されます。ゲームはプロセスタスクキューを無効にして、XAsyncBlock にキューを渡すように必須にすることもできます。私たちは、非同期処理と完了コールバックがいつどこで実行されるかを完全に制御するために、多くの開発者が手動ディスパッチモードを選択することを想定しています。タスクキューの詳細については、非同期タスクキューの設計を参照してください。

通知

通知には終わりがなく、何度も呼び出される可能性があります。通知は、非同期呼び出しの要件のサブセットをサポートする必要があります。

ポーリング付きの非同期
コールバック付きの非同期
コールバックが行われるスレッドの制御

通知はタスクキューを使用して、開発者がコールバックスレッドを制御できるようにしますが、それ以外は非同期ブロックを使用しません。Register および Unregister メソッドを備えた標準的なイベントに近い見た目と動作をするように設計されています。

呼び出し固有のパラメーター、タスクキュー、オプションの void コンテキスト、および強く型付けされたコールバックポインターを受け取る Register メソッド。最後のパラメーターはトークンを返す out パラメーターです。
呼び出し固有のコンテキストとトークンを受け取る Unregister メソッド。
ポーリングは、通知コールバックとは関係のない別のメソッドを追加することでサポートされます。

Windows メッセージを取得する次のような例を見てみましょう。

struct XTaskQueueRegistrationToken;

typedef void MessageAvailableCallback(void* context, const MSG* msg);

HRESULT RegisterMessageAvailable(
    XTaskQueueHandle queue,
    void* context,
    MessageAvailableCallback* callback,
    XTaskQueueRegistrationToken * token);

bool UnregisterMessageAvailable(XTaskQueueRegistrationToken token, bool
wait);

// Usage.
XTaskQueueRegistrationToken token;
RegisterMessageAvailable(queue, nullptr, [](void*, const MSG* msg)
{
    printf("Message: %drn", msg->message);
}, &token);

この例では、UnregisterMessageAvailable は最後の “wait” パラメーターを取り、bool を返すことに注意してください。これにより、呼び出しが実行中である間に登録解除をどのように処理するかを呼び出し元が決定できます。

非同期ライブラリ

非同期パターンをサポートする一貫した API の作成を容易にするため、API の「非同期の配管処理」を実装するために使用できるライブラリを提供しています。ライブラリの API は次のようになります。

enum class XAsyncOp : uint32_t
{
    Begin,
    DoWork,
    GetResult,
    Cancel,
    Cleanup
};

struct XAsyncProviderData
{
    XAsyncBlock* async;  
    size_t bufferSize;  
    void* buffer;  
    void* context;
};

typedef HRESULT CALLBACK XAsyncProvider(
_In_ XAsyncOp op,
_Inout_ XAsyncProviderData* data);

STDAPI XAsyncBegin (
_Inout_ XAsyncBlock* asyncBlock,
_In_opt_ void* context,
_In_opt_ void* identity,
_In_opt_ const char* identityName,
_In_ XAsyncProvider* provider);

STDAPI XAsyncSchedule(
_Inout_ XAsyncBlock* asyncBlock,
_In_ uint32_t delayInMs);

STDAPI_(void) XAsyncComplete(
_Inout_ XAsyncBlock* asyncBlock,
_In_ HRESULT result,
_In_ size_t requiredBufferSize);

STDAPI XAsyncGetResult(
_Inout_ XAsyncBlock* asyncBlock,
_In_opt_ void* identity,
_In_ size_t bufferSize,
_Out_writes_bytes_opt_(bufferSize) void* buffer,
_Out_opt_ size_t* bufferUsed);

この API は、単一のコールバックと、API が呼ばれている理由を示す操作値を組み合わせて使用します。また、呼び出しの進行に伴って埋められる単一のデータ構造もあります。この API を使用するには、以下の手順を実行します。

呼び出し元から渡された非同期ブロックを指定して XAsyncBegin を呼び出し、実装を提供するコールバックを提供します。
呼び出しの非同期処理を実行します。ワーカースレッドで処理を実行する必要がある場合は XAsyncSchedule を呼び出します。OS の非同期プリミティブを使用して、それらのプリミティブを time-critical-safe にとどまる程度に高速にセットアップできる場合は、そちらが推奨されます。
ワーカースレッドのコールバックから他の非同期処理を呼び出す必要がある場合は、ワーカーから E_PENDING を返すことができます。ワーカー内から XAsyncSchedule を呼び出して、追加の作業を再スケジュールすることもできます。
すべての処理が完了したら、XAsyncComplete を呼び出します。
結果を返すために、XAsyncGetResult のまわりに強く型付けされたラッパーを用意します。
非同期呼び出しにデータペイロードがない場合は、XAsyncGetStatus のまわりに強く型付けされたラッパーを用意し、XAsyncComplete に必要なバッファーサイズとしてゼロを渡す必要があります。

非同期プロバイダーコールバックは、次の操作で呼び出されます。

Begin 非同期プロバイダーは、XAsyncBegin の中でこのオペコードで呼び出されます。プロバイダーがこのオペコードを実装する場合は、XAsyncSchedule を呼び出すか外部の手段を通じて、非同期タスクを開始する必要があります。このコールバックは XAsyncBegin の呼び出しチェーンで同期的に呼び出されるため、決してブロックしないようにしてください。
DoWork タスクキューを使用して非同期処理をスケジュールするために XAsyncSchedule が呼び出された場合に呼ばれます。プロバイダー関数は必要な処理をすべて実行します。完了時には、結果コードとデータペイロードサイズを指定して XAsyncComplete を呼び出します (呼び出しにデータペイロードがない場合はゼロも可)。さらに非同期処理を行う必要がある場合は、プロバイダーはその処理をスケジュールし、E_PENDING を返す必要があります。
GetResult 呼び出しの結果を取得するために呼び出されます。データサイズは呼び出し完了時に XAsyncComplete に渡されているため、ここでの引数チェックは不要です。すべてのバッファーとバッファーサイズは、ライブラリによって既に検証されています。
Cancel ユーザーが非同期呼び出しをキャンセルすると呼び出されます。呼び出しをキャンセルできる場合は、それをキャンセルし、結果コードとして E_ABORT を指定して XAsyncComplete を呼び出します。
Cleanup 呼び出しが完全に終了し、プロバイダーが任意の動的メモリを削除できる時に呼び出されます。

非同期プロバイダーは、必要な操作のみを実装するだけで済みます。たとえば、クリーンアップを持たないキャンセル不能な非同期 IO は GetResult のみを実装すればよいのです。以下は、階乗を非同期に実装する FactorialAsync メソッドの例です。

UINT64 Factorial(UINT64 value)
{
    UINT64 result = 1;

    while (value != 0)
    {       
        result *= value;
        value--;
    }

    return result;
}

HRESULT FactorialAsync(UINT64 value, XAsyncBlock* async)
{
    struct CallData
    {
        UINT64 value;
        UINT64 result;
    };

    CallData* data = new CallData();
    data->value = value;
    data->result = 1;

    HRESULT hr = XAsyncBegin (async, data, FactorialAsync, __FUNCTION__, []
        (XAsyncOp op, XAsyncProviderData* data)
    {
        CallData* d = (CallData*)data->context;

        switch (op)
        {
        case XAsyncOp::Begin:
            return XAsyncSchedule(data->async, 0);

        case XAsyncOp::Cleanup:
            delete d;
            break;

        case XAsyncOp::GetResult:
            CopyMemory(data->buffer, &d->result, sizeof(UINT64));
            break;
 
        case XAsyncOp::DoWork:
            data->result = Factorial(data.Value);
            XAsyncComplete(data->async, S_OK, sizeof(UINT64));
            break;
        }

        return S_OK;
    });

    return hr;
}

HRESULT FactorialAsyncResult(XAsyncBlock* async, UINT64* result)
{
    return XAsyncGetResult(async, FactorialAsync, sizeof(UINT64), result);
}

リファレンス API ドキュメント

XAsync (API 目次)
- 関数
- 構造体
  - XAsyncBlock
XAsyncProvider (API 目次)
- 関数
XTaskQueue (API 目次)
- 関数
  - xtaskqueuecreate
  - xtaskqueuedispatch
xgamesave (API 目次)
- 関数
  - XGameSaveGetRemainingQuotaAsync
  - XGameSaveGetRemainingQuotaResult

GDK and Game Engines Integration

Steam porting guide

Game Principles

Core Features

Console Features

概念モデル

要件

API の種類

非同期 API パターン

非同期 API の使用方法

作業ディスパッチの制御

通知

非同期ライブラリ

リファレンス API ドキュメント

関連項目

​概念モデル

​要件

​API の種類

​非同期 API パターン

​非同期 API の使用方法

​作業ディスパッチの制御

​通知

​非同期ライブラリ

​リファレンス API ドキュメント

​関連項目

概念モデル

要件

API の種類

非同期 API パターン

非同期 API の使用方法

作業ディスパッチの制御

通知

非同期ライブラリ

リファレンス API ドキュメント

関連項目