En esta página

QtTaskTree::QCustomTask Class

template <typename Task, typename Adapter, typename Deleter> class QtTaskTree::QCustomTask

Una plantilla de clase que se utiliza para declarar elementos de tareas personalizadas y definir sus controladores de inicio y finalización. 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: QtTaskTree::ExecutableItem
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.

Tipos públicos

Funciones públicas

QCustomTask(SetupHandler &&setup = QCustomTask::TaskSetupHandler(), DoneHandler &&done = QCustomTask::TaskDoneHandler(), QtTaskTree::CallDone callDone = QtTaskTree::CallDoneFlag::Always)

Descripción detallada

Describe los elementos de tareas personalizadas dentro de las recetas del árbol de tareas.

Los nombres de las tareas personalizadas se asocian a alias con nombres únicos mediante la plantilla `QCustomTask`, con los parámetros ` Task`, ` Adapter ` y ` Deleter`. Por ejemplo, ` QThreadFunctionTask<T>` es un alias de la clase `QCustomTask` definida para funcionar con ` QThreadFunction<T>` como clase de tarea asociada. La siguiente tabla contiene las tareas personalizadas proporcionadas por la biblioteca `TaskTree` y sus clases de tarea asociadas:

Nombre de la tarea con aliasClase de tarea asociadaBreve descripción
QBarrierTaskQBarrierInicia una tarea de espera.
QThreadFunctionTask<ReturnType>QThreadFunction<TipoDeDevolución>Inicia una tarea asíncrona. Se ejecuta en un hilo independiente.
QProcessTaskQProcessInicia un proceso.
QNetworkReplyWrapperTaskQNetworkReplyWrapperEnvía una consulta de red.
QTaskTreeTaskQTaskTreeInicia un árbol de tareas anidado.
QTcpSocketWrapperTaskQTcpSocketWrapperEstablece una conexión TCP.
QTimeoutTaskstd::chrono::millisecondsInicia un temporizador.

El parámetro de plantilla « Task » es obligatorio y especifica qué tipo de ` Task ` instanciará la clase ` QTaskTree ` en ejecución cuando forme parte de una receta. El tipo ` Task ` debe poder construirse de forma predeterminada.

El argumento de plantilla ` Adapter ` es opcional. Se puede omitir si ` QDefaultTaskAdapter<Task>` se adapta correctamente al tipo ` Task `. De lo contrario, el ` Adapter ` para determinados ` Task ` debe tener la siguiente forma:

class Adapter
{
public:
    void operator()(Task *task, QTaskInterface *iface) { ... }
};

Implementa el operador() anterior para iniciar el task y llama al método QTaskInterface::reportDone() sobre el iface pasado cuando la tarea haya finalizado.

Se garantiza que tanto el Task como el QTaskInterface pasados perduran más que el Adapter. Si es necesario, el destructor de Adapter podrá seguir accediendo al Task pasado.

Para más detalles, véase QTaskInterface.

El argumento de plantilla Deleter es opcional. Por defecto, se utiliza std::default_delete<Task>. El eliminador personalizado Deleter resulta útil cuando el destructor de la tarea en ejecución Task podría bloquear el hilo de llamada. En lugar de bloquear, el eliminador personalizado puede trasladar la tarea en ejecución a un hilo independiente e implementar allí la destrucción con bloqueo. De este modo, se puede lograr la destrucción rápida (desde el punto de vista del hilo de llamada) de la tarea en ejecución con un destructor que bloquea.

Véase también QTaskInterface.

Documentación sobre tipos de miembro

[alias] QCustomTask::TaskDoneHandler

Alias de tipo para ` std::function<QtTaskTree::DoneResult(const Task &, QtTaskTree::DoneWith)> ` o ` DoneResult`.

TaskDoneHandler es un argumento opcional del constructor de un elemento de tarea personalizado. Cualquier función con la firma anterior, cuando se pase como controlador de finalización de tarea, será llamada por el árbol de tareas en ejecución una vez finalizada la ejecución de la tarea y antes de que el resultado final de la ejecución se comunique al grupo principal.

Dentro del cuerpo del controlador, puedes recuperar los datos finales de la tarea finalizada. Los parámetros adicionales, incluidos los almacenes, pueden pasarse al controlador mediante la captura lambda. También es posible decidir dinámicamente si la tarea debe finalizar con su valor de retorno o si el resultado final debe modificarse.

El argumento ` DoneWith ` es opcional y su controlador de finalización puede omitirlo. Cuando se proporciona, contiene la información sobre el resultado final de una tarea que se comunicará a su padre.

Si no tiene previsto leer ningún dato de la tarea finalizada, puede omitir el argumento ` const Task & `.

El valor devuelto de ` DoneResult ` es opcional y su manejador puede devolver ` void ` en su lugar. En este caso, el resultado final de la tarea será igual al valor indicado por el argumento ` DoneResult `. Cuando el manejador devuelve el valor ` DoneResult `, el resultado final de la tarea puede modificarse dentro del cuerpo del manejador `done` mediante el valor devuelto.

En el caso de un `TaskDoneHandler` del tipo ` DoneResult `, no se ejecuta ningún tratamiento adicional y la tarea finaliza incondicionalmente con el valor pasado en ` DoneResult`.

Véase también QCustomTask(), TaskSetupHandler y GroupDoneHandler.

[alias] QCustomTask::TaskSetupHandler

Alias de tipo para ` std::function<SetupResult(Task &)>`.

TaskSetupHandler es un argumento opcional del constructor de un elemento de tarea personalizado. Cualquier función con la firma anterior, cuando se pase como gestor de configuración de tareas, será llamada por el árbol de tareas en ejecución después de que se haya creado la tarea y antes de que se inicie.

