XTaskQueueDuplicateHandle

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

See also

XTaskQueue members
Asynchronous Programming Model
Async Task Queue Design