TaskTree 类

详细描述

使用 Tasking 命名空间构建可扩展的声明式任务树结构，其中可能包含异步任务，例如 QProcess、网络查询或 ConcurrentCall。TaskTree 结构使您能够以树的形式创建复杂的并行或顺序任务流，并在稍后随时运行。

根元素和任务

TaskTree 有一个强制性的 Group 根元素，可以包含任意数量的各种类型任务，例如 QProcessTask、NetworkQueryTask 或 ConcurrentCallTask

using namespace Tasking;

const Group root {
    QProcessTask(...),
    NetworkQueryTask(...),
    ConcurrentCallTask<int>(...)
};

TaskTree *taskTree = new TaskTree(root);
connect(taskTree, &TaskTree::done, ...);  // finish handler
taskTree->start();

上方的任务树包含顶级组元素，该元素包含类型为QProcessTask、NetworkQueryTask和< ConcurrentCallTask>的任务。调用taskTree->start()之后，任务以链式运行，首先是QProcessTask。当QProcessTask成功完成后，将启动NetworkQueryTask任务。最后，当网络任务成功完成后，将启动< ConcurrentCallTask>任务。

当最后一个正在运行的任务成功完成后，任务树被认为是成功运行的，并且会发出< a href="tasking-tasktree.html#done" translate="no">done()信号，携带< a href="tasking.html#DoneWith-enum" translate="no">DoneWith::Success。当任务以错误完成时，任务树的执行将停止，剩余的任务将被跳过。任务树以错误结束并发送带有< a href="tasking-tasktree.html#done" translate="no">TaskTree::done()信号的< a href="tasking.html#DoneWith-enum" translate="no">DoneWith::Error。

组

组的父元素将其视为单个任务。与其他任务一样，组可以启动，并且它可以成功完成或以错误结束。可以通过嵌套组元素来创建树状结构。

const Group root {
    Group {
        parallel,
        QProcessTask(...),
        ConcurrentCallTask<int>(...)
    },
    NetworkQueryTask(...)
};

上面的示例与第一个示例的不同之处在于，根元素有一个子组，该子组包含QProcessTask和< ConcurrentCallTask>。该子组是根中NetworkQueryTask的兄弟元素。该子组包含一个额外的parallel元素，指示其组以并行方式执行其任务。

因此，当启动上面的树时，QProcessTask和< ConcurrentCallTask>将立即启动并以并行方式运行。由于根组不包含parallel元素，其直接子任务的执行顺序。因此，当整个子组完成时，将启动NetworkQueryTask。该组被认为已完成，当其所有任务完成后。任务的完成顺序无关紧要。

因此，根据哪个任务运行更长时间（QProcessTask或< ConcurrentCallTask），可能出现以下情况

特殊情况以粗体标记。省略号表示前一事件（一个或多个任务）和下一事件（一个任务或多个任务）之间的不定时间量（任务或在继续运行）。事件之间没有点意味着它们是同步发生的。

呈现的情景假设所有任务都成功运行。如果任务在执行过程中失败，任务树将以错误结束。特别是，当QProcessTask在< ConcurrentCallTask仍然在执行时以错误结束，自动取消< ConcurrentCallTask，子组以错误完成，跳过NetworkQueryTask，并且树以错误结束。

任务类型

每个任务类型都与其对应的任务类关联，该类执行任务。例如，任务树内的QProcessTask与执行进程的QProcess类相关联。关联的对象将由任务树在适当的时间自动创建、启动和销毁。

如果一个根组由五个连续的QProcessTask任务组成，并且任务树执行该组，它会为第一个QProcessTask创建一个QProcess实例并启动它。如果QProcess实例成功完成，任务树将其销毁并为第二个QProcessTask创建一个新的QProcess实例，依此类推。如果第一个任务以错误完成，任务树将停止创建QProcess实例，并且根组以错误结束。

以下表格展示了任务类型及其对应的任务类示例

任务处理器

使用任务处理器来设置任务以执行，以及使能在任务以成功或错误完成时读取输出数据。

任务的启动处理器

当创建相应的任务类对象并在其启动之前，任务树调用可选的用户提供的设置处理器。设置处理器应该始终传递相关任务类对象的引用。

