章节导航#

• 本章重要 API 函数
• 学习前后依赖
• 1. 概述
• 2. 核心概念与原理
  • 2.1 线程亲和性：对象”属于”哪个线程
  • 2.2 事件循环是跨线程通信的地基
  • 2.3 两种多线程写法的对比
• 3. 关键机制：moveToThread 前后的对象归属迁移
  • 3.1 对象归属迁移流程图
  • 3.2 连接类型决定槽函数在哪个线程执行
• 4. 核心代码解析
  • 4.1 worker.h：可搬迁的工人类
  • 4.2 worker.cpp：耗时循环与停止标志
  • 4.3 mainwin.cpp：搬迁、启动与连线
  • 4.4 析构：quit + wait 的顺序不能反
• 5. 运行效果与验证
• 容易踩坑（注意点）
• 学习要点总结
  • 核心知识点
  • 关键 API
  • 下一步学习
• Q&A（常见问题）
• Tips（全局速记）

💡 Tips：本篇的阅读顺序建议是 2.1 → 3.1 → 4.3。先建立”对象有归属线程”这个心理模型，再看流程图，最后回到代码；反过来（先看代码）容易把 moveToThread 误当成”创建线程的函数”。

2.1 线程亲和性：对象”属于”哪个线程#

每个 QObject 内部都记着一个”我属于哪个线程”的指针（QObjectPrivate::threadData）。默认值是创建它的那个线程。这个归属决定了两件事：

1. 它接收的事件由谁分发：投递给该对象的事件（QEvent，包括排队的信号调用）会进入其所属线程的事件队列，由该线程的 exec() 取出并调用 event()。
2. 它的定时器归谁管：QTimer 必须在其所属线程里启停，跨线程 start() 会报 Timers cannot be started from another thread。

1
// 在 MainWin 构造函数里（主线程）
2
m_worker = new worker(30);        // 此刻 m_worker 的归属线程 = 主线程
3
m_worker->moveToThread(m_thread); // 归属改为 m_thread 代表的子线程
4
m_thread->start();               // 子线程真正跑起来，进入 exec() 事件循环

注意 new worker(30) 没有传 parent。这是硬性要求：moveToThread 会顺带把对象的所有子对象一起搬走，但如果对象自己有父亲，就意味着父亲和儿子会被劈到两个线程，Qt 直接拒绝这种操作。

2.2 事件循环是跨线程通信的地基#

跨线程信号槽之所以能工作，靠的不是魔法，而是事件队列 + 事件循环：

• 发送方 emit valueReady(0) 时，Qt 发现接收者 MainWin 的归属线程（主线程）≠ 当前线程（子线程）；
• 于是不直接调用槽，而是把”要调用哪个槽、参数是什么”打包成一个 QMetaCallEvent，深拷贝参数，投递到主线程的事件队列；
• 主线程的 app.exec() 在下一次空闲时取出该事件，在主线程上下文中调用 MainWin::do_lcd_show(0)。

这也解释了两个常见困惑：

• 为什么槽函数是”延迟”执行的？ 因为要排队等目标线程的事件循环轮到它。
• 为什么参数类型必须能被 qRegisterMetaType 识别？ 因为要深拷贝进事件对象里，Qt 必须知道怎么拷贝。内置类型和 Q_DECLARE_METATYPE 过的类型才行。

2.3 两种多线程写法的对比#

💡 Tips：原理层面最容易误解的三点，务必刻进脑子：

1. QThread 对象本身属于创建它的线程（本例是主线程），只有它 run() 里的代码在新线程。所以 m_thread 的槽函数（如 finished 的接收方）默认在主线程执行——这不是 bug，是设计。
2. moveToThread 之后对象属于子线程，主线程不能再直接碰它。想让它干活只能”发信号”或 invokeMethod，这是唯一正确的入口。
3. UI 只能在主线程。子线程里 m_lcdShow->display(...) 可能”看起来能跑”，但那是未定义行为——在 Windows 上可能偶尔正常、在 Linux/X11 上直接崩，或者留下一堆 QPainter 警告。

