XTaskQueueRegisterWaiter

将一个等待句柄注册到任务队列。

语法

HRESULT XTaskQueueRegisterWaiter(  
         XTaskQueueHandle queue,  
         XTaskQueuePort port,  
         HANDLE waitHandle,  
         void* callbackContext,  
         XTaskQueueCallback* callback,  
         XTaskQueueRegistrationToken* token  
)  

参数

queue _In_
类型：XTaskQueueHandle

要将回调提交到的队列。

port _In_
类型：XTaskQueuePort

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

waitHandle _In_
类型：HANDLE

要监视的句柄。

注意

这是等待句柄，收到信号后将导致调用回调。 等待句柄通常是自动或手动重置事件。 如果等待句柄已手动重置，只要事件收到信号，将反复调用回调。 如果这不是你想要的，请在回调中重置事件或取消注册等待回调。

callbackContext _In_opt_
类型：void*

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

callback _In_
类型：XTaskQueueCallback*

指向回调函数的指针。

token _Out_
类型：XTaskQueueRegistrationToken*

一个注册令牌。 可以将它传递给 XTaskQueueUnregisterWaiter 以取消注册等待。

返回值

类型：HRESULT

HRESULT 成功或错误代码。

备注

注意

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

满足等待句柄时，任务队列将调用给定的回调。 这提供了一种高效方式来将项添加到任务队列以响应句柄收到信号。

以下示例将一个 Win32 内核句柄注册到任务队列。 该句柄收到信号时，将您的回调提交给队列。 通常，您将创建一个自动重置事件以供发送信号。 如果句柄未自动重置，只要句柄未收到信号在当前回调完成后会提交新回调。

void CreatingTaskQueueWaiter()
{
    HANDLE waitEvent = CreateEvent(nullptr, FALSE, FALSE, nullptr);
    if (waitEvent == nullptr)
    {
        printf("Error creating wait handle: %d\r\n", GetLastError());
        return;
    }

    XTaskQueueHandle queue;

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

    if (FAILED(hr))
    {
        printf("Error creating task queue: %x\n", hr);
        CloseHandle(waitEvent);
        return;
    }

    auto callback = [](void*, bool)
    {
        printf("Callback invoked.\r\n");
    };

    XTaskQueueRegistrationToken token;

    hr = XTaskQueueRegisterWaiter(
        queue, 
        XTaskQueuePort::Completion, 
        waitEvent, 
        nullptr, 
        callback, 
        &token);

    if (FAILED(hr))
    {
        printf("Error registering task queue waiter: %x\n", hr);
        CloseHandle(waitEvent);
        XTaskQueueCloseHandle(queue);
        return;
    }

    // Now, whenever our wait event becomes signaled the callback will be called.
    for (uint32_t i = 0; i < 5; i++)
    {
        SetEvent(waitEvent);
        Sleep(100);
    }

    // Note: unregistering the waiter is optional
    XTaskQueueUnregisterWaiter(queue, token);
    XTaskQueueCloseHandle(queue);
    CloseHandle(waitEvent);
}

要求

头文件：XTaskQueue.h

库：xgameruntime.lib

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

另请参阅

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