深入浅出讲解 epoll 核心知识点（附参数 / 返回值全解析）

各位同学，我们今天的核心是搞懂epoll 为什么性能远超 select/poll，以及它的三个核心 API（epoll_create/epoll_ctl/epoll_wait）的用法 —— 尤其是每个参数的作用、返回值的含义，这些是实际开发中必须吃透的重点。

先回顾一个核心结论：epoll 之所以在高并发（比如监听 10000 个 fd）下性能几乎不下降，核心是它解决了 select/poll 的两个致命问题：

1. select/poll 每次调用都要把所有监听的 fd 从用户态拷贝到内核态，epoll 只需拷贝一次（通过 epoll_ctl）；
2. select/poll 返回后需要遍历所有 fd 判断是否就绪，epoll 直接返回就绪的 fd 列表，无需无效遍历。

而这两个优势，都和 epoll 的三个核心 API 的设计紧密相关。接下来我们逐个拆解。

一、epoll_create ()：创建 epoll 实例（内核事件管理器）

1. 函数原型

#include <sys/epoll.h>
int epoll_create(int size);

2. 核心作用

向 Linux 内核申请创建一个epoll 实例（可以理解为 “内核级的事件管理器”），内核会为这个实例初始化两个核心数据结构：

• 红黑树：存储所有需要监听的 fd 和对应的事件（支持高效增 / 删 / 改）；
• 就绪双向链表：存储已经就绪的 fd 事件（epoll_wait 直接从这里取数据）。函数返回一个唯一的文件描述符（epfd），后续所有 epoll 操作都通过这个 fd 关联到该实例。

3. 参数详解

参数名	类型	核心作用	注意事项
size	int	历史兼容参数，现代 Linux 已忽略	① 早期（Linux 2.6.8 前）：表示 “期望监听的 fd 数量”，内核据此初始化红黑树；② 现代 Linux：仅要求传入大于 0 的整数（比如 1、100、1024 都可以），传 0 会报错；③ 示例：epoll_create(1) 是最简洁的写法。

4. 返回值详解

返回值	含义	错误处理
非负整数	成功：返回 epoll 实例的文件描述符（epfd），比如 3、4、5（0/1/2 是标准输入 / 输出 / 错误）	-
-1	失败：内核创建 epoll 实例失败	① 用perror("epoll_create")打印具体错误；② 常见错误原因：→ ENFILE：系统打开的文件描述符总数达到上限；→ ENOMEM：内核内存不足；→ EINVAL：size 参数≤0。

5. 示例代码（极简）

int epfd = epoll_create(1);
if (epfd == -1) {
    perror("epoll_create failed"); // 打印错误原因，比如"epoll_create failed: Invalid argument"（size传0时）
    exit(1);
}
printf("epoll实例创建成功，epfd=%d\n", epfd); // 输出类似epfd=3

二、epoll_ctl ()：管理 epoll 实例的监听列表（红黑树操作）

1. 函数原型

#include <sys/epoll.h>
int epoll_ctl(int epfd, int op, int fd, struct epoll_event *event);

2. 核心作用

epoll 的 “控制接口”，用来操作 epoll 实例中的红黑树：

• 新增监听的 fd（EPOLL_CTL_ADD）；
• 删除不再监听的 fd（EPOLL_CTL_DEL）；
• 修改已有 fd 的监听事件（EPOLL_CTL_MOD）。这是 epoll “只拷贝一次 fd” 的关键 —— 只需通过 epoll_ctl 把 fd 注册到内核，后续无需重复拷贝。

3. 参数详解（逐个拆解，结合场景）

参数名	类型	核心作用	场景 / 注意事项
epfd	int	指向 epoll 实例的文件描述符（epoll_create 的返回值）	必须是有效的 epoll 实例 fd，传错会返回 - 1，错误码EBADF。
op	int	操作类型（红黑树的增 / 删 / 改）	可选值：① EPOLL_CTL_ADD：添加 fd 到红黑树（监听该 fd 的事件）；② EPOLL_CTL_DEL：从红黑树删除 fd（停止监听）；③ EPOLL_CTL_MOD：修改红黑树中 fd 的监听事件（比如从 EPOLLIN 改成 EPOLLOUT）。
fd	int	要操作的目标文件描述符	可以是：→ 监听套接字（listenfd）：监听新连接；→ 连接套接字（connfd）：监听客户端消息；→ 普通文件 / 管道 fd（epoll 也支持非 socket fd）；注意：fd 必须是 “打开状态”，传关闭的 fd 会报错（EBADF）。
event	struct epoll_event*	要监听的事件（ADD/MOD 时必填，DEL 时忽略）	① 类型是结构体指针，需先初始化结构体再传地址；② DEL 操作时可传 NULL（内核只需要 fd，不需要事件信息）；③ 核心是struct epoll_event的结构，下面单独讲。

关键补充：struct epoll_event 结构体解析

这是描述 “监听事件” 的核心结构体，定义如下：

struct epoll_event { 
    uint32_t     events;  // 要监听的事件类型（位掩码）
    epoll_data_t data;    // 用户自定义数据（联合体）
};

// 联合体：占用同一块内存，只需用其中一个字段即可
typedef union epoll_data { 
    void *ptr;   // 指向自定义数据（比如客户端结构体）
    int fd;      // 最常用：关联要监听的fd（方便epoll_wait识别）
    uint32_t u32;// 32位无符号整数
    uint64_t u64;// 64位无符号整数
} epoll_data_t;

（1）events 成员：监听事件类型（常用值）