3.1 对象归属迁移流程图#

下面这张图是本篇的核心。左半区是主线程，右半区是子线程；虚线箭头表示”跨线程排队投递”，实线箭头表示”同线程直接调用”。

箭头含义速查：

• A2 → M1：创建在主线程、立刻搬走，这是标准姿势。搬走的时机必须在 start() 之前或之后都行，但必须在”第一次让它干活”之前。
• A4 ⇢ B1：主线程只做一件事——往子线程的队列里塞一个”请执行 doWork”的事件，塞完立即返回，界面不卡。
• B3 ⇢ A5：子线程算出的数字排队回到主线程才敢碰 QLCDNumber。这一步是”UI 只能主线程”这条铁律的具体落地方式。
• A4 ⇢ B5（虚线且指向被 B2 占用的线程）：本工程最隐蔽的坑就在这条箭头上。doExit 是排队投递的，但子线程此刻正卡在 doWork 的 while 里，事件循环压根没机会取事件——所以”停止”按钮在任务跑完之前是无效的。详见第 4 节和踩坑清单。

3.2 连接类型决定槽函数在哪个线程执行#

💡 Tips：流程图里最关键的节点是 B2（doWork 的 while 循环）。它是一个”吞掉整个子线程事件循环”的节点——所有指向子线程的虚线箭头都会在它执行期间被堵在 B1 队列里。理解这一个节点，就理解了为什么”有了子线程也不等于随时可控”：排队投递的前提是目标线程有空闲去跑事件循环。想要”随时可停”，停止标志就必须绕开事件循环（用 atomic + DirectConnection），或者把耗时循环拆成可返回的小片（配合 QCoreApplication::processEvents()）。

4.1 worker.h：可搬迁的工人类#

1
class worker : public QObject          // ① 必须继承 QObject，才有 threadData 和信号槽
2
{
3
    Q_OBJECT                           // ② 必须有 Q_OBJECT，moc 才会生成元对象
4
public:
5
    explicit worker(int max, QObject *parent = nullptr);
6
    ~worker() override;
7

8
public slots:                          // ③ 声明为 slots，invokeMethod 才按名字找得到
9
    void doWork();
10
    void doExit();
11

12
signals:                               // ④ 结果只通过信号往外送，不直接碰 UI
13
    void valueReady(int value);
14
    void overReady();
15

16
private:
17
    int m_max;
18
    std::atomic<bool> task_running{false};   // ⑤ 跨线程读写的标志，必须 atomic
19
};

逐点说明：

• ① 继承 QObject 是 moveToThread 的前提。纯 C++ 类没有线程亲和性概念，也没有槽。删掉继承，整套机制全部失效。
• ② Q_OBJECT 不能省。少了它，moc 不生成 staticMetaObject，QMetaObject::invokeMethod(m_worker, "doWork", ...) 会在运行时输出 No such method 并静默返回 false——编译完全正常，跑起来毫无反应，这是新手最爱掉的坑。
• ③ 注意这里是 public slots: 而不是普通 public 函数。Qt6 里普通成员函数也能用新语法 connect 到信号，但按字符串名反射调用只认 slots 和 Q_INVOKABLE。
• ④ worker 头文件里没有 include 任何 QWidget。这是一种有意的架构约束：一个准备搬到子线程的类，若它连 UI 头文件都没见过，就不可能误碰 UI。
• ⑤ task_running 会被两个线程同时访问——主线程通过 doExit 写、子线程在 while 里读。如果写成裸 bool，编译器可能把 while(task_running) 优化成”只读一次寄存器”的死循环，永远看不到变化；std::atomic<bool> 既保证原子性，也阻止这种优化。

4.2 worker.cpp：耗时循环与停止标志#

