QtTaskTree Namespace | Extending Qt Creator Manual
Description: The QtTaskTree namespace encloses helper classes and global functions of the TaskTree module.

- Extending Qt Creator Manual
- QtTaskTree Namespace
- Extending Qt Creator Manual 19.0.0

# QtTaskTree Namespace

The QtTaskTree namespace encloses helper classes and global functions of the TaskTree module. More...

Header: | `#include <QtTaskTree>`

## Classes

class | Do
class | Else
class | ElseIf
class | ExecutionMode
class | For
class | Forever
class | ForeverIterator
class | Group
class | If
class | ListIterator
class | ParallelLimit
class | RepeatIterator
class | Storage
class | Then
class | UntilIterator
class | When

## Types

enum class | CallDone { Never, OnSuccess, OnError, OnCancel, Always }
flags | CallDoneFlags
enum class | DoneResult { Success, Error }
enum class | DoneWith { Success, Error, Cancel }
| GroupItems
enum class | SetupResult { Continue, StopWithSuccess, StopWithError }
enum class | WorkflowPolicy { StopOnError, ContinueOnError, StopOnSuccess, ContinueOnSuccess, StopOnSuccessOrError, …, FinishAllAndError }

## Functions

int | barrierAwaiterTask(const int &storedBarrier)
QtTaskTree::GroupItem | onGroupDone(Handler &&handler, QtTaskTree::CallDoneFlags callDone = CallDone::Always)
QtTaskTree::GroupItem | onGroupSetup(Handler &&handler)

## Detailed Description

See also Qt TaskTree.

## Classes

### class Do

A body element used with For and When constructs. More...

### class Else

An "else" element used in conditional expressions. More...

### class ElseIf

An "else if" element used in conditional expressions. More...

### class ExecutionMode

The group element describing execution mode. More...

### class For

A for loop element. More...

### class Forever

Infinite loop of subtasks. More...

### class ForeverIterator

Infinite iterator to be used inside For element. 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 If

An "if" element used in conditional expressions. More...

### class ListIterator

The list iterator to be used inside For element. More...

### class ParallelLimit

The parallel execution mode with a custom limit. More...

### class RepeatIterator

The repetitive iterator to be used inside For element. More...

### class Storage

A class template for custom data exchange in the running task tree. More...

### class Then

A "then" element used in conditional expressions. More...

### class UntilIterator

The conditional iterator to be used inside For element. More...

### class When

An element delaying the execution of a body until barrier advance. More...

## Type Documentation

### enum class QtTaskTree::CallDone
flags QtTaskTree::CallDoneFlags

This enum is an optional argument for the onGroupDone() element or custom task's constructor. It instructs the task tree on when the group's or task's done handler should be invoked.

Constant | Value | Description
--- | --- | ---
`QtTaskTree::CallDone::Never` | `0` | The done handler is never invoked.
`QtTaskTree::CallDone::OnSuccess` | `1 << 0` | The done handler is invoked only after successful execution, that is, when DoneWith::Success.
`QtTaskTree::CallDone::OnError` | `1 << 1` | The done handler is invoked only after failed execution, that is, when DoneWith::Error.
`QtTaskTree::CallDone::OnCancel` | `1 << 2` | The done handler is invoked only after canceled execution, that is, when DoneWith::Cancel.
`QtTaskTree::CallDone::Always` | `OnSuccess | OnError | OnCancel` | The done handler is always invoked.

The CallDoneFlags type is a typedef for QFlags<CallDone>. It stores an OR combination of CallDone values.

### enum class QtTaskTree::DoneResult

This enum is optionally returned from the group's or task's done handler function. When the done handler doesn't return any value, that is, its return type is `void`, its final return value is automatically deduced by the running task tree and reported to its parent group.

When the done handler returns the DoneResult, you can tweak the final return value inside the handler.

When the DoneResult is returned by the group's done handler, the group's workflow policy is ignored.

This enum is also used inside the QTaskInterface::done() signal and it indicates whether the task finished with success or an error.