Dentro del cuerpo del controlador, puedes configurar la tarea según tus necesidades. Los parámetros adicionales, incluidos los almacenes, pueden pasarse al controlador mediante la captura lambda. Puedes decidir dinámicamente si la tarea debe iniciarse o omitirse, tanto en caso de éxito como de error.

Nota: No inicies la tarea tú mismo dentro del controlador de inicio. Déjalo en manos de QTaskTree; de lo contrario, el comportamiento será indefinido. QTaskTree ya sabe cómo iniciar la tarea gracias al parámetro de plantilla «Adapter» pasado al constructor de QCustomTask<Task, Adapter, Deleter>.

El valor de retorno del controlador indica al árbol de tareas en ejecución cómo proceder una vez finalizada la invocación del controlador. El valor de retorno de ` SetupResult::Continue ` indica al árbol de tareas que continúe ejecutándose, es decir, que ejecute el ` Task` asociado. El valor de retorno de ` SetupResult::StopWithSuccess ` o ` SetupResult::StopWithError ` indica al árbol de tareas que omita la ejecución de la tarea y la finalice inmediatamente con éxito o con un error, respectivamente.

Cuando el tipo de retorno es SetupResult::StopWithSuccess o SetupResult::StopWithError, el controlador «done» de la tarea (si se ha proporcionado) no se invoca posteriormente.

El constructor de una tarea personalizada también acepta funciones en la forma abreviada de ` std::function<void(Task &)>`, es decir, el valor de retorno es ` void`. En este caso, se da por hecho que el valor de retorno es ` SetupResult::Continue`.

Véase también QCustomTask(), TaskDoneHandler y GroupSetupHandler.

Documentación de funciones miembro

[explicit] template < typename SetupHandler = QtTaskTree::QCustomTask<Task, Adapter, Deleter>::TaskSetupHandler, typename DoneHandler = QtTaskTree::QCustomTask<Task, Adapter, Deleter>::TaskDoneHandler, std::enable_if_t<!std::is_same_v<q20::remove_cvref_t<SetupHandler>, QCustomTask<Task, Adapter, Deleter>>, bool> = true > QCustomTask::QCustomTask(SetupHandler &&setup = QCustomTask::TaskSetupHandler(), DoneHandler &&done = QCustomTask::TaskDoneHandler(), QtTaskTree::CallDone callDone = QtTaskTree::CallDoneFlag::Always)

Crea una instancia de QCustomTask y asocia los controladores setup y done a la tarea. Cuando el árbol de tareas en ejecución está a punto de iniciar la tarea, instancia el objeto Task asociado, invoca el controlador setup con una referencia a la tarea creada y la inicia. Cuando la tarea en ejecución finaliza, el árbol de tareas invoca el controlador done, con una referencia const a la tarea creada.

El controlador setup que se pasa es de tipo TaskSetupHandler. Por ejemplo:

static void parseAndLog(const QString &input);

...

const QString input = ...;

const auto onFirstSetup = [input](QThreadFunction<void> &task) {
    if (input == "Skip")
        return SetupResult::StopWithSuccess; // This task won't start, the next one will
    if (input == "Error")
        return SetupResult::StopWithError; // This task and the next one won't start
    task.setThreadFunctionData(parseAndLog, input);
    // This task will start, and the next one will start after this one finished with success
    return SetupResult::Continue;
};

const auto onSecondSetup = [input](QThreadFunction<void> &task) {
    task.setThreadFunctionData(parseAndLog, input);
};

const Group group {
    QThreadFunctionTask<void>(onFirstSetup),
    QThreadFunctionTask<void>(onSecondSetup)
};

El controlador ` done ` es de tipo ` TaskDoneHandler `. De forma predeterminada, el controlador ` done ` se invoca cada vez que finaliza la tarea. Pase un valor no predeterminado para el argumento ` callDone ` cuando desee que el controlador se llame únicamente en caso de ejecución correcta, fallida o cancelada.

Véase también TaskSetupHandler y TaskDoneHandler.

Elementos no miembros relacionados

[alias] QBarrierTask

Alias de tipo para el tipo « QCustomTask » <QBarrier>, para su uso en recetas.

[alias] QNetworkReplyWrapperTask

Alias de tipo para el tipo « QCustomTask » <QNetworkReplyWrapper>, para su uso en recetas.

[alias] QProcessTask

Alias de tipo para el ` QCustomTask` <QProcess>, utilizando ` QProcessTaskDeleter`, para su uso dentro de recetas.

[alias] QTaskTreeTask

Alias de tipo para el tipo « QCustomTask » <QTaskTree>, para su uso en recetas.

[alias] QTcpSocketWrapperTask

Alias de tipo para el tipo « QCustomTask » <QTcpSocketWrapper>, para su uso en recetas.

[alias] template <typename ResultType> QThreadFunctionTask

Alias de tipo para QCustomTask<QThreadFunction<ResultType>>, donde ResultType especifica el tipo de retorno de la función del hilo, para su uso dentro de las recetas.

[alias] QTimeoutTask

Alias de tipo para la clase ` QCustomTask` <std::chrono::milliseconds>, para su uso en recetas. El ` std::chrono::milliseconds ` se utiliza para configurar la duración del tiempo de espera. El tiempo de espera por defecto es ` std::chrono::milliseconds::zero()`, es decir, la clase `QTimeoutTask` finaliza tan pronto como el control vuelve al bucle de eventos en ejecución.

Ejemplo de uso:

using namespace std::chrono;
using namespace std::chrono_literals;

const auto onSetup = [](milliseconds &timeout) { timeout = 1000ms; }
const auto onDone = [] { qDebug() << "Timed out."; }

const Group root {
    QTimeoutTask(onSetup, onDone)
};

Véase también timeoutTask().

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