Linux eventfd 原理与实战：高效线程/进程事件通知机制

在Linux下写多线程或者多进程程序，最绕不开的一件事就是：怎么高效地告诉另一个线程或进程“有活干了”。有人用管道，有人用信号量，有人直接条件变量加锁。如果你在维护或者设计一个高性能的网络服务，eventfd 这个名字你一定不陌生——它是内核专门提供的一种轻量级事件通知机制，本质上就是一个放在文件描述符上的计数器。我最早接触它是在做网络IO线程模型改造的时候，把原来用 pipe 唤醒IO线程的写法换成了 eventfd，延迟和代码复杂度都降了一截。

这篇文章不打算做成 man page 的翻译，我想从实际项目里怎么用、为什么这么用的角度，把 eventfd 讲透。内容包括：eventfd 的核心语义和设计思路、关键 API 参数、线程和进程两种场景下的完整示例、和 epoll 配合的注意点，以及我踩过的一些坑。无论你是刚接触 Linux 系统编程，还是已经在写网络框架，相信都能从中拿到一些可以直接用的东西。

1. 项目解读与核心设计思路

1.1 eventfd 到底是什么

先从内核视角看一次。调用 eventfd() 之后，内核帮你创建了一个匿名对象，这个对象内部维护一个 64 位无符号计数器，初始值由你传入。系统调用返回一个文件描述符，之后你对这个 fd 的读写，本质上就是在操作这个计数器。

• 往 fd 里 write 一个 8 字节整数，内核把这个整数加到计数器上。
• 从 fd 里 read 一个 8 字节整数，内核把当前计数器的值返回给你，然后把计数器清零。
• 如果计数器是 0，read 会阻塞（非阻塞模式下返回 EAGAIN），直到有线程写入。

这个设计把“事件通知”这件事抽象成了文件 I/O。你不需要自己维护一个共享变量，也不需要引入互斥锁，因为计数器的读写是内核原子完成的。更重要的是，它天然能被 select、poll、epoll 监听，这意味着你可以把一个 eventfd 塞进网络事件循环里，用它来唤醒主循环处理其他线程投递过来的任务。

用生活里的例子来类比，eventfd 就是一个“信箱里的信号旗”。投递者把旗子立起来（write 加 1），收信人看见旗子后取走信件并把旗子放下（read 清零）。不管投递者多频繁地立旗子，收信人只需要来看一次信箱就能知道“有事发生了”。

1.2 为什么需要 eventfd：三个典型痛点

既然已经有了 pipe、信号量、条件变量这些同步工具，为什么还要专门设计一个 eventfd？我结合实际使用体验说三个核心原因。

第一个痛点是 pipe 的唤醒开销。传统做法里，IO 线程阻塞在 epoll_wait 上，另一个线程想唤醒它，就得往 pipe 里写一个字节。pipe 本身有两个文件描述符，写端和读端都要管理，而且 pipe 有内核缓冲区。为了一个“有没有活”的布尔信号，你却要维护一个完整的字节流通道，这显然是杀鸡用牛刀。更重要的是，pipe 的读端会把数据真正读走，如果你连续写了好几次，接收方必须把缓冲区里的数据全部读完才能让 pipe 恢复到不可读状态，这中间容易出现“唤醒信号堆积”的问题。eventfd 则不然，无论你 write 多少次，计数都累加在一个 uint64_t 上，接收方 read 一次就能拿到累计的通知次数，不会堆积。

第二个痛点是条件变量和信号量的跨进程限制。C++ 的 std::condition_variable 只能在同一个进程内使用，无法用于多进程场景。System V 信号量虽然跨进程，但接口老、语义重，而且不能和 poll 系列配合——你没法在 epoll_wait 里同时等一个信号量和等一个 socket 事件。eventfd 是文件描述符，通过 fork 天然可以共享给子进程，通过 epoll 又能和网络事件统一管理，这是它作为“事件源”的最大优势。

第三个痛点是信号处理函数的局限性。有人会用 signal 或者 sigaction 来实现异步通知，但信号处理函数必须是异步信号安全的，你在里面能做的事情非常有限，而且标准信号存在丢失的可能。eventfd 把通知内容变成一个可读的计数器，处理逻辑回到正常的执行流里，没有任何 async-signal-safe 的限制，也不存在“丢了这次信号”的问题——计数一直放在那里，你随时来读都能读到。

1.3 适用场景与判断标准

