En esta página

QtTaskTree::QTaskTree Class

class QtTaskTree::QTaskTree

La clase QTaskTree ejecuta el árbol de tareas asíncronas definidas de forma declarativa. Más información...

Encabezado: #include <qtasktree.h>
CMake: find_package(Qt6 REQUIRED COMPONENTS TaskTree)
target_link_libraries(mytarget PRIVATE Qt6::TaskTree)
qmake: QT += tasktree
Desde: Qt 6.11
Heredado de: QObject
Estado: Vista previa tecnológica

Esta clase se encuentra en fase de vista previa tecnológica y está sujeta a cambios.

Nota: Todas las funciones de esta clase son reentrantes.

Funciones públicas

QTaskTree(QObject *parent)
QTaskTree(const QtTaskTree::Group &recipe, QObject *parent = nullptr)
virtual ~QTaskTree() override
qsizetype asyncCount() const
void cancel()
bool isRunning() const
void onStorageDone(const QtTaskTree::Storage<StorageStruct> &storage, Handler &&handler)
void onStorageSetup(const QtTaskTree::Storage<StorageStruct> &storage, Handler &&handler)
qsizetype progressMaximum() const
qsizetype progressValue() const
QtTaskTree::DoneWith runBlocking()
QtTaskTree::DoneWith runBlocking(const QFuture<void> &future)
void setRecipe(const QtTaskTree::Group &recipe)
void start()
qsizetype taskCount() const

Señales

void asyncCountChanged(qsizetype count)
void done(QtTaskTree::DoneWith result)
void progressValueChanged(qsizetype value)
void started()

Miembros públicos estáticos

QtTaskTree::DoneWith runBlocking(const QtTaskTree::Group &recipe)
QtTaskTree::DoneWith runBlocking(const QtTaskTree::Group &recipe, const QFuture<void> &future)

Funciones protegidas reimplementadas

virtual bool event(QEvent *event) override

Descripción detallada

La descripción de lo que debe hacer el árbol de tareas se transmite a través de la receta.

Documentación de las funciones de miembro

[explicit] QTaskTree::QTaskTree(QObject *parent)

Crea un árbol de tareas vacío con un ` parent` dado. Utiliza ` setRecipe()` para pasar una descripción declarativa sobre cómo debe ejecutar el árbol de tareas las tareas y cómo debe gestionar las tareas finalizadas.

Iniciar un árbol de tareas vacío no produce ningún efecto y se muestra el mensaje de advertencia correspondiente.

Véanse también setRecipe() y start().

[explicit] QTaskTree::QTaskTree(const QtTaskTree::Group &recipe, QObject *parent = nullptr)

Crea un árbol de tareas a partir de un ` recipe ` y un ` parent` dados. Una vez iniciado el árbol de tareas, ejecuta las tareas contenidas en el ` recipe ` y gestiona las tareas finalizadas según la descripción pasada.

Esta es una función sobrecargada.

Véanse también setRecipe() y start().

[override virtual noexcept] QTaskTree::~QTaskTree()

Destruye el árbol de tareas.

Si el árbol de tareas se está ejecutando en el momento de su destrucción, cancela inmediatamente todas las tareas en ejecución. En este caso, no se invocan los controladores, ni siquiera los controladores «done» de los grupos y las tareas ni los controladores « onStorageDone()». El árbol de tareas tampoco emite ninguna señal desde el destructor, ni siquiera las señales « done()» o « progressValueChanged()». Siempre se puede confiar en este comportamiento. Es totalmente seguro destruir el árbol de tareas en ejecución.

Es habitual destruir el árbol de tareas en ejecución. Se garantiza que la destrucción se ejecutará rápidamente, sin tener que esperar a que finalicen las tareas que se están ejecutando en ese momento, siempre que las tareas utilizadas implementen sus destructores de forma no bloqueante.

Nota: No llames al destructor directamente desde ninguno de los controladores de las tareas en ejecución ni desde las señales del árbol de tareas. En estos casos, utiliza en su lugar ` deleteLater()` ().

Véase también cancel().

qsizetype QTaskTree::asyncCount() const

Devuelve el recuento real actual de cadenas asíncronas de invocaciones.

