En esta página

Qt TaskTree C++ Classes

Contiene una biblioteca TaskTree de uso general. Más información...

Este módulo se encuentra en fase de vista previa tecnológica y está sujeto a cambios.

Este módulo se introdujo en Qt 6.11.

Espacios de nombres

QtTaskTree

Abarca todas las clases y funciones globales del módulo TaskTree

Clases

QtTaskTree::Do

Un elemento de cuerpo utilizado con las construcciones «For» y «When»

QtTaskTree::Else

Un elemento «else» utilizado en expresiones condicionales

QtTaskTree::ElseIf

Un elemento «else if» utilizado en expresiones condicionales

QtTaskTree::ExecutableItem

Clase base para elementos de tareas ejecutables

QtTaskTree::ExecutionMode

Elemento de grupo que describe el modo de ejecución

QtTaskTree::For

Un elemento de bucle «for»

QtTaskTree::Forever

Bucle infinito de subtareas

QtTaskTree::ForeverIterator

Iterador infinito para utilizar dentro del elemento «for»

QtTaskTree::Group

Representa el elemento básico para componer recetas declarativas que describen cómo ejecutar y gestionar un árbol anidado de tareas asíncronas

QtTaskTree::GroupItem

Representa el elemento básico que puede formar parte de cualquier grupo

QtTaskTree::If

Un elemento «if» utilizado en expresiones condicionales

QtTaskTree::Iterator

Clase base que se utilizará como iterador dentro del elemento «For»

QtTaskTree::ListIterator

Iterador de lista que se utilizará dentro del elemento «For»

QtTaskTree::ObjectSignal

Estructura que describe una subclase de QObject y su señal

QtTaskTree::ParallelLimit

Modo de ejecución paralela con un límite personalizado

QtTaskTree::QBarrier

Una tarea asíncrona que finaliza bajo demanda

QtTaskTree::QCustomTask

Una plantilla de clase utilizada para declarar elementos de tarea personalizados y definir sus controladores de inicio y finalización

QtTaskTree::QDefaultTaskAdapter

Una plantilla de clase que proporciona un adaptador de tareas predeterminado utilizado en QCustomTask

QtTaskTree::QMappedTaskTreeRunner

Un controlador de ejecución de árbol de tareas mapeado con un tipo de clave determinado

QtTaskTree::QNetworkReplyWrapper

Un envoltorio alrededor de QNetworkReply y QNetworkAccessManager

QtTaskTree::QParallelTaskTreeRunner

Un controlador de ejecución de árbol de tareas paralelo

QtTaskTree::QProcessTaskDeleter

Un eliminador personalizado para QProcess, utilizado por QProcessTask

QtTaskTree::QSequentialTaskTreeRunner

Un controlador de ejecución de árboles de tareas secuencial

QtTaskTree::QSingleTaskTreeRunner

Un controlador de ejecución de un único árbol de tareas

QtTaskTree::QStartedBarrier

Un QBarrier iniciado con un límite determinado

QtTaskTree::QSyncTask

Ejecuta de forma sincrónica un controlador personalizado entre otras tareas

QtTaskTree::QTaskInterface

Clase auxiliar que se utiliza al adaptar la interfaz de una tarea personalizada

QtTaskTree::QTaskTree

Ejecuta el árbol de tareas asíncronas definidas de forma declarativa

QtTaskTree::QTcpSocketWrapper

Un envoltorio para QTcpSocket

QtTaskTree::QThreadFunction

Una plantilla de clase que controla la ejecución de una función en un hilo independiente mediante QtConcurrent::run()

QtTaskTree::QThreadFunctionBase

Una clase base para la plantilla de clase QThreadFunction

QtTaskTree::RepeatIterator

Iterador repetitivo para su uso dentro del elemento «For»

QtTaskTree::Storage

Una plantilla de clase para el intercambio de datos personalizado en el árbol de tareas en ejecución

QtTaskTree::Then

Un elemento «then» utilizado en expresiones condicionales

QtTaskTree::UntilIterator

Iterador condicional para su uso dentro del elemento «For»

QtTaskTree::When

Un elemento que retrasa la ejecución de un cuerpo hasta que se supere una barrera

