CustomTask Class

template <typename Adapter> class Tasking::CustomTask

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

Header: #include <solutions/tasking/tasktree.h>
Inherits: Tasking::GroupItem

Public Types

Public Functions

CustomTask(SetupHandler &&setup, const Tasking::CustomTask::EndHandler &done = {}, const Tasking::CustomTask::EndHandler &error = {})
CustomTask<Adapter> &onDone(const Tasking::CustomTask::EndHandler &handler)
CustomTask<Adapter> &onError(const Tasking::CustomTask::EndHandler &handler)
CustomTask<Adapter> &onSetup(SetupHandler &&handler)
Tasking::GroupItem withTimeout(std::chrono::milliseconds timeout, const Tasking::GroupItem::GroupEndHandler &handler = {}) const

Detailed Description

The CustomTask class template is used inside TaskTree for describing custom task items.

Custom task names are aliased with unique names using the CustomTask template with a given TaskAdapter subclass as a template parameter. For example, ConcurrentCallTask<T> is an alias to the CustomTask that is defined to work with ConcurrentCall<T> as an associated task class. The following table contains all the built-in tasks and their associated task classes:

Aliased Task Name (Tasking Namespace)Associated Task ClassBrief Description
ConcurrentCallTask<ReturnType>ConcurrentCall<ReturnType>Starts an asynchronous task. Runs in a separate thread.
NetworkQueryTaskNetworkQuerySends a network query.
TaskTreeTaskTaskTreeStarts a nested task tree.
TimeoutTaskstd::chrono::millisecondsStarts a timer.
WaitForBarrierTaskMultiBarrier<Limit>Starts an asynchronous task waiting for the barrier to pass.

Member Type Documentation

[alias] CustomTask::EndHandler

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

[alias] CustomTask::Task

Type alias for Adapter::Type.

This is the associated task's type.

Member Function Documentation

template <typename SetupHandler> CustomTask::CustomTask(SetupHandler &&setup, const Tasking::CustomTask::EndHandler &done = {}, const Tasking::CustomTask::EndHandler &error = {})

Constructs the CustomTask instance and attaches the setup, done, and error 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 with success or an error, the task tree invokes done or error handler, respectively, with a const reference to the created task.

The passed setup handler is either of the std::function<SetupResult(Task &)> or std::function<void(Task &)> type. For example:

static void parseAndLog(const QString &input);

...

const QString input = ...;

const auto onFirstSetup = [input](ConcurrentCall<void> &task) {
    if (input == "Skip")
        return SetupResult::StopWithDone; // 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](ConcurrentCall<void> &task) {
    task.setConcurrentCallData(parseAndLog, input);
};

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

When the passed setup handler is of the std::function<SetupResult(Task &)> type, the return value of the handler instructs the running tree on how to proceed after the handler's invocation is finished. The default return value of SetupResult::Continue instructs the tree to continue running, i.e. to execute the associated Task. The return value of SetupResult::StopWithDone or SetupResult::StopWithError instructs the tree to skip the task's execution and finish immediately with success or an error, respectively. When the return type is either SetupResult::StopWithDone or SetupResult::StopWithError, the task's done or error handler (even if provided) are not called afterwards.

The setup handler may be of a shortened form of std::function<void(Task &)>, i.e. the return value is void. In this case it's assumed that the return value is SetupResult::Continue by default.

When the running task finishes, one of done or error handlers is called, depending on whether it finished with success or an error, respectively. Both handlers are of std::function<void(const Task &)> type.

See also onSetup(), onDone(), and onError().

CustomTask<Adapter> &CustomTask::onDone(const Tasking::CustomTask::EndHandler &handler)

Attaches the done handler to this task. The handler is invoked when the task finishes with success.

This function enables defining the task's details with a fluent interface style.

See also CustomTask(), onSetup(), and onError().

CustomTask<Adapter> &CustomTask::onError(const Tasking::CustomTask::EndHandler &handler)

Attaches the error handler to this task. The handler is invoked when the task finishes with an error.

This function enables defining the task's details with a fluent interface style.

See also CustomTask(), onSetup(), and onDone().

template <typename SetupHandler> CustomTask<Adapter> &CustomTask::onSetup(SetupHandler &&handler)

Attaches the setup handler to this task. The handler is invoked when the task is about to be started.

This function enables defining the task's details with a fluent interface style:

const auto onQuerySetup = [](NetworkQuery &task) { ... };
const auto onQueryError = [](const NetworkQuery &task) { ... };

const Group group {
    NetworkQueryTask(onQuerySetup, {}, onQueryError),
    NetworkQueryTask().onSetup(onQuerySetup).onError(onQueryError), // fluent interface style
    NetworkQueryTask(onQuerySetup, {}, onQueryError).withTimeout(500ms)
}

See also CustomTask(), onDone(), and onError().

Tasking::GroupItem CustomTask::withTimeout(std::chrono::milliseconds timeout, const Tasking::GroupItem::GroupEndHandler &handler = {}) const

Attaches TimeoutTask to a copy of this task, elapsing after timeout in milliseconds, with an optionally provided timeout handler, and returns the coupled item.

When the task finishes before timeout passes, the returned item finishes immediately with the task's result. Otherwise, the handler is invoked (if provided), the task is stopped, and the returned item finishes with an error.

See also onSetup().

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