El valor devuelto indica cuántas veces el control vuelve al bucle de eventos del llamante mientras se está ejecutando el árbol de tareas. Inicialmente, este valor es 0. Si la ejecución del árbol de tareas finaliza de forma totalmente sincrónica, este valor permanece en 0. Si el árbol de tareas contiene alguna tarea asíncrona que se haya iniciado correctamente durante una llamada a start(), este valor se incrementa a 1 justo antes de que finalice la llamada a start(). Posteriormente, cuando finaliza cualquier tarea asíncrona y se inician las posibles continuaciones, este valor vuelve a incrementarse. El incremento continúa hasta que finaliza el árbol de tareas. Cuando el árbol de tareas emite la señal « done()», el incremento se detiene. La señal « asyncCountChanged()» se emite cada vez que se incrementa este valor.

Véase también asyncCountChanged().

[signal] void QTaskTree::asyncCountChanged(qsizetype count)

Esta señal se emite cuando el árbol de tareas en ejecución está a punto de devolver el control al bucle de eventos del llamante. Cuando se inicia el árbol de tareas, esta señal se emite con un valor de « count » de « 0 », y posteriormente se emite cada vez que se actualiza el valor de « asyncCount()», con un valor actualizado de « count ». Cada señal enviada (excepto la inicial con el valor 0) garantiza que el árbol de tareas siga ejecutándose de forma asíncrona tras la emisión.

Véase también asyncCount().

void QTaskTree::cancel()

Cancela la ejecución del árbol de tareas en ejecución.

Cancela inmediatamente todas las tareas en ejecución. Todas las tareas y grupos en ejecución finalizan con un error, invocando sus manejadores «done» con DoneWith::Cancel. También se invocan los manejadores « onStorageDone()» de los almacenes. Asimismo, se envían las señales « progressValueChanged()». Siempre se puede confiar en este comportamiento.

La función `cancel()` se ejecuta de forma sincrónica, de modo que, tras una llamada a `cancel()`, todas las tareas en ejecución finalizan y el árbol ya está cancelado. Se garantiza que `cancel()` se ejecutará rápidamente, sin ninguna espera bloqueante a que finalicen las tareas que se están ejecutando en ese momento, siempre que las tareas utilizadas implementen sus destructores de forma no bloqueante.

Cuando el árbol de tareas está vacío, es decir, se ha construido con un constructor por defecto, una llamada a cancel() no tiene ningún efecto y se emite el mensaje de advertencia correspondiente.

En caso contrario, cuando el árbol de tareas no se haya iniciado, se ignora la llamada a `cancel()`.

Nota: No llames a esta función directamente desde ninguno de los controladores de las tareas en ejecución ni desde las señales del árbol de tareas.

Véase también ` ~QTaskTree()`.

[signal] void QTaskTree::done(QtTaskTree::DoneWith result)

Esta señal se emite cuando finaliza el árbol de tareas, pasando el ` result ` final de la ejecución. Una vez emitida esta señal, el árbol de tareas ya no llama a ningún controlador ni emite ninguna otra señal.

Nota: No elimines el árbol de tareas directamente desde el controlador de esta señal. Utiliza en su lugar deleteLater().

Véase también started().

[override virtual protected] bool QTaskTree::event(QEvent *event)

Reimplementa: QObject::event(QEvent *e).

bool QTaskTree::isRunning() const

Devuelve « true » si el árbol de tareas se está ejecutando en ese momento; en caso contrario, devuelve « false ».

Véase también start() y cancel().

template <typename StorageStruct, typename Handler> void QTaskTree::onStorageDone(const QtTaskTree::Storage<StorageStruct> &storage, Handler &&handler)

Instala un sistema de almacenamiento realizado en handler para que storage pueda recuperar dinámicamente los datos finales del árbol de tareas en ejecución.

El StorageHandler toma una referencia de const a la instancia de StorageStruct:

static QByteArray load(const QString&fileName) {... }

Storage<QByteArray> storage;

const auto onLoaderSetup = [](QThreadFunction<QByteArray> &task) {
    task.setThreadFunctionData(&load, "foo.txt");
};
const auto onLoaderDone = [storage](const QThreadFunction<QByteArray> &task) {
    *storage = task.result();
};

