Класс structured_task_group

Класс structured_task_group представляет коллекцию параллельной работы со сложной структурой. Можно поместить в очередь structured_task_group отдельные параллельные задачи с помощью объектов task_handle и ожидать их выполнения или отменить группу задач до завершения выполнения, что приведет к отмене всех задач, которые не начали выполнение.

Синтаксис

class structured_task_group;

Участники

Открытые конструкторы

Имя	Описание
Structured_task_group	Перегружен. Создает новый объект structured_task_group.
Деструктор ~structured_task_group	Уничтожает объект structured_task_group . Ожидается, что перед выполнением деструктора вызовет либо waitrun_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. Объект может не находиться в списке захвата лямбда-выражения и использоваться в задаче, если задача не использует одну из операций отмены.

• Все задачи, запланированные для structured_task_group объекта, планируются с помощью task_handle объектов, которые необходимо явно управлять временем существования.

• Несколько групп могут использоваться только в абсолютно вложенном порядке. Если объявляются два structured_task_group объекта, второй объявленный (внутренний) должен быть деструктор перед любым методом, кроме cancel того, или is_canceling вызывается на первом (внешнем). Это условие имеет значение true как в случае простого объявления нескольких structured_task_group объектов в одном или функционально вложенных область, так и в случае задачи, которая была помещена в structured_task_group очередь через run методы или run_and_wait методы.

• В отличие от общего task_group класса, все состояния в structured_task_group классе являются окончательными. После помещения задач в очередь группы и ожидания их завершения невозможно использовать ту же группу снова.

Дополнительные сведения см. в разделе "Параллелизм задач".

Иерархия наследования

structured_task_group

Требования

Заголовок: ppl.h

Пространство имен: concurrency

Отмена

Делает лучшие усилия, чтобы отменить вложенный дерево работы, корневой в этой группе задач. Каждая задача, запланированная в группе задач, будет отменена транзитивно, если это возможно.

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
Дескриптор запланированной работы. Обратите внимание, что вызывающий объект несет ответственность за время существования этого объекта. Среда выполнения будет продолжать ожидать, что она будет жить до waitrun_and_wait вызова метода или объекта structured_task_group .

_Размещения
Ссылка на расположение, в котором должна выполняться задача, представленная параметром _Task_handle.

Замечания

Среда выполнения создает копию рабочей функции, передаваемой этому методу. Любые изменения состояния, происходящие в объекте функции, передаваемом этому методу, не будут отображаться в копии этого объекта функции.

structured_task_group Если деструкция в результате очистки стека от исключения не требуется гарантировать, что вызов был выполнен в любой wait из методов.run_and_wait В этом случае деструктор будет соответствующим образом отменять и ожидать завершения задачи, представленной параметром _Task_handle .

Вызывает исключение invalid_multiple_scheduling, если дескриптор задачи, предоставленный _Task_handle параметром, уже был запланирован на объект группы задач с помощью run метода, и не было интервенного вызова waitrun_and_wait либо метода в этой группе задач.

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
Функция, которая будет вызываться для вызова текста работы. Это может быть лямбда-объект или другой объект, поддерживающий версию оператора вызова функции с подписью void operator()().

Возвращаемое значение

Указание того, была ли выполнена ожидание или группа задач была отменена, из-за явной операции отмены или исключения, вызываемого из одной из своих задач. Дополнительные сведения см. в task_group_status

Замечания

Обратите внимание, что одна или несколько задач, запланированных для этого structured_task_group объекта, могут выполняться встроенным образом в контексте вызова.

Если одна или несколько задач, запланированных для этого structured_task_group объекта, создает исключение, среда выполнения выберет одно из таких исключений выбора и распространяет его из вызова run_and_wait метода.

После возврата этой функции объект structured_task_group находится в конечном состоянии и не должен использоваться. Обратите внимание, что использование после возврата метода приведет к неопределенному run_and_wait поведению.

В неисключающем пути выполнения у вас есть мандат на вызов этого метода или wait метода перед деструктором structured_task_group выполнения.

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 . Ожидается, что перед выполнением деструктора вызовет либо waitrun_and_wait метод или метод, если деструктор не выполняется в результате очистки стека из-за исключения.

~structured_task_group();

Замечания

Если деструктор выполняется в результате нормального выполнения (например, не очистка стека из-за исключения), а ни waitrun_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 поведению.

В неисключающем пути выполнения у вас есть мандат на вызов этого метода или run_and_wait метода перед деструктором structured_task_group выполнения.

См. также

Пространство имен concurrency
Класс task_group
Класс task_handle