XTaskQueueSubmitDelayedCallback

将回调提交到给定端口的队列。

语法

HRESULT XTaskQueueSubmitDelayedCallback(  
         XTaskQueueHandle queue,  
         XTaskQueuePort port,  
         uint32_t delayMs,  
         void* callbackContext,  
         XTaskQueueCallback* callback  
)  

参数

queue _In_
类型：XTaskQueueHandle

要将回调提交到的队列。

port _In_
类型：XTaskQueuePort

要将回调提交到的端口。 可将回调分配给工作端口或完成端口。

delayMs _In_
类型：uint32_t

将回调提交给队列前要延迟的毫秒数。

注意

可以提交回调以便在将来的某个时间添加到队列。 如果 delayMs 为非零值，则将回调置于挂起的列表并使用下一最近的等待时间初始化计时器。 该时间过后，将具有下次的回调置于执行列表上。 该队列将引发 XTaskQueueMonitorCallback，如果队列正在线程池调度模式下运行，将提交线程池工作。

callbackContext _In_opt_
类型：void*

将传递给回调的可选上下文指针。

callback _In_
类型：XTaskQueueCallback*

指向回调函数的指针。

返回值

类型：HRESULT

HRESULT 成功或错误代码。

备注

在 delayMs 毫秒后将此回调添加到队列。

性能注意事项：
将某项添加到队列需要锁定并等待释放，以便满足上游代码的性能要求。 以下 API 是无锁的：

• XTaskQueueSubmitCallback
• XTaskQueueSubmitDelayedCallback
• XTaskQueueDispatch，前提是将 0 传递给 timeoutInMs

以下示例通过使用 XTaskQueueSubmitDelayedCallback 函数允许在将来提交回调。 这是一种在暂短延迟后重试失败调用的好方法；也可以将它作为定期事件的低廉计时器。

注意

SubmitCallback是一个帮助程序函数，它在代码示例中定义用于 XTaskQueueSubmitCallback 函数。

void SubmittingDelayedCallback()
{
    XTaskQueueHandle queue;

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

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

    struct CallContext
    {
        DWORD count;
        XTaskQueueHandle queue;
        XTaskQueueCallback* callback;
    } callContext;

    auto callback = [](void* context, bool cancel)
    {
        CallContext *callContext = static_cast<CallContext*>(context);
        callContext->count++;
        printf("Periodic callback %d\r\n", callContext->count);
        if (callContext->count != 10 && !cancel)
        {
            HRESULT hr = XTaskQueueSubmitDelayedCallback(
                callContext->queue, 
                XTaskQueuePort::Completion, 
                500, 
                callContext, 
                callContext->callback);

            if (FAILED(hr))
            {
                printf("Failed submitting next callback: 0x%x\r\n", hr);
                callContext->count = 10; // Prevent us from waiting forever.
            }
        }
    };

    callContext.count = 0;
    callContext.queue = queue;
    callContext.callback = callback;

    // Use the task queue to make 10 periodic calls
    hr = XTaskQueueSubmitDelayedCallback(
        queue,
        XTaskQueuePort::Completion,
        500,
        &callContext,
        callback);

    if (FAILED(hr))
    {
        printf("Failed submitting delayed callback: 0x%x\r\n", hr);
        XTaskQueueCloseHandle(queue);
        return;
    }

    // Now wait for all the calls to complete.
    while (callContext.count != 10)
    {
        Sleep(1000);
    }

    XTaskQueueTerminate(queue, true, nullptr, nullptr);
    XTaskQueueCloseHandle(queue);
}

要求

头文件：XTaskQueue.h

库：xgameruntime.lib

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

另请参阅

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