const Group root {
    storage,
    QThreadFunctionTask(onLoaderSetup, onLoaderDone, CallDoneFlag::OnSuccess)
};

QTaskTree taskTree(root);
auto collectStorage = [](const QByteArray&storage){
    qDebug() << "final content" << storage;
};
taskTree.onStorageDone(storage, collectStorage);
taskTree.start();

Cuando el árbol de tareas en ejecución está a punto de salir de un « Group » en el que se encuentra el « storage », destruye una instancia de « StorageStruct ». Justo antes de que se destruya la instancia de « StorageStruct », y después de que se hayan llamado todos los controladores posibles de este grupo, el árbol de tareas invoca el « handler » pasado. Esto permite leer dinámicamente el contenido final del almacenamiento dado y procesarlo posteriormente fuera del árbol de tareas.

Este controlador también se invoca cuando se cancela el árbol en ejecución. Sin embargo, no se invoca cuando se destruye el árbol en ejecución.

Véase también onStorageSetup().

template <typename StorageStruct, typename Handler> void QTaskTree::onStorageSetup(const QtTaskTree::Storage<StorageStruct> &storage, Handler &&handler)

Instala una configuración de almacenamiento handler para que storage transmita los datos iniciales de forma dinámica al árbol de tareas en ejecución.

El « StorageHandler » toma una referencia a la instancia de « StorageStruct »:

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

Storage<QByteArray> storage;

const auto onSaverSetup = [storage](QThreadFunction<QByteArray> &task) {
    task.setThreadFunctionData(&save, "foo.txt", *storage);
};

const Group root {
    storage,
    QThreadFunctionTask(onSaverSetup)
};

QTaskTree taskTree(root);
auto initStorage = [](QByteArray &storage){
    storage = "initial content";
};
taskTree.onStorageSetup(storage, initStorage);
taskTree.start();

Cuando el árbol de tareas en ejecución entra en un grupo en el que se encuentra el « storage », este crea una instancia de « StorageStruct », lista para ser utilizada dentro de dicho grupo. Justo después de que se cree la instancia de « StorageStruct » y antes de que se llame a cualquier controlador de este grupo, el árbol de tareas invoca el método « handler » que se le ha pasado. Esto permite configurar dinámicamente el contenido inicial del almacenamiento dado. Posteriormente, cuando se invoca el controlador de cualquier grupo, el árbol de tareas activa el almacenamiento creado e inicializado, de modo que esté disponible dentro del controlador de cualquier grupo.

Véase también onStorageDone().

qsizetype QTaskTree::progressMaximum() const

Devuelve el valor máximo de progressValue().

Nota: Actualmente , es lo mismo que taskCount(). Esto podría cambiar en el futuro.

Véase también ` progressValue()`.

qsizetype QTaskTree::progressValue() const

Devuelve el valor de progreso actual, que se encuentra entre 0 y progressMaximum().

El número devuelto indica cuántas tareas se han completado, cancelado u omitido mientras se ejecuta el árbol de tareas. Al iniciar el árbol de tareas, este número se establece en 0. Cuando finaliza el árbol de tareas, este número siempre es igual a progressMaximum().

Véanse también progressMaximum() y progressValueChanged().

[signal] void QTaskTree::progressValueChanged(qsizetype value)

Esta señal se emite cuando el árbol de tareas en ejecución ha finalizado, cancelado u omitido algunas tareas. La señal « value » indica el número total actual de tareas finalizadas, canceladas u omitidas. Cuando se inicia el árbol de tareas, y después de que se haya emitido la señal « started()», esta señal se emite con un valor inicial de « value » igual a « 0 ». Cuando el árbol de tareas está a punto de finalizar, y antes de que se emita la señal « done()», esta señal se emite con un valor final de « value » igual a « progressMaximum()».

Véase también progressValue() y progressMaximum().

QtTaskTree::DoneWith QTaskTree::runBlocking()

Ejecuta un bucle de eventos local con « QEventLoop::ExcludeUserInputEvents » e inicia el árbol de tareas.

