> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# XTaskQueueCreate

> XTaskQueueCreate

# XTaskQueueCreate

呼び出しをキューに登録してディスパッチするために使用できるタスク キューを作成します。

## 構文

```cpp theme={null}
HRESULT XTaskQueueCreate(  
         XTaskQueueDispatchMode workDispatchMode,  
         XTaskQueueDispatchMode completionDispatchMode,  
         XTaskQueueHandle* queue  
)  
```

### パラメーター

*workDispatchMode*   \_In\_\
Type: [XTaskQueueDispatchMode](https://docs.xbox.com/ja-jp/reference/system/xtaskqueue/enums/xtaskqueuedispatchmode.md)

キューの「ワーク」ポートのディスパッチ モードです。

*completionDispatchMode*   \_In\_\
Type: [XTaskQueueDispatchMode](https://docs.xbox.com/ja-jp/reference/system/xtaskqueue/enums/xtaskqueuedispatchmode.md)

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

*queue*   \_Out\_\
Type: XTaskQueueHandle\*

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

### 戻り値

Type: HRESULT

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

## 解説

> [!NOTE]
>
> この関数は、時間依存スレッドで呼び出しても安全ではありません。詳細については、[Time-sensitive threads](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads) を参照してください。

タスク キューは参照カウントされたオブジェクトです。[XTaskQueueCloseHandle](https://docs.xbox.com/ja-jp/reference/system/xtaskqueue/functions/xtaskqueueclosehandle.md) を呼び出して参照を解放します。

タスク キューにはワーク ポートと完了ポートがあり、いずれのポートに対してもタスクをキューに登録できます。各ポートには独自のディスパッチ モードを構成できます。

ほとんどのシナリオでは、**XTaskQueueCreate** API を使用してタスク キューを作成します。ただし、複数の非同期呼び出しを連鎖させる場合には、[XTaskQueueCreateComposite](https://docs.xbox.com/ja-jp/reference/system/xtaskqueue/functions/xtaskqueuecreatecomposite.md) を使用してコンポジット キューを作成すると便利な場合があります。実装内でタスク キューを使用する別の API を呼び出す必要がある API を考えてみてください。API の完了コールバックをリダイレクトして、呼び出し元の完了スレッドを占有しないようにしたい場合があります。この場合、ワーク ポートと完了ポートを別のキューのワーク ポートから構築するコンポジット タスク キューを作成できます。

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

> [!NOTE]
>
> **SubmitCallback** は、[XTaskQueueSubmitCallback](https://docs.xbox.com/ja-jp/reference/system/xtaskqueue/functions/xtaskqueuesubmitcallback.md) 関数のコード例で定義されているヘルパー関数です。

```cpp theme={null}
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 スレッドを作成します。

> [!NOTE]
>
> **SubmitCallback** は、[XTaskQueueSubmitCallback](https://docs.xbox.com/ja-jp/reference/system/xtaskqueue/functions/xtaskqueuesubmitcallback.md) 関数のコード例で定義されているヘルパー関数です。

```cpp theme={null}
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 本体

## 概念ドキュメント

* [タスク キューの作成](https://docs.xbox.com/ja-jp/build/core-features/common/async/async-libraries/async-library-xtaskqueue-example-create-task-queue.md)
* [XTaskQueue ライブラリの概要](https://docs.xbox.com/ja-jp/build/core-features/common/async/async-libraries/async-library-xtaskqueue.md)
* [非同期プログラミング モデル](https://docs.xbox.com/ja-jp/build/core-features/common/async/async-programming-model.md)
* [非同期プログラミングの設計目標と改善点](https://docs.xbox.com/ja-jp/build/core-features/common/async/async-whitepaper.md)
* [Time-sensitive threads](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)

## 関連項目

[XTaskQueue members](https://docs.xbox.com/ja-jp/reference/system/xtaskqueue/xtaskqueue_members.md)\
[非同期プログラミング モデル](https://docs.xbox.com/ja-jp/build/core-features/common/async/async-programming-model.md)\
[非同期タスク キューの設計](https://docs.xbox.com/ja-jp/build/core-features/common/async/async-task-queue-design.md)


## Related topics

- [XTaskQueueCreateComposite](https://docs.xbox.com/ja-jp/reference/system/xtaskqueue/functions/xtaskqueuecreatecomposite.md)
- [タスク キューの作成例](https://docs.xbox.com/ja-jp/build/core-features/common/async/async-libraries/async-library-xtaskqueue-example-create-task-queue.md)
- [XTaskQueueDispatchMode](https://docs.xbox.com/ja-jp/reference/system/xtaskqueue/enums/xtaskqueuedispatchmode.md)
- [方法: スレッド プール タスク キューの作成](https://docs.xbox.com/ja-jp/build/core-features/common/async/async-task-queue-design-howto/creating-thread-pool-task-queue.md)
- [XTaskQueue (API の内容)](https://docs.xbox.com/ja-jp/reference/system/xtaskqueue/xtaskqueue_members.md)