structured_task_group 類別

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 在取消期間（或保證不久）。

備註

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

run

在物件上 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 方法。

structured_task_group

建構新的 structured_task_group 物件。

structured_task_group();

structured_task_group(cancellation_token _CancellationToken);

參數

_CancellationToken
要與此結構化工作組建立關聯的取消標記。 當令牌取消時，將會取消結構化工作組。

備註

使用取消語彙基元的建構函式會建立 structured_task_group，當與語彙基元相關聯的來源取消時，它也會一併取消。 提供明確的取消令牌也會隔離此結構化工作組，而不要參與具有不同令牌或無令牌之父群組的隱含取消。

~structured_task_group

終結 structured_task_group 物件。 除非解構函式因為例外狀況而因為堆疊回溯而執行，否則您應該先在 物件上呼叫 wait 或 run_and_wait 方法。

~structured_task_group();

備註

如果解構函式會以正常執行的結果執行（例如，由於例外狀況而未堆疊回溯），而且未 wait 呼叫 和 run_and_wait 方法，解構函式可能會擲回 missing_wait 例外狀況。

wait

等到 上的所有工作 structured_task_group 都已完成或取消為止。

task_group_status wait();

傳回值

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

備註

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

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

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

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

另請參閱

concurrency 命名空間
task_group 類別
task_handle 類別