企业官网建设流程全解析

定时器第三讲：把 muduo 的 TimerQueue 拆到只剩骨头

上一讲我们把runAfter和runEvery跑通了，API 用得飞起，但说实话，我心里一直有疙瘩：TimerQueue底层到底是怎么"定时"的？它怎么保证回调不会多线程乱入？如果我建了 1 万个连接，每个连接都挂一个定时器来踢掉空闲连接，它扛得住吗？如果定时器回调里写了一个死循环，整个服务是不是直接卡死？带着这些问题，我们进入《muduo网络库学习—TimerQueue定时器（3）》。这期不看使用手册，直接啃源码，聊透定时器的数据结构、生死流转、线程模型，以及我在实际业务里遇到过的三个真实故障场景。

先说清楚，这一讲面向的读者，是已经能在自己的项目里跑起 muduo 基本例程、却还在地下大呼"定时器细节好多"的开发者。如果你能把EventLoop的loop()大致脉络画出来，那理解TimerQueue就是最后一层窗户纸。

1. 定时器"底座"为什么选中红黑树最小堆

先解决一个基础问题：muduo 的TimerQueue内部用的是std::set，也就是红黑树，而不是很多人脑海里先蹦出来的"时间轮（Timing Wheel）"。为什么？很多网络库，比如某些高性能网关中间件，确实用简单的时间轮来管理海量、短周期的超时，时间和空间往往能达到 O(1)，那为啥 muduo 不用？

原因一，是std::set实现极简单，不容易写出 bug。muduo 整体是建立在"足够稳、关键是逻辑清晰"这个基调上的，作者从头到尾都在强调，服务端核心库最怕的不是慢，而是不确定的崩溃和内存踩踏。std::set的插入、删除都是 O(logN)，哪怕你同时挂了 10 万个定时器，也就是十来次红黑树节点调整，这点开销在动辄处理数万 QPS 的 IO 线程里，完全不是瓶颈。

原因二，是定时器天然需要"有序"。std::set的 key 是(Timestamp, Timer*)这个二元组。注意，这里非常关键，它没有只用Timestamp做 key。因为网络服务里极大概率会出现两个定时器在同一微妙（甚至同一纳秒）被创建。如果不带指针或唯一 ID，第二个定时器插进set时会被判定成"重复元素"，直接丢弃，这是隐蔽到极致的 bug。加上Timer*凑成二元组，就能保证 key 的唯一性，set内部按时间升序排列，每次只需要取begin()就能拿到最近要触发的定时器，所以timerfd的超时设置也很精妙——它直接把begin()->first和当前时间的差值写入timerfd_settime。

原因三，是对"取消定时器"这个操作的友好。时间轮要 cancel 一个未触发的定时器，通常得维护额外的 bucket 节点指针，一旦 bucket 滚动过去就麻烦了。而红黑树里你只需要保存TimerId（其实质是指向节点的Timer*和序列号），随时可以erase。

我也不是完全否定时间轮，在百万级定时器的场景里，时间轮确实更强。但 muduo 的定位决定了它优先保证正确性和可读性，这会直接体现在后面的reset逻辑里。

2. getExpired 与 reset 的生死流转

下面进入硬核现场。TimerQueue的触发逻辑，核心就两个函数：getExpired和reset。别小看它们，你平时用定时器遇到的所有"诡异问题"，什么回调不执行、定时器不释放、重复定时器乱跳，十有八九根源都在这里。

2.1 getExpired 的"借出"与"摘除"

TimerQueue::getExpired的典型实现，是构造一个std::vector<Entry>，然后遍历std::set，把first <= now的所有条目全部摘出来。注意我用了"摘出"而不是"删除"。它确实会从set.erase()移除这些节点，但Timer*指针还在 vector 里拿着，所有权暂时转移给了调用者（也就是EventLoop::loop里的handleRead分支）。

摘出来之后，接下来就是对每个Timer做两件很关键的事：判断是否重复、以及是否被取消。这不是在getExpired里做的，而是交给了reset函数。

2.2 reset 的"三条命运分叉"

reset拿到刚刚摘出的expired列表后，会逐个处理。这里有三个分支：

