- Extending Qt Creator Manual
- Tasking Namespace
- Extending Qt Creator Manual 11.0.2

# Tasking Namespace

The Tasking namespace encloses all classes and global functions of the Tasking solution. More...

Header: | #include <Tasking>

## Classes

class | CustomTask
class | Group
class | GroupItem
class | TaskAdapter
class | TaskInterface
class | TaskTree

## Types

enum class | SetupResult { Continue, StopWithDone, StopWithError }
enum class | WorkflowPolicy { StopOnError, ContinueOnError, StopOnDone, ContinueOnDone, StopOnFinished, …, FinishAllAndError }

## Variables

const Tasking::GroupItem | continueOnDone
const Tasking::GroupItem | continueOnError
const Tasking::GroupItem | finishAllAndDone
const Tasking::GroupItem | finishAllAndError
const Tasking::GroupItem | parallel
const Tasking::GroupItem | sequential
const Tasking::GroupItem | stopOnDone
const Tasking::GroupItem | stopOnError
const Tasking::GroupItem | stopOnFinished

## Functions

Tasking::GroupItem | onGroupDone(const GroupItem::GroupEndHandler &handler)
Tasking::GroupItem | onGroupError(const GroupItem::GroupEndHandler &handler)
Tasking::GroupItem | onGroupSetup(SetupHandler &&handler)
Tasking::GroupItem | parallelLimit(int limit)
Tasking::GroupItem | workflowPolicy(Tasking::WorkflowPolicy policy)

## Macros

| TASKING_DECLARE_TASK(CustomTaskName, TaskAdapterClass)
| TASKING_DECLARE_TEMPLATE_TASK(CustomTaskName, TaskAdapterClass)

## Detailed Description

## Classes

### class CustomTask

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

### class Group

Group represents the basic element for composing declarative recipes describing how to execute and handle a nested tree of asynchronous tasks. More...

### class GroupItem

GroupItem represents the basic element that may be a part of any Group. More...

### class TaskAdapter

A class template for implementing custom task adapters. More...

### class TaskInterface

TaskInterface is the abstract base class for implementing custom task adapters. More...

### class TaskTree

The TaskTree class runs an async task tree structure defined in a declarative way. More...

## Type Documentation

### enum class Tasking::SetupResult

This enum is optionally returned from the group's or task's setup handler function. It instructs the running task tree on how to proceed after the setup handler's execution finished.

Constant | Value | Description
--- | --- | ---
`Tasking::SetupResult::Continue` | `0` | Default. The group's or task's execution continues normally. When a group's or task's setup handler returns void, it's assumed that it returned Continue.
`Tasking::SetupResult::StopWithDone` | `1` | The group's or task's execution stops immediately with success. When returned from the group's setup handler, all child tasks are skipped, and the group's onGroupDone() handler is invoked (if provided). The group reports success to its parent. The group's workflow policy is ignored. When returned from the task's setup handler, the task isn't started, its done handler isn't invoked, and the task reports success to its parent.
`Tasking::SetupResult::StopWithError` | `2` | The group's or task's execution stops immediately with an error. When returned from the group's setup handler, all child tasks are skipped, and the group's onGroupError() handler is invoked (if provided). The group reports an error to its parent. The group's workflow policy is ignored. When returned from the task's setup handler, the task isn't started, its error handler isn't invoked, and the task reports an error to its parent.

### enum class Tasking::WorkflowPolicy

This enum describes the possible behavior of the Group element when any group's child task finishes its execution. It's also used when the running Group is stopped.

