> ## 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

Registers a wait handle with a task queue.

## Syntax

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

### Parameters

*queue*   \_In\_\
Type: XTaskQueueHandle

The queue to submit the callback to.

*port*   \_In\_\
Type: [XTaskQueuePort](/reference/system/xtaskqueue/enums/xtaskqueueport)

The port to submit the callback to. Callbacks can be assigned to work or completion ports.

*waitHandle*   \_In\_\
Type: HANDLE

The handle to monitor.

<Note>This is the wait handle that, when signaled, will cause the callback to be invoked. The wait handle is typically an auto or manual reset event. If the wait handle is manual reset the callback will be invoked repeatedly as long as the event is signaled. If this isn't what you want, either reset the event while in the callback or unregister the wait callback.</Note>

*callbackContext*   \_In\_opt\_\
Type: void\*

An optional context pointer that will be passed to the callback.

*callback*   \_In\_\
Type: [XTaskQueueCallback\*](/reference/system/xtaskqueue/functions/xtaskqueuecallback)

A pointer to the callback function.

*token*   \_Out\_\
Type: [XTaskQueueRegistrationToken\*](/reference/system/xtaskqueue/structs/xtaskqueueregistrationtoken)

A registration token. This can be passed to [XTaskQueueUnregisterWaiter](/reference/system/xtaskqueue/functions/xtaskqueueunregisterwaiter) to unregister the wait.

### Return value

Type: HRESULT

HRESULT success or error code.

## Remarks

<Note>This function isn't safe to call on a time-sensitive thread. For more information, see [Time-sensitive threads](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads).</Note>

When the wait handle is satisfied the task queue will invoke the given callback. This provides an efficient way to add items to a task queue in response to handles becoming signaled.

The following example registers a Win32 kernel handle with a task queue. Your callback will be submitted to the queue when the handle becomes signaled. Normally, you would create an auto reset event to use for signaling. If the handle is not auto reset, a new callback will be submitted when the current callback completes for as long as the handle is signaled.

```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

**Header:** XTaskQueue.h

**Library:** xgameruntime.lib

**Supported platforms:** Windows, XBOX One family consoles and XBOX Series consoles

## Conceptual documentation

* [XTaskQueue library overview](/build/core-features/common/async/async-libraries/async-library-xtaskqueue)
* [Time-sensitive threads](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)

## See also

[XTaskQueue members](/reference/system/xtaskqueue/xtaskqueue_members)\
[Asynchronous Programming Model](/build/core-features/common/async/async-programming-model)\
[Async Task Queue Design](/build/core-features/common/async/async-task-queue-design)


## Related topics

- [XTaskQueueUnregisterWaiter](/reference/system/xtaskqueue/functions/xtaskqueueunregisterwaiter.md)
- [XTaskQueuePort](/reference/system/xtaskqueue/enums/xtaskqueueport.md)
- [XTaskQueue](/reference/system/xtaskqueue/xtaskqueue_members.md)
- [XTaskQueueRegistrationToken](/reference/system/xtaskqueue/structs/xtaskqueueregistrationtoken.md)
- [Unity C# API wrappers for the GDK](/build/gdk-and-engines/unity/unity-api-wrappers.md)