任务命名空间

Tasking 命名空间包含了 Tasking 解决方案中所有的类和全局函数。更多...

头文件	#include <Tasking>

类

class	CustomTask
class	ExecutableItem
class	Group
class	GroupItem
class	Storage
class	Sync
class	TaskAdapter
class	TaskInterface
class	TaskTree

类型

enum class	CallDoneIf { SuccessOrError, Success, Error }
enum class	DoneResult { Success, Error }
enum class	DoneWith { Success, Error, Cancel }
enum class	SetupResult { Continue, StopWithSuccess, StopWithError }
	TaskTreeTask
	TimeoutTask
enum class	WorkflowPolicy { StopOnError, ContinueOnError, StopOnSuccess, ContinueOnSuccess, StopOnSuccessOrError, …, FinishAllAndError }

变量

const Tasking::GroupItem	continueOnError
const Tasking::GroupItem	continueOnSuccess
const Tasking::GroupItem	finishAllAndError
const Tasking::GroupItem	finishAllAndSuccess
const Tasking::GroupItem	parallel
const Tasking::GroupItem	parallelIdealThreadCountLimit
const Tasking::GroupItem	sequential
const Tasking::GroupItem	stopOnError
const Tasking::GroupItem	stopOnSuccess
const Tasking::GroupItem	stopOnSuccessOrError

函数

Tasking::GroupItem	onGroupDone(Handler &&handler, Tasking::CallDoneIf callDoneIf = CallDoneIf::SuccessOrError)
Tasking::GroupItem	onGroupSetup(Handler &&handler)
Tasking::GroupItem	parallelLimit(int limit)
Tasking::GroupItem	workflowPolicy(Tasking::WorkflowPolicy policy)

详细描述

类

class CustomTask

用于声明显式任务项并定义其设置和完成处理器的类模板。更多...

class ExecutableItem

执行任务项的基类。更多...

class Group

Group 表示用于描述执行和处理嵌套异步任务树的声明性方法的元素。更多...

class GroupItem

GroupItem 表示可能是任何 Group 的基本元素。更多...

class Storage

用于在运行的任务树中进行自定义数据交换的类模板。更多...

class Sync

同步执行其他任务之间的自定义处理器。更多...

class TaskAdapter

用于实现自定义任务适配器的类模板。更多...

class TaskInterface

TaskInterface 是实现自定义任务适配器的抽象基类。更多...

class TaskTree

TaskTree 类按照声明性方式运行定义的异步任务树结构。更多...

类型文档

enum class Tasking::CallDoneIf

该枚举是函数onGroupDone()或自定义任务构造函数的可选参数。它指示任务树何时调用组或任务的完成处理程序。

常量	值	描述
`Tasking::CallDoneIf::SuccessOrError`	`0`	完成处理程序总是会被调用。
`Tasking::CallDoneIf::Success`	`1`	完成处理程序仅在执行成功后调用，即DoneWith::Success。
`Tasking::CallDoneIf::Error`	`2`	完成处理程序仅在执行失败后调用，即DoneWith::Error或DoneWith::Cancel。

枚举类型 Tasking::DoneResult

该枚举是组或任务的完成处理程序函数的可选返回值。当完成处理程序没有返回任何值时，即其返回类型为void，其最终返回值由运行任务树自动推导并报告给其父组。

当完成处理程序返回DoneResult时，您可以在处理程序内修改最终返回值。

当组完成处理程序返回DoneResult时，忽略组的工作流程策略。

该枚举也用于TaskInterface::done()信号中，它表示任务是否成功完成或出错。

常量	值	描述
`Tasking::DoneResult::Success`	`0`	组的或任务的执行以成功结束。
`Tasking::DoneResult::Error`	`1`	组的或任务的执行以错误结束。

枚举类型 Tasking::DoneWith

该枚举是组或任务的完成处理程序的可选参数。它指示组或任务是否以成功或错误结束，或者它已被取消。

它还作为TaskTree::done()信号的参数，表示TaskTree执行的最后结果。

