XTaskQueueCreate

创建任务队列，它可用于排队和调度调用。

语法

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

参数

workDispatchMode _In_
类型：XTaskQueueDispatchMode

队列“工作”端口的调度模式。

completionDispatchMode _In_
类型：XTaskQueueDispatchMode

队列“完成”端口的调度模式。

queue _Out_
类型：XTaskQueueHandle*

新创建的队列。

返回值

类型：HRESULT

HRESULT 成功或错误代码。

备注

注意

在时间敏感线程上调用此函数是不安全的。 有关详细信息，请参阅时间敏感线程。

任务队列是对引用计数的对象。 通过调用 XTaskQueueCloseHandle 释放引用。

任务队列具有工作端口和完成端口，任务可在任一端口排队。 每个端口可以使用自己的调度模式来配置。

对于大多数情形，您可以使用 XTaskQueueCreate API 创建一个任务队列。 但是，如果您正在将多个异步调用串接在一起，有时通过 XTaskQueueCreateComposite 创建一个复合队列很有用。 请考虑一个 API，其实现需要调用另一个使用某任务队列的 API。 你可能希望重定向该 API 的完成回调，以便它不会阻碍调用方的完成线程。 在这种情况下，您可以创建一个复合任务队列，其工作端口和完成端口都从另一队列的工作端口生成。

以下示例创建一个任务队列，该队列在系统线程池上调度工作回调和完成回调。

注意

SubmitCallback 是在 XTaskQueueSubmitCallback 函数的代码示例中定义的帮助程序函数。

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);
}

以下示例创建一个手动抽取的任务队列。 它将创建两个 STL 线程，调度用于工作端口和完成端口的调用。

注意

SubmitCallback 是在 XTaskQueueSubmitCallback 函数的代码示例中定义的帮助程序函数。

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();
}

要求

头文件：XTaskQueue.h

库：xgameruntime.lib

支持平台：Windows、Xbox One 系列主机和 Xbox Series 主机

另请参阅

XTaskQueue 成员
异步编程模型
异步任务队列设计