1
void worker::doWork()
2
{
3
    qDebug() << "工人工作的ID为：" << QThread::currentThreadId();  // ① 验证归属的关键
4
    int value = 0;
5
    task_running = true;
6
    while (task_running.load() && value <= m_max)               // ② 双条件退出
7
    {
8
        emit valueReady(value++);                              // ③ 结果外送，不碰 UI
9
        QThread::msleep(100);                                  // ④ 睡的是子线程
10
    }
11
    if (task_running.load()) {
12
        qDebug() << "Work normal over";                        // ⑤ 跑满 m_max 自然结束
13
    } else {
14
        qDebug() << "Worker  stop";                            // ⑥ 被 doExit 打断
15
    }
16
    emit overReady();                                          // ⑦ 无论哪种结束都通知 UI
17
}
18

19
void worker::doExit()
20
{
21
    qDebug() << "准备完成任务" << QThread::currentThreadId();
22
    task_running = false;
23
}

• ① 这一行 qDebug 是整个工程的”证据”。把它和 MainWin 构造里的 qDebug()<<"GUI线程ID号为："<<QThread::currentThreadId(); 对比：两个 ID 必须不同，才说明 moveToThread 真的生效了。删掉这行，你就失去了唯一的低成本验证手段。
• ② 循环条件是 task_running.load() && value <= m_max：前者响应”外部要求停止”，后者是”任务自然做完”。缺任何一个，都会得到一个无法中断或永不结束的任务。
• ③ emit valueReady(value++) 是唯一的输出通道。改成 m_lcdShow->display(value)（假如把窗口指针传进来）在语法上完全合法，但那是子线程直接操作 GUI，属于未定义行为。
• ④ QThread::msleep(100) 是 static 函数，睡的是调用它的线程——此刻是子线程，所以主线程界面照样流畅。这里也解释了为什么不能把这段代码留在主线程：同样的 msleep，在主线程就是界面冻结。
• ⑤⑥ 这个 if/else 的判断依据很巧：能走到循环外并且 task_running 仍为 true，只可能是 value > m_max 触发的自然结束；反之就是被 doExit 改成 false 打断的。
• ⑦ emit overReady() 放在两种分支之后，保证任何结束路径都会通知 UI 复位按钮。如果只在正常结束时 emit，按钮就会永远卡在”停止”文字上。

4.3 mainwin.cpp：搬迁、启动与连线#

1
MainWin::MainWin(QWidget *parent) : QWidget(parent),
2
    m_btnStart(nullptr), m_lcdShow(nullptr), m_thread(new QThread(this)),  // ①
3
    m_worker(nullptr), m_isRunning(false)
4
{
5
    initWin();
6
    qDebug() << "GUI线程ID号为：" << QThread::currentThreadId();
7
    m_worker = new worker(30);          // ② 关键：不传 parent
8
    m_worker->moveToThread(m_thread);   // ③ 改归属
9
    m_thread->start();                  // ④ 起线程 + 进 exec()
10

11
    connect(m_worker, &worker::valueReady, this, &MainWin::do_lcd_show);   // ⑤ 跨线程
12
    connect(m_worker, &worker::overReady,  this, &MainWin::do_task_work);  // ⑤
13
    connect(m_thread, &QThread::finished,  this, &MainWin::deleteLater);   // ⑥ 值得商榷
14
    connect(m_btnStart, &QPushButton::clicked, this, &MainWin::do_btn_work);
15
}
16

17
void MainWin::do_btn_work()
18
{
19
    if (!m_isRunning) {
20
        QMetaObject::invokeMethod(m_worker, "doWork", Qt::QueuedConnection);  // ⑦
21
        m_btnStart->setText("停止");
22
        m_isRunning = true;
23
    } else {
24
        QMetaObject::invokeMethod(m_worker, "doExit", Qt::QueuedConnection);  // ⑧ 陷阱
25
    }
26
}

• ① m_thread(new QThread(this))：QThread 对象本身挂在 MainWin 的对象树上，随窗口销毁自动 delete。注意这里 parent 给的是 this——QThread 对象归属主线程，这完全正确，它不是被搬走的那个对象。

• ② new worker(30) 故意不传 parent。这是 moveToThread 能成功的必要条件。如果写成 new worker(30, this)，控制台会打印 Cannot move objects with a parent，而程序继续运行——doWork 就在主线程跑，界面照旧冻结，且两处 currentThreadId() 打印出相同 ID。这是本工程”删掉会怎样”最值得亲手试一次的地方。

