Skip to main content

XTaskQueueTerminate

藉由取消所有擱置中的項目並防止新項目加入佇列,來終止工作佇列。

語法

參數

queue   _In_
類型:XTaskQueueHandle
要終止的佇列。 wait   _In_
類型:bool
True 表示等候終止完成。 callbackContext   _In_opt_
類型:void*
要傳遞給回呼的選擇性內容指標。 callback   _In_opt_
類型:XTaskQueueTerminatedCallback*
佇列終止時將呼叫的選擇性回呼。

傳回值

類型:HRESULT HRESULT 成功或錯誤碼。

備註

在時間敏感執行緒上呼叫此函式並不安全。如需詳細資訊,請參閱時間敏感執行緒。
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 視窗程序中。它也示範了在將工作佇列與其他執行緒模型整合時,如何正確終止工作佇列。

需求

標頭: XTaskQueue.h 程式庫: xgameruntime.lib 支援的平台: Windows、XBOX One 系列主機和 XBOX Series 主機

概念文件

另請參閱

XTaskQueue 成員
非同步程式設計模型
非同步工作佇列設計
Last modified on October 6, 2026