task_group 類別

發行項
10/12/2023

task_group 類別表示可以等候或取消的平行工作集合。

語法

class task_group;

成員

公用建構函式

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

公用方法

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

備註

與嚴格限制 structured_task_group 的類別不同，類別 task_group 更一般建構。它沒有任何structured_task_group 所述的限制。 task_group 物件可以安全地跨執行緒使用，並以自由格式的方式使用。建構的 task_group 缺點是它可能無法執行，以及 structured_task_group 執行少量工作之工作的建構。

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

繼承階層架構

task_group

需求

標頭： ppl.h

命名空間： concurrency

cancel

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

void cancel();

備註

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

is_canceling

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

bool is_canceling();

傳回值

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

備註

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

執行

在物件上 task_group 排程工作。 task_handle如果將物件當做參數傳遞至 run ，呼叫端會負責管理物件的存留期 task_handle 。採用函式物件參考做為參數的方法版本牽涉到執行時間內的堆積配置，執行效能可能低於使用對物件參考 task_handle 的版本。採用 _Placement 參數的版本會造成工作在該參數指定的位置變成優先執行。

template<
   typename _Function
>
void run(
   const _Function& _Func
);

template<
   typename _Function
>
void run(
   const _Function& _Func,
   location& _Placement
);

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

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

參數

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

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

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

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

備註

執行時間會排程提供的工作函式，以便稍後執行，這可以在呼叫函式傳回之後執行。此方法會使用 task_handle 物件來保存所提供工作函式的複本。因此，您傳遞給此方法的函式物件中發生的任何狀態變更都不會出現在該函式物件的複本中。此外，請確定您傳遞指標或參考工作函式之任何物件的存留期會維持有效，直到工作函式傳回為止。

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

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

run_and_wait

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

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 。

備註

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

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

從 run_and_wait 物件上的 task_group 方法傳回時，執行時間會將物件重設為可重複使用的全新狀態。這包括取消物件的情況 task_group 。

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

task_group

建構新的 task_group 物件。

task_group();

task_group(
   cancellation_token _CancellationToken
);

參數

_CancellationToken
取消與這個工作群組相關聯的語彙基元。取消語彙基元時，工作群組也會取消。

備註

使用取消語彙基元的建構函式會建立 task_group，當與語彙基元相關聯的來源取消時，它也會一併取消。提供明確的取消語彙基元也會將這個工作群組隔離，使其無法參與具有不同語彙基元或沒有語彙基元之父群組的隱含取消。

~task_group

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

~task_group();

備註

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

wait

等候物件上 task_group 的所有工作都已完成或已取消。

task_group_status wait();

傳回值

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

備註

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

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

在物件上 task_group 呼叫 wait 會將它重設為可重複使用的全新狀態。這包括取消物件的情況 task_group 。

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

另請參閱

concurrency 命名空間
 structured_task_group 類別
 task_handle 類別

共用方式為