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

# XTaskQueueCreate

> XTaskQueueCreate

# XTaskQueueCreate

Creates a task queue, which can be used to queue and dispatch calls.

## Syntax

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

### Parameters

*workDispatchMode*   \_In\_\
Type: [XTaskQueueDispatchMode](/reference/system/xtaskqueue/enums/xtaskqueuedispatchmode)

The dispatch mode for the "work" port of the queue.

*completionDispatchMode*   \_In\_\
Type: [XTaskQueueDispatchMode](/reference/system/xtaskqueue/enums/xtaskqueuedispatchmode)

The dispatch mode for the "completion" port of the queue.

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

The newly created queue.

### Return value

Type: HRESULT

HRESULT success or error code.

## Remarks

<Note>This function isn't safe to call on a time-sensitive thread. For more information, see [Time-sensitive threads](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads).</Note>

Task queues are reference counted objects. Release the reference by calling [XTaskQueueCloseHandle](/reference/system/xtaskqueue/functions/xtaskqueueclosehandle).

A task queue has work and completion ports and tasks can be queued to either port. Each port can be configured with its own dispatch mode.

For most scenarios, you create a task queue with the **XTaskQueueCreate** API. If you are chaining multiple asynchronous calls together, however, sometimes it is useful to create a composite queue via [XTaskQueueCreateComposite](/reference/system/xtaskqueue/functions/xtaskqueuecreatecomposite). Consider an API whose implementation needs to invoke another API that uses a task queue. You may want to redirect the completion callback of the API so it doesn't tie up the completion thread of the caller. In this case, you can create a composite task queue whose work and completion ports are built from the work port of another queue.

The following example creates a task queue that dispatches both work and completion callbacks on the system thread pool.

<Note>**SubmitCallback** is a helper function that is defined in the code example for the [XTaskQueueSubmitCallback](/reference/system/xtaskqueue/functions/xtaskqueuesubmitcallback) function.</Note>

```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);
}
```

The following example creates a manually-pumped task queue. It creates two STL threads that dispatch calls for both the work and completion ports.

<Note>**SubmitCallback** is a helper function that is defined in the code example for the [XTaskQueueSubmitCallback](/reference/system/xtaskqueue/functions/xtaskqueuesubmitcallback) function.</Note>

```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();
}
```

## Requirements

**Header:** XTaskQueue.h

**Library:** xgameruntime.lib

**Supported platforms:** Windows, XBOX One family consoles and XBOX Series consoles

## Conceptual documentation

* [Create task queue](/build/core-features/common/async/async-libraries/async-library-xtaskqueue-example-create-task-queue)
* [XTaskQueue library overview](/build/core-features/common/async/async-libraries/async-library-xtaskqueue)
* [Asynchronous Programming Model](/build/core-features/common/async/async-programming-model)
* [Asynchronous programming design goals and improvements](/build/core-features/common/async/async-whitepaper)
* [Time-sensitive threads](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)

## See also

[XTaskQueue members](/reference/system/xtaskqueue/xtaskqueue_members)\
[Asynchronous Programming Model](/build/core-features/common/async/async-programming-model)\
[Async Task Queue Design](/build/core-features/common/async/async-task-queue-design)


## Related topics

- [XTaskQueueCreateComposite](/reference/system/xtaskqueue/functions/xtaskqueuecreatecomposite.md)
- [Create task queue example](/build/core-features/common/async/async-libraries/async-library-xtaskqueue-example-create-task-queue.md)
- [XTaskQueue](/reference/system/xtaskqueue/xtaskqueue_members.md)
- [XTaskQueueDispatchMode](/reference/system/xtaskqueue/enums/xtaskqueuedispatchmode.md)
- [Making Async Calls](/services/playfab/sdks/c/async.md)