const auto onSetup = [](QProcess &process) {
    process.setCommand({"sleep", {"3"}});
};
const Group root {
    QProcessTask(onSetup)
};

您可以在设置处理器中修改传递的，这样任务树就可以根据您的配置启动进程。您不应该在设置处理器中调用process.start();，因为任务树在需要时调用它。设置处理器是可选的。当使用时，它必须作为任务的构造函数的第一个参数。

可选地，设置处理器可以返回一个SetupResult。返回的SetupResult会影响特定任务的进一步启动行为。可能的值包括

这在仅在满足条件时运行任务并且需要在之前启动的任务完成之前知道所需评估条件的数据时很有用。这种方式，设置处理器根据需要动态决定是否正常启动相应的任务或跳过它并报告成功或错误。有关任务间数据交换的更多信息，请参阅存储。

任务的完成处理器

当正在运行的任务完成后，任务树调用可选提供的完成处理器。处理器应该接受相关任务类对象的const 引用。

const auto onSetup = [](QProcess &process) {
    process.setCommand({"sleep", {"3"}});
};
const auto onDone = [](const QProcess &process, DoneWith result) {
    if (result == DoneWith::Success)
        qDebug() << "Success" << process.cleanedStdOut();
    else
        qDebug() << "Failure" << process.cleanedStdErr();
};
const Group root {
    QProcessTask(onSetup, onDone)
};

完成处理器可以从收集输出数据，并将其存储以供进一步处理或执行附加操作。

组处理器

类似于任务处理器，组处理器允许您设置一个组来执行，并在整个组成功完成或发生错误时应用更多操作。

组的开始处理器

任务树在启动子任务之前会调用组开始处理器。组处理器不接收任何参数

const auto onSetup = [] {
    qDebug() << "Entering the group";
};
const Group root {
    onGroupSetup(onSetup),
    QProcessTask(...)
};

组设置处理器是可选的。要定义组设置处理器，向组中添加一个onGroupSetup() 元素。onGroupSetup() 的参数是一个用户处理器。如果您向组中添加了多个 onGroupSetup() 元素，则会在运行时触发一个包含错误信息的断言。

与任务的开始处理器一样，组开始处理器可以返回SetupResult。返回的SetupResult值影响整个组的启动行为。如果您未指定组开始处理器或其返回类型为 void，则默认的组操作是SetupResult::Continue，因此所有任务都正常启动。否则，当开始处理器返回SetupResult::StopWithSuccess或SetupResult::StopWithError时，任务不会启动（它们会被跳过），并根据返回的值分别报告组本身的成功或失败。

const Group root {
    onGroupSetup([] { qDebug() << "Root setup"; }),
    Group {
        onGroupSetup([] { qDebug() << "Group 1 setup"; return SetupResult::Continue; }),
        QProcessTask(...) // Process 1
    },
    Group {
        onGroupSetup([] { qDebug() << "Group 2 setup"; return SetupResult::StopWithSuccess; }),
        QProcessTask(...) // Process 2
    },
    Group {
        onGroupSetup([] { qDebug() << "Group 3 setup"; return SetupResult::StopWithError; }),
        QProcessTask(...) // Process 3
    },
    QProcessTask(...) // Process 4
};

在上述示例中，一个根组的所有子组都已定义其设置处理器。以下场景假设所有启动的过程都成功完成

组的完成处理器

组的完成处理器在成功或失败执行任务后执行。组报告的最终值取决于其工作流程策略。处理器可以应用其他必要的操作。完成处理器定义在组内的 onGroupDone() 元素中。它可能包含可选的 DoneWith 参数，表示成功或失败执行。

const Group root {
    onGroupSetup([] { qDebug() << "Root setup"; }),
    QProcessTask(...),
    onGroupDone([](DoneWith result) {
        if (result == DoneWith::Success)
            qDebug() << "Root finished with success";
        else
            qDebug() << "Root finished with an error";
    })
};

组完成处理器是可选的。如果您向组中添加了多个 onGroupDone()，则会在运行时触发一个包含错误信息的断言。

其他组元素

组可以包含其他描述处理流程的元素，例如执行模式或工作流程策略。它还可以包含负责收集和共享在组执行过程中收集的特定公共数据的存储元素。