取值	含义	适用场景
EPOLLIN	所关联的 fd “可读”	① listenfd 可读：有新客户端连接；② connfd 可读：客户端发来了消息；③ 普通文件 fd 可读：文件有数据可读取。
EPOLLOUT	所关联的 fd “可写”	服务器要给客户端发消息（避免写阻塞）。
EPOLLRDHUP	流式套接字（TCP）的对端关闭连接 / 关闭写端	检测客户端主动断开（比 recv 返回 0 更及时）。
EPOLLET	设为 “边缘触发（ET）” 模式（默认是水平触发 LT）	高性能场景用 ET（减少事件触发次数），后续会专门讲 LT/ET 区别。
EPOLLONESHOT	事件触发一次后，自动取消监听	避免同一个 fd 的事件被多个线程重复处理。

（2）data 成员：用户自定义数据

最常用的是data.fd—— 把要监听的 fd 绑定到事件中，这样epoll_wait返回时，能直接从events[i].data.fd拿到就绪的 fd，无需额外判断。示例：

struct epoll_event ev;
ev.events = EPOLLIN | EPOLLRDHUP; // 监听“可读”+“客户端断开”事件
ev.data.fd = connfd; // 绑定客户端fd

4. 返回值详解

返回值	含义	错误处理
0	成功：红黑树操作完成（ADD/DEL/MOD 成功）	-
-1	失败：操作失败	常见错误原因：① EBADF：epfd 或 fd 不是有效的打开文件描述符；② EINVAL：epfd 不是 epoll 实例 fd，或 op 参数无效；③ ENOMEM：内核内存不足；④ EEXIST：op=EPOLL_CTL_ADD，但 fd 已在红黑树中；⑤ ENOENT：op=EPOLL_CTL_DEL/MOD，但 fd 不在红黑树中。

5. 示例代码（核心操作）

// 1. 创建epoll实例
int epfd = epoll_create(1);
// 2. 准备要监听的客户端fd（模拟accept返回的connfd）
int connfd = accept(listenfd, NULL, NULL);
// 3. 初始化事件结构体
struct epoll_event ev;
ev.events = EPOLLIN | EPOLLRDHUP; // 监听可读+客户端断开
ev.data.fd = connfd;
// 4. 把connfd添加到epoll实例（ADD操作）
int ret = epoll_ctl(epfd, EPOLL_CTL_ADD, connfd, &ev);
if (ret == -1) {
    perror("epoll_ctl ADD failed");
    close(connfd);
    return -1;
}
// 5. 后续：客户端断开，删除connfd（DEL操作）
ret = epoll_ctl(epfd, EPOLL_CTL_DEL, connfd, NULL); // DEL操作event传NULL
if (ret == -1) {
    perror("epoll_ctl DEL failed");
}
close(connfd);

三、epoll_wait ()：等待事件就绪（从就绪链表取数据）

1. 函数原型

#include <sys/epoll.h>
int epoll_wait(int epfd, struct epoll_event *events, int maxevents, int timeout);

2. 核心作用

等待内核分发 I/O 事件：

• 如果没有事件就绪，调用线程会被挂起（阻塞）；
• 当有事件就绪时，内核会把 “就绪事件” 从 “就绪链表” 拷贝到用户态的events数组中；
• 返回就绪的事件数量，线程被唤醒。这是 epoll 比 select/poll 快的核心 —— 只返回就绪的 fd，无需遍历所有监听的 fd。

3. 参数详解

参数名	类型	核心作用	场景 / 注意事项
epfd	int	指向 epoll 实例的文件描述符	必须是 epoll_create 返回的有效 fd。
events	struct epoll_event*	输出型数组（用户态内存）	① 用来接收内核返回的 “就绪事件”；② 数组大小由开发者定义（比如 128、1024）；③ 数组中的每个元素对应一个就绪的 fd 事件。
maxevents	int	epoll_wait 最多能返回的事件数	① 必须≤events数组的长度（否则会越界）；② 通常直接设为数组长度（比如数组是 events [128]，maxevents=128）；③ 传 0 会报错（EINVAL）。
timeout	int	超时时间（单位：毫秒 ms）	可选值：① -1：永久阻塞（直到有事件就绪，最常用）；② 0：立即返回（不管有没有事件，非阻塞模式）；③ >0：等待指定毫秒（比如 1000=1 秒），超时返回 0。

4. 返回值详解

返回值	含义	处理逻辑
>0	成功：返回就绪的事件数量（n）	遍历events[0] ~ events[n-1]，处理每个就绪事件（比如读客户端消息）；注意：n≤maxevents，实际就绪数可能远小于监听的 fd 总数。
0	超时：timeout>0 时，等待指定时间后仍无事件就绪	可做心跳检测、资源清理等操作，然后重新调用 epoll_wait。
-1	失败：调用出错	常见错误原因：① EBADF：epfd 不是有效 fd；② EINVAL：epfd 不是 epoll 实例 fd，或 maxevents≤0；③ EINTR：调用被信号中断（比如 Ctrl+C），可重新调用 epoll_wait。

三、核心概念：水平触发（LT）vs 边缘触发（ET）

这是 epoll 最容易懵的点，用「水龙头」的例子讲，一看就懂：

模式	生活化例子	编程特点
水平触发（LT，默认）	水龙头没关紧，一直滴水 → 你每次看都能看到水（事件一直触发）	只要 FD 还有数据可读，epoll_wait 就一直返回这个事件；✅ 新手友好，不用一次性读完数据；❌ 略低效（但日常够用）
边缘触发（ET）	水龙头只开一次，流一次水 → 你只有在「水开始流」的瞬间能看到（事件只触发一次）	仅当 FD 的「数据状态变化」时触发（比如从无数据→有数据）；✅ 性能更高（减少重复触发）；❌ 必须用非阻塞 FD + 一次性读完所有数据（否则数据会残留）

新手建议：先掌握 LT 模式（默认），写聊天室、常规服务器完全够用；ET 模式等基础扎实了再学。