Descripción detallada

Utiliza la biblioteca TaskTree para crear recetas que describan qué tareas asíncronas deben ejecutarse y utiliza estas recetas dentro de QTaskTree para ejecutarlas.

Las recetas son descripciones declarativas sobre qué tipos de tareas deben crearse y ejecutarse, por ejemplo: QProcess, QNetworkReplyWrapper o QThreadFunction<ReturnType>, o si deben ejecutarse en secuencia o en paralelo. Dentro de las recetas se pueden definir diferentes rutas de continuación dependiendo de si la tarea anterior finalizó con éxito o con un error. También es posible anidar tareas en elementos « Group », y cada « Group » puede ejecutar sus tareas de acuerdo con su propio modo de ejecución o política de flujo de trabajo. Las recetas forman las estructuras de árbol de tareas.

Tareas asíncronas

Una tarea asíncrona es cualquier tarea que se puede iniciar y que, posteriormente, finaliza con éxito o con un error. «Posteriormente» significa que, tras iniciar la tarea, el control vuelve al bucle de eventos en ejecución. No bloqueamos el hilo que realiza la llamada hasta que la tarea haya finalizado. Para utilizar el árbol de tareas, necesitamos que haya un bucle de eventos en funcionamiento.

Ejemplos de tareas asíncronas:

Árbol de recetas y tareas

Para entender mejor qué son la receta y el árbol de tareas, utilicemos la analogía del cartucho y el reproductor. Cuando escribimos una receta, es como si estuviéramos creando un cartucho, así que simplemente preparamos una descripción detallada de lo que el reproductor debe hacer más adelante, cuando el cartucho se inserte en el reproductor (árbol de tareas) y se inicie. La receta en sí misma es solo una descripción declarativa para el árbol de tareas sobre lo que este debe hacer cuando la receta se le pasa al árbol de tareas y este se inicia. La receta por sí sola no hace nada sin un árbol de tareas: es como un cartucho sin reproductor.

A continuación, se ofrece un breve resumen sobre las responsabilidades de la receta y el árbol de tareas.

La receta (cartucho) describe:

  • qué tareas debe crear dinámicamente el árbol de tareas en ejecución (a través de QCustomTask)
  • en qué orden
  • qué estructuras de datos debe crear dinámicamente el árbol de tareas en ejecución (a través de Storage)
  • cómo configurar cada tarea antes de su inicio
  • cómo recopilar datos cuando las tareas hayan finalizado
  • modo de ejecución (las tareas deben ejecutarse en secuencia o en paralelo)
  • política de flujo de trabajo

Árbol de tareas (reproductor):

  • lee la receta y crea tareas y estructuras de datos automáticamente
  • gestiona el ciclo de vida de las tareas y estructuras de datos creadas
  • ejecuta continuaciones
  • elige diferentes rutas en función de los resultados de las tareas finalizadas y de las políticas del flujo de trabajo
  • proporciona información básica sobre el progreso

Tareas personalizadas

Dado que la receta es una descripción para el árbol de tareas sobre qué tareas debe crear al iniciarse dicho árbol, no podemos crear estas tareas directamente dentro de una receta. En su lugar, necesitamos una forma declarativa de indicar al árbol de tareas que cree e inicie estas tareas por nosotros en un momento posterior. Por ejemplo, si queremos que el árbol de tareas cree e inicie « QProcess », lo describimos colocando un elemento « QProcessTask » dentro de una receta. « QProcessTask » es un alias de « QCustomTask » <QProcess>. Cada tipo de tarea debe proporcionar su correspondiente « QCustomTask » <Type> para que pueda utilizarse dentro de las recetas.

La siguiente tabla muestra algunas tareas personalizadas integradas listas para ser incluidas en recetas:

Tarea personalizada (utilizada en recetas)Clase de tarea (creada por el árbol de tareas en ejecución)Breve descripción
QProcessTaskQProcessInicia el proceso.
QThreadFunctionTask<ReturnType>QThreadFunction<ReturnType>Inicia una tarea asíncrona, que se ejecuta en un hilo independiente.
QTaskTreeTaskQTaskTreeInicia un árbol de tareas anidadas.
QNetworkReplyWrapperTaskQNetworkReplyWrapperInicia una descarga de red.
QTcpSocketWrapperTaskQTcpSocketWrapperInicia una conexión TCP.