执行模式

在组中，执行模式元素指定了组的直接子任务如何启动。最常见的执行模式是顺序和并行。也可以通过使用parallelLimit() 函数来指定并行任务的数量限制。

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

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

工作流程策略

组中的工作流程策略元素指定了组如何处理其直接子任务之一完成的情况。有关可能策略的详细描述，请参考WorkflowPolicy。

如果组的子项也是一个组，则子组根据其自己的工作流程策略运行其任务。

存储

使用Storage元素在任务之间交换信息。特别是在顺序执行模式下，在任务需要从其他已完成任务中获取数据之前，任务可以启动。例如，一个通过从源读取并将其写入目标来复制数据的任务树可能如下所示

static QByteArray load(const QString &fileName) { ... }
static void save(const QString &fileName, const QByteArray &array) { ... }

static Group copyRecipe(const QString &source, const QString &destination)
{
    struct CopyStorage { // [1] custom inter-task struct
        QByteArray content; // [2] custom inter-task data
    };

    // [3] instance of custom inter-task struct manageable by task tree
    const Storage<CopyStorage> storage;

    const auto onLoaderSetup = [source](ConcurrentCall<QByteArray> &async) {
        async.setConcurrentCallData(&load, source);
    };
    // [4] runtime: task tree activates the instance from [7] before invoking handler
    const auto onLoaderDone = [storage](const ConcurrentCall<QByteArray> &async) {
        storage->content = async.result(); // [5] loader stores the result in storage
    };

    // [4] runtime: task tree activates the instance from [7] before invoking handler
    const auto onSaverSetup = [storage, destination](ConcurrentCall<void> &async) {
        const QByteArray content = storage->content; // [6] saver takes data from storage
        async.setConcurrentCallData(&save, destination, content);
    };
    const auto onSaverDone = [](const ConcurrentCall<void> &async) {
        qDebug() << "Save done successfully";
    };

    const Group root {
        // [7] runtime: task tree creates an instance of CopyStorage when root is entered
        storage,
        ConcurrentCallTask<QByteArray>(onLoaderSetup, onLoaderDone, CallDoneIf::Success),
        ConcurrentCallTask<void>(onSaverSetup, onSaverDone, CallDoneIf::Success)
    };
    return root;
}

const QString source = ...;
const QString destination = ...;
TaskTree taskTree(copyRecipe(source, destination));
connect(&taskTree, &TaskTree::done,
        &taskTree, [](DoneWith result) {
    if (result == DoneWith::Success)
        qDebug() << "The copying finished successfully.";
});
tasktree.start();

在上面的示例中，任务间的数据由一个包含在CopyStorage自定义结构体中的QByteArray内容变量[2]。如果加载器成功完成，它将数据存储在CopyStorage::content变量[5]中。然后保存器使用该变量来配置保存任务[6]。

为了使任务树管理CopyStorage结构体，创建了一个Storage<CopyStorage>实例[3]。如果将此对象的副本作为组的子项插入[7]，则在任务树进入该组时，将动态创建CopyStorage结构体的实例。当任务树离开此组时，将销毁现有的CopyStorage结构体实例，因为它不再需要。

如果包含该共同Storage<CopyStorage>实例副本的多个任务树同时运行（包括当任务树在不同线程中运行时），则每个任务树都包含其自己的CopyStorage结构体副本。

您可以从组的任何处理程序中通过存储对象访问CopyStorage。这包括所有具有存储对象的下属任务的处理程序。要访问处理器中的自定义结构体，请将Storage<CopyStorage>对象的副本传递给处理器（例如，在lambda捕获中）[4]。

当任务树在包含存储的子树中调用处理器时[7]，任务树在存储对象内部激活其自己的CopyStorage实例。因此，只能在处理器体内访问CopyStorage结构体。要从Storage<CopyStorage>中访问当前激活的CopyStorage，请使用Storage::operator->()、Storage::operator*()或Storage::activeStorage()方法。

以下列表总结如何将存储对象用于任务树

