Back to Qt.io
Contact Us Blog Download Qt
En esta página

QtTaskTree::QCustomTask Class

template <typename Task, typename Adapter = QtTaskTree::QDefaultTaskAdapter<Task>, typename Deleter = std::default_delete<Task>> class QtTaskTree::QCustomTask

Una plantilla de clase utilizada para declarar elementos de tarea personalizados y definir sus controladores de configuración y finalización. Más...

Cabecera: #include <qtasktree.h>
CMake: find_package(Qt6 REQUIRED COMPONENTS TaskTree)
target_link_libraries(mytarget PRIVATE Qt6::TaskTree)
qmake: QT += tasktree
Desde: Qt 6.11
Hereda: QtTaskTree::ExecutableItem

Nota: Todas las funciones de esta clase son reentrantes.

Tipos Públicos

TaskDoneHandler
TaskSetupHandler

Funciones Públicas

QCustomTask(SetupHandler &&setup = QCustomTask::TaskSetupHandler(), DoneHandler &&done = QCustomTask::TaskDoneHandler(), QtTaskTree::CallDone callDone = QtTaskTree::CallDoneFlag::Always)
QBarrierTask
QNetworkReplyWrapperTask
QProcessTask
QTaskTreeTask
QTcpSocketWrapperTask
QThreadFunctionTask
QTimeoutTask

Descripción Detallada

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

Los nombres de tareas personalizadas se aliasan con nombres únicos utilizando la plantilla QCustomTask con una Tarea, Adaptador y Eliminador determinados. Por ejemplo, QThreadFunctionTask<T> es un alias de la QCustomTask que se define para trabajar con QThreadFunction<T> como clase de tarea asociada. La siguiente tabla contiene tareas personalizadas proporcionadas por la biblioteca TaskTree y sus clases de tareas asociadas:

Nombre de la tarea aliasClase de tarea asociadaBreve descripción
QBarrierTaskQBarrierInicia una tarea awaiter.
QThreadFunctionTask<Tipo de retorno>QThreadFunction<Tipo de retorno>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 anidadas.
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á el QTaskTree en ejecución cuando forme parte de la receta. El tipo Task debe ser construible por defecto.

El argumento Adapter template es opcional. Puede omitirse si QDefaultTaskAdapter<Tarea> está bien para adaptar el tipo Task. De lo contrario, el Adapter para ciertos Task necesita tener la siguiente forma:

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

Implementar el operador() anterior para iniciar la task, y llamar al método QTaskInterface::reportDone() en el iface pasado cuando la tarea haya terminado.

Se garantiza que Task y QTaskInterface pasados sobreviven a Adapter. Si es necesario, el destructor de Adapter aún puede acceder a 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 Deleter personalizado es útil cuando el destructor del Task en ejecución puede potencialmente bloquear el hilo llamador. En lugar de bloquear, el destructor personalizado puede mover la tarea en ejecución a un hilo separado e implementar allí la destrucción bloqueante. De esta manera, se puede lograr la destrucción rápida (vista desde el hilo llamador) de la tarea en ejecución con un destructor bloqueante.

Véase también QTaskInterface.

Documentación de tipos de miembros

[alias] QCustomTask::TaskDoneHandler

Tipo de alias para std::function<QtTaskTree::DoneResult(const Task &, QtTaskTree::DoneWith)> o DoneResult.

El TaskDoneHandler es un argumento opcional del constructor de un elemento de tarea personalizado. Cualquier función con la firma anterior, cuando se pasa como un manejador de tarea terminada, será llamada por el árbol de tareas en ejecución después de que la ejecución de la tarea haya terminado y antes de que el resultado final de la ejecución sea reportado al grupo padre.

Dentro del cuerpo del manejador se pueden recuperar los datos finales de la tarea finalizada. Los parámetros adicionales, incluidos los almacenamientos, pueden pasarse al manejador a través de la captura lambda. También es posible decidir dinámicamente si la tarea debe terminar con su valor de retorno, o si el resultado final debe ser retocado.

El argumento DoneWith es opcional y el gestor de tareas realizadas 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 DoneResult es opcional y su gestor 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 ser ajustado dentro del cuerpo del manejador hecho por el valor devuelto.

Para un TaskDoneHandler del tipo DoneResult, no se ejecuta ninguna manipulación adicional, y la tarea finaliza incondicionalmente con el valor pasado de 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 pasa como manejador de configuración de tarea, será llamada por el árbol de tareas en ejecución después de que se cree la tarea y antes de que se inicie.

Dentro del cuerpo del manejador, puede configurar la tarea según sus necesidades. Los parámetros adicionales, incluyendo los almacenamientos, pueden ser pasados al manejador a través de la captura lambda. Puede decidir dinámicamente si la tarea debe iniciarse o saltarse con éxito o con un error.

Nota: No inicie usted mismo la tarea dentro del manejador de inicio. Déjelo para QTaskTree, de lo contrario el comportamiento es indefinido. QTaskTree ya sabe cómo iniciar la tarea gracias al parámetro de plantilla Adapter pasado al constructor QCustomTask<Task, Adapter, Deleter>.

El valor de retorno del manejador instruye al árbol de tareas en ejecución sobre cómo proceder una vez finalizada la invocación del manejador. 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 error, respectivamente.

Cuando el tipo de retorno es SetupResult::StopWithSuccess o SetupResult::StopWithError, no se llama al gestor de tareas realizadas (si se proporciona).

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 asume 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)

Construye una instancia de QCustomTask y adjunta los manejadores 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 al manejador setup con una referencia a la tarea creada, y la inicia. Cuando la tarea en ejecución finaliza, el árbol de tareas invoca un manejador done, con una referencia const a la tarea creada.

El manejador setup pasado es del 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 manejador done es del tipo TaskDoneHandler. Por defecto, el manejador done es invocado cada vez que la tarea termina. Pase un valor no predeterminado para el argumento callDone cuando desee que el manejador sea llamado sólo en una ejecución exitosa, fallida o cancelada.

Véase también TaskSetupHandler y TaskDoneHandler.

No miembros relacionados

[alias] QBarrierTask

Tipo de alias para el QCustomTask<QBarrier>, que se utilizará dentro de las recetas.

[alias] QNetworkReplyWrapperTask

Tipo de alias para el QCustomTask<QNetworkReplyWrapper>, que se utilizará dentro de las recetas.

[alias] QProcessTask

Escriba un alias para el QCustomTask<QProcess>, utilizando QProcessTaskDeleter, que se utilizará dentro de las recetas.

[alias] QTaskTreeTask

Tipo de alias para el QCustomTask<QTaskTree>, que se utilizará dentro de las recetas.

[alias] QTcpSocketWrapperTask

Tipo de alias para el QCustomTask<QTcpSocketWrapper>, que se utilizará dentro de las recetas.

[alias] template <typename ResultType> QThreadFunctionTask

Alias de tipo para el QCustomTask<QThreadFunction<ResultType>>, para ser utilizado dentro de recetas.

[alias] QTimeoutTask

Tipo de alias para el QCustomTask<std::chrono::milliseconds>, que se utilizará dentro de las recetas. El std::chrono::milliseconds se utiliza para establecer la duración del tiempo de espera. El tiempo de espera por defecto es std::chrono::milliseconds::zero(), es decir, la QTimeoutTask termina 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)
};

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