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	ExecutableItem
class	For
class	Forever
class	ForeverIterator
class	Group
class	GroupItem
class	If
class	Iterator
class	ListIterator
class	RepeatIterator
class	Storage
class	Then
class	UntilIterator
class	When

Types

	BarrierKickerGetter
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 }

Variables

const QtTaskTree::GroupItem	continueOnError
const QtTaskTree::GroupItem	continueOnSuccess
const QtTaskTree::ExecutableItem	errorItem
const QtTaskTree::GroupItem	finishAllAndError
const QtTaskTree::GroupItem	finishAllAndSuccess
const QtTaskTree::GroupItem	nullItem
const QtTaskTree::GroupItem	parallel
const QtTaskTree::GroupItem	parallelIdealThreadCountLimit
const QtTaskTree::GroupItem	sequential
const QtTaskTree::GroupItem	stopOnError
const QtTaskTree::GroupItem	stopOnSuccess
const QtTaskTree::GroupItem	stopOnSuccessOrError
const QtTaskTree::ExecutableItem	successItem

Functions

QtTaskTree::ExecutableItem	barrierAwaiterTask(const QStoredMultiBarrier<Limit> &storedBarrier)
QtTaskTree::GroupItem	onGroupDone(Handler &&handler, QtTaskTree::CallDoneFlags callDone = CallDone::Always)
QtTaskTree::GroupItem	onGroupSetup(Handler &&handler)
QtTaskTree::GroupItem	parallelLimit(int limit)
QtTaskTree::ExecutableItem	signalAwaiterTask(const typename QtPrivate::FunctionPointer<Signal>::Object *sender, Signal signal)
QtTaskTree::ExecutableItem	timeoutTask(const std::chrono::milliseconds &timeout, QtTaskTree::DoneResult result = DoneResult::Error)
QtTaskTree::GroupItem	workflowPolicy(QtTaskTree::WorkflowPolicy policy)
QtTaskTree::Group	operator>>(const QtTaskTree::For &forItem, const QtTaskTree::Do &doItem)
QtTaskTree::Group	operator>>(const QtTaskTree::When &whenItem, const QtTaskTree::Do &doItem)

Detailed Description

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 ExecutableItem

Base class for executable task items. More...

class For

A for loop element. 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 GroupItem

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

class If

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

class Iterator

Base class to be used as an iterator inside For element. More...

class ListIterator

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

`[alias]` BarrierKickerGetter

Type alias for the function taking a QStoredBarrier and returning ExecutableItem, i.e. std::function<ExecutableItem(const QStoredBarrier &)>, to be used inside When constructor.

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 TaskInterface::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.

Variable Documentation

const QtTaskTree::GroupItem QtTaskTree::continueOnError

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

const QtTaskTree::GroupItem QtTaskTree::continueOnSuccess

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

const QtTaskTree::ExecutableItem QtTaskTree::errorItem

A convenient global executable element containing an empty, erroneous, synchronous task.

This is useful in if-statements to indicate that a branch ends with an error:

const ExecutableItem conditionalTask = ...;

Group group {
    stopOnError,
    If (conditionalTask) >> Then {
        ...
    } >> Else {
        errorItem
    },
    nextTask
};

In the above example, if the conditionalTask finishes with an error, the Else branch is chosen, which finishes immediately with an error. This causes the nextTask to be skipped (because of the stopOnError workflow policy of the group) and the group finishes with an error.

See also successItem.

const QtTaskTree::GroupItem QtTaskTree::finishAllAndError

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

const QtTaskTree::GroupItem QtTaskTree::finishAllAndSuccess

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

const QtTaskTree::GroupItem QtTaskTree::nullItem

A convenient global group's element indicating a no-op item.

This is useful in conditional expressions to indicate the absence of an optional element:

const ExecutableItem task = ...;
const std::optional<ExecutableItem> optionalTask = ...;

Group group {
    task,
    optionalTask ? *optionalTask : nullItem
};

const QtTaskTree::GroupItem QtTaskTree::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 QtTaskTree::GroupItem QtTaskTree::parallelIdealThreadCountLimit

A convenient global group's element describing the parallel execution mode with a limited number of tasks running simultanously. The limit is equal to the ideal number of threads excluding the calling thread.

This is a shortcut to:

parallelLimit(qMax(QThread::idealThreadCount() - 1, 1))

See also parallel and parallelLimit().

const QtTaskTree::GroupItem QtTaskTree::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 QtTaskTree::GroupItem QtTaskTree::stopOnError

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

This is the default workflow policy of the Group element.

const QtTaskTree::GroupItem QtTaskTree::stopOnSuccess

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

const QtTaskTree::GroupItem QtTaskTree::stopOnSuccessOrError

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

const QtTaskTree::ExecutableItem QtTaskTree::successItem

A convenient global executable element containing an empty, successful, synchronous task.

This is useful in if-statements to indicate that a branch ends with success:

const ExecutableItem conditionalTask = ...;

const Group group {
    stopOnSuccess,
    If (conditionalTask) >> Then {
        ...
    } >> Else {
        successItem
    },
    nextTask
};