• ③④ moveToThread 和 start() 的先后顺序不敏感（都在 invokeMethod 之前即可），但先搬后起是更清晰的表达：先定户口，再开门营业。

• ⑤ 这两个 connect 用的是默认 Qt::AutoConnection。因为 m_worker 属子线程、this 属主线程，Qt 在信号发射的那一刻比较两者归属，自动选 QueuedConnection。这就是”跨线程信号槽自动安全”的全部秘密——你什么都不用写。

• ⑥ connect(m_thread, &QThread::finished, this, &MainWin::deleteLater)：这行的意图应该是”线程结束就清理”，但接收者写成了 this（主窗口）。语义变成了”线程一结束就删主窗口”。在本例中，finished 是在析构函数 quit()+wait() 时才发出的，窗口本来就在销毁，所以没炸；但如果哪天你在运行期主动 m_thread->quit()，主窗口会被 deleteLater 掉，界面凭空消失。更符合意图的写法是 connect(m_thread, &QThread::finished, m_worker, &QObject::deleteLater);——顺手也修掉了 m_worker 从未被 delete 的内存泄漏（跑一遍会发现 worker::~worker 的 qDebug 永远不打印，就是证据）。

• ⑦ invokeMethod(..., "doWork", Qt::QueuedConnection) 是正确用法：把”执行 doWork”投递到子线程队列，主线程立刻返回，然后界面继续响应。这里绝对不能写成 m_worker->doWork()——那是在主线程直接调用，界面冻结 3 秒，多线程白做。

• ⑧ invokeMethod(..., "doExit", Qt::QueuedConnection) 是本工程最值得研究的陷阱：doExit 也被排进子线程队列，可子线程正卡在 doWork 的 while + msleep 里，事件循环无法运转，这个事件要等 doWork 整个跑完才会被取出——那时候设 task_running=false 已经毫无意义。正确写法是 Qt::DirectConnection：

  1
  // 让 doExit 就在 GUI 线程里执行，直接写那个 atomic 标志
  2
  QMetaObject::invokeMethod(m_worker, "doExit", Qt::DirectConnection);

  这也正是 task_running 被设计成 std::atomic<bool> 的原因——它本来就是准备被另一个线程直接写的。用 atomic 却又走 QueuedConnection，等于买了防弹衣却把它挂在衣柜里。

4.4 析构：quit + wait 的顺序不能反#

1
MainWin::~MainWin() {
2
    qDebug() << __PRETTY_FUNCTION__;
3
    m_thread->quit();   // ① 请求事件循环退出
4
    m_thread->wait();   // ② 阻塞等线程真正结束
5
}

• ① quit() 只是给子线程的事件循环发一个”退出”请求，函数立刻返回，线程可能还在跑。
• ② wait() 阻塞主线程，直到子线程函数真正返回。少了 wait() 会发生什么？ MainWin 析构完成、m_worker 所在线程可能还在 emit valueReady，而接收者 MainWin 已成野指针 → 随机崩溃。这是多线程程序里最典型的”退出时偶尔崩”。
• 顺序反了（先 wait() 再 quit()）会直接死锁：主线程等一个永远不会收到退出请求的线程。
• 补充一个本例的隐患：如果退出时任务还在跑，quit() 同样要排队等 doWork 结束，wait() 会把主窗口关闭卡住最长 3 秒。健壮做法是析构里先 doExit（Direct）再 quit()、wait()。

💡 Tips：这几段代码里藏着的关键细节，一句话一条：