Devuelve ` DoneWith::Success ` si el árbol de tareas ha finalizado correctamente; en caso contrario, devuelve ` DoneWith::Error`.

Nota: Evita utilizar este método desde el hilo principal. Utiliza en su lugar la función asíncrona start(). Este método debe utilizarse en hilos que no sean el principal o en pruebas automáticas.

Véase también ` start()`.

[static] QtTaskTree::DoneWith QTaskTree::runBlocking(const QtTaskTree::Group &recipe)

Crea un árbol de tareas temporal utilizando el objeto ` recipe ` pasado como parámetro y lo ejecuta de forma bloqueante.

Devuelve ` DoneWith::Success ` si el árbol de tareas ha finalizado correctamente; en caso contrario, devuelve ` DoneWith::Error`.

Nota: Evita utilizar este método desde el hilo principal. Utiliza en su lugar la función asíncrona ` start()`. Este método debe utilizarse en hilos distintos del principal o en pruebas automáticas.

Véase también ` start()`.

QtTaskTree::DoneWith QTaskTree::runBlocking(const QFuture<void> &future)

El objeto ` future ` pasado se utiliza para escuchar el evento de cancelación. Cuando se cancela el árbol de tareas, este método cancela el objeto ` future` pasado.

Esta función sobrecarga QTaskTree::runBlocking().

[static] QtTaskTree::DoneWith QTaskTree::runBlocking(const QtTaskTree::Group &recipe, const QFuture<void> &future)

El objeto ` future ` pasado se utiliza para escuchar el evento de cancelación. Cuando se cancela el árbol de tareas, este método cancela el objeto ` future` pasado.

Esta función sobrecarga QTaskTree::runBlocking(const Group &recipe).

void QTaskTree::setRecipe(const QtTaskTree::Group &recipe)

Establece un « recipe » determinado para el árbol de tareas. Una vez iniciado el árbol de tareas, este ejecuta las tareas contenidas en el « recipe » y gestiona las tareas finalizadas de acuerdo con la descripción pasada.

Nota: Si se invoca para un árbol de tareas en ejecución, la llamada se ignora.

Véase también QTaskTree(const QtTaskTree::Group &recipe, QObject *parent = nullptr) y start().

void QTaskTree::start()

Inicia el árbol de tareas.

Utiliza setRecipe() o el constructor para establecer la descripción declarativa según la cual el árbol de tareas ejecutará las tareas contenidas y gestionará las tareas finalizadas.

Cuando el árbol de tareas está vacío, es decir, se ha construido con un constructor por defecto, una llamada a start() no produce ningún efecto y se emite el mensaje de advertencia correspondiente.

En caso contrario, cuando el árbol de tareas ya se está ejecutando, una llamada a start() se ignora y se emite el mensaje de advertencia correspondiente.

En cualquier otro caso, se inicia el árbol de tareas.

El árbol de tareas iniciado puede finalizar de forma sincrónica, por ejemplo, cuando el controlador de inicio del grupo principal devuelve « SetupResult::StopWithError ». Por este motivo, la conexión a la señal «done» debe establecerse antes de llamar a `start()`. Utiliza ` isRunning()` para detectar si el árbol de tareas sigue en ejecución tras una llamada a `start()`.

La implementación del árbol de tareas depende del bucle de eventos en ejecución. Asegúrate de que tengas un ` QEventLoop`, un ` QCoreApplication` o una de sus subclases en ejecución (o a punto de ejecutarse) al llamar a este método.

Véase también QTaskTree(const QtTaskTree::Group &recipe, QObject *parent = nullptr), setRecipe(), isRunning() y cancel().

[signal] void QTaskTree::started()

Esta señal se emite cuando se inicia el árbol de tareas. A la emisión de esta señal le sigue, de forma sincrónica, la señal progressValueChanged() con un valor inicial de 0.

Véanse también start() y done().

qsizetype QTaskTree::taskCount() const

Devuelve el número de tareas asíncronas que contiene la receta guardada.

Nota: El número devuelto no incluye las tareas de tipo « QSyncTask ».

Nota: Cualquier tarea o grupo que se haya configurado mediante withTimeout() aumenta el número total de tareas en 1.

Véase también setRecipe() y progressMaximum().

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