QtTaskTree::QTaskTree Class

成员函数文档

[explicit] QTaskTree::QTaskTree(QObject *parent)

用给定的parent 构建一棵空任务树。使用setRecipe() 传递声明式描述，说明任务树应如何执行任务以及如何处理已完成的任务。

启动空任务树时不会执行任何操作，并会发出相关警告信息。

另请参阅 setRecipe() 和start()。

[explicit] QTaskTree::QTaskTree(const QtTaskTree::Group &recipe, QObject *parent = nullptr)

用给定的recipe 和parent 构建任务树。任务树启动后，它会执行recipe 中包含的任务，并根据传递的描述处理已完成的任务。

另请参见 setRecipe() 和start()。

[override virtual noexcept] QTaskTree::~QTaskTree()

销毁任务树。

当任务树在运行时被销毁，它会立即取消所有正在运行的任务。在这种情况下，不会调用任何处理程序，甚至不会调用组和任务的已完成处理程序或onStorageDone() 处理程序。任务树也不会从析构函数中发出任何信号，甚至不会发出done() 或progressValueChanged() 信号。我们可以始终依赖这种行为。析构运行中的任务树是完全安全的。

析构运行中的任务树是一种常见模式。只要使用的任务以非阻塞方式实现了它们的析构函数，就能保证析构快速运行，而无需等待当前运行的任务完成。

另请参见 cancel()。

qsizetype QTaskTree::asyncCount() const

返回异步调用链的当前实际次数。

返回值表示在任务树运行期间，有多少次控制返回到调用者的事件循环。最初，该值为0 。如果任务树的执行完全同步完成，则该值仍为0 。如果任务树中包含在调用start() 期间成功启动的异步任务，则在调用start() 结束前，该值会被提升至1 。随后，当任何异步任务结束并启动任何可能的连续任务时，该值将再次被提升。碰撞会一直持续到任务树结束。当任务树发出done() 信号时，碰撞停止。该值的每次碰撞都会发出asyncCountChanged() 信号。

另请参见 asyncCountChanged()。

[signal] void QTaskTree::asyncCountChanged(qsizetype count)

当运行中的任务树即将把控制权返回给调用者的事件循环时，就会发出该信号。任务树启动时，该信号的count 值为0 ，以后每当asyncCount() 值发生碰撞时，都会以更新后的count 值发出该信号。每个发送的信号（除了初始值为0 的信号）都能保证任务树在发送后仍在异步运行。

另请参见 asyncCount()。

void QTaskTree::cancel()

取消正在运行的任务树的执行。

立即取消所有正在运行的任务。所有正在运行的任务和组都会以错误结束，并调用其已完成处理程序DoneWith::Cancel 。存储的onStorageDone() 处理程序也会被调用。progressValueChanged() 信号也在发送。这种行为可以始终依赖。

cancel() 函数是同步执行的，因此调用 cancel() 后，所有正在运行的任务都已完成，树也已取消。只要使用的任务以非阻塞方式实现了它们的析构函数，就能保证 cancel() 快速运行，而不会阻塞等待当前运行任务的结束。

当任务树为空时，即使用默认构造函数构造时，调用 cancel() 将不会执行操作，并发出相关警告信息。

否则，当任务树未启动时，调用 cancel() 会被忽略。

另请参见 ~QTaskTree()。

[signal] void QTaskTree::done(QtTaskTree::DoneWith result)

该信号在任务树结束时发出，传递执行的最终result 。发出该信号后，任务树既不会调用任何处理程序，也不会再发出任何信号。

另请参见 started().

[override virtual protected] bool QTaskTree::event(QEvent *event)

重实现：QObject::event(QEvent *e)。

bool QTaskTree::isRunning() const

如果任务树当前正在运行，则返回true ；否则返回false 。

另请参阅 start() 和cancel()。

template <typename StorageStruct, typename Handler> void QTaskTree::onStorageDone(const QtTaskTree::Storage<StorageStruct> &storage, Handler &&handler)

为storage 安装一个已完成存储的handler ，以便从运行中的任务树动态检索最终数据。

StorageHandler 将const 引用到StorageStruct 实例：

