XTaskQueueDispatch

Article
03/16/2023

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

Syntax

bool XTaskQueueDispatch(  
         XTaskQueueHandle queue,  
         XTaskQueuePort port,  
         uint32_t timeoutInMs  
)

Parameters

queue _In_
Type: XTaskQueueHandle

The queue to dispatch work on.

port _In_
Type: 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, XTaskQueueDispatchMode::SerializedThreadPool, or XTaskQueueDispatchMode::Immediate, 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.

alert 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
XTaskQueueSubmitDelayedCallback
XTaskQueueDispatch, provided that 0 is passed for timeoutInMs

alert Performance Note:
The amount of time spent by 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 function.

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

Share via