不是所有线程同步问题都该用 eventfd。我自己的判断标准很简单：

• 如果你需要的是“有数据可读/可写”或者“有任务到达”这种二值通知，而且接收方会阻塞在 epoll_wait 或 poll 上，那 eventfd 非常合适。
• 如果你只是在同一个进程内传递一个简单的布尔状态，而且对延迟极度敏感，std::atomic + std::condition_variable 可能比你用系统调用更合适。eventfd 每次唤醒都有一次内核调用，condvar 在无竞争时只是用户态操作，延迟能低一个数量级。
• 如果需要传输实际的数据内容，那别用 eventfd，老老实实用 pipe、socketpair 或者共享内存队列。eventfd 只负责“通知”，不负责“搬运数据”。

我碰到过有人只用 eventfd 传字符串，结果还得在外面包一层队列，多此一举。eventfd 的正确使用姿势是配合一个队列：生产者往队列里放任务，然后 write eventfd 通知消费者；消费者被唤醒后从队列里取任务处理。eventfd 在这套组合里只当“门铃”，不当“信箱”。

2. 核心 API 与关键参数解析

2.1 eventfd() 系统调用：三个关键点

eventfd() 的函数签名非常简洁，它只有两个参数：

c复制#include <sys/eventfd.h>

int eventfd(unsigned int initval, int flags);

第一个参数 initval 是计数器的初始值。绝大多数场景下你传 0 就行了，表示“初始没有事件”。你很少需要从一个非零值开始。

第二个参数 flags 在 Linux 2.6.27 之前只能传 0，之后引入了几个有用的位：

• EFD_CLOEXEC：在执行 exec 时自动关闭这个 fd。如果一个 fd 不需要在子进程里继续存在，加上它最稳妥，能避免 fd 泄漏到 exec 出来的程序里。
• EFD_NONBLOCK：让读写变成非阻塞。这个标志的效果和直接对这个 fd 调用 fcntl(fd, F_SETFL, O_NONBLOCK) 一样，但放在参数里更统一。多线程环境里，非阻塞 read 几乎总是必需的，后面我会解释原因。
• EFD_SEMAPHORE：提供一个“信号量语义”的读取模式。普通模式下 read 返回累计计数并清零；这个模式下 read 只返回 1，计数器减 1。如果你想把 eventfd 当计数信号量用，就加这个标志。

参数本身没什么难的，真正的细节在 read/write 的语义里。

2.2 read/write 语义：八字节的讲究

eventfd 的 read 和 write 有几个硬性规定，不遵守就直接报错：

• 传给 read 的缓冲区大小必须至少是 8 字节；少于 8 字节，read 返回 EINVAL。
• 传给 write 的缓冲区大小也必须正好是 8 字节；写入的值会被加到计数器上。
• 写入的值如果是 0xFFFFFFFFFFFFFFFF，会返回 EINVAL。

普通模式下，当计数器非零时，read 会一次性返回计数器的当前值，然后把计数器清零。这里有个容易被忽视的细节：如果计数器的值超过了 uint64_t 能表示的最大范围，read 返回的值是 0xFFFFFFFFFFFFFFFF，而计数器会被重置为 0xFFFFFFFFFFFFFFFE。这在理论上是边界情况，但语义上保证了 read 至少能拿到一个“爆表了”的信号。

EFD_SEMAPHORE 模式的行为完全不同。每次 read 只返回 1，计数器减 1。假如计数器现在是 5，普通模式读一次得到 5，计数清零；信号量模式读一次得到 1，计数变成 4，你还需要读四次才会读到 EAGAIN。这两种模式各有用处，后面实操部分我会展开。

还有一个所有新手都会踩的坑：write 可以多次累加。write(fd, &one, 8) 两次之后计数器是 2，这时候如果接收方在 epoll_wait 里被唤醒，它只 read 一次就能拿到 2。这既是 eventfd 高效的地方，也是容易搞错的地方——接收方必须意识到“自己被唤醒一次，可能对应着发送方多次通知”，并根据自己的业务语义决定是否要清空计数器。

2.3 阻塞、非阻塞与 epoll 集成

eventfd 的 fd 可以阻塞，也可以非阻塞。阻塞模式下，如果计数器是 0，read 会一直挂起直到有人写入；这看起来很方便，但实际项目里几乎不用，因为一旦你阻塞在 read 上，就没法同时监听其他 fd 的事件了。除非你的程序只有一个事件源，否则阻塞 read 等于把事件循环堵死。