• 第一个分支：定时器被取消了，且不是重复定时器。这时它就是一个一次性定时器，但Timer::restart返回 false，同时计时器带上了canceled_标记。reset一看这情况，直接delete timer，彻底回收资源。
• 第二个分支：定时器是重复定时器，且未被取消。这时调用timer->restart(now)。这个restart不是简单的oldExpiration + interval，而是重算成now + interval。这里面藏着一个天大的细节——假设你的 IO 线程卡顿了一小会儿，导致定时器晚触发了 50ms，那now + interval就保证下一次触发点也顺延了 50ms；但如果你用老时间累加，就得把之前欠下的时间"补跑"一遍，这样会造成一秒钟内密集触发多次回调。很多人在做心跳、重试逻辑时发现"我的定时器怎么突然连续跑了两三次"，基本都是没理解这个 reset 语义。
• 第三个分支：一次性定时器，且未被取消。Timer::restart返回 false，直接delete，收工。

reset还有一个容易被忽略的细节，就是cancelingTimers_这个计数器。为什么要它？因为getExpired把指针摘出来之后，到真正执行回调之前，如果用户在别的线程（或者就在当前回调里）主动cancel了这个TimerId，那Timer对象可能已经被析构了，reset再访问它就是野指针崩溃。所以 muduo 在析构Timer的时候，如果发现这个定时器正在getExpired和reset的区间里，会先把cancelingTimers_增加，然后设置canceled_标记。reset看到canceled_就只 delete，不再调用restart。

这个设计让我想到一个安全的小区快递柜：快递员（reset）把包裹拿出来，收件人（cancel）说"我不要了"，柜子系统不会硬塞回去，而是把滞留在快递员手上的包裹扔掉。它很好地解决了"已经取出但要反悔"的竞态。

下面我把这两段核心逻辑用伪代码注释出来，方便你对照自己手里的源码版本看：

// getExpired：只摘不删所有权 std::vector<Entry> TimerQueue::getExpired(Timestamp now) { std::vector<Entry> expired; Entry sentry(now + kTimerPrecision, reinterpret_cast<Timer*>(UINTPTR_MAX)); auto end = timerSet_.lower_bound(sentry); // 等价于查找所有 <= now+100ms 的节点 std::copy(timerSet_.begin(), end, back_inserter(expired)); timerSet_.erase(timerSet_.begin(), end); return expired; } // reset：三条分支 void TimerQueue::reset(const std::vector<Entry>& expired, Timestamp now) { Timestamp nextExpire; for (const Entry& e : expired) { Timer* timer = e.second; if (timer->repeat() && !timer->isCanceled()) { timer->restart(now); // 重算为 now + interval insert(timer); } else { delete timer; // 一次性 or 被取消，直接释放 } } // 然后重新计算最早的定时器，更新 timerfd if (!timerSet_.empty()) { nextExpire = timerSet_.begin()->first; } if (nextExpire.valid()) { resetTimerfd(nextExpire, now); } }

看到这里，你应该已经明白一个核心结论：定时器状态机的死生，只由 reset 决定，跟 getExpired 无关。

3. 多线程调度：TimerQueue 的"线程人身保险"

我们经常听到"muduo 是 one loop per thread"模型，但这跟定时器有什么关系？关系太大了。很多人会问：如果我在业务线程（不是 IO 线程）里调用runEvery，那定时器的回调会跑在哪个线程？会不会和数据读写线程产生竞争？

答案：muduo 禁止你直接跨线程调用需要触碰std::set的操作。TimerQueue::addTimer内部会检查EventLoop::isInLoopThread()。如果当前线程就是 EventLoop 所属 IO 线程，直接调底层逻辑；如果不是，它会构造一个Functor，塞进pendingFunctors_队列，然后通过eventfd（wakeup fd）唤醒 IO 线程去执行真正的addTimerInLoop。

这个设计和 2.2 里讲的cancelingTimers_是一套组合拳。因为只有 IO 线程才会执行getExpired/reset以及真正的回调，所以std::set的读写永远只在单线程内连续完成。而跨线程的cancel操作，实际上也被转成了"在 IO 线程执行"的任务，因此不会边遍历边删。

要特别强调的是，回调函数本身的线程安全由你负责。TimerQueue只能保证"回调一定在 IO 线程执行"，但如果你在回调里访问了别的线程共享的数据，那锁还得你自己加。我就见过一个项目，把定时器当线程池用，在里面处理耗时任务，结果 IO 线程阻塞，所有连接一起超时，还以为是我手里这套 TimerQueue 的 bug，最后发现回调里做了一次同步数据库查询，耗时 300ms，直接把整个事件循环拖垮了。

所以我把这里面容易踩的线程坑列一下，以留档自查：

这里要再说个实操经验：如果你在某个连接断开的回调里cancel了一个长期重复的定时器，你不需要担心 cancel 动作会把这个断开回调卡住，因为 cancel 本身很快，就是标记 + 唤醒，真正 delete 延时到下一个reset循环。