Consulta QTaskInterface y Task Adapters para obtener más información sobre cómo adaptar una tarea concreta para su uso en recetas.

Ejemplo de receta

El archivo QTaskTree contiene un elemento de nivel superior Group, también conocido como «receta», que puede contener cualquier número de tareas de diversos tipos, tales como QProcessTask, QNetworkReplyWrapperTask o QThreadFunctionTask<ReturnType>:

const Group recipe {
    QProcessTask(...),
    QNetworkReplyWrapperTask(...),
    QThreadFunctionTask<int>(...)
};

QTaskTree *taskTree = new QTaskTree(recipe);
connect(taskTree, &QTaskTree::done, ...);  // finish handler
taskTree->start();

La receta anterior consta de un elemento de nivel superior del tipo Group que contiene tareas de los tipos QProcessTask, QNetworkReplyWrapperTask y QThreadFunctionTask<int>. Tras la llamada a taskTree->start(), las tareas se crean y se ejecutan en cadena, comenzando por QProcess. Cuando la tarea QProcess finaliza con éxito, se inicia la tarea QNetworkReplyWrapper. Por último, cuando la tarea de red finaliza con éxito, se inicia la tarea QThreadFunction<int>.

Cuando la última tarea en ejecución finaliza con éxito, se considera que el árbol de tareas se ha ejecutado correctamente y se emite la señal QTaskTree::done() con DoneWith::Success. Cuando una tarea finaliza con un error, se detiene la ejecución del árbol de tareas y se omiten las tareas restantes. El árbol de tareas finaliza con un error y envía la señal QTaskTree::done() con DoneWith::Error.

Grupos

El padre de Group lo considera una única tarea. Al igual que otras tareas, el grupo se puede iniciar y puede finalizar con éxito o con un error. Los elementos Group se pueden anidar para crear una estructura de árbol:

const Group recipe {
    Group {
        parallel,
        QProcessTask(...),
        QThreadFunctionTask<int>(...)
    },
    QNetworkReplyWrapperTask(...)
};

El ejemplo anterior difiere del primero en que el elemento de nivel superior tiene un subgrupo que contiene el QProcessTask y el QThreadFunctionTask<int>. El subgrupo es un elemento hermano del QNetworkReplyWrapperTask en la raíz. El subgrupo contiene un elemento adicional parallel que indica a su Group que ejecute sus tareas en paralelo.

Así pues, cuando el QTaskTree inicia la receta anterior, el QProcess y el QThreadFunction<int> se inician inmediatamente y se ejecutan en paralelo. Dado que el grupo raíz no contiene un elemento parallel, sus tareas hijas directas se ejecutan en secuencia. Por lo tanto, el QNetworkReplyWrapper se inicia cuando todo el subgrupo ha finalizado. Se considera que el grupo ha finalizado cuando todas sus tareas han finalizado. El orden en el que finalizan las tareas no es relevante.

Por lo tanto, dependiendo de qué tarea dure más (QProcess o QThreadFunction<int>), pueden darse los siguientes casos:

Escenario 1Escenario 2
El grupo raíz se iniciaComienza el grupo raíz
Comienza el subgrupoComienza el subgrupo
QProcess comienzaQProcess comienza
QThreadFunction<int> comienzaQThreadFunction<int> se inicia
......
QProcess finalizaQThreadFunction<int> termina
......
QThreadFunction<int> terminaQProcess finaliza
El subgrupo finalizaEl subgrupo termina
QNetworkReplyWrapper se iniciaQNetworkReplyWrapper se inicia
......
QNetworkReplyWrapper finalizaQNetworkReplyWrapper finaliza
El grupo raíz finalizaEl grupo raíz finaliza

Las diferencias entre los escenarios se indican en negrita. Los tres puntos significan que transcurre un tiempo indeterminado entre el evento anterior y el siguiente (una o varias tareas continúan ejecutándose). La ausencia de puntos entre los eventos significa que estos se producen de forma sincrónica.

