Linux 等待队列源码剖析:从调度原语到工业级实现
- 2026-09-08 04:30:46
本篇是从调度器视角看进程同步：三个原语的下篇
上篇我们手写了 30 行极简实现 my_sync，已经覆盖进程阻塞的全部核心逻辑，但存在两个致命工程缺陷：
只能等待单个进程：多进程同时阻塞时，后到达进程会直接覆盖原有 waiter 指针；
缺少并发保护：多核场景下读写 waiter 会发生数据撕裂。
一、开篇：从 my_sync 到等待队列
回顾上篇手写玩具实现 my_sync：
struct my_sync {int ready;struct task_struct *waiter;};/* 等待函数 */voidmy_wait(struct my_sync *sync){sync->waiter = current; // 规则1：先入队for (;;) {set_current_state(TASK_UNINTERRUPTIBLE); // 规则2a：先改状态if (sync->ready) // 规则2b：再检查条件break;schedule(); // 规则2c：最后才休眠}set_current_state(TASK_RUNNING); // 规则6：退出前恢复运行状态sync->waiter = NULL; // 清理}/* 唤醒函数 */voidmy_wakeup(struct my_sync *sync){struct task_struct *waker;sync->ready = 1; // 规则3：先改条件smp_mb(); // 规则4：内存屏障waker = READ_ONCE(sync->waiter); // 规则5：快照共享变量if (waker) {wake_up_process(waker);}}
两个缺陷对应的工程解法：
list_head，容纳任意数量等待者 | |
spinlock_t，保护全部链表操作 |
这也构成等待队列头最核心的两个字段：
struct wait_queue_head {spinlock_t lock; // ← 解决多核并发安全struct list_head head; // ← 解决多进程同时等待};typedef struct wait_queue_head wait_queue_head_t;
下面带着这个对照视角，拆解内核真实源码。
二、数据结构速查：比 my_sync 多了什么
2.1 队列头：锁 + 链表
struct wait_queue_head {spinlock_t lock; // ← 解决多核并发安全struct list_head head; // ← 解决多进程同时等待};typedef struct wait_queue_head wait_queue_head_t;
设计决策 自旋锁直接内嵌在队列头，队列头本身就是共享临界资源；所有入队、出队、链表遍历操作，都必须持有这把锁。
wake_up() 内部实际调用了spin_lock_irqsave(&wq_head->lock, flags)，因此无论在进程上下文还是中断上下文调用 wake_up() 都是安全的。
2.2 队列项：进程指针 + 唤醒回调
struct wait_queue_entry {unsigned int flags; // 状态标记集合void *private; // 指向 task_struct，对标 my_sync->waiterwait_queue_func_t func; // 被唤醒时执行回调函数struct list_head entry; // 链表节点，串联全部等待项};
对比 my_sync->waiter 的能力进化：
三、API 速查手册与选型指南
按功能分类整理，方便开发时快速索引。
3.1 初始化接口
DECLARE_WAIT_QUEUE_HEAD(name)：静态定义并初始化队列头。适用于全局或文件域的静态变量。init_waitqueue_head(wq_head)：动态初始化队列头。适用于堆上分配的结构体。DEFINE_WAIT(name)：静态定义现代标准队列项，绑定默认自动唤醒回调autoremove_wake_function，唤醒成功后自动出队清理，无需手动删链。适配prepare_to_wait / finish_wait成套现代接口，所有新内核代码首选，覆盖 90% 业务场景。
💡 范式区分与核心禁忌
现代标准范式（新代码首选）：
DEFINE_WAIT+autoremove_wake_function+prepare_to_wait / finish_wait。自动管理队列项入队、出队、清理，规避 UAF 与内存泄漏风险，是内核主流开发规范。遗留兼容范式（仅老代码维护）：
DECLARE_WAITQUEUE+default_wake_function。无自动清理逻辑，必须手动配对add_wait_queue / remove_wait_queue，新项目禁止使用。核心禁忌：两套范式绝对不能交叉混用 API（如
DEFINE_WAIT搭配手动remove_wait_queue、DECLARE_WAITQUEUE依赖自动出队），会直接导致重复删链、内存残留、Use-After-Free 等致命 bug。
3.2 入队 / 出队接口
入队接口
prepare_to_wait()：清除独占标志，非独占入队。将队列项插入链表队头，支持全局批量唤醒。适用于绝大多数多进程监听、事件通知类场景，是新代码默认的标准入队方式。prepare_to_wait_exclusive()：设置独占标志，独占入队。将队列项插入链表队尾，唤醒时仅唤醒一个独占等待进程，天然规避惊群效应。适用于资源竞争场景，典型用于 TCP accept、设备独占 IO 等待等。prepare_to_wait_event()：跟随队列项配置，高阶封装接口。是wait_event系列宏的底层实现，在入队、状态切换基础上内置信号 pending 预检测，提前处理信号中断分支并安全清理队列项，彻底杜绝信号退出导致的 UAF 与内存残留。
出队接口
finish_wait()：现代统一出队收尾接口，配套上述所有入队接口使用。自动将进程恢复为TASK_RUNNING运行态，安全判空链表节点并按需自动清理，无需手动删链。完美适配autoremove_wake_function自动出队机制，根治手动管理的各类内存 bug。
3.3 睡眠接口（推荐，自动管理入队出队）
wait_event(wq, cond)：状态TASK_UNINTERRUPTIBLE，不可被信号中断，无超时。wait_event_interruptible(wq, cond)：状态TASK_INTERRUPTIBLE，可被信号中断，无超时。wait_event_timeout(wq, cond, timeout)：状态TASK_UNINTERRUPTIBLE，不可被信号中断，支持超时。wait_event_interruptible_timeout(wq, cond, timeout)：状态TASK_INTERRUPTIBLE，可被信号中断，支持超时。wait_event_killable(wq, cond)：状态TASK_KILLABLE，仅致命信号SIGKILL可中断，无超时。大量内核 I/O 路径使用。
⚠️ 关键提醒：
wait_event_interruptible、wait_event_*_timeout、wait_event_killable这些接口必须检查返回值，因为它们可能因信号或超时而提前返回，此时条件未必成立。
3.4 唤醒接口
wake_up(wq)：唤醒目标为TASK_INTERRUPTIBLE+TASK_UNINTERRUPTIBLE。唤醒所有非独占项；对于独占项，默认只唤醒 1 个。wake_up_interruptible(wq)：仅唤醒TASK_INTERRUPTIBLE状态的进程，独占行为同上。wake_up_nr(wq, nr)：唤醒目标与wake_up一致，区别是可唤醒指定数量nr个独占等待项。wake_up_all(wq)：唤醒目标与wake_up一致，但忽略独占标记，唤醒全部等待进程。
⚠️ 高频误区：很多开发者误以为 wake_up() 只会唤醒一个进程。真实行为是：非独占等待项会全部唤醒；只有设置了 WQ_FLAG_EXCLUSIVE 标志的独占项，默认才只唤醒一个。
四、两个例子看 API 怎么用
例子1：最简用法 — 使用封装宏（绝大多数业务）
上篇 my_wait 需要手动完成：入队 → 修改状态 → schedule → 出队。 wait_event 系列宏把整套逻辑封装为一行代码。
// 阻塞等待条件成立wait_event(wq, condition);// 修改条件，触发唤醒condition = 1;wake_up(&wq);
内部自动处理入队、状态切换、调度、出队清理。普通驱动开发优先这套写法。
例子2：现代接口手动范式（小众高阶场景）
绝大多数场景优先使用 wait_event 封装宏，极简且安全。仅需自定义等待逻辑、精细控制阻塞流程时，使用【现代成套手动接口】（DEFINE_WAIT + prepare_to_wait + finish_wait）。
对比玩具实现 my_sync：
// my_sync 单等待者sync->waiter = current; // 入队（指针赋值）for (;;) {set_current_state(TASK_UNINTERRUPTIBLE);if (sync->ready)break;schedule();}set_current_state(TASK_RUNNING);sync->waiter = NULL; // 出队（清空指针）
内核现代标准手动编码范式：
// 配套：DEFINE_WAIT + prepare_to_wait + finish_wait 标准三件套DEFINE_WAIT(wait);for (;;) {prepare_to_wait(&wq, &wait, TASK_UNINTERRUPTIBLE);if (condition)break;// 条件不满足，主动让出CPU阻塞schedule();}// 统一收尾：恢复运行态 + 安全清理队列项finish_wait(&wq, &wait);
上述极简代码，内核底层完全等价于下方手动现代范式，所有复杂的队列管理、状态处理、异常兜底均被宏封装，极大降低手写bug概率。
玩具实现、现代内核实现逻辑对照：
核心本质：链表替换指针解决多进程；自旋锁保护链表解决多核；其余阻塞唤醒逻辑与玩具实现完全一致。
补充： 手动范式里使用循环判断cond是否满足，是因为存在虚假唤醒，即使没有任何人调用 wake_up，进程也有可能被调度器唤醒。这是 Linux 调度器允许的行为，不是 bug。
五、等待宏的源码拆解
下面深入内核源码，看 wait_event 宏如何实现「入队 → 修改状态 → schedule → 出队」整套流程。
5.1 ___wait_event 宏完整展开
#define ___wait_event(wq_head, condition, state, exclusive, ret, cmd) \({ \__label__ __out; \struct wait_queue_entry __wq_entry; \long __ret = ret; \\init_wait_entry(&__wq_entry, exclusive ? WQ_FLAG_EXCLUSIVE : 0); \// 规则1：初始化队列项，准备入队 \\for (;;) { \long __int = prepare_to_wait_event(&wq_head, &__wq_entry, state);\// 内部完成：入队 + set_current_state \\if (condition) // 规则2：改状态后校验条件break;if (___wait_is_interruptible(state) && __int) { // 信号到来处理__ret = __int;goto __out;}cmd; // 执行 schedule()}finish_wait(&wq_head, &__wq_entry); // 规则6：恢复运行态、清理队列项__out:__ret;})
___wait_event 宏中的 cmd 参数允许传入 schedule()、schedule_timeout() 等，这正是 wait_event_timeout 的实现基础。下面一小段代码展示如何使用：
#define __wait_event_timeout(wq_head, condition, timeout) \___wait_event(wq_head, ___wait_cond_timeout(condition), \TASK_UNINTERRUPTIBLE, 0, timeout, \__ret = schedule_timeout(__ret))
5.2 prepare_to_wait_event：入队 + 修改进程状态
longprepare_to_wait_event(struct wait_queue_head *wq_head,struct wait_queue_entry *wq_entry, int state){unsigned long flags;long ret = 0;spin_lock_irqsave(&wq_head->lock, flags);if (signal_pending_state(state, current)) {list_del_init(&wq_entry->entry); // 有未处理信号，直接出队ret = -ERESTARTSYS;} else {if (list_empty(&wq_entry->entry)) {// ★规则1验证：先完成入队，再修改进程状态if (wq_entry->flags & WQ_FLAG_EXCLUSIVE)__add_wait_queue_entry_tail(wq_head, wq_entry);else__add_wait_queue(wq_head, wq_entry);}set_current_state(state); // ★规则2验证：修改状态，之后才会schedule}spin_unlock_irqrestore(&wq_head->lock, flags);return ret;}
5.3 prepare_to_wait_event 使用的自旋锁带了内存屏障
prepare_to_wait_event 在 spin_lock_irqsave 内完成了所有写操作，释放锁时自带 UNLOCK 语义屏障；
wake_up 在遍历链表前通过 spin_lock 获得了 ACQUIRE 语义，因此内核自旋锁已经隐式保证了唤醒者与等待者之间的序关系，无需额外显式屏障。
my_sync里没有锁保护，所以要用内存屏障来保护。使用内存屏障比较复杂，容易出错，而使用这些锁，会自带内存屏障，代码写起来也不容易出错。
5.4 finish_wait：恢复运行态
voidfinish_wait(struct wait_queue_head *wq_head, struct wait_queue_entry *wq_entry){__set_current_state(TASK_RUNNING); // ★规则6：强制恢复运行态if (!list_empty_careful(&wq_entry->entry)) {spin_lock_irqsave(&wq_head->lock, flags);list_del_init(&wq_entry->entry);spin_unlock_irqrestore(&wq_head->lock, flags);}}
为什么必须恢复 TASK_RUNNING？ 循环 break 只代表条件成立，进程状态依旧是 TASK_INTERRUPTIBLE；不恢复的话调度器会继续认为进程处于休眠，永远不会调度运行。
六、唤醒路径的源码拆解
6.1 __wake_up_common：遍历等待链表
static int __wake_up_common(struct wait_queue_head *wq_head, unsigned int mode,int nr_exclusive, int wake_flags, void *key){wait_queue_entry_t *curr, *next;list_for_each_entry_safe_from(curr, next, &wq_head->head, entry) {unsigned flags = curr->flags;int ret;// 执行对应现代唤醒回调：autoremove_wake_functionret = curr->func(curr, mode, wake_flags, key);if (ret < 0)break;// 独占等待阈值耗尽，停止唤醒，缓解惊群效应if (ret && (flags & WQ_FLAG_EXCLUSIVE) && !--nr_exclusive)break;}return nr_exclusive;}
💡 惊群效应核心补充：
当大量进程同时阻塞等待同一个事件时，普通唤醒会批量唤醒所有等待进程，但最终仅有一个进程能抢占到目标资源，其余被唤醒的进程会再次进入休眠，产生大量无效上下文切换，浪费CPU资源、降低系统吞吐。
内核通过 WQ_FLAG_EXCLUSIVE 独占等待机制高效缓解该问题：设置该标志的独占等待进程会插入链表尾部，唤醒时仅唤醒指定数量的独占等待进程，从内核层面规避大规模无效唤醒，解决惊群问题。
6.2 autoremove_wake_function：唤醒后移除队列
intautoremove_wake_function(struct wait_queue_entry *wq_entry, unsigned mode,int sync, void *key){int ret = default_wake_function(wq_entry, mode, sync, key);if (ret)list_del_init(&wq_entry->entry); // 唤醒成功，立刻从链表摘除return ret;}
七、常见致命陷阱与破解
陷阱1：持有自旋锁时睡眠 → 内核 Panic
spin_lock(&lock);wait_event(wq, condition); // ❌错误！schedule 在持有自旋锁期间调用spin_unlock(&lock); // 永远得不到执行
根因：自旋锁持有期间抢占被禁用，schedule 触发调度，直接死锁；内核 BUG_ON(in_atomic()) 检测触发panic。
破解：自旋锁内部仅做条件判断；调用 wait_event 之前释放自旋锁 / RCU读锁。
陷阱 2：未检查返回值，误以为条件一定成立
wait_event_interruptible、wait_event_*_timeout、wait_event_killable 这些接口可能由于信号或者超时提前返回。需要判断返回值。
// ❌ 错误：wait_event_interruptible 可能因信号返回，但 condition 仍为 falsewait_event_interruptible(wq, condition);do_something(); // ← 危险！condition 可能仍为 false
根因：wait_event_interruptible 的退出条件有两个：
condition 变为 true → 正常唤醒；
进程收到信号（SIGINT/SIGTERM）→ 函数直接返回，不保证 condition 为 true。
破解：判断返回值。
// ✅ 正确方式 1：检查返回值ret = wait_event_interruptible(wq, condition);if (ret)return ret; // 返回 ret（可能为 -ERESTARTSYS）do_something(); // 此时 condition 一定为 true
注意wait_event_interruptible_timeout() 的返回值有四种情况：
0：超时时间耗尽，condition仍为false1：超时时间耗尽，但condition在超时瞬间刚好变为true（极少见）> 1（剩余 jiffies）：condition在超时前变为true，返回剩余的 jiffies 数（至少 1）-ERESTARTSYS：被信号中断
陷阱3：误用老旧接口、信号返回未清理 → Use‑After‑Free
现代接口 wait_event_interruptible 会自动处理信号分支、清理队列项，无此风险。该bug仅存在于老旧 DECLARE_WAITQUEUE 接口，手动管理链表演变的遗留坑，新项目用现代接口可完全规避。
// 仅老旧接口存在的风险代码（新项目禁止模仿）DECLARE_WAITQUEUE(wait, current); // 遗留旧接口！新项目禁用add_wait_queue(&wq, &wait);while (!condition) {set_current_state(TASK_INTERRUPTIBLE);schedule();if (signal_pending(current)) {remove_wait_queue(&wq, &wait); // 旧接口必须手动清理，极易遗漏return -ERESTARTSYS;}}remove_wait_queue(&wq, &wait);
最优规避方案：全程使用现代等待队列接口，彻底抛弃老旧手动管理范式，从代码层面杜绝此类漏洞。
陷阱4：栈上队列项提前返回，生命周期不匹配 → Use‑After‑Free
int func(void){DEFINE_WAIT(wait);prepare_to_wait(&wq, &wait, TASK_INTERRUPTIBLE);if (some_error)return -EINVAL; // ❌直接return，栈帧销毁，但队列项还挂在链表！// ...等待逻辑...finish_wait(&wq, &wait);return 0;}
根因：DEFINE_WAIT 宏初始化的是栈上变量，函数返回栈销毁，如果没有出队，链表引用已经销毁的栈内存，触发UAF。
破解：所有异常分支，都要保证队列项出队之后再return。
八、总结
从 30 行的玩具 my_sync 到内核等待队列，本质只做了两件事：
list_head | |
spinlock_t，全部队列操作持有锁 |
围绕这两个数据结构，内核构建了一套完备的阻塞/唤醒基础设施：
封装宏 wait_event系列：自动完成入队、改状态、schedule、出队，屏蔽底层细节，是 90% 场景的首选；手动范式 prepare_to_wait + finish_wait：灵活可控，适用于自己控制流程的高阶场景；独占等待 WQ_FLAG_EXCLUSIVE：将唤醒数量限制为 1 个，从内核层面缓解惊群效应；信号/超时退出： _interruptible和_timeout变体提供了可被打断、有超时上限的等待能力，务必检查返回值。
理解等待队列，本质上就是理解 Linux 如何将“阻塞-唤醒”这一对操作抽象为链表+锁的通用基础设施，并用宏封装将正确性沉淀到内核内部，让开发者只需关注业务条件本身。
