task_group (Clase)task_group Class

La clase task_group representa una colección de trabajo paralelo que es posible esperar o cancelar.The task_group class represents a collection of parallel work which can be waited on or canceled.

SintaxisSyntax

class task_group;

MiembrosMembers

Constructores públicosPublic Constructors

NombreName DescripciónDescription
task_grouptask_group Sobrecargado.Overloaded. Construye un nuevo objeto task_group.Constructs a new task_group object.
~ task_group destructor~task_group Destructor Destruye un objeto task_group .Destroys a task_group object. Se espera llamar al wait run_and_wait método o en el objeto antes de que se ejecute el destructor, a menos que el destructor se esté ejecutando como resultado del desenredado de la pila debido a una excepción.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.

Métodos públicosPublic Methods

NOMBREName DescripciónDescription
cancelcancel Realiza el mejor intento de cancelar el subárbol del trabajo raíz en este grupo de tareas.Makes a best effort attempt to cancel the sub-tree of work rooted at this task group. Cada tarea programada en el grupo de tareas se cancelará de manera transitiva si es posible.Every task scheduled on the task group will get canceled transitively if possible.
is_cancelingis_canceling Informa al llamador de si el grupo de tareas está actualmente en medio de una cancelación.Informs the caller whether or not the task group is currently in the midst of a cancellation. Esto no indica necesariamente que cancel se llamara al método en el task_group objeto (aunque ciertamente califica este método para que devuelva 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). Es posible que el task_group objeto se esté ejecutando en línea y que se haya cancelado un grupo de tareas en el árbol de trabajo.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. En casos como estos en los que el tiempo de ejecución puede determinar con anterioridad el tiempo que pasará la cancelación a través de este task_group objeto, también se true devolverá.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.
realizarrun Sobrecargado.Overloaded. Programa una tarea en el task_group objeto.Schedules a task on the task_group object. Si un task_handle objeto se pasa como un parámetro a run , el llamador es responsable de administrar la duración del task_handle objeto.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. La versión del método que toma una referencia a un objeto de función como parámetro implica la asignación del montón dentro del tiempo de ejecución que puede ser menor que el uso de la versión que toma una referencia a un task_handle objeto.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. La versión que toma el parámetro _Placement hace que la tarea se desvíe hacia la ejecución en la ubicación especificada por ese parámetro.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 Sobrecargado.Overloaded. Programa una tarea para que se ejecute en línea en el contexto de llamada con la ayuda del task_group objeto para la compatibilidad con la cancelación completa.Schedules a task to be run inline on the calling context with the assistance of the task_group object for full cancellation support. A continuación, la función espera hasta que todo el trabajo del task_group objeto se haya completado o cancelado.The function then waits until all work on the task_group object has either completed or been canceled. Si un task_handle objeto se pasa como un parámetro a run_and_wait , el llamador es responsable de administrar la duración del task_handle objeto.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.
currirwait Espera hasta que todo el trabajo del task_group objeto se haya completado o cancelado.Waits until all work on the task_group object has either completed or been canceled.

ObservacionesRemarks

A diferencia de la clase muy restringida structured_task_group , la task_group clase es una construcción mucho más general.Unlike the heavily restricted structured_task_group class, the task_group class is much more general construct. No tiene ninguna de las restricciones descritas en structured_task_group.It does not have any of the restrictions described by structured_task_group. task_grouplos objetos se pueden usar de forma segura en todos los subprocesos y usarse de forma libre.task_group objects may safely be used across threads and utilized in free-form ways. La desventaja de la task_group construcción es que puede que no sea así como la structured_task_group construcción de tareas que realizan pequeñas cantidades de trabajo.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.

Para obtener más información, consulte paralelismo de tareas.For more information, see Task Parallelism.

Jerarquía de herenciaInheritance Hierarchy

task_group

RequisitosRequirements

Encabezado: PPL. hHeader: ppl.h

Espacio de nombres: simultaneidadNamespace: concurrency

Cancelarcancel

Realiza el mejor intento de cancelar el subárbol del trabajo raíz en este grupo de tareas.Makes a best effort attempt to cancel the sub-tree of work rooted at this task group. Cada tarea programada en el grupo de tareas se cancelará de manera transitiva si es posible.Every task scheduled on the task group will get canceled transitively if possible.

void cancel();

ObservacionesRemarks

Para obtener más información, consulte cancelación.For more information, see Cancellation.

is_cancelingis_canceling

