QtTaskTree::QCustomTask Class
template <typename Task, typename Adapter, typename Deleter> class QtTaskTree::QCustomTask一个用于声明自定义任务项并定义其初始化和完成处理程序的类模板。更多内容...
| 头文件： | #include <qtasktree.h> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS TaskTree) target_link_libraries(mytarget PRIVATE Qt6::TaskTree) |
| qmake： | QT += tasktree |
| 自： | Qt 6.11 |
| 继承自： | QtTaskTree::ExecutableItem |
| 状态： | 技术预览 |
该类处于技术预览阶段，内容可能会有变动。
注意：该类中的所有函数均为可重入函数。
公共类型
公共函数
| QCustomTask(SetupHandler &&setup = QCustomTask::TaskSetupHandler(), DoneHandler &&done = QCustomTask::TaskDoneHandler(), QtTaskTree::CallDone callDone = QtTaskTree::CallDoneFlag::Always) |
相关的非成员
| QBarrierTask | |
| QNetworkReplyWrapperTask | |
| QProcessTask | |
| QTaskTreeTask | |
| QTcpSocketWrapperTask | |
| QThreadFunctionTask | |
| QTimeoutTask |
详细说明
描述任务树配方中的自定义任务项。
自定义任务名称通过 QCustomTask 模板，结合给定的Task 、Adapter 和Deleter ，以唯一名称进行别名设置。例如，QThreadFunctionTask<T> 是 QCustomTask 的别名，该 QCustomTask 被定义为与QThreadFunction<T> 作为关联任务类配合使用。下表列出了 TaskTree 库提供的自定义任务及其关联的任务类：
| 别名任务名称 | 关联任务类 | 简要说明 |
|---|---|---|
| QBarrierTask | QBarrier | 启动一个等待器任务。 |
| QThreadFunctionTask<返回类型> | QThreadFunction<返回类型> | 启动一个异步任务。在单独的线程中运行。 |
| QProcessTask | QProcess | 启动一个进程。 |
| QNetworkReplyWrapperTask | QNetworkReplyWrapper | 发送网络查询。 |
| QTaskTreeTask | QTaskTree | 启动一个嵌套任务树。 |
| QTcpSocketWrapperTask | QTcpSocketWrapper | 建立 TCP 连接。 |
| QTimeoutTask | std::chrono::milliseconds | 启动一个定时器。 |
Task 模板参数是必填的，用于指定当运行中的QTaskTree 作为配方的一部分时，将实例化何种类型的Task 。Task 类型必须支持默认构造。
Adapter 模板参数是可选的。如果QDefaultTaskAdapter<Task>能够适配Task 类型，则可以省略该参数。否则，针对特定Task 的Adapter 必须采用以下形式：
class Adapter
{
public:
void operator()(Task *task, QTaskInterface *iface) { ... }
};实现上述 operator() 方法以启动task ，并在任务完成时对传入的iface 调用QTaskInterface::reportDone() 方法。
可以保证，传入的Task 和QTaskInterface 的存活时间将长于Adapter 。如有必要，Adapter 的析构函数仍可访问传入的Task 。
更多详细信息请参阅QTaskInterface 。
Deleter 模板参数是可选的。默认情况下，使用std::default_delete<Task> 。当正在运行的Task 的析构函数可能阻塞调用者线程时，自定义的Deleter 就派上了用场。自定义删除器不会直接阻塞，而是会将正在运行的任务移至一个单独的线程中，并在该线程中实现阻塞式销毁。 通过这种方式，可以实现（从调用线程的角度来看）带有阻塞式析构函数的运行中任务的快速销毁。
另请参阅 QTaskInterface 。
成员类型文档
[alias] QCustomTask::TaskDoneHandler
std::function<QtTaskTree::DoneResult(const Task &, QtTaskTree::DoneWith)> 或DoneResult 的类型别名。
TaskDoneHandler 是自定义任务元素构造函数的一个可选参数。任何具有上述签名的函数，当作为任务完成处理程序传递时，都将在任务执行完成之后、执行的最终结果报告给父组之前，由正在运行的任务树调用。
在处理程序的主体内部，您可以从已完成的任务中检索最终数据。包括存储区在内的附加参数可通过 lambda 捕获传递给处理程序。此外，还可以动态决定任务是应以返回值结束，还是应调整最终结果。
DoneWith 参数是可选的，您的完成处理程序可以省略它。如果提供了该参数，它将包含任务最终结果的相关信息，这些信息将上报给其父组。
如果您不打算从已完成的任务中读取任何数据，可以省略 `const Task & ` 参数。
返回的 `DoneResult ` 值是可选的，您的处理程序也可以返回 `void `。在这种情况下，任务的最终结果将等于 `DoneResult ` 参数指定的值。当处理程序返回 `DoneResult ` 值时，任务的最终结果可以在 `done` 处理程序的主体中根据返回值进行调整。
对于类型为DoneResult 的 TaskDoneHandler，不会执行任何额外处理，任务将无条件地以传入的DoneResult 值结束。
另请参阅 QCustomTask()、TaskSetupHandler 以及GroupDoneHandler 。
[alias] QCustomTask::TaskSetupHandler
std::function<SetupResult(Task &)> 的类型别名。
TaskSetupHandler 是自定义任务元素构造函数的一个可选参数。任何具有上述签名的函数，当作为任务设置处理程序传递时，都将在任务创建后、启动前由正在运行的任务树调用。
在处理程序的主体内部，您可以根据需要配置该任务。包括存储在内的附加参数可通过 lambda 捕获传递给处理程序。您可以动态决定是否启动任务，或以成功或错误状态跳过任务。
注意：请 勿在启动处理程序内部自行启动任务。应交由QTaskTree 负责，否则行为将无法定义。由于传递给QCustomTask<Task, Adapter, Deleter>构造函数的Adapter模板参数，QTaskTree 已知晓如何启动该任务。
处理器的返回值会指示正在运行的任务树在处理器调用完成后如何继续执行。SetupResult::Continue 的返回值指示任务树继续运行，即执行相关的Task 。SetupResult::StopWithSuccess 或SetupResult::StopWithError 的返回值指示任务树跳过该任务的执行，并分别以成功或错误的状态立即结束该任务。
当返回类型为SetupResult::StopWithSuccess 或SetupResult::StopWithError 时，任务的完成处理程序（如果提供）随后将不会被调用。
自定义任务的构造函数也接受std::function<void(Task &)> 这种简写形式的函数，即返回值为void 。在这种情况下，默认假设返回值为SetupResult::Continue 。
另请参阅 QCustomTask()、TaskDoneHandler 以及GroupSetupHandler 。
成员函数文档
[explicit] template <
typename SetupHandler = QtTaskTree::QCustomTask<Task, Adapter, Deleter>::TaskSetupHandler,
typename DoneHandler = QtTaskTree::QCustomTask<Task, Adapter, Deleter>::TaskDoneHandler,
std::enable_if_t<!std::is_same_v<q20::remove_cvref_t<SetupHandler>, QCustomTask<Task, Adapter, Deleter>>, bool> = true
>
QCustomTask::QCustomTask(SetupHandler &&setup = QCustomTask::TaskSetupHandler(), DoneHandler &&done = QCustomTask::TaskDoneHandler(), QtTaskTree::CallDone callDone = QtTaskTree::CallDoneFlag::Always)
创建一个 QCustomTask 实例，并将setup 和done 处理程序附加到该任务上。 当运行中的任务树即将启动该任务时，它会实例化关联的Task 对象，调用setup 处理程序（传入对已创建任务的引用），并启动该任务。当运行中的任务完成时，任务树会调用done 处理程序，并传入对已创建任务的const 引用。
传递的setup 处理程序属于TaskSetupHandler 类型。例如：
static void parseAndLog(const QString &input);
...
const QString input = ...;
const auto onFirstSetup = [input](QThreadFunction<void> &task) {
if (input == "Skip")
return SetupResult::StopWithSuccess; // This task won't start, the next one will
if (input == "Error")
return SetupResult::StopWithError; // This task and the next one won't start
task.setThreadFunctionData(parseAndLog, input);
// This task will start, and the next one will start after this one finished with success
return SetupResult::Continue;
};
const auto onSecondSetup = [input](QThreadFunction<void> &task) {
task.setThreadFunctionData(parseAndLog, input);
};
const Group group {
QThreadFunctionTask<void>(onFirstSetup),
QThreadFunctionTask<void>(onSecondSetup)
};done 处理程序的类型为TaskDoneHandler 。默认情况下，每当任务完成时，都会调用done 处理程序。若希望仅在执行成功、失败或被取消时调用该处理程序，请为callDone 参数传递非默认值。
另请参阅 TaskSetupHandler 和TaskDoneHandler 。
相关的非成员
[alias] QBarrierTask
QCustomTask<QBarrier> 的类型别名，用于在配方中使用。
[alias] QNetworkReplyWrapperTask
QCustomTask<QNetworkReplyWrapper> 的类型别名，用于在配方中使用。
[alias] QProcessTask
为QCustomTask<QProcess> 定义类型别名，使用QProcessTaskDeleter ，供在配方中使用。
[alias] QTaskTreeTask
QCustomTask<QTaskTree> 的类型别名，用于在配方中使用。
[alias] QTcpSocketWrapperTask
QCustomTask<QTcpSocketWrapper> 的类型别名，用于在配方中使用。
[alias] template <typename ResultType> QThreadFunctionTask
QCustomTask<QThreadFunction<ResultType>> 的类型别名，其中ResultType 指定线程函数的返回类型，用于在配方中。
[alias] QTimeoutTask
QCustomTask 的类型别名 <std::chrono::milliseconds> ，用于在配方中使用。std::chrono::milliseconds 用于设置超时时长。默认超时行为为std::chrono::milliseconds::zero() ，即当控制权返回至正在运行的事件循环时，QTimeoutTask立即结束。
使用示例：
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 {
QTimeoutTask(onSetup, onDone)
};另请参阅 timeoutTask()。
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
