structured_task_group 類別

發行項
10/12/2023

structured_task_group 類別代表平行工作的高度結構化集合。您可以使用 task_handle 物件，將個別平行工作佇列到 structured_task_group 中並等候這些工作完成，也可以在工作完成執行前取消工作群組，這樣會中止所有尚未開始執行的工作。

語法

class structured_task_group;

成員

公用建構函式

名稱	描述
structured_task_group	已多載。建構新的 `structured_task_group` 物件。
~structured_task_group解構函式	終結 `structured_task_group` 物件。除非解構函式因為例外狀況而因為堆疊回溯而執行，否則您應該先在物件上呼叫 `wait` 或 `run_and_wait` 方法。

公用方法

名稱	描述
cancel	盡最大努力取消此工作組根目錄的工作子樹狀結構。如果可能，在工作組上排程的每個工作都會以可轉移方式取消。
is_canceling	通知呼叫者，工作群組目前是否在取消期間。這不一定表示 `cancel` 已在物件上 `structured_task_group` 呼叫方法（雖然如此確實限定這個方法可傳回 `true` ）。可能是 `structured_task_group` 物件正在內嵌執行，且工作樹狀結構中進一步的工作群組已取消。如果這類情況下，執行時間可以事先判斷取消將流經此 `structured_task_group` 物件的情況， `true` 也會傳回。
run	已多載。在物件上 `structured_task_group` 排程工作。呼叫端會管理在參數中 `_Task_handle` 傳遞之物件的存留期 `task_handle` 。採用 `_Placement` 參數的版本會造成工作在該參數指定的位置變成優先執行。
run_and_wait	已多載。排程在呼叫內容上內嵌執行的工作，並協助 `structured_task_group` 物件提供完整取消支援。 `task_handle`如果將物件當做參數傳遞至 `run_and_wait` ，呼叫端會負責管理物件的存留期 `task_handle` 。然後，函式會等到物件上 `structured_task_group` 的所有工作都已完成或取消為止。
等	等到上的所有工作 `structured_task_group` 都已完成或取消為止。

備註

針對物件的使用 structured_task_group 方式，有一些嚴重的限制，以提升效能：

多個執行緒無法使用單 structured_task_group 一物件。物件上 structured_task_group 的所有作業都必須由建立物件的執行緒執行。此規則的兩個例外是成員函式 cancel 和 is_canceling 。除非工作使用其中一個取消作業，否則物件可能不在 Lambda 運算式的擷取清單中，而且在工作內使用。
排程到 structured_task_group 物件的所有工作都會透過使用 task_handle 明確管理存留期的物件來排程。
多個群組只能以絕對巢狀順序使用。如果宣告了兩 structured_task_group 個物件，則第二個物件必須在任何方法之前解構，但第一個方法除外 cancel 或 is_canceling 呼叫第一個方法（外部物件）。這兩種情況都為 true，只要在相同或功能巢狀範圍內宣告多個 structured_task_group 物件，以及透過 run 或 run_and_wait 方法排入佇列的工作 structured_task_group 案例。
不同于一般 task_group 類別，類別中的所有 structured_task_group 狀態都是最終狀態。您將工作佇列至群組並等候工作完成之後，就不能再使用同一個群組。

如需詳細資訊，請參閱工作平行處理原則。

繼承階層架構

structured_task_group

需求

標頭： ppl.h

命名空間： concurrency

cancel

盡最大努力取消此工作組根目錄的工作子樹狀結構。如果可能，在工作組上排程的每個工作都會以可轉移方式取消。

void cancel();

備註

如需詳細資訊，請參閱取消。

is_canceling

通知呼叫者，工作群組目前是否在取消期間。這不一定表示 cancel 已在物件上 structured_task_group 呼叫方法（雖然如此確實限定這個方法可傳回 true ）。可能是 structured_task_group 物件正在內嵌執行，且工作樹狀結構中進一步的工作群組已取消。如果這類情況下，執行時間可以事先判斷取消將流經此 structured_task_group 物件的情況， true 也會傳回。

bool is_canceling();

傳回值

指出物件是否 structured_task_group 在取消期間（或保證不久）。

備註

如需詳細資訊，請參閱取消。

執行

在物件上 structured_task_group 排程工作。呼叫端會管理在參數中 _Task_handle 傳遞之物件的存留期 task_handle 。採用 _Placement 參數的版本會造成工作在該參數指定的位置變成優先執行。

template<class _Function>
void run(
    task_handle<_Function>& _Task_handle);

template<class _Function>
void run(
    task_handle<_Function>& _Task_handle,
    location& _Placement);

參數

_功能
要叫用以執行工作控制碼主體的函式物件類型。

_Task_handle
排程工作的控制碼。請注意，呼叫端對此物件的存留期負責。執行時間會繼續預期其會存留，直到 wait 在此 structured_task_group 物件上呼叫或 run_and_wait 方法為止。

_位置
位置的參考，這是 _Task_handle 參數代表的工作應該執行的位置。

備註

執行時間會建立您傳遞給此方法的工作函式複本。您傳遞給此方法的函式物件中發生的任何狀態變更，都不會出現在該函式物件的複本中。

structured_task_group如果由於堆疊從例外狀況回溯而解構，您就不需要保證已對或 run_and_wait 方法進行 wait 呼叫。在此情況下，解構函式會適當地取消，並等候參數表示 _Task_handle 的工作完成。

如果參數所提供的 _Task_handle 工作控制碼已透過方法排程到工作組物件 run 上，而且該工作組上沒有對或 run_and_wait 方法的介入呼叫 wait ，則擲回invalid_multiple_scheduling 例外狀況。

run_and_wait

排程在呼叫內容上內嵌執行的工作，並協助 structured_task_group 物件提供完整取消支援。 task_handle如果將物件當做參數傳遞至 run_and_wait ，呼叫端會負責管理物件的存留期 task_handle 。然後，函式會等到物件上 structured_task_group 的所有工作都已完成或取消為止。

template<class _Function>
task_group_status run_and_wait(task_handle<_Function>& _Task_handle);

template<class _Function>
task_group_status run_and_wait(const _Function& _Func);

參數

_功能
將要叫用以執行工作的函式物件類型。

_Task_handle
工作控制碼，將在呼叫內容上內嵌執行。請注意，呼叫端對此物件的存留期負責。執行時間會繼續預期它會持續運作，直到 run_and_wait 方法完成執行為止。

_Func
將呼叫以叫用工作主體的函式。這可能是 Lambda 或其他物件，其支援具有簽章 void operator()() 的函式呼叫運算子版本。

傳回值

由於明確取消作業或從其中一個工作擲回例外狀況，表示已滿足等候或工作組已取消。如需詳細資訊，請參閱 task_group_status

備註

請注意，排程至此 structured_task_group 物件的一或多個工作可能會在呼叫內容上內嵌執行。

如果排程至此 structured_task_group 物件的一或多個工作擲回例外狀況，執行時間會選取其選擇的其中一個例外狀況，並將其傳播出方法的呼叫 run_and_wait 。

這個函式傳回後，就會將 structured_task_group 物件視為處於最終狀態而且不應使用。請注意，方法傳回後的 run_and_wait 使用率會導致未定義的行為。

在非例外的執行路徑中，您必須在執行解構函 structured_task_group 式之前呼叫這個方法或 wait 方法。