Skip to main content

XTaskQueueTerminate

通过取消所有挂起项并阻止将新项排入队列来终止任务队列。

Syntax

Parameters

queue   _In_
类型:XTaskQueueHandle
要终止的队列。 wait   _In_
类型:bool
True 表示等待终止完成。 callbackContext   _In_opt_
类型:void*
要传递给回调的可选上下文指针。 callback   _In_opt_
类型:XTaskQueueTerminatedCallback*
可选回调,将在队列终止时调用。

Return value

类型:HRESULT HRESULT 成功或错误代码。

Remarks

此函数在时间敏感线程上调用不安全。有关详细信息,请参阅时间敏感线程
XTaskQueueCloseHandle 只是递减任务队列对象上的内部引用计数。如果队列中仍有回调,这些回调会保持对队列对象的引用,它们仍可能被调用。这可能会给应用程序关闭带来问题。当应用程序关闭时,需要确保清理后不会执行任何虚假回调。XTaskQueue 提供 XTaskQueueTerminate API 来对队列执行受控终止。 终止任务队列会执行以下操作:
  1. 两个端口的所有回调都将在其 canceled 参数设置为 true 的情况下被调用。
  2. 工作端口上的所有挂起回调将被调度。向工作端口提交新回调将失败并返回 E_ABORT。
  3. 完成端口上的所有挂起回调将被调度。向完成端口提交新回调将失败并返回 E_ABORT。
在此过程完成后,如果 wait 为 true,XTaskQueueTerminate 将返回。如果 wait 为 false,则终止是异步发生的。如果提供终止回调,将在终止结束时从完成线程调用它。
  • XTaskQueueTerminate 不会关闭队列句柄。终止之后,仍需要调用 XTaskQueueCloseHandle
  • 如果在通过调用 XTaskQueueDispatch 为队列回调提供服务的线程上调用 XTaskQueueTerminate,请勿将 wait 参数传入 true,否则代码可能会死锁。
以下示例演示了如何终止先前创建的任务队列。
SubmitCallback 是在 XTaskQueueSubmitCallback 函数的代码示例中定义的帮助程序函数。
任务队列可以与 UI 线程集成。通常,你希望排队到完成端口的回调在 UI 线程上运行。此示例使用线程池执行工作,但将完成端口回调集成到 Win32 Window Proc 中。它还演示了在将任务队列与另一种线程模型集成时正确终止任务队列的方法。

Requirements

头文件: XTaskQueue.h 库: xgameruntime.lib 受支持的平台: Windows、XBOX One 系列主机和 XBOX Series 主机

Conceptual documentation

See also

XTaskQueue 成员
异步编程模型
异步任务队列设计
最后修改于 2026年8月24日