> ## 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.

# XTaskQueueDispatch

> XTaskQueueDispatch

# XTaskQueueDispatch

Processes an item in the task queue for the given port.

## Syntax

```cpp theme={null}
bool XTaskQueueDispatch(  
         XTaskQueueHandle queue,  
         XTaskQueuePort port,  
         uint32_t timeoutInMs  
)  
```

### Parameters

*queue*   \_In\_\
Type: XTaskQueueHandle

The queue to dispatch work on.

*port*   \_In\_\
Type: [XTaskQueuePort](/reference/system/xtaskqueue/enums/xtaskqueueport)

The port to dispatch.

*timeoutInMs*   \_In\_\
Type: uint32\_t

The number of milliseconds to wait for work to arrive before returning false. You may pass **INFINITE** to wait forever.

### Return value

Type: bool

Returns true if this function dispatched a call or false if it did not. This function will also return false if the queue is terminated, even if **INFINITE** is passed as a timeout.

## Remarks

You can pass a timeout, which will cause **XTaskQueueDispatch** to wait for something to arrive in the queue.

If a task queue port was created with [XTaskQueueDispatchMode::ThreadPool](/reference/system/xtaskqueue/enums/xtaskqueuedispatchmode), [XTaskQueueDispatchMode::SerializedThreadPool](/reference/system/xtaskqueue/enums/xtaskqueuedispatchmode), or [XTaskQueueDispatchMode::Immediate](/reference/system/xtaskqueue/enums/xtaskqueuedispatchmode), dispatch modes it will dispatch callbacks automatically. For manual dispatch ports you need to call **XTaskQueueDispatch**. **XTaskQueueDispatch** can be called for any dispatch mode but note that a call is always dispatched on the thread that calls **XTaskQueueDispatch**.

<img src="https://mintcdn.com/microsoft-4404708b/gzrdvT5kpqAXKEQt/images/gdk/reference/note.gif?s=6c1a4c009b25ad5315c45ce51bc83983" alt="alert" width="10" height="10" data-path="images/gdk/reference/note.gif" /> **Performance Note:**\
Adding an item to a queue needs to be lock and wait free in order to satisfy the performance requirements of upstream code. The following APIs are lock free:

* [XTaskQueueSubmitCallback](/reference/system/xtaskqueue/functions/xtaskqueuesubmitcallback)
* [XTaskQueueSubmitDelayedCallback](/reference/system/xtaskqueue/functions/xtaskqueuesubmitdelayedcallback)
* [XTaskQueueDispatch](/reference/system/xtaskqueue/functions/xtaskqueuedispatch), provided that 0 is passed for *timeoutInMs*

<img src="https://mintcdn.com/microsoft-4404708b/gzrdvT5kpqAXKEQt/images/gdk/reference/note.gif?s=6c1a4c009b25ad5315c45ce51bc83983" alt="alert" width="10" height="10" data-path="images/gdk/reference/note.gif" /> **Performance Note:**\
The amount of time spent by [XTaskQueueDispatch](/reference/system/xtaskqueue/functions/xtaskqueuedispatch) when processing an item from the Work port is variable and dependent on the work being performed.
In some cases the calling thread could block waiting for other system work to complete.

The following example shows how to use the **XTaskQueueDispatch** function to process items in the task queue.

<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

* [Clean up task queue](/build/core-features/common/async/async-libraries/async-library-xtaskqueue-example-cleanup-task-queue)
* [Dispatch task queue](/build/core-features/common/async/async-libraries/async-library-xtaskqueue-example-dispatch-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)

## 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

- [XTaskQueueDispatchMode](/reference/system/xtaskqueue/enums/xtaskqueuedispatchmode.md)
- [XTaskQueuePort](/reference/system/xtaskqueue/enums/xtaskqueueport.md)
- [Making Async Calls](/services/playfab/sdks/c/async.md)
- [Making async calls in the PlayFab Unified SDK](/services/playfab/sdks/unified-sdk/async-model.md)
- [Making async calls in the XSAPI C API](/services/xbox-services/fundamentals/xbox-services-api/live-flatc-async-patterns.md)