Los escenarios presentados suponen que todas las tareas se ejecutan correctamente. Si una tarea falla durante su ejecución, el árbol de tareas finaliza con un error. En concreto, cuando QProcess finaliza con un error mientras QThreadFunction<int> aún se está ejecutando, QThreadFunction<int> se cancela automáticamente, el subgrupo finaliza con un error, se omite QNetworkReplyWrapper y el árbol finaliza con un error.

Manejadores de tareas

Utiliza los controladores de Task para configurar una tarea para su ejecución y para permitir la lectura de los datos de salida de la tarea cuando finaliza con éxito o con un error.

Manejador de inicio de la tarea

Cuando se crea un objeto de tarea y antes de que se inicie, el árbol de tareas invoca un controlador de configuración opcional proporcionado por el usuario. El controlador de configuración siempre debe tomar una referencia al objeto de la clase de tarea asociada:

const auto onSetup = [](QProcess &process) {
    process.setProgram("sleep");
    process.setArguments({"3"});
};
const Group root {
    QProcessTask(onSetup)
};

Puedes modificar el objeto ` QProcess ` pasado en el controlador de configuración, de modo que el árbol de tareas pueda iniciar el proceso según tu configuración. No debes llamar a ` process.start(); ` en el controlador de configuración, ya que el árbol de tareas lo llama cuando es necesario. El controlador de configuración es opcional. Cuando se utilice, debe ser el primer argumento del constructor de la tarea.

Opcionalmente, el controlador de configuración puede devolver un ` SetupResult`. El ` SetupResult ` devuelto influye en el comportamiento posterior de inicio de una tarea determinada. Los valores posibles son:

SetupResult ValorBreve descripción
ContinueLa tarea se iniciará con normalidad. Este es el comportamiento por defecto cuando el controlador de configuración no devuelve un ` SetupResult ` (es decir, su tipo de retorno es ` void`).
StopWithSuccessLa tarea no se iniciará y notificará que se ha completado con éxito a su padre.
StopWithErrorLa tarea no se iniciará y notificará un error a su tarea principal.

Esto resulta útil para ejecutar una tarea únicamente cuando se cumple una condición y los datos necesarios para evaluar dicha condición no se conocen hasta que finalicen las tareas iniciadas previamente. De este modo, el controlador de configuración decide dinámicamente si iniciar la tarea correspondiente de forma normal o omitirla e informar de un éxito o de un error. Para obtener más información sobre el intercambio de datos entre tareas, consulta Storage.

Manejador «Done» de la tarea

Cuando una tarea en ejecución finaliza, el árbol de tareas invoca un controlador de finalización proporcionado de forma opcional. El controlador debe tomar una referencia const al objeto de la clase de tarea asociada:

const auto onSetup = [](QProcess&process) {
    process.setProgram("sleep");
    process.setArguments({"3"});
};
const auto onDone = [](const QProcess&process, DoneWith result) {
    if (result== DoneWith::Success)
        qDebug() << "Success" << process.cleanedStdOut();
   sino
        qDebug() << "Failure" << process.cleanedStdErr();
};
const Group root {
    QProcessTask(onSetup, onDone)
};

El controlador «done» puede recopilar datos de salida de ` QProcess` y almacenarlos para su posterior procesamiento o realizar acciones adicionales.

Nota: Si el controlador de configuración de la tarea devuelve ` StopWithSuccess ` o ` StopWithError`, no se invoca el controlador «done».

Manejadores de grupo

Al igual que los controladores de tareas, los controladores de grupos permiten configurar un grupo para que se ejecute y aplicar más acciones cuando todo el grupo finalice con éxito o con un error.

Manejador de inicio del grupo

El árbol de tareas invoca el controlador de inicio del grupo antes de iniciar las tareas secundarias. El controlador de grupo no admite ningún argumento:

const auto onSetup = [] {
    qDebug() << "Entering the group";
};
const Group root {
    onGroupSetup(onSetup),
    QProcessTask(...)
};

