XTaskQueueCreate

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

Syntax

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

Parameters

workDispatchMode   _In_
Type: XTaskQueueDispatchMode

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

completionDispatchMode   _In_
Type: 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

Task queues are reference counted objects. Release the reference by calling 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. 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.

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.

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

See also

XTaskQueue members
Asynchronous Programming Model
Async Task Queue Design