Класс task_grouptask_group Class

Класс task_group представляет коллекцию параллельной работы, для которой возможно ожидание или отмена.The task_group class represents a collection of parallel work which can be waited on or canceled.

СинтаксисSyntax

class task_group;

ЧленыMembers

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

nameName ОписаниеDescription
task_grouptask_group Перегружен.Overloaded. Создает новый объект task_group.Constructs a new task_group object.
Деструктор ~ task_group~task_group Destructor Уничтожает объект task_group .Destroys a task_group object. Ожидается вызов wait run_and_wait метода или для объекта до выполнения деструктора, если только деструктор не выполняется как результат очистки стека из-за исключения.You are expected to call the either the wait or run_and_wait method on the object prior to the destructor executing, unless the destructor is executing as the result of stack unwinding due to an exception.

Открытые методыPublic Methods

nameName ОписаниеDescription
cancelcancel Предпринимает попытку отменить поддерево работы с корнем в этой группе задач.Makes a best effort attempt to cancel the sub-tree of work rooted at this task group. Если возможно, все задачи, запланированные в группе задач, будут отменены транзитивно.Every task scheduled on the task group will get canceled transitively if possible.
is_cancelingis_canceling Информирует вызывающий объект о том, находится ли группа задач в данный момент в процессе отмены.Informs the caller whether or not the task group is currently in the midst of a cancellation. Это не обязательно означает, что cancel метод был вызван для task_group объекта (хотя, безусловно, этот метод должен быть возвращен true ).This does not necessarily indicate that the cancel method was called on the task_group object (although such certainly qualifies this method to return true). Это может быть случай, когда task_group объект выполняется в строке, а группа задач в рабочем дереве была отменена.It may be the case that the task_group object is executing inline and a task group further up in the work tree was canceled. В таких случаях, где среда выполнения может заранее определить, что отмена будет передаваться через этот task_group объект, true также будет возвращена.In cases such as these where the runtime can determine ahead of time that cancellation will flow through this task_group object, true will be returned as well.
запускаrun Перегружен.Overloaded. Планирует задачу для task_group объекта.Schedules a task on the task_group object. Если task_handle объект передается в качестве параметра в run , вызывающий объект отвечает за управление временем существования task_handle объекта.If a task_handle object is passed as a parameter to run, the caller is responsible for managing the lifetime of the task_handle object. Версия метода, которая принимает ссылку на объект функции в качестве параметра, включает выделение кучи внутри среды выполнения, что может выполняться менее эффективно, чем использование версии, которая принимает ссылку на task_handle объект.The version of the method that takes a reference to a function object as a parameter involves heap allocation inside the runtime which may be perform less well than using the version that takes a reference to a task_handle object. Версия, принимающая параметр _Placement, заставляет задачу стремиться к выполнению в расположении, указанном этим параметром.The version which takes the parameter _Placement causes the task to be biased towards executing at the location specified by that parameter.
run_and_waitrun_and_wait Перегружен.Overloaded. Планирует выполнение задачи в вызывающем контексте с помощью task_group объекта для полной поддержки отмены.Schedules a task to be run inline on the calling context with the assistance of the task_group object for full cancellation support. Затем функция ожидает task_group завершения или отмены любой работы над объектом.The function then waits until all work on the task_group object has either completed or been canceled. Если task_handle объект передается в качестве параметра в run_and_wait , вызывающий объект отвечает за управление временем существования task_handle объекта.If a task_handle object is passed as a parameter to run_and_wait, the caller is responsible for managing the lifetime of the task_handle object.
ожиданияwait Ожидает завершения или отмены любой работы над task_group объектом.Waits until all work on the task_group object has either completed or been canceled.

КомментарииRemarks

В отличие от сильно ограниченного structured_task_group класса, task_group класс является гораздо более общей конструкцией.Unlike the heavily restricted structured_task_group class, the task_group class is much more general construct. В нем отсутствуют ограничения, описанные в structured_task_group.It does not have any of the restrictions described by structured_task_group. task_group объекты можно безопасно использовать в потоках и использовать в произвольных направлениях.task_group objects may safely be used across threads and utilized in free-form ways. Недостатком task_group конструкции является то, что она может не выполняться, а также structured_task_group конструкцию для задач, выполняющих небольшие объемы работы.The disadvantage of the task_group construct is that it may not perform as well as the structured_task_group construct for tasks which perform small amounts of work.

