Back to Doc.qt.io
Contact Us Blog Download Qt

QCustomTask Class

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

A class template used for declaring custom task items and defining their setup and done handlers. More...

Header: #include <qtasktree.h>
Inherits: QtTaskTree::ExecutableItem

Note: All functions in this class are reentrant.

Public Types

TaskDoneHandler
TaskSetupHandler

Public Functions

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

Detailed Description

Describes custom task items within task tree recipes.

Custom task names are aliased with unique names using the QCustomTask template with a given Task, Adapter and Deleter. For example, QConcurrentCallTask<T> is an alias to the QCustomTask that is defined to work with QConcurrentCall<T> as an associated task class. The following table contains custom tasks provided by the TaskTree library and their associated task classes:

Aliased Task NameAssociated Task ClassBrief Description
QBarrierTaskQBarrierStarts an awaiter task.
QConcurrentCallTask<ReturnType>QConcurrentCall<ReturnType>Starts an asynchronous task. Runs in a separate thread.
QProcessTaskQProcessStarts a process.
QNetworkReplyWrapperTaskQNetworkReplyWrapperSends a network query.
QTaskTreeTaskQTaskTreeStarts a nested task tree.
QTcpSocketWrapperTaskQTcpSocketWrapperEstablishes TCP connection.
QTimeoutTaskstd::chrono::millisecondsStarts a timer.

The Task template parameter is mandatory, and specifies what type of Task the running QTaskTree will instantiate when it's a part of recipe. The Task type needs to be default constructible.

The Adapter template argument is optional. It may be skipped if QDefaultTaskAdapter<Task> is fine to adapt the Task type. Otherwise, the Adapter for certain Task needs to have the following form:

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

Implement the operator() above to start the task, and call QTaskInterface::reportDone() method on the passed iface when the task is finished.

It is guaranteed the passed Task and QTaskInterface outlives the Adapter. If necessary, the destructor of Adapter may still access the passed Task.

For more details see QTaskInterface.

The Deleter template argument is optional. By default, the std::default_delete<Task> is used. The custom Deleter is useful when the destructor of the running Task may potentially block the caller thread. Instead of blocking, the custom deleter may move the running task into a separate thread and implement the blocking destruction there. In this way, the fast destruction (seen from the caller thread) of the running task with a blocking destructor may be achieved.

See also QTaskInterface.

Member Type Documentation

[alias] QCustomTask::TaskDoneHandler

Type alias for std::function<QtTaskTree::DoneResult(const Task &, QtTaskTree::DoneWith)> or DoneResult.

The TaskDoneHandler is an optional argument of a custom task element's constructor. Any function with the above signature, when passed as a task done handler, will be called by the running task tree after the task execution finished and before the final result of the execution is reported back to the parent group.

Inside the body of the handler you may retrieve the final data from the finished task. The additional parameters, including storages, may be passed to the handler via the lambda capture. It is also possible to decide dynamically whether the task should finish with its return value, or the final result should be tweaked.

The DoneWith argument is optional and your done handler may omit it. When provided, it holds the info about the final result of a task that will be reported to its parent.

If you do not plan to read any data from the finished task, you may omit the const Task & argument.

The returned DoneResult value is optional and your handler may return void instead. In this case, the final result of the task will be equal to the value indicated by the DoneResult argument. When the handler returns the DoneResult value, the task's final result may be tweaked inside the done handler's body by the returned value.

For a TaskDoneHandler of the DoneResult type, no additional handling is executed, and the task finishes unconditionally with the passed value of DoneResult.

See also QCustomTask(), TaskSetupHandler, and GroupDoneHandler.

[alias] QCustomTask::TaskSetupHandler

Type alias for std::function<SetupResult(Task &)>.

TaskSetupHandler is an optional argument of a custom task element's constructor. Any function with the above signature, when passed as a task setup handler, will be called by the running task tree after the task is created and before it is started.

Inside the body of the handler, you may configure the task according to your needs. The additional parameters, including storages, may be passed to the handler via the lambda capture. You can decide dynamically whether the task should be started or skipped with success or an error.

Note: Do not start the task inside the start handler by yourself. Leave it for QTaskTree, otherwise the behavior is undefined. QTaskTree already knows how to start the task thanks to the Adapter template parameter passed to the QCustomTask<Task, Adapter, Deleter> constructor.

The return value of the handler instructs the running task tree on how to proceed after the handler's invocation is finished. The return value of SetupResult::Continue instructs the task tree to continue running, that is, to execute the associated Task. The return value of SetupResult::StopWithSuccess or SetupResult::StopWithError instructs the task tree to skip the task's execution and finish it immediately with success or an error, respectively.

When the return type is either SetupResult::StopWithSuccess or SetupResult::StopWithError, the task's done handler (if provided) isn't called afterwards.

The constructor of a custom task accepts also functions in the shortened form of std::function<void(Task &)>, that is, the return value is void. In this case, it's assumed that the return value is SetupResult::Continue.

See also QCustomTask(), TaskDoneHandler, and GroupSetupHandler.

Member Function Documentation

template <typename SetupHandler = QCustomTask<Task, Adapter, Deleter>::TaskSetupHandler, typename DoneHandler = QCustomTask<Task, Adapter, Deleter>::TaskDoneHandler> QCustomTask::QCustomTask(SetupHandler &&setup = QCustomTask::TaskSetupHandler(), DoneHandler &&done = QCustomTask::TaskDoneHandler(), QtTaskTree::CallDoneFlags callDone = QtTaskTree::CallDone::Always)

Constructs a QCustomTask instance and attaches the setup and done handlers to the task. When the running task tree is about to start the task, it instantiates the associated Task object, invokes setup handler with a reference to the created task, and starts it. When the running task finishes, the task tree invokes a done handler, with a const reference to the created task.

The passed setup handler is of the TaskSetupHandler type. For example:

static void parseAndLog(const QString &input);

...

const QString input = ...;

const auto onFirstSetup = [input](QConcurrentCall<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.setConcurrentCallData(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](QConcurrentCall<void> &task) {
    task.setConcurrentCallData(parseAndLog, input);
};

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

The done handler is of the TaskDoneHandler type. By default, the done handler is invoked whenever the task finishes. Pass a non-default value for the callDone argument when you want the handler to be called only on a successful, failed, or canceled execution.

See also TaskSetupHandler and TaskDoneHandler.

Related Non-Members

[alias] QBarrierTask

Type alias for the QCustomTask<QBarrier>, to be used inside recipes.

[alias] template <typename ResultType> QConcurrentCallTask

Type alias for the QCustomTask<QConcurrentCall<ResultType>>, to be used inside recipes.

[alias] QNetworkReplyWrapperTask

Type alias for the QCustomTask<QNetworkReplyWrapper>, to be used inside recipes.

[alias] QProcessTask

Type alias for the QCustomTask<QProcess>, using QProcessDeleter, to be used inside recipes.

[alias] QTaskTreeTask

Type alias for the QCustomTask<QTaskTree>, to be used inside recipes.

[alias] QTcpSocketWrapperTask

Type alias for the QCustomTask<QTcpSocketWrapper>, to be used inside recipes.

[alias] QTimeoutTask

Type alias for the QCustomTask<std::chrono::milliseconds>, to be used inside recipes. The std::chrono::milliseconds is used to set up the timeout duration. The default timeout is std::chrono::milliseconds::zero(), that is, the QTimeoutTask finishes as soon as the control returns to the running event loop.

Example usage:

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)
};

See also timeoutTask().

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