task_group 类

项目
10/18/2023

task_group 类表示可以等待或取消的并行工作的集合。

语法

class task_group;

成员

公共构造函数

名称	描述
task_group	已重载。构造新的 `task_group` 对象。
~task_group 析构函数	销毁 `task_group` 对象。应在执行析构函数之前在对象上调用 `wait` 或 `run_and_wait` 方法，除非由于异常导致堆栈展开而正在执行析构函数。

公共方法

名称	说明
cancel	尽最大努力尝试取消植根于此任务组的工作子树。如果可能，任务组上计划的每个任务都将以可传递方式取消。
is_canceling	通知调用方任务组当前是否正在取消。这并不一定表示在 `task_group` 对象上调用了 `cancel` 方法（尽管这样肯定使此方法返回 `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` 对象的生存期。
wait	等待至 `task_group` 对象上的所有工作都已完成或已取消。

备注

与受到严格限制的 structured_task_group 类不同，该 task_group 类采用更常规的构造。它不会受到任何 structured_task_group 所描述的限制。 task_group 对象可以安全地在不同线程之间使用，且在利用形式上也非常自由。 task_group 构造的缺点是，对于执行少量工作的任务，它的执行效果可能不如 structured_task_group 构造。

有关详细信息，请参阅任务并行。

继承层次结构

task_group

要求

标头：ppl.h

命名空间： 并发

cancel

尽最大努力尝试取消植根于此任务组的工作子树。如果可能，任务组上计划的每个任务都将以可传递方式取消。

void cancel();

备注

有关详细信息，请参阅取消。

is_canceling

通知调用方任务组当前是否正在取消。这并不一定表示在 task_group 对象上调用了 cancel 方法（尽管这样肯定使此方法返回 true）。可能是 task_group 对象正在内联执行并且工作树中更靠前的任务组已取消。在运行时可以提前确定取消将流经此 task_group 对象的情况下，也将返回 true。

bool is_canceling();

返回值

指示 task_group 对象是否正在取消（或保证很快取消）。

备注

有关详细信息，请参阅取消。

run

在 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
);

参数

_Function
将调用以执行任务句柄主体的函数对象的类型。

_Func
将被调用以调用任务主体的函数。这可能是一个 Lambda 表达式或其他支持带有签名 void operator()() 的函数调用运算符版本的对象。

_Placement
对应执行 _Func 参数所表示任务的位置的引用。

_Task_handle
正在计划的工作的句柄。请注意，调用方对此对象的生存期负责。在此 task_group 对象上调用 wait 或 run_and_wait 方法之前，运行时将继续期望它保持运行状态。

备注

运行时将提供的工作函数安排至稍后运行，该函数可以在调用函数返回后运行。此方法使用 task_handle 对象来保存所提供的工作函数的副本。因此，传递给此方法的函数对象中发生的任何状态更改都不会出现在该函数对象的副本中。此外，请确保通过指针传递或通过引用工作函数传递的任何对象的生存期在工作函数返回之前保持有效。

如果 task_group 因异常堆栈展开而析构，则无需保证已调用 wait 或 run_and_wait 方法。在这种情况下，析构函数将相应地取消并等待 _Task_handle 参数表示的任务完成。

如果 _Task_handle 参数给出的任务句柄已通过 run 方法计划到任务组对象，并且尚未对该任务组上的 wait 或 run_and_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
);

参数

_Function
将调用以执行任务主体的函数对象的类型。

_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 方法。

另请参阅

并发命名空间
 structured_task_group 类
 task_handle 类