structured_task_group 类

项目
10/17/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	通知调用方任务组当前是否正在取消。这并不一定表示在 `structured_task_group` 对象上调用了 `cancel` 方法（尽管这样肯定使此方法返回 `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` 对象上的所有工作都已完成或已取消。
wait	等到 `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 之外的任何方法之前销毁。此条件适用于在相同范围或功能嵌套范围内简单地声明多个 structured_task_group 对象的情况，以及通过 run 或 run_and_wait 方法排队到 structured_task_group 的任务的情况。
与常规 task_group 类不同，structured_task_group 类中的所有状态都是最终状态。已将任务排队到组并等待它们完成后，你可能不会再次使用同一个组。

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

继承层次结构

structured_task_group

要求

标头：ppl.h

命名空间： 并发

cancel

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

void cancel();

注解

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

is_canceling

通知调用方任务组当前是否正在取消。这并不一定表示在 structured_task_group 对象上调用了 cancel 方法（尽管这样肯定使此方法返回 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);

参数

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

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

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

注解

运行时创建传递给此方法的工作函数的副本。传递给此方法的函数对象中发生的任何状态更改都不会出现在该函数对象的副本中。

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

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

参数

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

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