QtTaskTree::QTaskTree Class

Documentación de las funciones miembro

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

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

Iniciar un árbol de tareas vacío no funciona y se emite el mensaje de advertencia correspondiente.

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

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

Construye un árbol de tareas con un recipe y un parent dados. Una vez iniciado el árbol de tareas, ejecuta las tareas contenidas en recipe y gestiona las tareas finalizadas de acuerdo con la descripción pasada.

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

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

Destruye el árbol de tareas.

Cuando el árbol de tareas se está ejecutando mientras se destruye, cancela inmediatamente todas las tareas en ejecución. En este caso, no se llama a ningún manejador, ni siquiera a los manejadores de grupos y tareas realizadas o a onStorageDone(). El árbol de tareas tampoco emite ninguna señal desde el destructor, ni siquiera done() o progressValueChanged(). Siempre se puede confiar en este comportamiento. Es completamente seguro destruir el árbol de tareas en ejecución.

Es un patrón habitual destruir el árbol de tareas en ejecución. Está garantizado que la destrucción se ejecutará rápidamente, sin tener que esperar a que las tareas en ejecución finalicen, siempre que las tareas utilizadas implementen sus destructores de forma no bloqueante.

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 vuelve el control al bucle de eventos del llamante mientras se ejecuta el árbol de tareas. Inicialmente, este valor es 0. Si la ejecución del árbol de tareas finaliza de forma totalmente síncrona, este valor permanece 0. Si el árbol de tareas contiene alguna tarea asíncrona que se inicia con éxito durante una llamada a start(), este valor pasa a ser 1 justo antes de que finalice la llamada a start(). Más tarde, cuando finaliza cualquier tarea asíncrona y se inician las posibles continuaciones, este valor se incrementa de nuevo. Este proceso continúa hasta que finaliza el árbol de tareas. Cuando el árbol de tareas emite la señal done(), el bumping se detiene. La señal asyncCountChanged() se emite en cada salto de 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 el valor count de 0, y se emite posteriormente en cada salto de valor asyncCount() con un valor count actualizado. Cada señal enviada (excepto la inicial con el valor de 0) garantiza que el árbol de tareas sigue ejecutándose de forma asíncrona después de 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 a sus gestores de finalización con DoneWith::Cancel. También se invocan los manejadores onStorageDone() de los almacenamientos. Las señales progressValueChanged() también se envían. 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 han finalizado y el árbol ya está cancelado. Está garantizado que cancel() se ejecutará rápidamente, sin ninguna espera de bloqueo para que las tareas actualmente en ejecución finalicen, siempre que las tareas utilizadas implementen sus destructores de forma no bloqueante.

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

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

Véase también ~QTaskTree().

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

Esta señal se emite cuando el árbol de tareas ha finalizado, pasando la result final de la ejecución. El árbol de tareas no llama a ningún manejador, ni emite ninguna señal después de que esta señal haya sido emitida.

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 actualmente; 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 almacenamiento realizado handler para que storage recupere los datos finales dinámicamente del árbol de tareas en ejecución.

El StorageHandler toma una referencia const a la instancia StorageStruct:

estático QByteArray load(const QString &fileName) { ... }  Storage<QByteArray> almacenamiento;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 abandonar un Group en el que se encuentra el storage, destruye una instancia de StorageStruct. Justo antes de que la instancia StorageStruct sea destruida, y después de que todos los manejadores posibles de este grupo hayan sido llamados, el árbol de tareas invoca al handler pasado. Esto permite leer dinámicamente el contenido final del almacenamiento dado y procesarlo posteriormente fuera del árbol de tareas.

Este manejador también se llama cuando se cancela el árbol en ejecución. Sin embargo, no se llama 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 pase los datos iniciales dinámicamente al árbol de tareas en ejecución.

El StorageHandler toma una referencia a la instancia 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, crea una instancia StorageStruct, lista para ser utilizada dentro de este grupo. Justo después de que se cree la instancia StorageStruct, y antes de que se llame a cualquier manejador de este grupo, el árbol de tareas invoca al handler pasado. Esto permite configurar dinámicamente el contenido inicial para el almacenamiento dado. Posteriormente, cuando se invoca a cualquier gestor de grupo, el árbol de tareas activa el almacenamiento creado e inicializado, de modo que esté disponible dentro de cualquier gestor de grupo.

Véase también onStorageDone().

qsizetype QTaskTree::progressMaximum() const

Devuelve el máximo de progressValue().

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 finalizado, cancelado u omitido mientras se ejecuta el árbol de tareas. Cuando se inicia el árbol de tareas, este número es igual a 0. Cuando el árbol de tareas finaliza, este número siempre es igual a progressMaximum().

Véase 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. El value da el número total actual de tareas terminadas, 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 value inicial de 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 el value final de 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 con éxito; en caso contrario devuelve DoneWith::Error.

Véase también start().

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

Construye un árbol de tareas temporal utilizando el recipe pasado y lo ejecuta bloqueando.

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

Véase también start().

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

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

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

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

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

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

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

void QTaskTree::start()

Inicia el árbol de tareas.

Utilice 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, construido con un constructor por defecto, una llamada a start() es no-op y se emite el mensaje de advertencia correspondiente.

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

En caso contrario, se inicia el árbol de tareas.

El árbol de tareas iniciado puede finalizar de forma sincrónica, por ejemplo cuando el gestor de inicio del grupo principal devuelva SetupResult::StopWithError. Por esta razón, la conexión a la señal done debe establecerse antes de llamar a start(). Utilice isRunning() para detectar si el árbol de tareas sigue ejecutándose después de una llamada a start().

La implementación del árbol de tareas depende del bucle de eventos en ejecución. Asegúrese de que tiene un QEventLoop, QCoreApplication, o una de sus subclases en ejecución (o a punto de ejecutarse) cuando llame a este método.

Ver 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. La emisión de esta señal es seguida sincrónicamente por la señal progressValueChanged() con un valor inicial 0.

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

qsizetype QTaskTree::taskCount() const

Devuelve el número de tareas asíncronas contenidas en la receta almacenada.

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