structured_task_group (Clase)

La clase structured_task_group representa una colección muy estructurada de trabajos paralelos. Puede poner en cola tareas individuales paralelas a structured_task_group mediante objetos task_handle, y esperar a que se completen, o cancelar el grupo de tareas antes de que haya finalizado su ejecución, que anulará cualquier tarea cuya ejecución no haya comenzado.

Sintaxis

class structured_task_group;

Miembros

Constructores públicos

Nombre	Descripción
grupo_de_tareas_estructurado	Sobrecargado Construye un nuevo objeto structured_task_group.
Destructor de ~structured_task_group	Destruye un objeto structured_task_group . Se espera que llame al método wait o run_and_wait en el objeto antes de que se ejecute el destructor, a menos que el destructor se ejecute como resultado del desenredo de la pila debido a una excepción.

Métodos públicos

Nombre	Descripción
cancel	Intenta cancelar el subárbol de tareas cuyo origen está en este grupo de tareas. Cada tarea programada en el grupo de tareas se cancelará de forma transitiva si es posible.
está_cancelando	Informa al autor de la llamada si el grupo de tareas está actualmente en medio de una cancelación. Esto no indica necesariamente que el método cancel haya sido llamado en el objeto structured_task_group (aunque esta circunstancia ciertamente califica al método para que devuelva true). Es posible que el objeto structured_task_group se esté ejecutando en línea y se haya cancelado un grupo de tareas más adelante en el árbol de trabajo. En casos como estos, donde el tiempo de ejecución puede determinar con antelación que la cancelación fluirá a través de este objeto structured_task_group, true también se devolverá.
run	Sobrecargado Programa una tarea en el objeto structured_task_group. El llamador administra la duración del objeto task_handle pasado en el parámetro _Task_handle. La versión que toma el parámetro _Placement hace que la tarea esté sesgada hacia la ejecución en la ubicación especificada por ese parámetro.
run_and_wait	Sobrecargado Programa una tarea que se va a ejecutar directamente en el contexto de llamada con la ayuda del objeto structured_task_group para soporte completo de cancelación. Si un objeto task_handle se pasa como parámetro a run_and_wait, el autor de la llamada es responsable de administrar la duración del objeto task_handle. A continuación, la función espera hasta que todo el trabajo en el objeto structured_task_group se haya completado o se haya cancelado.
wait	Espera hasta que todo el trabajo en structured_task_group se haya completado o cancelado.

Comentarios

Hay una serie de restricciones graves que se aplican al uso de un objeto structured_task_group para obtener rendimiento:

• Varios subprocesos no pueden usar un solo objeto structured_task_group. El subproceso que creó el objeto debe realizar todas las operaciones de un objeto structured_task_group. Las dos excepciones a esta regla son las funciones miembro cancel y is_canceling. Es posible que el objeto no esté en la lista de capturas de una expresión lambda y se use dentro de una tarea, a menos que la tarea use una de las operaciones de cancelación.

• Todas las tareas programadas para un objeto structured_task_group se programan mediante el uso de objetos task_handle de los que debe administrar explícitamente la duración.

• Solo se pueden utilizar varios grupos en un orden estrictamente anidado. Si se declaran dos objetos structured_task_group, el segundo que se declara (el interno) debe destruirse antes de que se llame a cualquier método excepto cancel o is_canceling en el primero (el externo). Esta condición se cumple tanto en el caso de simplemente declarar varios objetos structured_task_group dentro de los mismos alcances o de manera funcionalmente anidada, como en el caso de una tarea que se puso en cola a través de structured_task_group mediante los métodos run o run_and_wait.

• A diferencia de la clase general task_group, todos los estados de la clase structured_task_group son finales. Después de poner en cola las tareas en el grupo y esperar a que se completen, es posible que no vuelva a usar el mismo grupo.

Para obtener más información, consulte Paralelismo de tareas.

Jerarquía de herencia

structured_task_group

Requisitos

Encabezado: ppl.h

Espacio de nombres: simultaneidad

cancelar

Intenta cancelar el subárbol de tareas cuyo origen está en este grupo de tareas. Cada tarea programada en el grupo de tareas se cancelará de forma transitiva si es posible.

void cancel();

Comentarios

Para obtener más información, consulte Cancelación.

está_cancelando

Informa al autor de la llamada si el grupo de tareas está actualmente en medio de una cancelación. Esto no indica necesariamente que el método cancel haya sido llamado en el objeto structured_task_group (aunque esta circunstancia ciertamente califica al método para que devuelva true). Es posible que el objeto structured_task_group se esté ejecutando en línea y se haya cancelado un grupo de tareas más adelante en el árbol de trabajo. En casos como estos, donde el tiempo de ejecución puede determinar con antelación que la cancelación fluirá a través de este objeto structured_task_group, true también se devolverá.

bool is_canceling();

Valor devuelto

Indicación de si el objeto structured_task_group está en medio de una cancelación (o se garantiza que lo estará en breve).

Comentarios

Para obtener más información, consulte Cancelación.

ejecutar

Programa una tarea en el objeto structured_task_group. El llamador administra la duración del objeto task_handle pasado en el parámetro _Task_handle. La versión que toma el parámetro _Placement hace que la tarea esté sesgada hacia la ejecución en la ubicación especificada por ese parámetro.

template<class _Function>
void run(
    task_handle<_Function>& _Task_handle);

template<class _Function>
void run(
    task_handle<_Function>& _Task_handle,
    location& _Placement);