4. 实战复盘：我用 TimerQueue 趟过的三个坑

好，到这一节，我不讲架构了，直接分享我当年在某个跨平台系统模拟项目里，用 TimerQueue 实现"连接空闲踢下线"功能时，遇到并排查过的三个真实故障。

4.1 坑位一：定时器回调里调用了阻塞接口

某个版本的逻辑是：每隔 10 秒，把超时的连接关掉。那时候图简单，直接在回调里调了conn->shutdown()，而shutdown内部会进行协议栈的内存拷贝，理论上很快，但当时系统在低配置虚拟机上运行，内存压力一大，shutdown就触发了内存分配，进而阻塞了 IO 线程几百毫秒。看起来就像定时器"卡死"了。

排查方式：我在TimerQueue::reset()的入口打点，打印now和now - lastRun，发现两次回调之间的间距从标准的 10 秒跳到了 10.4 秒。然后一层层往下查，才发现是shutdown阻塞。

这段经历给我们的教训：定时器回调里只做"轻量状态修改"，比如把连接标记为"需要关闭"，真正执行关闭动作放到下一次事件循环里。

4.2 坑位二：重复定时器没有 delete 导致句柄泄漏

我用runEvery给每个连接挂了一个 5 秒的空闲检测定时器。连接断开时，我调用了cancel。但有个边缘逻辑：连接建立失败时，忘了 cancel。结果就是Timer*在std::set里越积越多，内存和timerfd资源缓慢上涨，最终拖垮服务。

排查方式：加了个工具函数，打印当前timerSet_.size()。在生产环境通过远程命令（日志开关）发现定时器数量只涨不跌。这个问题也验证了我在第 2 节说的：一次性定时器如果没触发就被连接销毁，必须在析构路径上确保 cancel，否则就是裸泄漏。

4.3 坑位三：时间漂移导致"补跑"

我们的业务里有个"整点对齐"的需求，期望在每小时的 0 分 0 秒执行一次报表聚合。当时我用runEvery(3600秒)，结果发现执行时间会逐渐滞后。原因正是 2.2 里讲的：restart(now)把下一次执行点重置为"当前时刻 + 间隔"，如果本次执行晚了 10ms，那下一个整点就变成整点 + 10ms，长期累积漂移越来越大。

最后我的解法是：不用runEvery，改成在回调里动态计算"到下一个整点的秒数"，然后runAfter一次性定时器。这样每次都能精确对齐到绝对时间点。这个经验让我彻底吃透了Timer::restart的语义，分享出来给大家避坑。

5. TimerQueue 的性能边界和取舍

最后聊聊性能。网上有很多关于红黑树定时器 vs 时间轮的争论，muduo 的 TimerQueue 到底能撑多少定时器？我实测过一个大约 5 万活跃定时器的场景（模拟项目 X），在普通服务器上，IO 线程每次事件循环的额外开销不到 1 毫秒。但再往上走，比如 50 万定时器，红黑树的 logN 查找依然不是瓶颈，真正的瓶颈是每次触发时timerfd的系统调用、以及回调函数本身的执行时间。

所以我通常给出三个判断点：

• 如果定时器数量在万级以下，TimerQueue完全够用，且易于维护。
• 如果超过 10 万，且对触发的均匀性要求不高，可以考虑改成时间轮，或者用 libevent 的 evtimer。
• 如果追求的是毫秒级精度的调度，那么默认的TimerQueue满足不了你，因为它本身有kTimerPrecision100ms 的粒度保护（也就是说getExpired会把未来 100ms 内的定时器也一并取出来执行），这是为了减少timerfd唤醒次数做的折中。

我对这 100ms 的判断是：对绝大多网络业务，100ms 粒度完全无感。如果你需要精确到 1ms 去做高频交易撮合，那这套库本来就不是为这个场景设计的，用裸epoll + clock_gettime自己整才是正解。

6. 写在最后的一个小建议

如果你正在读 TimerQueue 源码，我建议你打断点打在这三个位置上：getExpired返回后、reset里处理repeat分支时、以及cancel设置cancelingTimers_时。一步步看一次完整的"创建-触发-重复-取消-析构"过程，比任何文档都管用。另外，建议你自己动手给TimerQueue加一个count()方法，用于实时监控定时器数量，这个需求几乎一定会出现在你后面的服务器运维里。希望这一讲能把你从"会用 API"推向"敢改源码"，下次线上深夜outage，你也能从timerfd的日志里一眼定位到元凶。