常量	值	描述
`Tasking::DoneWith::Success`	`0`	组的或任务的执行以成功结束。
`Tasking::DoneWith::Error`	`1`	组的或任务的执行以错误结束。
`Tasking::DoneWith::Cancel`	`2`	组的或任务的执行被取消。这发生在用户调用TaskTree::cancel()取消运行的任务树或当组的工作流程策略导致取消其一些运行中的子任务时。当组的或任务的执行被取消时，从处理程序返回Tasking::DoneResult来修改完成处理程序的最终结果是没有效果的。

枚举类型 Tasking::SetupResult

该枚举是组或任务的设置处理程序函数的可选返回值。它在设置处理程序执行完成后指示运行任务树如何继续。

常量	值	描述
`Tasking::SetupResult::Continue`	`0`	默认值。组的或任务的执行按正常方式继续。当一个组或任务的设置处理程序返回void，则假定它返回Continue。
`Tasking::SetupResult::StopWithSuccess`	`1`	组的或任务的执行立即以成功结束。当从组的设置处理程序返回时，所有子任务都将被跳过，组的onGroupDone()处理程序将使用DoneWith::Success被调用。组向其父组报告成功。忽略组的工作流程策略。当从任务的设置处理程序返回时，任务不会开始，其完成处理程序不会被调用，任务向其父组报告成功。
`Tasking::SetupResult::StopWithError`	`2`	当组或任务的执行立即停止并发生错误。从组的设置处理程序返回时，所有子任务都将跳过，并且组的onGroupDone()处理程序会使用DoneWith::Error调用。组向其父级报告错误，忽略组的作业流程策略。从任务的设置处理程序返回时，任务不会启动，其错误处理程序不会被调用，并将错误报告给其父级。

`[别名]` Tasking::TaskTreeTask

用于在内部配方中使用的CustomTask的类型别名，与TaskTree任务关联。

`[别名]` Tasking::TimeoutTask

用于在内部配方中使用的CustomTask的类型别名，与std::chrono::milliseconds类型关联。使用std::chrono::milliseconds设置超时时间。默认超时是std::chrono::milliseconds::zero()，即TimeoutTask在控制返回到运行的事件循环后立即完成。

示例用法

using namespace std::chrono;
using namespace std::chrono_literals;

const auto onSetup = [](milliseconds &timeout) { timeout = 1000ms; }
const auto onDone = [] { qDebug() << "Timed out."; }

const Group root {
    Timeout(onSetup, onDone)
};

enum class Tasking::WorkflowPolicy

此枚举描述了当任何组子任务完成执行时的Group元素可能的行为。它也在运行组被取消时使用。

常量	值	描述
`Tasking::WorkflowPolicy::StopOnError`	`0`	默认。对应于stopOnError全局元素。如果有任何子任务以错误结束，则组停止并以错误结束。如果所有子任务都成功完成，则组以成功结束。如果组为空，则以成功结束。
`Tasking::WorkflowPolicy::ContinueOnError`	`1`	对应于continueOnError全局元素。与stopOnError类似，但如果有任何子任务以错误结束，执行将继续直到所有任务完成，该组随后报告一个错误，即使在组中有其它任务成功的完成。如果所有子任务都成功完成，则组以成功结束。如果组为空，则以成功结束。
`Tasking::WorkflowPolicy::StopOnSuccess`	`2`	对应于stopOnSuccess全局元素。如果有任何子任务成功结束，则组停止并以成功结束。如果所有子任务都以错误结束，则组以错误结束。如果组为空，则以错误结束。
`Tasking::WorkflowPolicy::ContinueOnSuccess`	`3`	对应于continueOnSuccess全局元素。与stopOnSuccess类似，但如果有任何子任务成功完成，执行将继续直到所有任务完成，随后组报告成功，即使在组中有其他任务以错误结束。如果所有子任务都成功完成，则组以成功结束。如果组为空，则以错误结束。
`Tasking::WorkflowPolicy::StopOnSuccessOrError`	`4`	对应于stopOnSuccessOrError全局元素。组可以启动尽可能多的任务。当任何任务完成时，组停止并报告任务的结果。仅在并行模式下有效。在顺序模式下，仅启动第一个任务，当它完成时，组也将完成，因此其他任务总是被跳过。如果组为空，则以错误结束。
`Tasking::WorkflowPolicy::FinishAllAndSuccess`	`5`	对应于finishAllAndSuccess全局元素。该组执行所有任务并忽略它们的返回结果。当所有任务完成后，组成功完成。如果组为空，它也以成功完成。
`Tasking::WorkflowPolicy::FinishAllAndError`	`6`	对应于finishAllAndError全局元素。该组执行所有任务并忽略它们的返回结果。当所有任务完成后，组以错误完成。如果组为空，它也以错误完成。