Informa al llamador de si el grupo de tareas está actualmente en medio de una cancelación.Informs the caller whether or not the task group is currently in the midst of a cancellation. Esto no indica necesariamente que cancel se llamara al método en el task_group objeto (aunque ciertamente califica este método para que devuelva 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). Es posible que el task_group objeto se esté ejecutando en línea y que se haya cancelado un grupo de tareas en el árbol de trabajo.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. En casos como estos en los que el tiempo de ejecución puede determinar con anterioridad el tiempo que pasará la cancelación a través de este task_group objeto, también se true devolverá.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();

Valor devueltoReturn Value

Una indicación de si el task_group objeto está en medio de una cancelación (o se garantiza que esté en breve).An indication of whether the task_group object is in the midst of a cancellation (or is guaranteed to be shortly).

ObservacionesRemarks

Para obtener más información, consulte cancelación.For more information, see Cancellation.

realizarrun

Programa una tarea en el task_group objeto.Schedules a task on the task_group object. Si un task_handle objeto se pasa como un parámetro a run , el llamador es responsable de administrar la duración del task_handle objeto.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. La versión del método que toma una referencia a un objeto de función como parámetro implica la asignación del montón dentro del tiempo de ejecución que puede ser menor que el uso de la versión que toma una referencia a un task_handle objeto.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. La versión que toma el parámetro _Placement hace que la tarea se desvíe hacia la ejecución en la ubicación especificada por ese parámetro.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
);

ParámetrosParameters

_Function_Function
Tipo del objeto de función que se invocará para ejecutar el cuerpo del identificador de la tarea.The type of the function object that will be invoked to execute the body of the task handle.

_Func_Func
Función a la que se llamará para invocar el cuerpo de la tarea.A function which will be called to invoke the body of the task. Puede ser una expresión lambda u otro objeto que admita una versión del operador de llamada de función con la signatura 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
Referencia a la ubicación donde debe ejecutarse la tarea representada por el _Func parámetro.A reference to the location where the task represented by the _Func parameter should execute.

_Task_handle_Task_handle
Identificador del trabajo que se va a programar.A handle to the work being scheduled. Tenga en cuenta que el autor de la llamada tiene la responsabilidad de la duración de este objeto.Note that the caller has responsibility for the lifetime of this object. El tiempo de ejecución continuará esperando que esté activo hasta que se haya wait run_and_wait llamado al método o en este task_group objeto.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.

ObservacionesRemarks

El motor en tiempo de ejecución programa la función de trabajo proporcionada para que se ejecute en un momento posterior, que puede ser después de que la función de llamada vuelva.The runtime schedules the provided work function to run at a later time, which can be after the calling function returns. Este método usa un objeto task_handle para contener una copia de la función de trabajo proporcionada.This method uses a task_handle object to hold a copy of the provided work function. Por lo tanto, los cambios de estado que se producen en un objeto de función que se pasa a este método no aparecerán en la copia de ese objeto de función.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. Además, asegúrese de que la duración de los objetos que pase por puntero o por referencia a la función de trabajo siga siendo válida hasta que se devuelva la función de trabajo.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.

Si el se task_group destruye como resultado del desenredado de la pila de una excepción, no es necesario garantizar que se ha realizado una llamada al wait run_and_wait método o.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. En este caso, el destructor se cancelará correctamente y se esperará a que se complete la tarea representada por el _Task_handle parámetro.In this case, the destructor will appropriately cancel and wait for the task represented by the _Task_handle parameter to complete.

El método produce una excepción invalid_multiple_scheduling si el identificador de tarea proporcionado por el _Task_handle parámetro ya se ha programado en un objeto de grupo de tareas a través del run método y no hay ninguna llamada intermedia al wait método o run_and_wait en ese grupo de tareas.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

Programa una tarea para que se ejecute en línea en el contexto de llamada con la ayuda del task_group objeto para la compatibilidad con la cancelación completa.Schedules a task to be run inline on the calling context with the assistance of the task_group object for full cancellation support. A continuación, la función espera hasta que todo el trabajo del task_group objeto se haya completado o cancelado.The function then waits until all work on the task_group object has either completed or been canceled. Si un task_handle objeto se pasa como un parámetro a run_and_wait , el llamador es responsable de administrar la duración del task_handle objeto.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
);

ParámetrosParameters

_Function_Function
Tipo del objeto de función que se invocará para ejecutar el cuerpo de la tarea.The type of the function object that will be invoked to execute the body of the task.

