XTaskQueueSubmitCallback

Article
03/16/2023

Submits a callback to the queue for the given port.

Syntax

HRESULT XTaskQueueSubmitCallback(  
         XTaskQueueHandle queue,  
         XTaskQueuePort port,  
         void* callbackContext,  
         XTaskQueueCallback* callback  
)

Parameters

queue _In_
Type: XTaskQueueHandle

The queue to submit the callback to.

port _In_
Type: XTaskQueuePort

The port to submit the callback to. Callbacks can be assigned to work or completion ports.

callbackContext _In_opt_
Type: void*

An optional context pointer that will be passed to the callback.

callback _In_
Type: XTaskQueueCallback*

A pointer to the callback function.

Return value

Type: HRESULT

HRESULT success or error code.

Remarks

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

The following example demonstrates how a callback is submitted to either the work or completion port of a task queue. It first submits a work callback, and then at the end of the work callback it submits a completion callback, which will be typical.

void CALLBACK SampleCompletionCallback(void*, bool cancel)
{
    printf("Completion invoked on thread %d.  Cancel? %d.\r\n", GetCurrentThreadId(), cancel);
}

void CALLBACK SampleWorkCallback(void* context, bool cancel)
{
    printf("Worker invoked on thread %d. Cancel? %d.\r\n", GetCurrentThreadId(), cancel);
    XTaskQueueHandle queueFromContext = static_cast<XTaskQueueHandle>(context);

    HRESULT hrCompletion = XTaskQueueSubmitCallback(
        queueFromContext, 
        XTaskQueuePort::Completion, 
        nullptr, 
        SampleCompletionCallback);

    if (FAILED(hrCompletion))
    {
        printf("Error 0x%x submitting completion.\r\n", hrCompletion);
    }
}

void SubmitCallbacks(XTaskQueueHandle queue)
{
    HRESULT hrWork = XTaskQueueSubmitCallback(
        queue, 
        XTaskQueuePort::Work, 
        queue, 
        SampleWorkCallback);

    if (FAILED(hrWork))
    {
        printf("Error 0x%x submitting work.\r\n", hrWork);
    }
}

Requirements

Header: XTaskQueue.h

Library: xgameruntime.lib

Supported platforms: Windows, Xbox One family consoles and Xbox Series consoles

Share via