Constant | Value | Description
--- | --- | ---
`Tasking::WorkflowPolicy::StopOnError` | `0` | Default. Corresponds to the stopOnError global element. If any child task finishes with an error, the group stops and finishes with an error. If all child tasks finished with success, the group finishes with success. If a group is empty, it finishes with success.
`Tasking::WorkflowPolicy::ContinueOnError` | `1` | Corresponds to the continueOnError global element. Similar to stopOnError, but in case any child finishes with an error, the execution continues until all tasks finish, and the group reports an error afterwards, even when some other tasks in the group finished with success. If all child tasks finish successfully, the group finishes with success. If a group is empty, it finishes with success.
`Tasking::WorkflowPolicy::StopOnDone` | `2` | Corresponds to the stopOnDone global element. If any child task finishes with success, the group stops and finishes with success. If all child tasks finished with an error, the group finishes with an error. If a group is empty, it finishes with an error.
`Tasking::WorkflowPolicy::ContinueOnDone` | `3` | Corresponds to the continueOnDone global element. Similar to stopOnDone, but in case any child finishes successfully, the execution continues until all tasks finish, and the group reports success afterwards, even when some other tasks in the group finished with an error. If all child tasks finish with an error, the group finishes with an error. If a group is empty, it finishes with an error.
`Tasking::WorkflowPolicy::StopOnFinished` | `4` | Corresponds to the stopOnFinished global element. The group starts as many tasks as it can. When any task finishes, the group stops and reports the task's result. Useful only in parallel mode. In sequential mode, only the first task is started, and when finished, the group finishes too, so the other tasks are always skipped. If a group is empty, it finishes with an error.
`Tasking::WorkflowPolicy::FinishAllAndDone` | `5` | Corresponds to the finishAllAndDone global element. The group executes all tasks and ignores their return results. When all tasks finished, the group finishes with success. If a group is empty, it finishes with success.
`Tasking::WorkflowPolicy::FinishAllAndError` | `6` | Corresponds to the finishAllAndError global element. The group executes all tasks and ignores their return results. When all tasks finished, the group finishes with an error. If a group is empty, it finishes with an error.

Whenever a child task's result causes the Group to stop, i.e. in case of StopOnError, StopOnDone, or StopOnFinished policies, the Group stops the other running child tasks (if any - for example in parallel mode), and skips executing tasks it has not started yet (for example, in the sequential mode - those, that are placed after the failed task). Both stopping and skipping child tasks may happen when parallelLimit() is used.

The table below summarizes the differences between various workflow policies:

WorkflowPolicy | Executes all child tasks | Result | Result when the group is empty
--- | --- | --- | ---
StopOnError | Stops when any child task finished with an error and reports an error | An error when at least one child task failed, success otherwise | Success
ContinueOnError | Yes | An error when at least one child task failed, success otherwise | Success
StopOnDone | Stops when any child task finished with success and reports success | Success when at least one child task succeeded, an error otherwise | An error
ContinueOnDone | Yes | Success when at least one child task succeeded, an error otherwise | An error
StopOnFinished | Stops when any child task finished and reports child task's result | Success or an error, depending on the finished child task's result | An error
FinishAllAndDone | Yes | Success | Success
FinishAllAndError | Yes | An error | An error

If a child of a group is also a group, the child group runs its tasks according to its own workflow policy. When a parent group stops the running child group because of parent group's workflow policy, i.e. when the StopOnError, StopOnDone, or StopOnFinished policy was used for the parent, the child group's result is reported according to the Result column and to the child group's workflow policy row in the table above.

## Variable Documentation

### const Tasking::GroupItem Tasking::continueOnDone

A convenient global group's element describing the ContinueOnDone workflow policy.

### const Tasking::GroupItem Tasking::continueOnError

A convenient global group's element describing the ContinueOnError workflow policy.

### const Tasking::GroupItem Tasking::finishAllAndDone

A convenient global group's element describing the FinishAllAndDone workflow policy.

### const Tasking::GroupItem Tasking::finishAllAndError

A convenient global group's element describing the FinishAllAndError workflow policy.

### const Tasking::GroupItem Tasking::parallel

A convenient global group's element describing the parallel execution mode.

All the direct child tasks of a group are started after the group is started, without waiting for the previous child tasks to finish. In this mode, all child tasks run simultaneously.

See also sequential and parallelLimit().

### const Tasking::GroupItem Tasking::sequential

A convenient global group's element describing the sequential execution mode.

This is the default execution mode of the Group element.

When a Group has no execution mode, it runs in the sequential mode. All the direct child tasks of a group are started in a chain, so that when one task finishes, the next one starts. This enables you to pass the results from the previous task as input to the next task before it starts. This mode guarantees that the next task is started only after the previous task finishes.

See also parallel and parallelLimit().

### const Tasking::GroupItem Tasking::stopOnDone

A convenient global group's element describing the StopOnDone workflow policy.

### const Tasking::GroupItem Tasking::stopOnError

A convenient global group's element describing the StopOnError workflow policy.

This is the default workflow policy of the Group element.