_Task_handle_Task_handle
Identificador de la tarea que se ejecutará insertada en el contexto de la llamada.A handle to the task which will be run inline on the calling context. Tenga en cuenta que el autor de la llamada tiene la responsabilidad de la duración de este objeto.Note that the caller has responsibility for the lifetime of this object. El motor en tiempo de ejecución seguirá esperando que esté activo hasta que run_and_wait finalice la ejecución del método.The runtime will continue to expect it to live until the run_and_wait method finishes execution.

_Func_Func
Función a la que se llamará para invocar el cuerpo del trabajo.A function which will be called to invoke the body of the work. Puede ser una expresión lambda u otro objeto que admita una versión del operador de llamada de función con la signatura 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()().

Valor devueltoReturn Value

Indica si se ha satisfecho la espera o si se ha cancelado el grupo de tareas, debido a una operación de cancelación explícita o a que se ha producido una excepción desde una de sus tareas.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. Para obtener más información, vea task_group_status.For more information, see task_group_status.

ObservacionesRemarks

Tenga en cuenta que una o varias de las tareas programadas para este task_group objeto pueden ejecutarse en línea en el contexto de llamada.Note that one or more of the tasks scheduled to this task_group object may execute inline on the calling context.

Si una o varias de las tareas programadas para este task_group objeto producen una excepción, el tiempo de ejecución seleccionará una de estas excepciones de su elección y la propagará fuera de la llamada al run_and_wait método.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.

Al volver del run_and_wait método en un task_group objeto, el runtime restablece el objeto a un estado limpio en el que se puede volver a usar.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. Esto incluye el caso en el que task_group se canceló el objeto.This includes the case where the task_group object was canceled.

En la ruta de acceso no excepcional de la ejecución, tiene un mandato para llamar a este método o al método antes de que se wait ejecute el destructor de 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

Construye un nuevo objeto task_group.Constructs a new task_group object.

task_group();

task_group(
   cancellation_token _CancellationToken
);

ParámetrosParameters

_CancellationToken_CancellationToken
Token de cancelación que se va a asociar a este grupo de tareas.A cancellation token to associate with this task group. El grupo de tareas se cancelará cuando se cancele el token.The task group will be canceled when the token is canceled.

ObservacionesRemarks

El constructor que toma un token de cancelación crea un objeto task_group que se cancelará cuando se cancele el origen asociado al token.The constructor that takes a cancellation token creates a task_group that will be canceled when the source associated with the token is canceled. Proporcionar un token de cancelación explícito también aísla este grupo de tareas de participar en una cancelación implícita de un grupo primario con un token diferente o sin token.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

Destruye un objeto task_group .Destroys a task_group object. Se espera llamar al wait run_and_wait método o en el objeto antes de que se ejecute el destructor, a menos que el destructor se esté ejecutando como resultado del desenredado de la pila debido a una excepción.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();

ObservacionesRemarks

Si el destructor se ejecuta como resultado de la ejecución normal (por ejemplo, no desenredado de la pila debido a una excepción) y no se ha llamado a los wait run_and_wait métodos ni, el destructor puede producir una excepción 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.

currirwait

Espera hasta que todo el trabajo del task_group objeto se haya completado o cancelado.Waits until all work on the task_group object has either completed or been canceled.

task_group_status wait();

Valor devueltoReturn Value

Indica si se ha satisfecho la espera o si se ha cancelado el grupo de tareas, debido a una operación de cancelación explícita o a que se ha producido una excepción desde una de sus tareas.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. Para obtener más información, vea task_group_status.For more information, see task_group_status.

ObservacionesRemarks

Tenga en cuenta que una o varias de las tareas programadas para este task_group objeto pueden ejecutarse en línea en el contexto de llamada.Note that one or more of the tasks scheduled to this task_group object may execute inline on the calling context.

Si una o varias de las tareas programadas para este task_group objeto producen una excepción, el tiempo de ejecución seleccionará una de estas excepciones de su elección y la propagará fuera de la llamada al wait método.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.

La llamada a wait en un task_group objeto lo restablece a un estado limpio en el que se puede volver a usar.Calling wait on a task_group object resets it to a clean state where it can be reused. Esto incluye el caso en el que task_group se canceló el objeto.This includes the case where the task_group object was canceled.

En la ruta de acceso no excepcional de la ejecución, tiene un mandato para llamar a este método o al método antes de que se run_and_wait ejecute el destructor de 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.

Consulte tambiénSee also

Espacio de nombres de simultaneidadconcurrency Namespace
structured_task_group (clase)structured_task_group Class
task_handle (clase)task_handle Class