非阻塞模式配合 epoll 才是标准姿势。把 eventfd 注册进 epoll 后，当计数器从 0 变成非 0 时，epoll 会返回该 fd 的可读事件。处理事件时执行一次 read，把计数清零，然后继续 epoll_wait。这里有两种触发方式需要注意：

• 水平触发（LT，默认）：只要计数器非 0，每次 epoll_wait 都会返回可读。你读完了它才不报。
• 边缘触发（ET）：只在计数器从 0 变成非 0 的那一次报告可读。如果你这次没 read，或者 read 没把计数清零，之后即使计数器一直非 0，也不会再触发一次可读事件，必须等下一次 write 才能再次触发。

用 ET 模式时，接收方必须在处理逻辑里保证把计数 read 干净，否则很可能丢失唤醒信号。我在最初从 LT 切换到 ET 时就吃过一次亏，后面单独说。

3. 实操过程：从线程到进程的三套完整实现

3.1 场景一：线程池任务唤醒（基础版）

先来一个最经典的用法：一个线程池里，工作线程阻塞等待任务，主线程投递任务后用 eventfd 唤醒一个空闲线程。

c复制#include <sys/eventfd.h>
#include <pthread.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <errno.h>

int g_efd;

void *worker(void *arg) {
    uint64_t buf;
    for (;;) {
        ssize_t n = read(g_efd, &buf, sizeof(buf));
        if (n == -1 && errno == EAGAIN) {
            continue; // 非阻塞模式下没有事件，回到循环继续等
        }
        if (n != sizeof(buf)) {
            perror("read");
            break;
        }
        printf("worker: wake up, count = %llu\n", (unsigned long long)buf);
        // 这里从任务队列里取任务处理...
        break; // 演示用，只处理一次就退出
    }
    return NULL;
}

int main(void) {
    g_efd = eventfd(0, EFD_NONBLOCK);
    if (g_efd < 0) {
        perror("eventfd");
        return 1;
    }

    pthread_t tid;
    pthread_create(&tid, NULL, worker, NULL);

    uint64_t one = 1;
    ssize_t n = write(g_efd, &one, sizeof(one));
    if (n != sizeof(one)) {
        perror("write");
    }

    pthread_join(tid, NULL);
    close(g_efd);
    return 0;
}

这个示例省略了任务队列的加锁细节，但 eventfd 的用法是完整的。注意两点：第一，eventfd 用非阻塞模式创建，这样 worker 在 read 返回 EAGAIN 时可以继续做别的事（或者直接回到 epoll_wait）。第二，主线程 write 之前不需要加锁，eventfd 内核会处理竞争的原子性。

如果你是在一个不断运行的线程池里，worker 应该把 read 放进 epoll_wait 的循环里，而不是单纯阻塞在 read 上。下面的场景三会展示完整写法。

3.2 场景二：进程间事件通知（fork 版）

eventfd 一个容易被忽略的能力是跨进程。fork() 之后，子进程会继承父进程的文件描述符表，父进程创建的 eventfd 在子进程里同样可用，而且它们指向同一个内核计数器。

c复制#include <sys/eventfd.h>
#include <sys/wait.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>

int main(void) {
    int efd = eventfd(0, EFD_NONBLOCK | EFD_CLOEXEC);
    if (efd < 0) {
        perror("eventfd");
        exit(1);
    }

    pid_t pid = fork();
    if (pid == 0) {
        // 子进程：等待父进程通知
        uint64_t buf;
        ssize_t n = read(efd, &buf, sizeof(buf));
        if (n == sizeof(buf)) {
            printf("child: got notification, value = %llu\n",
                   (unsigned long long)buf);
        }
        close(efd);
        _exit(0);
    }

    // 父进程：等一下再通知子进程
    sleep(1);
    uint64_t one = 1;
    write(efd, &one, sizeof(one));

    wait(NULL);
    close(efd);
    return 0;
}

这段代码里有一个重要的细节：fork 之后，父进程和子进程各自持有一个指向同一个内核对象的 fd，但这个对象只在该 fd 的所有副本都关闭之后才会被释放。如果你只需要子进程等父进程的通知，子进程读完后记得 close，父进程也要在 wait 之后 close。如果忘了 close，fd 就会泄漏，而且内核对象的生命周期会延长到最后一个持有者退出，这在长时间运行的服务进程里会累积成严重的资源问题。