### const Tasking::GroupItem Tasking::stopOnFinished

A convenient global group's element describing the StopOnFinished workflow policy.

## Function Documentation

### Tasking::GroupItem Tasking::onGroupDone(const GroupItem::GroupEndHandler &handler)

Constructs a group's element holding the group done handler. The handler is invoked whenever the group finishes with success. Depending on the group's workflow policy, this handler may also be called when the running group is stopped (e.g. when finishAllAndDone element was used).

When the handler is invoked, all of the group's child tasks are already finished.

If a group contains the Storage elements, the handler is invoked before the storages are destructed, so that the handler may still perform a last read of the active storages' data.

See also GroupItem::GroupEndHandler, onGroupSetup(), and onGroupError().

### Tasking::GroupItem Tasking::onGroupError(const GroupItem::GroupEndHandler &handler)

Constructs a group's element holding the group error handler. The handler is invoked whenever the group finishes with an error. Depending on the group's workflow policy, this handler may also be called when the running group is stopped (e.g. when stopOnError element was used).

When the handler is invoked, all of the group's child tasks are already finished.

If a group contains the Storage elements, the handler is invoked before the storages are destructed, so that the handler may still perform a last read of the active storages' data.

See also GroupItem::GroupEndHandler, onGroupSetup(), and onGroupDone().

### template <typename SetupHandler> Tasking::GroupItem Tasking::onGroupSetup(SetupHandler &&handler)

Constructs a group's element holding the group setup handler. The handler is invoked whenever the group starts.

The passed handler is either of `std::function<SetupResult()>` or `std::function<void()>` type. For more information on possible argument type, refer to GroupItem::GroupSetupHandler.

When the handler is invoked, none of the group's child tasks are running yet.

If a group contains the Storage elements, the handler is invoked after the storages are constructed, so that the handler may already perform some initial modifications to the active storages.

See also GroupItem::GroupSetupHandler, onGroupDone(), and onGroupError().

### Tasking::GroupItem Tasking::parallelLimit(int limit)

Constructs a group's element describing the execution mode.

The execution mode element in a Group specifies how the direct child tasks of the Group are started.

For convenience, when appropriate, the sequential or parallel global elements may be used instead.

The limit defines the maximum number of direct child tasks running in parallel:

- When limit equals to 0, there is no limit, and all direct child tasks are started together, in the oder in which they appear in a group. This means the fully parallel execution, and the parallel element may be used instead.
- When limit equals to 1, it means that only one child task may run at the time. This means the sequential execution, and the sequential element may be used instead. In this case child tasks run in chain, so the next child task starts after the previous child task has finished.
- When other positive number is passed as limit, the group's child tasks run in parallel, but with a limited number of tasks running simultanously. The limit defines the maximum number of tasks running in parallel in a group. When the group is started, the first batch of tasks is started (the number of tasks in a batch equals to the passed limit, at most), while the others are kept waiting. When any running task finishes, the group starts the next remaining one, so that the limit of simultaneously running tasks inside a group isn't exceeded. This repeats on every child task's finish until all child tasks are started. This enables you to limit the maximum number of tasks that run simultaneously, for example if running too many processes might block the machine for a long time.

In all execution modes, a group starts tasks in the oder in which they appear.

If a child of a group is also a group, the child group runs its tasks according to its own execution mode.

See also sequential and parallel.

### Tasking::GroupItem Tasking::workflowPolicy(Tasking::WorkflowPolicy policy)

Constructs a group's workflow policy element for a given policy.

For convenience, global elements may be used instead.

See also stopOnError, continueOnError, stopOnDone, continueOnDone, stopOnFinished, finishAllAndDone, finishAllAndError, and WorkflowPolicy.

## Macro Documentation

### TASKING_DECLARE_TASK(CustomTaskName, TaskAdapterClass)

Registers the new custom task type under a CustomTaskName name inside the Tasking namespace for the passed TaskAdapterClass adapter class.

For more information on implementing the custom task adapters, refer to Task Adapters.

### TASKING_DECLARE_TEMPLATE_TASK(CustomTaskName, TaskAdapterClass)

Registers the new custom task template type under a CustomTaskName name inside the Tasking namespace for the passed TaskAdapterClass adapter class template.

For more information on implementing the custom task adapters, refer to Task Adapters.