Parámetros

_Function
Tipo del objeto de función que se invocará para ejecutar el cuerpo de un gestor de tareas.

_Task_handle
Una referencia al trabajo que se está programar. Tenga en cuenta que el llamante tiene la responsabilidad del ciclo de vida de este objeto. El tiempo de ejecución seguirá esperando que esté activo hasta que se haya llamado al método wait o run_and_wait en este objeto structured_task_group.

_Colocación
Referencia a la ubicación donde se debe ejecutar la tarea representada por el parámetro _Task_handle.

Comentarios

El entorno de ejecución crea una copia de la función de trabajo que pasa a este método. Los cambios de estado que se produzcan en un objeto de función que pase a este método no aparecerán en la copia de ese objeto de función.

Si el structured_task_group se destruye como resultado del desenrollado de la pila de una excepción, no es necesario garantizar que se haya realizado una llamada al método wait o run_and_wait. En este caso, el destructor cancelará correctamente y esperará a que se complete la tarea representada por el parámetro _Task_handle.

Produce una excepción invalid_multiple_scheduling si el manipulador de tareas proporcionado por el parámetro _Task_handle ya se ha programado en un objeto de grupo de tareas a través del método run y no ha habido ninguna llamada de intervención al método wait o run_and_wait en ese grupo de tareas.

ejecutar_y_esperar

Programa una tarea que se va a ejecutar directamente en el contexto de llamada con la ayuda del objeto structured_task_group para soporte completo de cancelación. Si un objeto task_handle se pasa como parámetro a run_and_wait, el autor de la llamada es responsable de administrar la duración del objeto task_handle. A continuación, la función espera hasta que todo el trabajo en el objeto structured_task_group se haya completado o se haya cancelado.

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ámetros

_Function
Tipo del objeto de función que se invocará para ejecutar la tarea.

_Task_handle
Un identificador para la tarea que se ejecutará en línea en el contexto de llamada. Tenga en cuenta que el llamante tiene la responsabilidad del ciclo de vida de este objeto. El tiempo de ejecución seguirá activo hasta que el método run_and_wait finalice la ejecución.

_Func
Una función que se llamará para invocar el contenido del trabajo. Puede ser una expresión lambda u otro objeto que admita una versión del operador de llamada de función con la firma void operator()().

Valor devuelto

Indicación de si se cumplió la espera o se canceló el grupo de tareas debido a una operación de cancelación explícita o a una excepción lanzada desde una de sus tareas. Para obtener más información, consulte task_group_status

Comentarios

Tenga en cuenta que una o varias tareas programadas para este objeto structured_task_group pueden ejecutarse en línea en el contexto de llamada.

Si una o varias de las tareas programadas para este objeto structured_task_group producen una excepción, el tiempo de ejecución seleccionará una excepción de su elección y la propagará fuera de la llamada al método run_and_wait.

Una vez que se devuelve esta función, el objeto structured_task_group se considera en un estado final y no debe usarse. Tenga en cuenta que el uso después de que el método run_and_wait devuelva dará como resultado un comportamiento indefinido.

En el camino de ejecución no excepcional, debe llamar a este método o al método wait antes de que se ejecute el destructor de structured_task_group.

grupo_de_tareas_estructurado

Construye un nuevo objeto structured_task_group.

structured_task_group();

structured_task_group(cancellation_token _CancellationToken);

Parámetros

_CancellationToken
Token de cancelación que se va a asociar a este grupo estructurado de tareas. El grupo de tareas estructurado se cancelará cuando se cancele el token.

Comentarios

El constructor que toma un token de cancelación crea un objeto structured_task_group que se cancelará cuando se cancele el origen asociado al token. Proporcionar un token de cancelación explícito también aísla a este grupo de tareas estructurado de participar en una cancelación implícita desencadenada por un grupo primario con un token diferente o sin token.

grupo_de_tarea_estructurado

Destruye un objeto structured_task_group . Se espera que llame al método wait o run_and_wait en el objeto antes de que se ejecute el destructor, a menos que el destructor se ejecute como resultado del desenredo de la pila debido a una excepción.

~structured_task_group();

Comentarios

Si el destructor se ejecuta como resultado de la ejecución normal (por ejemplo, no se desenreda la pila debido a una excepción) y no se ha llamado a los métodos wait ni run_and_wait, el destructor puede producir una excepción missing_wait.

esperar

Espera hasta que todo el trabajo en structured_task_group se haya completado o cancelado.

task_group_status wait();

Valor devuelto

Indicación de si se cumplió la espera o se canceló el grupo de tareas debido a una operación de cancelación explícita o a una excepción que se lanza desde una de sus tareas. Para obtener más información, consulte task_group_status

Comentarios

Tenga en cuenta que una o varias de las tareas programadas para este objeto structured_task_group se pueden ejecutar de manera directa en el contexto de llamada.

Si una o varias de las tareas programadas para este objeto structured_task_group producen una excepción, el tiempo de ejecución seleccionará una excepción de su elección y la propagará fuera de la llamada al método wait.

Una vez que se devuelve esta función, el objeto structured_task_group se considera en un estado final y no debe usarse. Tenga en cuenta que el uso después de que el método wait devuelva dará como resultado un comportamiento indefinido.

En la ruta de ejecución normal, tiene la obligación de llamar a este método o al método run_and_wait antes de que se ejecute el destructor de structured_task_group.

Consulte también

espacio de nombres de concurrencia
task_group Clase
task_handle clase