El controlador de configuración del grupo es opcional. Para definir un controlador de configuración del grupo, añade un elemento « onGroupSetup()» a un grupo. El argumento de « onGroupSetup()» es un controlador de usuario. Si añades más de un elemento « onGroupSetup()» a un grupo, se activará una comprobación en tiempo de ejecución que incluirá un mensaje de error.

Al igual que el controlador de inicio de la tarea, el controlador de inicio del grupo puede devolver SetupResult. El valor devuelto por SetupResult afecta al comportamiento de inicio de todo el grupo. Si no se especifica un controlador de inicio del grupo, o si su tipo de retorno es void, la acción predeterminada del grupo es Continue, de modo que todas las tareas se inician normalmente. Por el contrario, cuando el controlador de inicio devuelve StopWithSuccess o StopWithError, las tareas no se inician (se omiten) y el propio grupo informa de un éxito o de un error, dependiendo del valor devuelto, respectivamente.

const Group root {
    onGroupSetup([] { qDebug() << "Root setup"; }),
    Group {
        onGroupSetup([] { qDebug() << "Group 1 setup"; return SetupResult::Continue; }),
        QProcessTask(...) // Process 1
    },
    Group {
        onGroupSetup([] { qDebug() << "Group 2 setup"; return SetupResult::StopWithSuccess; }),
        QProcessTask(...) // Process 2
    },
    Group {
        onGroupSetup([] { qDebug() << "Group 3 setup"; return SetupResult::StopWithError; }),
        QProcessTask(...) // Process 3
    },
    QProcessTask(...) // Process 4
};

En el ejemplo anterior, todos los subgrupos de un grupo raíz definen sus controladores de configuración. El siguiente escenario supone que todos los procesos iniciados finalizan con éxito:

EscenarioComentario
El grupo raíz se iniciaNo devuelve SetupResult, por lo que se ejecutan sus tareas.
El Grupo 1 se iniciaDevuelve Continue, por lo que se ejecutan sus tareas.
Se inicia el proceso 1
......
El proceso 1 finaliza (con éxito)
El grupo 1 finaliza (éxito)
El grupo 2 se iniciaDevuelve StopWithSuccess, por lo que se omite el proceso 2 y el grupo 2 informa de que ha finalizado con éxito.
El Grupo 2 finaliza (éxito)
El grupo 3 comienzaDevuelve StopWithError, por lo que se omite el proceso 3 y el grupo 3 informa de un error.
El grupo 3 finaliza (error)
El grupo raíz finaliza (error)El grupo 3, que es un hijo directo del grupo raíz, ha finalizado con un error, por lo que el grupo raíz detiene su ejecución, omite el proceso 4, que aún no ha comenzado, y notifica un error.

Manejador «Done» de los grupos

El controlador de finalización de un « Group » se ejecuta tras la ejecución, ya sea correcta o fallida, de sus tareas. El valor final notificado por el grupo depende de su « Workflow Policy ». El controlador puede aplicar otras acciones necesarias. El controlador de finalización se define dentro del elemento « onGroupDone()» de un grupo. Puede tomar el argumento opcional « DoneWith », que indica si la ejecución ha sido correcta o ha fallado:

const Group root {
    onGroupSetup([] { qDebug() << "Configuración de la raíz"; }),
    QProcessTask(...),
    onGroupDone([](DoneWith result) {
        if (result== DoneWith::Success)
            qDebug() << "Root finished with success";
       sino
            qDebug() << "Root finished with an error";
    })
};

El controlador «done» del grupo es opcional. Si añades más de un onGroupDone() a un grupo, se activa una comprobación en tiempo de ejecución que incluye un mensaje de error.

Nota: Aunque el controlador de configuración del grupo devuelva StopWithSuccess o StopWithError, se invocará el controlador «done» del grupo. Este comportamiento difiere del del controlador «done» de una tarea y podría cambiar en el futuro.

Otros elementos del grupo

Un grupo puede contener otros elementos que describen el flujo de procesamiento, como el ` execution mode ` o el ` workflow policy`. También puede contener elementos de almacenamiento encargados de recopilar y compartir datos comunes personalizados recopilados durante la ejecución del grupo.

Modo de ejecución

