XTaskQueueGetPort

Article
11/09/2023

Returns the task queue port handle for the given port.

Syntax

HRESULT XTaskQueueGetPort(  
         XTaskQueueHandle queue,  
         XTaskQueuePort port,  
         XTaskQueuePortHandle* portHandle  
)

Parameters

queue _In_
Type: XTaskQueueHandle

The task queue to get the port from.

port _In_
Type: XTaskQueuePort

The port to get.

portHandle _Out_
Type: XTaskQueuePortHandle*

The task queue port handle for the given port.

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.

Task queue port handles are owned by the task queue and do not have to be closed. They are used when creating composite task queues.

The following example creates a composite queue whose work and completion ports both use the work port of the original queue. A composite task queue is a task queue that is composed of parts from other queues. Composite task queues are useful when one asynchronous task needs to call another, and the completion from that task is an intermediate step that should not waste cycles on the completion thread.

Note

SubmitCallback is a helper function that is defined in the code example for the XTaskQueueSubmitCallback function.

void CreatingCompositeQueue()
{
    XTaskQueueHandle queue;

    HRESULT hr = XTaskQueueCreate(
        XTaskQueueDispatchMode::ThreadPool, 
        XTaskQueueDispatchMode::Manual, 
        &queue);

    if (FAILED(hr))
    {
        printf("failed to create task queue: 0x%x\r\n", hr);
        return;
    }

    XTaskQueuePortHandle workPort;

    // Create a composite queue that uses the work port from
    // another queue for both work and completion ports.

    hr = XTaskQueueGetPort(queue, XTaskQueuePort::Work, &workPort);
    if (FAILED(hr))
    {
        printf("failed to get work port 0x%x\r\n", hr);
        XTaskQueueCloseHandle(queue);
        return;
    }

    XTaskQueueHandle compositeQueue;
    hr = XTaskQueueCreateComposite(workPort, workPort, &compositeQueue);
    if (FAILED(hr))
    {
        printf("failed to create composiute queue 0x%x\r\n", hr);
        XTaskQueueCloseHandle(queue);
        return;
    }

    // Use the queue as needed
    SubmitCallbacks(compositeQueue);

    // Wait a while for the callbacks to run
    Sleep(1000);

    XTaskQueueCloseHandle(compositeQueue);
    XTaskQueueCloseHandle(queue);
}

Requirements

Header: XTaskQueue.h

Library: xgameruntime.lib

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

Partager via