• moveToThread 后不要再给对象设父对象，setParent() 会把它拽回父亲所在线程的管辖，等于撤销了搬迁。
• 子线程绝对不碰 UI：worker 里只有 emit，没有任何 widget 指针，这是设计出来的纪律不是巧合。
• invokeMethod 的字符串方法名没有编译期检查：把 "doWork" 拼成 "dowork"，编译通过、运行无反应。Qt5.10+ 可以写 QMetaObject::invokeMethod(m_worker, &worker::doWork, Qt::QueuedConnection);，让编译器帮你查错。
• __PRETTY_FUNCTION__ 是 GCC/Clang/MinGW 扩展，MSVC 下要用 __FUNCSIG__；跨平台请用 Qt 提供的 Q_FUNC_INFO。
• m_worker 全程没被 delete，worker::~worker() 的日志永远不出现——一个被”看起来能跑”掩盖的泄漏。

核心知识点#

1. 线程亲和性：每个 QObject 都有归属线程，决定它的事件由谁分发、槽由谁执行。moveToThread 改的就是这个归属，它不创建线程。
2. 事件循环是跨线程通信的基础设施：跨线程 connect 自动降级为 QueuedConnection，参数被深拷贝、事件排队、由目标线程 exec() 取出执行。目标线程一旦被死循环占用，排队机制立即失效。
3. worker-object 模式（本篇写法）优于继承 QThread：业务类保持纯净的 QObject，天然拥有事件循环、能收信号、可多任务复用同一线程。
4. UI 只能在 GUI 线程：子线程唯一合法的输出方式是 emit 信号，让主线程的槽去更新界面。
5. 协作式停止：耗时循环必须自己检查停止标志（std::atomic<bool>），并且这个标志要通过不依赖事件循环的路径（Direct 调用）来设置。
6. 确定性收尾：quit() → wait() 是固定顺序；worker 用 finished → deleteLater 释放。

关键 API#

下一步学习#

• qt20 绘图基础：本篇建立的”UI 只能在主线程”铁律，直接决定了下一篇 paintEvent 为什么只能由主线程的事件循环调用、为什么用 update()（投递事件）而不是 repaint()（同步绘制）。
• qt21 自定义控件：当绘制内容来自子线程算出的数据（比如实时速度采样）时，正是本篇 emit → 主线程槽 → setSpeed() → update() 这条链路的实战。
• qt22 SQLite：数据库查询是典型耗时操作，会用到本篇的 worker 模式；同时要额外注意”QSqlDatabase 连接对象不能跨线程共享，每个线程要用不同 connectionName 各开一个连接”。

💡 Tips：本篇与”下一步”的挂钩点写死在一句话里——qt20 的 update() 之所以是”请求重绘”而不是”立即重绘”，就是因为它走的是本篇讲的事件队列。你在 qt19 学会的”投递事件 → 事件循环取出 → 执行”这个心理模型，在 qt20 会以 update() → QPaintEvent → paintEvent() 的形式再出现一次。两篇本质上是同一个机制的两种应用。

最容易忽视的细节#

1. new worker(30) 后面那个”没有的 parent”，是整个工程最重要的一行”没写的代码”。 它不是疏忽，是 moveToThread 的硬性前置条件。读代码时看到”该有 parent 却没有”，第一反应就该是”这个对象要被搬走”。
2. std::atomic<bool> 和 Qt::QueuedConnection 在本工程里是互相矛盾的设计。 atomic 的存在意义是”允许被别的线程直接写”，而 Queued 却坚持”排队到本线程执行”。发现这种矛盾，往往就找到了代码的真实 bug。
3. 两行 currentThreadId() 的 qDebug 比任何注释都有用。 多线程调试没有比”打印线程 ID”更廉价可靠的手段了。养成在每个关键槽的第一行打线程 ID 的习惯，能省掉一半的困惑。
4. QThread::finished 是在 run() 返回之后、线程对象层面发出的，不是在 quit() 调用时发出的。所以析构里 quit() 之后马上 wait()，finished 的槽通常在 wait() 返回后的事件循环里才跑——而此时若接收者是 this 而 this 正在析构，就是一段”侥幸没炸”的代码。

踩坑记录#