Дополнительные сведения см. в разделе параллелизм задач.For more information, see Task Parallelism.

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

task_group

ТребованияRequirements

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

Пространство имен: параллелизмNamespace: concurrency

Отменаcancel

Предпринимает попытку отменить поддерево работы с корнем в этой группе задач.Makes a best effort attempt to cancel the sub-tree of work rooted at this task group. Если возможно, все задачи, запланированные в группе задач, будут отменены транзитивно.Every task scheduled on the task group will get canceled transitively if possible.

void cancel();

КомментарииRemarks

Дополнительные сведения см. в разделе Отмена.For more information, see Cancellation.

is_cancelingis_canceling

Информирует вызывающий объект о том, находится ли группа задач в данный момент в процессе отмены.Informs the caller whether or not the task group is currently in the midst of a cancellation. Это не обязательно означает, что cancel метод был вызван для task_group объекта (хотя, безусловно, этот метод должен быть возвращен true ).This does not necessarily indicate that the cancel method was called on the task_group object (although such certainly qualifies this method to return true). Это может быть случай, когда task_group объект выполняется в строке, а группа задач в рабочем дереве была отменена.It may be the case that the task_group object is executing inline and a task group further up in the work tree was canceled. В таких случаях, где среда выполнения может заранее определить, что отмена будет передаваться через этот task_group объект, true также будет возвращена.In cases such as these where the runtime can determine ahead of time that cancellation will flow through this task_group object, true will be returned as well.

bool is_canceling();

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

Указывает, task_group находится ли объект в процессе отмены (или гарантированно будет вскоре).An indication of whether the task_group object is in the midst of a cancellation (or is guaranteed to be shortly).

КомментарииRemarks

Дополнительные сведения см. в разделе Отмена.For more information, see Cancellation.

запускаrun

Планирует задачу для task_group объекта.Schedules a task on the task_group object. Если task_handle объект передается в качестве параметра в run , вызывающий объект отвечает за управление временем существования task_handle объекта.If a task_handle object is passed as a parameter to run, the caller is responsible for managing the lifetime of the task_handle object. Версия метода, которая принимает ссылку на объект функции в качестве параметра, включает выделение кучи внутри среды выполнения, что может выполняться менее эффективно, чем использование версии, которая принимает ссылку на task_handle объект.The version of the method that takes a reference to a function object as a parameter involves heap allocation inside the runtime which may be perform less well than using the version that takes a reference to a task_handle object. Версия, принимающая параметр _Placement, заставляет задачу стремиться к выполнению в расположении, указанном этим параметром.The version which takes the parameter _Placement causes the task to be biased towards executing at the location specified by that parameter.

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

ПараметрыParameters

_Function_Function
Тип объекта функции, который будет вызываться для выполнения тела маркера задачи.The type of the function object that will be invoked to execute the body of the task handle.

_Func_Func
Функция, которая будет вызываться для вызова текста задачи.A function which will be called to invoke the body of the task. Это может быть лямбда-выражение или другой объект, который поддерживает версию оператора вызова функции с сигнатурой void operator()() .This may be a lambda expression or other object which supports a version of the function call operator with the signature void operator()().

_Placement_Placement
Ссылка на расположение, в котором должна выполняться задача, представленная параметром _Func.A reference to the location where the task represented by the _Func parameter should execute.

_Task_handle_Task_handle
Маркер запланированной работы.A handle to the work being scheduled. Обратите внимание, что вызывающий объект отвечает за время существования этого объекта.Note that the caller has responsibility for the lifetime of this object. Среда выполнения продолжит ожидать, пока для wait run_and_wait этого объекта не будет вызван метод или task_group .The runtime will continue to expect it to live until either the wait or run_and_wait method has been called on this task_group object.

КомментарииRemarks