进程间用 eventfd 比用信号的好处在于：你不需要注册信号处理器，也不担心信号丢失；而且你可以在子进程里把 eventfd 交给自己的 epoll 管理，和其他 fd 一起等待。这在多进程模型（比如 prefork 服务器）里非常实用——master 进程可以用一个 eventfd 优雅地通知所有 worker 进程退出。

3.3 场景三：与 epoll 配合实现异步唤醒（生产版）

在真实的服务器里，eventfd 最常出现在网络事件循环中。主线程阻塞在 epoll_wait 上，其他工作线程需要唤醒它来执行一个回调或者处理新投递的任务。下面是一个最小但完整的事件循环骨架：

c复制#include <sys/eventfd.h>
#include <sys/epoll.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <errno.h>
#include <string.h>

#define MAX_EVENTS 64

int main(void) {
    // 创建 eventfd，注意加上 EFD_CLOEXEC
    int efd = eventfd(0, EFD_NONBLOCK | EFD_CLOEXEC);
    if (efd < 0) {
        perror("eventfd");
        exit(1);
    }

    int ep = epoll_create1(0);
    struct epoll_event ev;
    ev.events = EPOLLIN; // 默认水平触发
    ev.data.fd = efd;
    if (epoll_ctl(ep, EPOLL_CTL_ADD, efd, &ev) < 0) {
        perror("epoll_ctl");
        exit(1);
    }

    struct epoll_event events[MAX_EVENTS];

    while (1) {
        int n = epoll_wait(ep, events, MAX_EVENTS, -1);
        for (int i = 0; i < n; i++) {
            if (events[i].data.fd == efd) {
                uint64_t cnt;
                ssize_t r = read(efd, &cnt, sizeof(cnt));
                if (r == sizeof(cnt)) {
                    printf("eventfd wake, accumulated %llu\n",
                           (unsigned long long)cnt);
                }
            }
            // 其他 fd 事件处理...
        }
    }

    close(ep);
    close(efd);
    return 0;
}

这个骨架看起来简单，但它是很多网络库的核心模式。需要注意：如果主循环用 epoll_wait(ep, events, MAX_EVENTS, -1) 的 -1 表示无限阻塞，那 eventfd 就是唯一的“闹钟”。一旦有其他线程 write 了 eventfd，主循环立刻返回，然后你可以在同一轮循环里继续处理 socket 事件。这正是很多高性能服务器能“用很少的线程支撑大量连接”的关键。

如果要用边缘触发（EPOLLET），你必须非常小心。ET 模式下，eventfd 只在计数从 0 变为非 0 时报告可读；如果你在事件处理里没有把计数器 read 到 0，下次 write 时计数器可能仍然非 0，这样内核不会产生新的边沿，唤醒信号就丢了。解决方法是：一旦确认可读，就循环 read 直到返回 EAGAIN（多线程同时 write 时尤其需要这样做），确保计数器清零。

3.4 性能观察与使用建议

我不是性能测试专家，但在网络框架里做过几次粗略对照，结论很明确：eventfd 比 pipe 轻得多。

这里说的“典型唤醒开销”指的是从 write 到对方 read 返回的大致耗时。eventfd 因为只维护一个计数器，内核路径比 pipe 短，在同样的硬件上通常会快一些。但要注意，如果你的代码里事件处理本身很重，这点性能差异完全被业务逻辑掩盖了，没必要为了省零点几微秒把代码搞复杂。

我对使用者的建议是：优先把 eventfd 当“唤醒信号”用，不要把它当成数据传输通道。通知之后具体做什么，应该由任务队列或共享内存里的状态决定。这样 eventfd 的语义最清晰，也不容易在并发下出错。

4. 常见问题与排查技巧实录

4.1 read 返回 EAGAIN 的三种场景

非阻塞模式下 read 返回 -1 且 errno 为 EAGAIN，代表“当前没有事件”。很多人一遇到 EAGAIN 就慌了，其实它可能有三种完全不同的来源。

第一种是计数器本来就是 0，这是正常状态。你 write 一次再 read，就不会有 EAGAIN。

第二种是你在 EFD_SEMAPHORE 模式下读完了所有计数。比如计数是 3，你读了三次，第四次 read 就会 EAGAIN。这符合信号量语义，不是错误。

