XTaskQueueDuplicateHandle

Article
06/22/2023

Duplicates a XTaskQueueHandle object.

Syntax

HRESULT XTaskQueueDuplicateHandle(  
         XTaskQueueHandle queueHandle,  
         XTaskQueueHandle* duplicatedHandle  
)

Parameters

queueHandle _In_
Type: XTaskQueueHandle

The queue to reference.

duplicatedHandle _Out_
Type: XTaskQueueHandle*

The duplicated queue handle.

Return value

Type: HRESULT

HRESULT success or error code.

Remarks

Use XTaskQueueCloseHandle to close the XTaskQueueHandle object.

The following example demonstrates how to duplicate a task queue handle. If you have long-running work, you might want to duplicate the task queue handle for the duration of that work. This prevents anyone that calls the XTaskQueueCloseHandle function from closing the queue while you still need it.

void DuplicatingTaskQueueHandle()
{
    XTaskQueueHandle queue;

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

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

    class LongRunningWork
    {
    public:
        HRESULT Initialize(XTaskQueueHandle queue)
        {
            return XTaskQueueDuplicateHandle(queue, &m_queue);
        }
        
        ~LongRunningWork()
        {
            if (m_queue != nullptr)
            {
                XTaskQueueCloseHandle(m_queue);
            }
        }

    private:
        XTaskQueueHandle m_queue = nullptr;
    };

    LongRunningWork work;
    hr = work.Initialize(queue);
    
    // Note that LongRunningWork's queue handle is still valid.
    XTaskQueueCloseHandle(queue);

    if (FAILED(hr))
    {
        printf("Failed to duplicate queue handle: 0x%x\r\n", hr);
    }
}

Requirements

Header: XTaskQueue.h

Library: xgameruntime.lib

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

Share via