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
structured_task_group	Con sobrecarga. Construye un nuevo objeto structured_task_group.
Destructor ~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	Realiza un mejor intento de cancelar el subárbol del trabajo raíz en este grupo de tareas. Cada tarea programada en el grupo de tareas se cancelará de forma transitiva si es posible.
is_canceling	Informa al autor de la llamada si el grupo de tareas está actualmente en medio de una cancelación. Esto no indica necesariamente que se llamó al método cancel en el objeto structured_task_group (aunque ciertamente califica este método para devolver true). Puede ser el caso de que el objeto structured_task_group se esté ejecutando alineado y se canceló un grupo de tareas mas 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	Con sobrecarga. Programa una tarea en el objeto structured_task_group. El autor de la llamada 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	Con sobrecarga. Programa una tarea que se va a ejecutar alineada en el contexto de llamada con la ayuda del objeto structured_task_group para admitir la cancelación completa. 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 usar varios grupos en orden absolutamente 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 es true en el caso de simplemente declarar varios objetos structured_task_group dentro de los mismos ámbitos anidados o funcionalmente, así como el caso de una tarea que se puso en cola a structured_task_group través de 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

cancel

Realiza un mejor intento de cancelar el subárbol del trabajo raíz 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.

is_canceling

Informa al autor de la llamada si el grupo de tareas está actualmente en medio de una cancelación. Esto no indica necesariamente que se llamó al método cancel en el objeto structured_task_group (aunque ciertamente califica este método para devolver true). Puede ser el caso de que el objeto structured_task_group se esté ejecutando alineado y se canceló un grupo de tareas mas 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.

run

Programa una tarea en el objeto structured_task_group. El autor de la llamada 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 del manipulador de tareas.

_Task_handle
Manipulador del trabajo que se está programando. Tenga en cuenta que el autor de la llamada tiene la responsabilidad de la duración 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.

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

Comentarios

El tiempo de ejecución crea una copia de la función de trabajo que se 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 los structured_task_group se destruyen como resultado del desenredado 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.

run_and_wait

Programa una tarea que se va a ejecutar alineada en el contexto de llamada con la ayuda del objeto structured_task_group para admitir la cancelación completa. 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
El manipulador de la tarea que se ejecutará insertada en el contexto de llamada. Tenga en cuenta que el autor de la llamada tiene la responsabilidad de la duración de este objeto. El tiempo de ejecución seguirá activo hasta que el método run_and_wait finalice la ejecución.

_Func
Función a la que se llamará para invocar el cuerpo 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 que se inicia 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 insertadas dentro del 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 la ruta de acceso 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.

structured_task_group

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 de tareas estructurado. 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 de un grupo primario con un token diferente o sin token.

~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.

~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.

wait

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 inicia 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 insertadas dentro del 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 acceso de ejecución no excepcional, debe 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

concurrency (espacio de nombres)
task_group (clase)
task_handle (clase)