第三种是你忘了 EFD_NONBLOCK 标志，但又用 fcntl 设置了其他标志，导致 fd 实际上处于非阻塞状态。这种隐蔽问题排查时最费时间，建议创建 eventfd 时统一把 EFD_NONBLOCK 写在 flags 里。

另外，read 的缓冲区如果小于 8 字节，返回的是 EINVAL 而不是 EAGAIN。这个错误码经常被人忽略，一旦出现，基本就是结构体定义的问题。

4.2 EFD_SEMAPHORE 的“一次一个”陷阱

EFD_SEMAPHORE 是个大坑，因为它和普通模式的行为差异太反直觉。普通模式 read 一次把所有计数拿走，信号量模式 read 一次只拿走 1。

我在项目里见过这样的 bug：生产者往 eventfd 里 write 了 10 次，消费者期望 read 一次后得到 10，然后清空，结果因为创建时加上了 EFD_SEMAPHORE，read 只返回 1。业务逻辑立刻混乱，因为 epoll 仍然报告 fd 可读，消费者却以为是异常状态。

如果你的目标只是“唤醒一次并处理所有待办事项”，就不要用 EFD_SEMAPHORE。普通模式的“一次性取走计数”才是聚合通知的正确语义。EFD_SEMAPHORE 适合你想精确控制“每次事件处理量”的场景，比如限制一次处理一个任务。

4.3 计数器溢出与语义边界

eventfd 的计数器是 64 位无符号整数，理论上写满 2^64 次才会溢出。但有一个边界行为值得知道：当计数器达到 0xfffffffffffffffe 时，写入会阻塞（或返回 EAGAIN），而 read 返回的计数值是 0xffffffffffffffff，之后计数器被重置为 0xfffffffffffffffe。

这个行为在实际业务里几乎不可能触发，但我在做压力测试时碰到过一次。如果你通过 eventfd 做高频计数，建议在业务层加一个阈值判断，别让计数器无限制增长。正常情况下，每次通知之后都 read 一次，计数器就会归零，不会积累。

4.4 fork 之后的 fd 继承问题

fork 后子进程继承 eventfd，看起来方便，但隐藏着资源管理的问题。父进程如果不小心把 eventfd 给多个子进程共享，你得想清楚“谁负责读”。如果所有子进程都阻塞在同一个 eventfd 上，那么一次 write 只会唤醒其中一个（内核会把事件交给一个等待者），其余子进程继续睡眠。这既可能是你要的（负载均衡），也可能是你不想看到的（漏通知）。

另一个容易被忽略的点：如果子进程只是 fork 出来准备 exec，exec 之后它会执行新程序。如果创建 eventfd 时没有加 EFD_CLOEXEC，这个 fd 会跟着进入新程序，成为一次 fd 泄漏的来源。很多程序崩溃后很难排查的“fd 怎么会变多”，往往就是这类继承导致的。所以我的习惯是：eventfd 一律 EFD_NONBLOCK | EFD_CLOEXEC，除非业务明确需要子进程继承它。

4.5 用 fdinfo 观测运行状态

调试 eventfd 问题最快的方法，不是加日志，而是直接看内核暴露的 fd 信息。Linux 在 /proc/<pid>/fdinfo/<fd> 里会显示 eventfd 的当前计数：

text复制pos:    0
flags:  02
mnt_id: 27
cnt:    3

最后一行 cnt 就是 eventfd 计数器当前的值。如果程序行为诡异，比如 epoll 一直报告可读，但业务上觉得没有新任务，你就可以 cat /proc/<pid>/fdinfo/<fd> 看一眼——如果 cnt 一直很大，说明有线程在疯狂 write 而没有人 read；如果 cnt 是 0 但 epoll 仍然可读，那就要检查是不是用了 ET 模式没读干净。

这个命令我在排查生产事故时用过很多次，效果立竿见影。比你在代码里到处加日志要快得多。

最后说一点个人体会。eventfd 是我在 Linux 下做异步编程时使用频率最高的同步原语之一，但它不是万能的。它解决的是“如何高效、安全地通知”这个单一问题，至于通知之后的数据怎么组织、任务怎么分配，那是队列和业务逻辑的事。把 eventfd 定位成“门铃”，你会发现整个代码结构清晰很多。希望这篇内容能帮你少踩一些坑，尤其是 EFD_SEMAPHORE 和 ET 模式的这两个，我当初都实打实地付出过调试时间。