每当子任务的结果导致组停止时，即在使用StopOnError、StopOnSuccess或StopOnSuccessOrError策略时，组将取消其他正在运行的子任务（如果有，例如在并行模式中），并跳过执行它尚未启动的任务（例如，在顺序模式中 - 那些在失败任务之后放置的任务）。在调用parallelLimit()时，取消和跳过子任务都可能发生。

下表总结了各种工作流程策略之间的差异

WorkflowPolicy	执行所有子任务	结果	组为空时的结果
StopOnError	任何子任务以错误完成时停止并报告错误	至少一个子任务失败时为错误，否则为成功	成功
ContinueOnError	是	至少一个子任务失败时为错误，否则为成功	成功
StopOnSuccess	任何子任务以成功完成时停止并报告成功	至少一个子任务成功时为成功，否则为错误	错误
ContinueOnSuccess	是	至少一个子任务成功时为成功，否则为错误	错误
StopOnSuccessOrError	任何子任务完成时停止并报告子任务的结果	根据已完成的子任务的结果，为成功或错误	错误
FinishAllAndSuccess	是	成功	成功
FinishAllAndError	是	错误	错误

如果组的子代也是一个组，则子组的任务将根据其自己的工作流程策略运行。当父组由于其工作流程策略停止运行子组时（即当父组使用了StopOnError、StopOnSuccess或StopOnSuccessOrError策略时），子组的结果将根据上表中的“结果”列和“子组的工作流程策略”行报告。

变量文档

const Tasking::GroupItem Tasking::continueOnError

一个方便的全局组元素，描述了ContinueOnError工作流程策略。

const Tasking::GroupItem Tasking::continueOnSuccess

一个方便的全局组元素，描述了ContinueOnSuccess工作流程策略。

const Tasking::GroupItem Tasking::finishAllAndError

一个方便的全局组元素，描述了FinishAllAndError工作流程策略。

const Tasking::GroupItem Tasking::finishAllAndSuccess

一个方便的全局组元素，描述了FinishAllAndSuccess工作流程策略。

const Tasking::GroupItem Tasking::parallel

一个方便的全局组元素，描述了并行执行模式。

在一个组启动后，其所有直接子任务都会启动，无需等待先前的子任务完成。在这种模式下，所有子任务同时运行。

另请参阅 并行和并行限制。

const Tasking::GroupItem Tasking::parallelIdealThreadCountLimit

一个方便的全局组元素，描述了具有有限任务同时运行的并行执行模式。限制等于理想线程数（不包含调用线程）。

这是一个快捷方式到

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

另请参阅 并行和并行限制。

const Tasking::GroupItem Tasking::sequential

一个方便的全局组元素，描述了顺序执行模式。

这是组元素的默认执行模式。

当一个组没有执行模式时，它将在顺序模式下运行。组的所有直接子任务都将依次启动，因此当一项任务完成时，下一项任务才开始。这使您能够在下一任务开始之前将前一项任务的结果作为输入传递给下一项任务。此模式保证只有在前一项任务完成后才会启动下一项任务。

另请参阅 并行和并行限制。

const Tasking::GroupItem Tasking::stopOnError

一个方便的全局组元素，描述了 StopOnError 工作流策略。

这是组元素的默认工作流策略。

const Tasking::GroupItem Tasking::stopOnSuccess

一个方便的全局组元素，描述了 StopOnSuccess 工作流策略。

const Tasking::GroupItem Tasking::stopOnSuccessOrError

一个方便的全局组元素，描述了 StopOnSuccessOrError 工作流策略。

函数文档

template <typename Handler> Tasking::GroupItem Tasking::onGroupDone(Handler &&handler, Tasking::CallDoneIf callDoneIf = CallDoneIf::SuccessOrError)

构建一个包含组完成处理程序的组元素。默认情况下，handler 在组完成后将被调用。当您希望处理程序只在成功或失败执行时被调用时，请为 callDoneIf 参数传递非默认值。根据组的流程策略，处理程序也可能会在正在运行的组被取消（例如，当使用了 stopOnError 元素）时被调用。