Среда выполнения планирует выполнение предоставленной рабочей функции позднее, что может быть после возврата вызывающей функции.The runtime schedules the provided work function to run at a later time, which can be after the calling function returns. Этот метод использует объект task_handle для хранения копии предоставленной рабочей функции.This method uses a task_handle object to hold a copy of the provided work function. Таким образом, любые изменения состояния, происходящие в объекте функции, который передается в этот метод, не будут отображаться в копии этого объекта функции.Therefore, any state changes that occur in a function object that you pass to this method will not appear in your copy of that function object. Кроме того, убедитесь, что время существования всех объектов, передаваемых по указателю или по ссылке на рабочую функцию, остается допустимым до тех пор, пока Рабочая функция не вернет значение.In addition, make sure that the lifetime of any objects that you pass by pointer or by reference to the work function remain valid until the work function returns.

Если task_group деструкторы являются результатом очистки стека из-за исключения, нет необходимости гарантировать, что был сделан вызов wait run_and_wait метода или.If the task_group destructs as the result of stack unwinding from an exception, you do not need to guarantee that a call has been made to either the wait or run_and_wait method. В этом случае деструктор будет отменяться соответствующим образом и ожидать завершения задачи, представленной _Task_handle параметром.In this case, the destructor will appropriately cancel and wait for the task represented by the _Task_handle parameter to complete.

Метод вызывает исключение invalid_multiple_scheduling , если обработчик задач, заданный _Task_handle параметром, уже был запланирован в объекте группы задач с помощью run метода, и в данной группе задач не был выполнен промежуточный вызов wait метода или run_and_wait .The method throws an invalid_multiple_scheduling exception if the task handle given by the _Task_handle parameter has already been scheduled onto a task group object via the run method and there has been no intervening call to either the wait or run_and_wait method on that task group.

run_and_waitrun_and_wait

Планирует выполнение задачи в вызывающем контексте с помощью task_group объекта для полной поддержки отмены.Schedules a task to be run inline on the calling context with the assistance of the task_group object for full cancellation support. Затем функция ожидает task_group завершения или отмены любой работы над объектом.The function then waits until all work on the task_group object has either completed or been canceled. Если task_handle объект передается в качестве параметра в run_and_wait , вызывающий объект отвечает за управление временем существования task_handle объекта.If a task_handle object is passed as a parameter to run_and_wait, the caller is responsible for managing the lifetime of the task_handle object.

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

ПараметрыParameters

_Function_Function
Тип объекта функции, который будет вызван для выполнения основной части задачи.The type of the function object that will be invoked to execute the body of the task.

_Task_handle_Task_handle
Обработчик для задачи, который будет выполняться встроенным в контекст вызывающего.A handle to the task which will be run inline on the calling context. Обратите внимание, что вызывающий объект отвечает за время существования этого объекта.Note that the caller has responsibility for the lifetime of this object. Среда выполнения будет продолжать ожидать, пока run_and_wait метод не завершит выполнение.The runtime will continue to expect it to live until the run_and_wait method finishes execution.

_Func_Func
Функция, которая будет вызываться для вызова текста работы.A function which will be called to invoke the body of the work. Это может быть лямбда-выражение или другой объект, который поддерживает версию оператора вызова функции с сигнатурой void operator()() .This may be a lambda expression or other object which supports a version of the function call operator with the signature void operator()().

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

Значение, указывающее, было ли выполнено ожидание или отменена группа задач из-за явной операции отмены или исключения, вызываемого одной из задач.An indication of whether the wait was satisfied or the task group was canceled, due to either an explicit cancel operation or an exception being thrown from one of its tasks. Дополнительные сведения см. в разделе task_group_status.For more information, see task_group_status.

КомментарииRemarks

Обратите внимание, что одна или несколько задач, запланированных на этот task_group объект, могут выполняться встроенным в контекст вызывающего.Note that one or more of the tasks scheduled to this task_group object may execute inline on the calling context.

Если одна или несколько задач, запланированных на этот task_group объект, вызывают исключение, среда выполнения выберет одно из таких исключений и распространит его из вызова run_and_wait метода.If one or more of the tasks scheduled to this task_group object throws an exception, the runtime will select one such exception of its choosing and propagate it out of the call to the run_and_wait method.