El elemento de modo de ejecución de un grupo especifica cómo se inician las tareas hijas directas del grupo. Los modos de ejecución más comunes son « sequential » y « parallel ». También es posible especificar el límite de tareas que se ejecutan en paralelo mediante el elemento « ParallelLimit ».

En todos los modos de ejecución, un grupo inicia las tareas en el orden en que aparecen.

Si una tarea hija de un grupo es también un grupo, el grupo hijo ejecuta sus tareas según su propio modo de ejecución.

Política de flujos de trabajo

El elemento de política de flujo de trabajo de un « Group » especifica cómo debe comportarse el grupo cuando finalice cualquiera de las tareas de sus hijos directos. Para obtener una descripción detallada de las posibles políticas, consulte WorkflowPolicy.

Si un elemento secundario de un grupo es también un grupo, dicho grupo secundario ejecuta sus tareas de acuerdo con su propia política de flujo de trabajo.

Almacenamiento

Utiliza el elemento « Storage » para intercambiar información entre tareas. En particular, en el modo de ejecución secuencial, cuando una tarea necesita datos de otra tarea ya finalizada antes de poder iniciarse. Por ejemplo, un árbol de tareas que copia datos leyéndolos de una fuente y escribiéndolos en un destino podría tener el siguiente aspecto:

static QByteArray load(const QString&fileName) {... }
static void save(const QString&fileName, const QByteArray&array) {... }

static Group copyRecipe(const QString&fuente, const QString&destination)
{
    struct CopyStorage { // [1] estructura personalizada entre tareas
        QByteArray content; // [2] datos personalizados entre tareas
    };

    // [3] instancia de una estructura personalizada entre tareas gestionable por el árbol de tareas
    const Storage<CopyStorage> storage;

    const auto onLoaderSetup = [source](QThreadFunction<QByteArray> &async) {
        async.setThreadFunctionData(&load, source);
    };
   // [4] tiempo de ejecución: el árbol de tareas activa la instancia de [7] antes de invocar el controlador
    const auto onLoaderDone = [storage](const QThreadFunction<QByteArray> &async) {
        storage->content = async.result(); // [5] el cargador almacena el resultado en storage
    };

   // [4] tiempo de ejecución: el árbol de tareas activa la instancia de [7] antes de invocar el controlador
    const auto onSaverSetup = [storage, destination](QThreadFunction<void> &async) {
        const QByteArray content = storage->content; // [6] el guardador toma los datos del almacenamiento
        async.setThreadFunctionData(&save, destination, content);
    };
    const auto onSaverDone = [](const QThreadFunction<void> &async) {
        qDebug() << "Save done successfully";
    };

    const Group root {
        // [7] en tiempo de ejecución: el árbol de tareas crea una instancia de CopyStorage al entrar en root
        storage,
        QThreadFunctionTask<QByteArray>(onLoaderSetup, onLoaderDone, CallDoneFlag::OnSuccess),
        QThreadFunctionTask<void>(onSaverSetup, onSaverDone, CallDoneFlag::OnSuccess)
    };
    return root;
}

...

const QString source =...;
const QString destino =...;
QTaskTree árbolDeTareas(copiarReceta(origen, destino));
conectar(&árbolDeTareas,&QTaskTree::done, &árbolDeTareas, [](DoneWith resultado) {
    si (resultado== DoneWith::Success)
        qDebug() << "The copying finished successfully.";
});
tasktree.start();

En el ejemplo anterior, los datos entre tareas consisten en una variable de contenido QByteArray [2] incluida en una estructura personalizada CopyStorage [1]. Si el cargador finaliza correctamente, almacena los datos en una variable CopyStorage::content [5]. A continuación, el guardador utiliza la variable para configurar la tarea de guardado [6].

Para que un árbol de tareas pueda gestionar la estructura « CopyStorage », se crea una instancia de « Storage<CopyStorage>» [3]. Si se inserta una copia de este objeto como elemento secundario del grupo [7], se crea dinámicamente una instancia de la estructura CopyStorage cuando el árbol de tareas entra en este grupo. Cuando el árbol de tareas abandona este grupo, la instancia existente de la estructura CopyStorage se destruye, ya que ya no es necesaria.