传递的 handler 是 std::function<DoneResult(DoneWith)> 类型。返回的 DoneResult 类型或 DoneWith 类型参数可以省略（即，其返回类型可以是 void）。有关可能的处理程序类型的更多信息，请参阅 GroupItem::GroupDoneHandler。

当 handler 被调用时，组的所有子任务都已经完成。

如果一个组包含存储元素，则在进行存储元素的析构之前，会调用处理器，这样处理器还可以执行对活动存储数据的最后一次读取。

另请参阅GroupItem::GroupDoneHandler和onGroupSetup。

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

构建一个包含组设置处理器的组元素。每当组开始时，都会调用处理器。

传入的处理器类型为std::function<SetupResult()>或std::function<void()>。有关处理器类型的更多信息，请参阅GroupItem::GroupSetupHandler。

当调用处理器时，组中还没有任何子任务正在运行。

如果一个组包含存储元素，则在存储元素构造后调用处理器，这样处理器已经可以对活动存储执行一些初始修改。

另请参阅GroupItem::GroupSetupHandler和onGroupDone。

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

构建一个描述执行模式的组元素。

在组中，执行模式元素指定了组直接子任务是如何启动的。

为了方便，在适当的情况下，可以使用顺序或并行全局元素。

limit定义了并行运行的总直接子任务的最大数量

当limit等于0时，没有限制，并且在组中按顺序启动所有的直接子任务。这意味着完全并行执行，并且可以使用并行元素代替。
当limit等于1时，这意味着每次只能运行一个子任务。这意味着顺序执行，并且可以使用顺序元素代替。在这种情况下，子任务以链式运行，因此下一个子任务在先前的子任务完成后开始。
当传递非零正数作为limit时，组子任务并行运行，但同时运行的任务数量有限。该limit定义了组中并行运行的任务的最大数量。当组启动时，会启动第一批任务（批次中的任务数等于传入的limit，最多），而其他任务在等待。当任何运行的任务完成后，组启动下一个剩余的任务，这样组内并行运行的任务limit不会超过。在所有子任务完成之前，重复此操作。这允许您限制同时运行的任务的最大数量，例如，如果运行过多的进程可能会导致机器长时间阻塞。

在所有执行模式中，组以任务出现的顺序启动任务。

如果一个组子项也是一个组，则子组按其自己的执行模式运行任务。

另见顺序和并行。

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

为特定策略构建一个组的工作流策略元素。

为了方便，可以使用全局元素来代替。

另见 stopOnError、continueOnError、stopOnSuccess、continueOnSuccess、stopOnSuccessOrError、finishAllAndSuccess、finishAllAndError 和 WorkflowPolicy。

任务命名空间

类

类型

变量

函数

详细描述

类

class CustomTask

class ExecutableItem

class Group

class GroupItem

class Storage

class Sync

class TaskAdapter

class TaskInterface

class TaskTree

类型文档

enum class Tasking::CallDoneIf

枚举类型 Tasking::DoneResult

枚举类型 Tasking::DoneWith

枚举类型 Tasking::SetupResult

[别名] Tasking::TaskTreeTask

[别名] Tasking::TimeoutTask

enum class Tasking::WorkflowPolicy

变量文档

const Tasking::GroupItem Tasking::continueOnError

const Tasking::GroupItem Tasking::continueOnSuccess

const Tasking::GroupItem Tasking::finishAllAndError

const Tasking::GroupItem Tasking::finishAllAndSuccess

const Tasking::GroupItem Tasking::parallel

const Tasking::GroupItem Tasking::parallelIdealThreadCountLimit

const Tasking::GroupItem Tasking::sequential

const Tasking::GroupItem Tasking::stopOnError

const Tasking::GroupItem Tasking::stopOnSuccess

const Tasking::GroupItem Tasking::stopOnSuccessOrError

函数文档

template <typename Handler> Tasking::GroupItem Tasking::onGroupDone(Handler &&handler, Tasking::CallDoneIf callDoneIf = CallDoneIf::SuccessOrError)

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

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

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

`[别名]` Tasking::TaskTreeTask

`[别名]` Tasking::TimeoutTask