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)

0当正在运行的任务树即将将控制权交还给调用者的事件循环时，会发出此信号。任务树启动时，会发出此信号，其count 值为0 ；此后，每当asyncCount()值发生变化时，都会再次发出此信号，并更新count 值。 每次发送的信号（初始信号的 值为 除外）都保证在信号发出后，任务树仍以异步方式运行。

另请参阅 asyncCount()。

void QTaskTree::cancel()

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

立即取消所有正在运行的任务。所有正在运行的任务和组都将以错误状态结束，并通过DoneWith::Cancel 调用其done处理程序。存储的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 接受一个指向StorageStruct 实例的const 引用：

staticQByteArray load(constQString&fileName) {...}

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)
};

QTaskTree taskTree(root);
autocollectStorage= [](constQByteArray&storage){
    qDebug() << "final content" << storage;
};
taskTree.onStorageDone(storage,collectStorage);
taskTree.start();

当正在运行的任务树即将离开存放storage 的Group 时，它会销毁一个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()

当任务树启动时，会发出此信号。该信号发出后，会同步触发progressValueChanged()信号，其初始值为0 。

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

qsizetype QTaskTree::taskCount() const

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

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