Si se ejecutan simultáneamente varios árboles de tareas que contienen una copia de la instancia común de « Storage » <CopyStorage> (incluido el caso en el que los árboles de tareas se ejecutan en hilos diferentes), cada árbol de tareas contiene su propia copia de la estructura « CopyStorage ».

Se puede acceder a CopyStorage desde cualquier controlador del grupo que cuente con un objeto de almacenamiento. Esto incluye todos los controladores de todas las tareas descendientes del grupo que cuenten con un objeto de almacenamiento. Para acceder a la estructura personalizada en un controlador, se debe pasar la copia del objeto Storage<CopyStorage> al controlador (por ejemplo, en una captura lambda) [4].

Cuando el árbol de tareas invoca un manejador en un subárbol que contiene el almacenamiento [7], el árbol de tareas activa su propia instancia de CopyStorage dentro del objeto Storage<CopyStorage>. Por lo tanto, solo se puede acceder a la estructura CopyStorage desde el interior del cuerpo del manejador. Para acceder a la CopyStorage actualmente activa desde dentro de Storage<CopyStorage>, utiliza los métodos Storage::operator->(), Storage::operator*() o Storage::activeStorage().

La siguiente lista resume cómo utilizar un objeto Storage en el árbol de tareas:

  1. Define la estructura personalizada MyStorage con datos personalizados [1], [2]
  2. Crea una instancia del almacenamiento Storage<MyStorage> [3]
  3. Pasa la instancia de « Storage » <MyStorage> a los controladores [4]
  4. Acceder a la instancia de MyStorage en los controladores [5], [6]
  5. Insertar la instancia de Storage<MyStorage> en un grupo [7]

Clase QTaskTree

QTaskTree ejecuta la estructura en árbol de tareas asíncronas según la receta descrita por el elemento raíz Group.

Dado que « QTaskTree » también es una tarea asíncrona, puede formar parte de otro « QTaskTree ». Para colocar un « QTaskTree » anidado dentro de otro « QTaskTree », inserta el elemento « QTaskTreeTask » dentro de otro elemento « Group ».

QTaskTree informa del progreso de las tareas completadas durante su ejecución. El valor de progreso aumenta cuando una tarea finaliza, se omite o se cancela. Cuando QTaskTree finaliza y se emite la señal QTaskTree::done(), el valor actual del progreso es igual al valor máximo de progreso. El progreso máximo es igual al número total de tareas asíncronas de un árbol. Un « QTaskTree » anidado se cuenta como una única tarea, y sus tareas secundarias no se cuentan en el árbol de nivel superior. Los grupos en sí mismos no se cuentan como tareas, pero sí se cuentan sus tareas. Las tareas de « QSyncTask » no son asíncronas, por lo que no se cuentan como tareas.

Para establecer datos iniciales adicionales para el árbol en ejecución, modifica las instancias de almacenamiento de un árbol cuando este las cree instalando un controlador de configuración de almacenamiento:

Storage<CopyStorage> storage;
const Group root = ...; // storage placed inside root's group and inside handlers
QTaskTree taskTree(root);
auto initStorage = [](CopyStorage &storage) {
    storage.content = "initial content";
};
taskTree.onStorageSetup(storage, initStorage);
taskTree.start();

Cuando el árbol de tareas en ejecución crea una instancia de CopyStorage, y antes de que se llame a ningún controlador dentro del árbol, el árbol de tareas llama al controlador initStorage, para permitir la configuración de los datos iniciales del almacenamiento, específicos de esta ejecución concreta de taskTree.

Del mismo modo, para recopilar algunos datos de resultados adicionales del árbol en ejecución, léelos de las instancias de almacenamiento del árbol cuando estén a punto de ser destruidas. Para ello, instala un controlador de finalización de almacenamiento:

Storage<CopyStorage> storage;
const Group root =...; // almacenamiento situado dentro del grupo de root y dentro de los manejadores
QTaskTree taskTree(root);
auto collectStorage = [](const CopyStorage &storage) {
    qDebug() << "final content" << storage.content;
};
taskTree.onStorageDone(storage, collectStorage);
taskTree.start();

