Класс structured_task_group

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

Синтаксис

class 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 также будет возвращена.
запустить	Перегружен. Планирует задачу в объекте 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

Пространство имен: конкурентность

Отмена

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

void cancel();

Замечания

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

отменяется

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

bool is_canceling();

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

Указание того, находится ли structured_task_group объект в процессе отмены (или в любом случае будет вскоре).

Замечания

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

запускать

Планирует задачу в объекте 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 или run_and_wait на этом объекте structured_task_group.

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

Замечания

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

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

Вызывает исключение invalid_multiple_scheduling, если дескриптор задачи, который предоставлен _Task_handle параметром, уже был запланирован на объект группы задач с помощью метода run, и где не было промежуточного вызова ни для метода wait, ни для метода run_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(cancellation_token _CancellationToken);

Параметры

_CancellationToken
Токен отмены, который нужно ассоциировать с этой структурированной группой задач. Структурированная группа задач будет отменена, когда токен будет отменен.

Замечания

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

структурированная группа задач

Уничтожает объект structured_task_group . Перед выполнением деструктора ожидается, что вы вызовете либо метод wait, либо run_and_wait, если только деструктор не выполняется в результате очистки стека из-за исключения.

~structured_task_group();

Замечания

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

См. также

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