Tasking Namespace

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

Header: #include <Tasking>

Classes

class CustomTask
class TaskAdapter

Types

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

Functions

int onGroupSetup(SetupHandler &&)

Detailed Description

Classes

class CustomTask

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

class TaskAdapter

A class template for implementing custom task adapters. 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.

ConstantValueDescription
Tasking::SetupResult::Continue0Default. 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::StopWithDone1The 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::StopWithError2The 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.

ConstantValueDescription
Tasking::WorkflowPolicy::StopOnError0Default. 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::ContinueOnError1Corresponds 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::StopOnDone2Corresponds 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::ContinueOnDone3Corresponds 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::StopOnFinished4Corresponds 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::FinishAllAndDone5Corresponds 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::FinishAllAndError6Corresponds 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:

WorkflowPolicyExecutes all child tasksResultResult when the group is empty
StopOnErrorStops when any child task finished with an error and reports an errorAn error when at least one child task failed, success otherwiseSuccess
ContinueOnErrorYesAn error when at least one child task failed, success otherwiseSuccess
StopOnDoneStops when any child task finished with success and reports successSuccess when at least one child task succeeded, an error otherwiseAn error
ContinueOnDoneYesSuccess when at least one child task succeeded, an error otherwiseAn error
StopOnFinishedStops when any child task finished and reports child task's resultSuccess or an error, depending on the finished child task's resultAn error
FinishAllAndDoneYesSuccessSuccess
FinishAllAndErrorYesAn errorAn 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.

Function Documentation

template <typename SetupHandler> int Tasking::onGroupSetup(SetupHandler &&)

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().