> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# XTaskQueueRegisterWaiter

> XTaskQueueRegisterWaiter

# XTaskQueueRegisterWaiter

向任务队列注册等待句柄。

## Syntax

```cpp theme={null}
HRESULT XTaskQueueRegisterWaiter(  
         XTaskQueueHandle queue,  
         XTaskQueuePort port,  
         HANDLE waitHandle,  
         void* callbackContext,  
         XTaskQueueCallback* callback,  
         XTaskQueueRegistrationToken* token  
)  
```

### Parameters

*queue*   \_In\_\
类型：XTaskQueueHandle

要向其提交回调的队列。

*port*   \_In\_\
类型：[XTaskQueuePort](/reference/system/xtaskqueue/enums/xtaskqueueport)

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

*waitHandle*   \_In\_\
类型：HANDLE

要监视的句柄。

<Note>这是等待句柄，收到信号时将导致调用回调。等待句柄通常是自动或手动重置事件。如果等待句柄是手动重置的，则只要该事件发出信号，就会重复调用回调。如果这不是你想要的，请在回调期间重置该事件，或者取消注册等待回调。</Note>

*callbackContext*   \_In\_opt\_\
类型：void\*

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

*callback*   \_In\_\
类型：[XTaskQueueCallback\*](/reference/system/xtaskqueue/functions/xtaskqueuecallback)

指向回调函数的指针。

*token*   \_Out\_\
类型：[XTaskQueueRegistrationToken\*](/reference/system/xtaskqueue/structs/xtaskqueueregistrationtoken)

注册令牌。可以将其传递给 [XTaskQueueUnregisterWaiter](/reference/system/xtaskqueue/functions/xtaskqueueunregisterwaiter) 以取消注册等待。

### Return value

类型：HRESULT

HRESULT 成功或错误代码。

## Remarks

<Note>此函数在时间敏感线程上调用不安全。有关详细信息，请参阅[时间敏感线程](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)。</Note>

当等待句柄得到满足时，任务队列将调用给定的回调。这提供了一种响应句柄变为已发出信号状态而向任务队列添加项目的高效方法。

以下示例向任务队列注册一个 Win32 内核句柄。当该句柄变为已发出信号时，将向该队列提交回调。通常，你会创建一个自动重置事件用于发信号。如果句柄不是自动重置的，则只要句柄发出信号，当前回调完成时就会提交新的回调。

```cpp theme={null}
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);
}
```

## Requirements

**头文件：** XTaskQueue.h

**库：** xgameruntime.lib

**受支持的平台：** Windows、XBOX One 系列主机和 XBOX Series 主机

## Conceptual documentation

* [XTaskQueue 库概述](/build/core-features/common/async/async-libraries/async-library-xtaskqueue)
* [时间敏感线程](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)

## See also

[XTaskQueue 成员](/reference/system/xtaskqueue/xtaskqueue_members)\
[异步编程模型](/build/core-features/common/async/async-programming-model)\
[异步任务队列设计](/build/core-features/common/async/async-task-queue-design)


## Related topics

- [XTaskQueueUnregisterWaiter](/zh-CN/reference/system/xtaskqueue/functions/xtaskqueueunregisterwaiter.md)
- [XTaskQueuePort](/zh-CN/reference/system/xtaskqueue/enums/xtaskqueueport.md)
- [XTaskQueueRegistrationToken](/zh-CN/reference/system/xtaskqueue/structs/xtaskqueueregistrationtoken.md)
- [XTaskQueue](/zh-CN/reference/system/xtaskqueue/xtaskqueue_members.md)
- [面向 GDK 的 Unity C# API 包装器](/zh-CN/build/gdk-and-engines/unity/unity-api-wrappers.md)