静态QByteArrayload(constQString文件名） {...} Storage<QByteArray>storage;const autoonLoaderSetup= [](QThreadFunction<QByteArray> &task) { task.setThreadFunctionData(&load, "foo.txt"); };const autoonLoaderDone= [storage](constQThreadFunction<QByteArray> &task) {*storage =task.result(); };constGroup root { storage、    QThreadFunctionTask(onLoaderSetup,onLoaderDone,CallDoneFlag::OnSuccess) }；QTaskTreetaskTree(root);autocollectStorage= [](constQByteArray&storage){    qDebug() << "final content" << storage;
}; taskTree.onStorageDone(storage,collectStorage); taskTree.start();

当运行中的任务树即将离开Group （storage 位于其中）时，它会销毁StorageStruct 实例。就在StorageStruct 实例被析构之前，并且在调用了该组中所有可能的处理程序之后，任务树会调用传递的handler 。这样就能动态读取给定存储空间的最终内容，并在任务树之外对其进行进一步处理。

任务树取消运行时也会调用该处理程序。不过，运行中的任务树被销毁时不会调用该处理程序。

另请参见 onStorageSetup().

template <typename StorageStruct, typename Handler> void QTaskTree::onStorageSetup(const QtTaskTree::Storage<StorageStruct> &storage, Handler &&handler)

为storage 安装存储设置handler ，以便将初始数据动态传递给运行中的任务树。

StorageHandler 会引用 StorageStruct 实例：

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

Storage<QByteArray> storage;

const auto onSaverSetup = [storage](QThreadFunction<QByteArray> &task) {
    task.setThreadFunctionData(&save, "foo.txt", *storage);
};

const Group root {
    storage,
    QThreadFunctionTask(onSaverSetup)
};

QTaskTree taskTree(root);
auto initStorage = [](QByteArray &storage){
    storage = "initial content";
};
taskTree.onStorageSetup(storage, initStorage);
taskTree.start();

当运行中的任务树进入storage 所在的组时，它会创建一个StorageStruct 实例，以便在该组内使用。在创建StorageStruct 实例后，在调用该组的任何处理程序之前，任务树会调用传递的handler 。这样就能为指定存储动态设置初始内容。之后，当任何组的处理程序被调用时，任务树就会激活已创建和初始化的存储空间，这样它就可以在任何组的处理程序中使用。

另请参见 onStorageDone()。

qsizetype QTaskTree::progressMaximum() const

返回progressValue() 的最大值。

另请参阅 progressValue()。

qsizetype QTaskTree::progressValue() const

返回当前进度值，介于0 和progressMaximum() 之间。

返回的数字表示任务树运行时有多少任务已完成、取消或跳过。任务树启动时，该数字设置为0 。任务树结束时，该数字始终等于progressMaximum() 。

另请参阅 progressMaximum() 和progressValueChanged()。

[signal] void QTaskTree::progressValueChanged(qsizetype value)

当运行中的任务树完成、取消或跳过某些任务时，就会发出该信号。value 显示当前已完成、取消或跳过的任务总数。当任务树启动时，在started() 信号发出后，该信号会与初始value 0 一起发出。当任务树即将结束时，在done() 信号发出前，该信号会与最终value progressMaximum () 一起发出。

另请参阅 progressValue() 和progressMaximum()。

QtTaskTree::DoneWith QTaskTree::runBlocking()

通过QEventLoop::ExcludeUserInputEvents 执行本地事件循环，并启动任务树。

如果任务树成功完成，则返回DoneWith::Success ；否则返回DoneWith::Error 。

另请参阅 start()。

[static] QtTaskTree::DoneWith QTaskTree::runBlocking(const QtTaskTree::Group &recipe)

使用传入的recipe 构建临时任务树并阻塞运行。

如果任务树成功完成，则返回DoneWith::Success ；否则返回DoneWith::Error 。

另请参阅 start()。

QtTaskTree::DoneWith QTaskTree::runBlocking(const QFuture<void> &future)

传递的future 用于监听取消事件。当任务树被取消时，该方法会取消传递的future 。

[static] QtTaskTree::DoneWith QTaskTree::runBlocking(const QtTaskTree::Group &recipe, const QFuture<void> &future)

传递的future 用于监听取消事件。当任务树被取消时，该方法会取消传递的future 。

void QTaskTree::setRecipe(const QtTaskTree::Group &recipe)

为任务树设置给定的recipe 。任务树启动后，它会执行recipe 中包含的任务，并根据传递的描述处理已完成的任务。

另请参阅 QTaskTree(const QtTaskTree::Group &recipe, QObject *parent = nullptr) 和start() 。

void QTaskTree::start()

启动任务树。

使用setRecipe() 或构造函数设置声明说明，任务树将根据声明说明执行包含的任务并处理已完成的任务。

当任务树为空时，即使用默认构造函数构造任务树时，调用 start() 将不会执行任务，并发出相关警告信息。

否则，当任务树已经运行时，调用 start() 会被忽略并发出相关警告信息。

否则，任务树将被启动。

已启动的任务树可能会同步结束，例如当主组的启动处理程序返回SetupResult::StopWithError 时。因此，应在调用 start() 之前建立与 done 信号的连接。使用isRunning() 可以检测任务树在调用 start() 后是否仍在运行。

任务树的实现依赖于运行中的事件循环。调用此方法时，请确保QEventLoop 、QCoreApplication 或其子类之一正在运行（或即将运行）。

另请参阅 QTaskTree(const QtTaskTree::Group &recipe, QObject *parent = nullptr),setRecipe(),isRunning(), 和cancel().

[signal] void QTaskTree::started()

该信号在任务树启动时发出。该信号发出后，会同步发出带有初始0 值的progressValueChanged() 信号。

另请参阅 start() 和done()。

qsizetype QTaskTree::taskCount() const

返回存储配方中包含的异步任务数。

另请参阅 setRecipe() 和progressMaximum()。