1. 定义具有自定义数据 [1]、[2] 的自定义结构 MyStorage
2. 创建 Storage<MyStorage> 存储实例 [3]
3. 将 Storage<MyStorage> 实例传递给处理器 [4]
4. 在处理器中访问 MyStorage 实例 [5]、[6]
5. 将 Storage<MyStorage> 实例插入组 [7]

TaskTree 类

TaskTree 根据组根元素描述的配方执行异步任务的树结构。

由于 TaskTree 也是异步任务，它可以成为另一个 TaskTree 的一部分。要嵌套 TaskTree 在另一个 TaskTree 中，将 TaskTreeTask 元素插入另一个组元素中。

TaskTree 在运行时报告已完成任务的进度。任务完成或跳过或取消时进度值增加。当 TaskTree 完成，并发射 TaskTree::done() 信号时，当前的进度值等于最大进度值。最大进度等于树中异步任务的总数。嵌套的 TaskTree 计为一个任务，其子任务不计入顶级树。组本身不计入任务，但其任务计入。《a href="tasking-sync.html" translate="no">Sync 任务不是异步任务，因此不计入任务。

为了为运行的树设置其他初始数据，通过安装存储设置处理器在创建树时修改存储实例

Storage<CopyStorage> storage;
const Group root = ...; // storage placed inside root's group and inside handlers
TaskTree taskTree(root);
auto initStorage = [](CopyStorage &storage) {
    storage.content = "initial content";
};
taskTree.onStorageSetup(storage, initStorage);
taskTree.start();

当运行的任务树创建一个 CopyStorage 实例时，在调用树中的任何处理器之前，任务树调用 initStorage 处理器，以设置存储的唯一初始数据，该数据对 taskTree 的此次运行是独有的。

同样，为了收集运行树的某些其他结果数据，在即将销毁它们时从树中的存储实例读取。为此，安装一个存储完成处理器

Storage<CopyStorage> storage;
const Group root = ...; // storage placed inside root's group and inside handlers
TaskTree taskTree(root);
auto collectStorage = [](const CopyStorage &storage) {
    qDebug() << "final content" << storage.content;
};
taskTree.onStorageDone(storage, collectStorage);
taskTree.start();

当运行的任务树即将销毁一个 CopyStorage 实例时，任务树调用 collectStorage 处理器，以读取存储的唯一最终数据，该数据对 taskTree 的此次运行是独有的。

任务适配器

要扩展 TaskTree 以包含新的任务类型，实现一个从 TaskAdapter 类模板派生的简单适配器类。以下类是一个单次计时器的适配器，这可以被认为是一个新的异步任务。

class TimerTaskAdapter : public TaskAdapter<QTimer>
{
public:
    TimerTaskAdapter() {
        task()->setSingleShot(true);
        task()->setInterval(1000);
        connect(task(), &QTimer::timeout, this, [this] { emit done(DoneResult::Success); });
    }
private:
    void start() final { task()->start(); }
};

using TimerTask = CustomTask<TimerTaskAdapter>;

您必须从使用实现运行任务的类的模板参数实例化的 TaskAdapter 类模板导出自定义适配器。上面的代码使用 QTimer 来运行任务。这个类之后作为任务处理器的参数出现。此类参数的实例自动成为 TaskAdapter 模板的一个成员，可以通过 TaskAdapter::task() 方法访问。 TimerTaskAdapter 的构造函数最初配置 QTimer 对象并连接到 QTimer::timeout() 信号。当信号被触发时， TimerTaskAdapter 发射 TaskInterface::done(DoneResult::Success) 信号来通知任务树任务已成功完成。如果它发射 TaskInterface::done(DoneResult::Error)，则任务以错误完成。 TaskAdapter::start() 方法启动计时器。

为了在TaskTree中的名称下访问，请将定义为一个指向CustomTask&l;TimerTaskAdapter>的别名。这样，TimerTask就变成了一个新的自定义任务类型，并使用。

现在，新的任务类型已被注册，您可以在TaskTree中使用它。

const auto onSetup = [](QTimer &task) { task.setInterval(2000); };
const auto onDone = [] { qDebug() << "timer triggered"; };
const Group root {
    TimerTask(onSetup, onDone)
};

当启动包含上述示例根的任务树时，它将在两秒内打印一条调试消息，然后成功完成。