При возврате из run_and_wait метода task_group объекта среда выполнения сбрасывает объект в исходное состояние, в котором его можно использовать повторно.Upon return from the run_and_wait method on a task_group object, the runtime resets the object to a clean state where it can be reused. Это включает случай, когда task_group объект был отменен.This includes the case where the task_group object was canceled.

В неисключительном пути выполнения у вас есть требование вызывать этот метод или wait метод перед деструктором task_group выполнения.In the non-exceptional path of execution, you have a mandate to call either this method or the wait method before the destructor of the task_group executes.

task_grouptask_group

Создает новый объект task_group.Constructs a new task_group object.

task_group();

task_group(
   cancellation_token _CancellationToken
);

ПараметрыParameters

_CancellationToken_CancellationToken
Токен отмены для связывания с этой группой задач.A cancellation token to associate with this task group. Группа задач будет отменена, когда будет отменен токен.The task group will be canceled when the token is canceled.

КомментарииRemarks

Конструктор, который принимает токен отмены, создает task_group, которая будет отменена, когда будет отменен источник, связанный с этим токеном.The constructor that takes a cancellation token creates a task_group that will be canceled when the source associated with the token is canceled. Предоставление явного токена отмены также изолирует эту группу задач от участия в неявной отмене из родительской группы с другим токеном или без токена.Providing an explicit cancellation token also isolates this task group from participating in an implicit cancellation from a parent group with a different token or no token.

~ task_group~task_group

Уничтожает объект task_group .Destroys a task_group object. Ожидается вызов wait run_and_wait метода или для объекта до выполнения деструктора, если только деструктор не выполняется как результат очистки стека из-за исключения.You are expected to call the either the wait or run_and_wait method on the object prior to the destructor executing, unless the destructor is executing as the result of stack unwinding due to an exception.

~task_group();

КомментарииRemarks

Если деструктор выполняется как результат обычного выполнения (например, если не используется Очистка стека из-за исключения) и ни один из методов и wait не run_and_wait вызван, деструктор может вызвать исключение missing_wait .If the destructor runs as the result of normal execution (for example, not stack unwinding due to an exception) and neither the wait nor run_and_wait methods have been called, the destructor may throw a missing_wait exception.

ожиданияwait

Ожидает завершения или отмены любой работы над task_group объектом.Waits until all work on the task_group object has either completed or been canceled.

task_group_status wait();

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

Значение, указывающее, было ли выполнено ожидание или отменена группа задач из-за явной операции отмены или исключения, вызываемого одной из задач.An indication of whether the wait was satisfied or the task group was canceled, due to either an explicit cancel operation or an exception being thrown from one of its tasks. Дополнительные сведения см. в разделе task_group_status.For more information, see task_group_status.

КомментарииRemarks

Обратите внимание, что одна или несколько задач, запланированных на этот task_group объект, могут выполняться встроенным в контекст вызывающего.Note that one or more of the tasks scheduled to this task_group object may execute inline on the calling context.

Если одна или несколько задач, запланированных на этот task_group объект, вызывают исключение, среда выполнения выберет одно из таких исключений и распространит его из вызова wait метода.If one or more of the tasks scheduled to this task_group object throws an exception, the runtime will select one such exception of its choosing and propagate it out of the call to the wait method.

Вызов wait для task_group объекта сбрасывает его в исходное состояние, в котором его можно использовать повторно.Calling wait on a task_group object resets it to a clean state where it can be reused. Это включает случай, когда task_group объект был отменен.This includes the case where the task_group object was canceled.

В неисключительном пути выполнения у вас есть требование вызывать этот метод или run_and_wait метод перед деструктором task_group выполнения.In the non-exceptional path of execution, you have a mandate to call either this method or the run_and_wait method before the destructor of the task_group executes.

См. также разделSee also

Пространство имен Concurrencyconcurrency Namespace
Класс structured_task_groupstructured_task_group Class
Класс task_handletask_handle Class