• “停止按钮不好使”排查了半天，最后发现不是按钮的问题，是事件循环被堵了。 这个经历很典型：多线程 bug 的现象出现位置和根因位置往往相距很远。看到”投递的调用没执行”，第一步永远是问”目标线程此刻在干什么？它有空跑事件循环吗？”
• 带 parent 的 moveToThread 失败是”静默”的。 Qt 大量使用”打印警告 + 继续运行”的容错策略（moveToThread 失败、invokeMethod 找不到方法、QTimer 跨线程 start 都是这样）。所以开发阶段必须盯着控制台输出，把 Qt 的警告当成编译错误来对待。
• worker 析构日志从没出现过。 这类”没发生的事”最难察觉——测试只会验证”该发生的发生了”，不会验证”该释放的释放了”。给每个类的析构函数加一行 qDebug() << Q_FUNC_INFO;，是排查 Qt 对象生命周期问题的低成本高收益做法。

与后续章节的衔接#

1. → qt20 绘图基础：update() 的本质是”往事件队列投递一个 QPaintEvent”，和本篇 invokeMethod(Queued) 是同一个机制。理解了本篇，你就能解释为什么连续调 10 次 update() 只会重绘一次（事件被合并）。
2. → qt21 自定义控件：实时仪表盘的数据源常常是子线程（传感器、串口）。标准链路就是本篇的 worker::emit dataReady(v) → 主线程 SpeedWidget::setSpeed(v) → update() → paintEvent()。三篇笔记在这里合成一条完整的工业级数据可视化管线。
3. → qt22 SQLite：数据库的耗时查询要用本篇的 worker 模式；但数据库有额外约束——QSqlDatabase 连接不能跨线程使用，必须在使用它的那个线程里 addDatabase(type, uniqueConnectionName) 并 open()。这是”线程亲和性”概念在资源管理层面的延伸。
4. → 后续网络/文件章节：QNetworkAccessManager 本身是异步的（内部已有线程），不需要你 moveToThread；但同步的 QFile 大文件读写、图片解码就需要。判断标准是”这个 API 是否会阻塞调用线程”。

设计决策思考#

• 为什么 Qt 不允许多线程操作 GUI，而不是加锁做成线程安全的？ 因为 GUI 操作的粒度太细、调用太频繁（一次布局刷新涉及成百上千次属性读写），逐个加锁的开销会吃掉大部分性能收益，而且极易死锁（widget 的父子关系是图状的，锁顺序无法统一）。底层原因还有一层：Windows 的窗口消息、X11 的连接、macOS 的 AppKit 本身就要求在特定线程调用。Qt 的选择是”承认这个约束，并提供一条安全的跨线程数据通道（事件队列）“，把复杂度限制在一个明确的点上——这比”到处加锁但仍然不保证正确”更工程化。
• 为什么官方从”继承 QThread”改推荐”moveToThread”？ 继承 QThread 时，QThread 子类对象归属主线程，而 run() 在子线程——同一个类的成员变量被两个线程访问，天然容易写错（这是 Qt 早年最著名的困惑源，官方博客那篇《You’re doing it wrong》就是专门讲这个的）。moveToThread 把”线程管理”（QThread）和”业务逻辑”（worker）拆成两个对象，各自归属清晰，心智负担骤降。这是一个”用组合代替继承”的经典案例。
• 为什么停止任务要用”协作式标志”而不是”强制杀线程”？ QThread::terminate() 会在任意指令处切断线程，此时它可能正持有锁、正在 malloc 中途、刚打开文件还没关——留下的是不可恢复的进程状态。协作式停止（检查标志 → 自己清理 → 正常返回）虽然需要业务代码配合，但换来了确定性。这也解释了为什么本例把耗时循环写成 while(flag && ...) 而不是 for(...)：留出被中断的机会，是可中断任务的设计前提。
• 为什么 emit 的参数要深拷贝而不是传引用？ 因为排队投递意味着”信号发出”和”槽执行”之间存在时间差，发送方栈上的临时变量早就销毁了。Qt 选择深拷贝进 QMetaCallEvent，代价是要求参数类型可拷贝且已注册元类型。理解这一点，你就知道为什么跨线程信号不该传裸指针——拷贝的是指针值，指向的对象生命周期没人管，这是跨线程传参最隐蔽的悬空引用来源。