- Extending Qt Creator Manual
- TaskingSolution
- CustomTask
- Extending Qt Creator Manual 13.0.2

# CustomTask Class

template <typename Adapter> class Tasking::CustomTask

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

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

- List of all members, including inherited members

Note: All functions in this class are reentrant.

## Public Types

| Deleter
| Task
| TaskDoneHandler
| TaskSetupHandler

## Public Functions

| CustomTask(SetupHandler &&setup = TaskSetupHandler(), DoneHandler &&done = TaskDoneHandler(), Tasking::CallDoneIf callDoneIf = CallDoneIf::SuccessOrError)

## Detailed Description

Describes custom task items within task tree recipes.

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 example custom tasks and their associated task classes:

Aliased Task Name (Tasking Namespace) | Associated Task Class | Brief Description
--- | --- | ---
ConcurrentCallTask<ReturnType> | ConcurrentCall<ReturnType> | Starts an asynchronous task. Runs in a separate thread.
NetworkQueryTask | NetworkQuery | Sends a network query.
TaskTreeTask | TaskTree | Starts a nested task tree.
TimeoutTask | `std::chrono::milliseconds` | Starts a timer.
WaitForBarrierTask | MultiBarrier<Limit> | Starts an asynchronous task waiting for the barrier to pass.

## Member Type Documentation

### `[alias]` CustomTask::Deleter

Type alias for the task's type deleter associated with the custom task's `Adapter`.

### `[alias]` CustomTask::Task

Type alias for the task type associated with the custom task's `Adapter`.

### `[alias]` CustomTask::TaskDoneHandler

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

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

See also CustomTask(), TaskSetupHandler, and GroupDoneHandler.

### `[alias]` CustomTask::TaskSetupHandler

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

The `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 TaskTree, otherwise the behavior is undefined.

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 CustomTask(), TaskDoneHandler, and GroupSetupHandler.

## Member Function Documentation

### template <typename SetupHandler, typename DoneHandler> CustomTask::CustomTask(SetupHandler &&setup = TaskSetupHandler(), DoneHandler &&done = TaskDoneHandler(), Tasking::CallDoneIf callDoneIf = CallDoneIf::SuccessOrError)

Constructs a `CustomTask` 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](ConcurrentCall<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](ConcurrentCall<void> &task) {
         task.setConcurrentCallData(parseAndLog, input);
     };

     const Group group {
         ConcurrentCallTask<void>(onFirstSetup),
         ConcurrentCallTask<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 callDoneIf argument when you want the handler to be called only on a successful or failed execution.

See also TaskSetupHandler and TaskDoneHandler.