Cuando el árbol de tareas en ejecución está a punto de destruir una instancia de CopyStorage, el árbol de tareas llama al controlador collectStorage para permitir la lectura de los datos finales del almacenamiento, propios de esta ejecución concreta de taskTree.

Adaptadores de tareas

Permitir que nuevos tipos de tareas formen parte de las recetas es bastante sencillo. Basta con definir un nuevo alias de tarea para la plantilla ` QCustomTask `, pasando tu tipo ` Task ` como primer argumento de la plantilla, de la siguiente manera:

class Worker : public QObject
{
public:
    void start() { ... }

signals:
    void done(bool result);
};

using WorkerTask = QCustomTask<Worker>;

Esto funcionará si se cumplen las siguientes condiciones:

  1. Tu tarea derive de ` QObject`.
  2. Tu tarea tiene un método público start() que inicia la tarea.
  3. Tu tarea emite la señal done(bool) o done(DoneResult) cuando ha finalizado.

Si tu tarea no cumple estas condiciones, aún así puedes adaptarla para que funcione con el marco TaskTree, proporcionando un segundo argumento de plantilla con el adaptador personalizado. Supongamos que queremos adaptar QTimer para que funcione con TaskTree. El Adapter podría tener el siguiente aspecto:

class TimerAdapter
{
public:
    void operator()(QTimer *task, QTaskInterface *iface) {
        task->setSingleShot(true);
        QObject::connect(task, &QTimer::timeout, iface, [iface] {
            iface->reportDone(DoneResult::Success);
        });
        task->start();
    }
};

using TimerTask = QCustomTask<QTimer, TimerAdapter>;

Ahora ya puedes empezar a utilizar TimerTask en tus recetas, así:

const auto onSetup = [](QTimer&task) {
    task.setInterval(2000);
};

const auto onDone = [](const QTimer&task) {
    qDebug() << "Timer triggered after" << task.interval() << "ms.";
};

const Group recipe {
    TimerTask(onSetup, onDone)
};

Nota: La clase que implementa la tarea en ejecución debe tener un constructor por defecto, y los objetos de esta clase deben ser libremente destructibles. Debe permitirse destruir una tarea en ejecución, preferiblemente sin esperar a que esta finalice (es decir, un destructor seguro y no bloqueante de una tarea en ejecución). Para lograr la destrucción no bloqueante de una tarea que tiene un destructor bloqueante, se recomienda utilizar el parámetro de plantilla opcional ` Deleter ` de ` QCustomTask ` (el tercer argumento de plantilla).

Ejecutores de árboles de tareas

El ejecutor del árbol de tareas gestiona el ciclo de vida de la ` QTaskTree ` subyacente utilizada para ejecutar la receta dada.

La siguiente tabla resume las diferencias entre los distintos ejecutores de árboles de tareas:

Nombre de la claseDescripción
QSingleTaskTreeRunnerGestiona la ejecución de un único árbol de tareas. El método QSingleTaskTreeRunner::start() inicia de forma incondicional la receta pasada, reiniciando cualquier árbol de tareas que pudiera estar en ejecución. Solo puede ejecutarse un árbol de tareas a la vez.
QSequentialTaskTreeRunnerGestiona la ejecución secuencial de árboles de tareas. El método ` QSequentialTaskTreeRunner::enqueue()` inicia la receta pasada si el ejecutor de árboles de tareas está inactivo. De lo contrario, la receta se coloca en la cola. Cuando finaliza la tarea actual, el ejecutor ejecuta la receta retirada de la cola de forma secuencial. Solo puede ejecutarse un árbol de tareas a la vez.
QParallelTaskTreeRunnerGestiona las ejecuciones paralelas de árboles de tareas. El método ` QParallelTaskTreeRunner::start()` inicia incondicionalmente la receta pasada y mantiene en paralelo cualquier árbol de tareas que pueda estar ejecutándose.
QMappedTaskTreeRunnerGestiona las ejecuciones de árboles de tareas asignados. El método ` QMappedTaskTreeRunner::start()` inicia incondicionalmente la receta especificada para una clave determinada. Si ya hay otro árbol de tareas con la misma clave en ejecución, este se reiniciará. Los árboles de tareas con claves diferentes no se ven afectados y continúan su ejecución.

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.