Skip to main content

XTaskQueueTerminate

Terminates a task queue by canceling all pending items and preventning new items from being queued.

Syntax

Parameters

queue   _In_
Type: XTaskQueueHandle
The queue to terminate. wait   _In_
Type: bool
True to wait for the termination to complete. callbackContext   _In_opt_
Type: void*
An optional context pointer to pass to the callback. callback   _In_opt_
Type: XTaskQueueTerminatedCallback*
An optional callback that will be called when the queue has terminated.

Return value

Type: HRESULT HRESULT success or error code.

Remarks

This function isn’t safe to call on a time-sensitive thread. For more information, see Time-sensitive threads.
XTaskQueueCloseHandle simply decrements an internal reference count on the task queue object. If there are callbacks still in the queue, those callbacks hold a reference on the queue object and they may still be called. This can pose a problem for app shutdown. When an app shuts down it will need to ensure no spurious callbacks execute after cleanup. XTaskQueue provides the XTaskQueueTerminate API to perform a controlled termination of a queue. Terminating a task queue performs the following operations:
  1. All callbacks for both ports will be invoked with their canceled parameter set to true.
  2. All callbacks pending on the work port will be dispatched. Submitting new callbacks to the work port will fail with E_ABORT.
  3. All callbacks pending on the completion port will be dispatched. Submitting new callbacks to the completion port will fail with E_ABORT.
After this process completes XTaskQueueTerminate will return if wait is true. If wait is false, termination happens asynchronously. If you supply a termination callback it will be invoked from the completion thread at the end of termination.
  • XTaskQueueTerminate does not close the queue handle. After terminating you still need to call XTaskQueueCloseHandle.
  • If you call XTaskQueueTerminate on a thread that is servicing queue callbacks by calling XTaskQueueDispatch, do not pass true for the wait parameter or your code may deadlock.
The following example demonstrates how to terminate a previously created task queue.
SubmitCallback is a helper function that is defined in the code example for the XTaskQueueSubmitCallback function.
A task queue can be integrated with a UI thread. Typically, you would want callbacks queued to the completion port to run on the UI thread. This example uses the thread pool for work but integrates completion port callbacks into a Win32 Window Proc. It also demonstrates correct termination of a task queue when integrating it with another threading model.

Requirements

Header: XTaskQueue.h Library: xgameruntime.lib Supported platforms: Windows, XBOX One family consoles and XBOX Series consoles

Conceptual documentation

See also

XTaskQueue members
Asynchronous Programming Model
Async Task Queue design
Last modified on August 20, 2026