次の方法で共有

XTaskQueueCreate

  • [アーティクル]

呼び出しのキューイングとディスパッチに使用できるタスク キューを作成します。

構文

HRESULT XTaskQueueCreate(  
         XTaskQueueDispatchMode workDispatchMode,  
         XTaskQueueDispatchMode completionDispatchMode,  
         XTaskQueueHandle* queue  
)

パラメーター

workDispatchMode _In_
型: XTaskQueueDispatchMode

キューの "処理" ポートのディスパッチ モードです。

completionDispatchMode _In_
型: XTaskQueueDispatchMode

キューの "完了" ポートのディスパッチ モードです。

queue _Out_
型: XTaskQueueHandle*

新しく作成されたキュー。

戻り値

型: HRESULT

HRESULT 成功またはエラー コード。

解説

注意

この関数は、時間依存のスレッドで呼び出すのに安全ではありません。 詳細については、「時間依存のスレッド」を参照してください。

タスク キューは参照カウントされるオブジェクトです。 XTaskQueueCloseHandle を呼び出して、参照を解放します。

タスク キューには処理ポートと完了ポートがあり、タスクはどちらのポートにもキューイングできます。 各ポートを、独自のディスパッチ モードで構成できます。

ほとんどのシナリオでは、XTaskQueueCreate API でタスク キューを作成します。 ただし、複数の非同期呼び出しをチェーンする場合は、XTaskQueueCreateComposite で複合キューを作成すると便利な場合があります。 タスク キューを使用する別の API を呼び出す必要がある API の実装を考えてみてください。 呼び出し元の完了スレッドを縛り付けないように、API の完了コールバックをリダイレクトすることが必要な場合があります。 この場合は、処理ポートと完了ポートが別のキューの処理ポートから構築されている複合タスク キューを作成することができます。

次の例では、システム スレッド プールで処理コールバックと完了コールバックの両方をディスパッチするタスク キューを作成します。

注意

SubmitCallback は、 XTaskQueueSubmitCallback 関数のコード例で定義されているヘルパー関数です。

void CreatingTaskQueue()
{
    XTaskQueueHandle queue;
    HRESULT hr = XTaskQueueCreate(XTaskQueueDispatchMode::ThreadPool, XTaskQueueDispatchMode::ThreadPool, &queue);
    if (FAILED(hr))
    {
        printf("Creating queue failed: 0x%x\r\n", hr);
        return;
    }

    SubmitCallbacks(queue);

    // Wait a while for the callbacks to run
    Sleep(1000);

    XTaskQueueTerminate(queue, true, nullptr, nullptr);
}

次の例では、手動でポンプされるタスク キューを作成します。 処理ポートと完了ポート両方の呼び出しをディスパッチする 2 つの STL スレッドを作成します。

注意

SubmitCallback は、 XTaskQueueSubmitCallback 関数のコード例で定義されているヘルパー関数です。

void CreatingTaskQueueWithManualThreads()
{
    // Create a manual task queue
    XTaskQueueHandle queue;
    HRESULT hr = XTaskQueueCreate(XTaskQueueDispatchMode::Manual, XTaskQueueDispatchMode::Manual, &queue);
    if (FAILED(hr))
    {
        printf("Creating queue failed: 0x%x\r\n", hr);
        return;
    }

    // We create threads to pump the queue: one for the work port
    // and one for the completion port.
    std::thread workThread([queue]
    {
        while (XTaskQueueDispatch(queue, XTaskQueuePort::Work, INFINITE));
    });

    std::thread completionThread([queue]
    {
        while (XTaskQueueDispatch(queue, XTaskQueuePort::Completion, INFINITE));
    });

    SubmitCallbacks(queue);

    // Wait a while for the callbacks to run
    Sleep(1000);

    // Terminating the queue will cause a waiting DispatchTaskQueue to return
    // false.  
    XTaskQueueTerminate(queue, true, nullptr, nullptr);

    workThread.join();
    completionThread.join();
}

要件

ヘッダー: XTaskQueue.h

ライブラリ: xgameruntime.lib

サポートされているプラットフォーム: Windows、Xbox One ファミリー本体、Xbox Series 本体

関連項目

XTaskQueue のメンバー
非同期プログラミング モデル
非同期タスク キューの設計