XTaskQueueRegisterWaiter

Article
06/22/2023

Registers a wait handle with a task queue.

Syntax

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

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.

callbackContext _In_opt_
Type: void*

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

callback _In_
Type: XTaskQueueCallback*

A pointer to the callback function.

token _Out_
Type: XTaskQueueRegistrationToken*

A registration token. This can be passed to 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.

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 becomming 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.

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

Share via