In the above example, if the conditionalTask finishes with an error, the Else branch is chosen, which finishes immediately with success. This causes the nextTask to be skipped (because of the stopOnSuccess workflow policy of the group) and the group finishes with success.

See also errorItem.

Function Documentation

template <int Limit> QtTaskTree::ExecutableItem QtTaskTree::barrierAwaiterTask(const QStoredMultiBarrier<Limit> &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().

QtTaskTree::GroupItem QtTaskTree::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.

template <typename Signal> QtTaskTree::ExecutableItem QtTaskTree::signalAwaiterTask(const typename QtPrivate::FunctionPointer<Signal>::Object **sender, Signal signal*)

Returns the awaiter task that finishes when passed sender emits the signal.

Note: The connection to the passed sender and signal is established not when the returned task is created or placed into a recipe, but when the task is started by the QTaskTree. Ensure, the passed sender outlives any running task tree containing the returned task. If the signal was emitted before the task started, i.e. before the connection was established, the task will finish on first emission of the signal after the task started.

QtTaskTree::ExecutableItem QtTaskTree::timeoutTask(const std::chrono::milliseconds &timeout, QtTaskTree::DoneResult result = DoneResult::Error)

Creates QTimeoutTask with timeout duration, after which the task finishes with result.

See also QTimeoutTask.

QtTaskTree::GroupItem QtTaskTree::workflowPolicy(QtTaskTree::WorkflowPolicy policy)

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

For convenience, global elements may be used instead.

QtTaskTree::Group QtTaskTree::operator>>(const QtTaskTree::For &forItem, const QtTaskTree::Do &doItem)

Combines forItem with doItem body and returns a Group ready to be used in task tree recipes.

QtTaskTree::Group QtTaskTree::operator>>(const QtTaskTree::When &whenItem, const QtTaskTree::Do &doItem)

Combines whenItem with doItem body and returns a Group ready to be used in task tree recipes.

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

QtTaskTree Namespace

Classes

Types

Variables

Functions

Detailed Description

Classes

class Do

class Else

class ElseIf

class ExecutableItem

class For

class Forever

class ForeverIterator

class Group

class GroupItem

class If

class Iterator

class ListIterator

class RepeatIterator

class Storage

class Then

class UntilIterator

class When

Type Documentation

[alias] BarrierKickerGetter

enum class QtTaskTree::CallDoneflags QtTaskTree::CallDoneFlags

enum class QtTaskTree::DoneResult

enum class QtTaskTree::DoneWith

[alias] QtTaskTree::GroupItems

enum class QtTaskTree::SetupResult

enum class QtTaskTree::WorkflowPolicy

Variable Documentation

const QtTaskTree::GroupItem QtTaskTree::continueOnError

const QtTaskTree::GroupItem QtTaskTree::continueOnSuccess

const QtTaskTree::ExecutableItem QtTaskTree::errorItem

const QtTaskTree::GroupItem QtTaskTree::finishAllAndError

const QtTaskTree::GroupItem QtTaskTree::finishAllAndSuccess

const QtTaskTree::GroupItem QtTaskTree::nullItem

const QtTaskTree::GroupItem QtTaskTree::parallel

const QtTaskTree::GroupItem QtTaskTree::parallelIdealThreadCountLimit

const QtTaskTree::GroupItem QtTaskTree::sequential

const QtTaskTree::GroupItem QtTaskTree::stopOnError

const QtTaskTree::GroupItem QtTaskTree::stopOnSuccess

const QtTaskTree::GroupItem QtTaskTree::stopOnSuccessOrError

const QtTaskTree::ExecutableItem QtTaskTree::successItem

Function Documentation

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

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

template <typename Handler> QtTaskTree::GroupItem QtTaskTree::onGroupSetup(Handler &&handler)

QtTaskTree::GroupItem QtTaskTree::parallelLimit(int limit)

template <typename Signal> QtTaskTree::ExecutableItem QtTaskTree::signalAwaiterTask(const typename QtPrivate::FunctionPointer<Signal>::Object *sender, Signal signal)

QtTaskTree::ExecutableItem QtTaskTree::timeoutTask(const std::chrono::milliseconds &timeout, QtTaskTree::DoneResult result = DoneResult::Error)

QtTaskTree::GroupItem QtTaskTree::workflowPolicy(QtTaskTree::WorkflowPolicy policy)

QtTaskTree::Group QtTaskTree::operator>>(const QtTaskTree::For &forItem, const QtTaskTree::Do &doItem)

QtTaskTree::Group QtTaskTree::operator>>(const QtTaskTree::When &whenItem, const QtTaskTree::Do &doItem)

`[alias]` BarrierKickerGetter

enum class QtTaskTree::CallDone
flags QtTaskTree::CallDoneFlags

`[alias]` QtTaskTree::GroupItems

template <typename Signal> QtTaskTree::ExecutableItem QtTaskTree::signalAwaiterTask(const typename QtPrivate::FunctionPointer<Signal>::Object **sender, Signal signal*)