Constant | Value | Description
--- | --- | ---
`QtTaskTree::DoneResult::Success` | `0` | The group's or task's execution ends with success.
`QtTaskTree::DoneResult::Error` | `1` | The group's or task's execution ends with an error.

### enum class QtTaskTree::DoneWith

This enum is an optional argument for the group's or task's done handler. It indicates whether the group or task finished with success or an error, or it was canceled.

It is also used as an argument inside the QTaskTree::done() signal, indicating the final result of the QTaskTree execution.

Constant | Value | Description
--- | --- | ---
`QtTaskTree::DoneWith::Success` | `0` | The group's or task's execution ended with success.
`QtTaskTree::DoneWith::Error` | `1` | The group's or task's execution ended with an error.
`QtTaskTree::DoneWith::Cancel` | `2` | The group's or task's execution was canceled. This happens when the user calls QTaskTree::cancel() for the running task tree or when the group's workflow policy results in canceling some of its running children. Tweaking the done handler's final result by returning DoneResult from the handler is no-op when the group's or task's execution was canceled.

### `[alias]` QtTaskTree::GroupItems

Type alias for QList<GroupItem>.

### enum class QtTaskTree::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
--- | --- | ---
`QtTaskTree::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.
`QtTaskTree::SetupResult::StopWithSuccess` | `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 with DoneWith::Success. 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.
`QtTaskTree::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 onGroupDone() handler is invoked with DoneWith::Error. 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 QtTaskTree::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 canceled.

Constant | Value | Description
--- | --- | ---
`QtTaskTree::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.
`QtTaskTree::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.
`QtTaskTree::WorkflowPolicy::StopOnSuccess` | `2` | Corresponds to the stopOnSuccess 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.
`QtTaskTree::WorkflowPolicy::ContinueOnSuccess` | `3` | Corresponds to the continueOnSuccess global element. Similar to stopOnSuccess, 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.
`QtTaskTree::WorkflowPolicy::StopOnSuccessOrError` | `4` | Corresponds to the stopOnSuccessOrError 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.
`QtTaskTree::WorkflowPolicy::FinishAllAndSuccess` | `5` | Corresponds to the finishAllAndSuccess 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.
`QtTaskTree::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, that is, in case of StopOnError, StopOnSuccess, or StopOnSuccessOrError policies, the Group cancels 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 canceling 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
StopOnSuccess | Stops when any child task finished with success and reports success | Success when at least one child task succeeded, an error otherwise | An error
ContinueOnSuccess | Yes | Success when at least one child task succeeded, an error otherwise | An error
StopOnSuccessOrError | 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
FinishAllAndSuccess | 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, that is, when the StopOnError, StopOnSuccess, or StopOnSuccessOrError 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.

## Function Documentation

### template <int Limit> int QtTaskTree::barrierAwaiterTask(const int &storedBarrier)

Returns the awaiter task that finishes when passed storedBarrier is finished.

Note: The passed storedBarrier needs to be placed in the same recipe as a sibling item to the returned task or in any ancestor Group, otherwise you may expect a crash.

### template <typename Handler> QtTaskTree::GroupItem QtTaskTree::onGroupDone(Handler &&handler, QtTaskTree::CallDoneFlags callDone = CallDone::Always)

Constructs a group's element holding the group done handler. By default, the handler is invoked whenever the group 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. Depending on the group's workflow policy, this handler may also be called when the running group is canceled (e.g. when stopOnError element was used).

The passed handler is of the `std::function<DoneResult(DoneWith)>` type. Optionally, each of the return DoneResult type or the argument DoneWith type may be omitted (that is, its return type may be `void`). For more information on a possible handler type, refer to GroupItem::GroupDoneHandler.

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::GroupDoneHandler and onGroupSetup().

### template <typename Handler> QtTaskTree::GroupItem QtTaskTree::onGroupSetup(Handler &&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 the `std::function<SetupResult()>` or the `std::function<void()>` type. For more information on a possible handler 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 and onGroupDone().