Linux epoll 事件模型终极指南：深入解析 epoll_event 与事件类型

<摘要>
epoll_event 结构体是 Linux 高性能 I/O 多路复用机制 epoll 的核心组成部分，其 events 字段通过一系列位掩码（如 EPOLLIN, EPOLLOUT, EPOLLET 等）精确描述了用户感兴趣或内核返回的文件描述符状态。这些事件类型是构建现代高性能网络服务器（如 Nginx, Redis）和应用程序的基石。本文将从 epoll 的演进背景和设计哲学出发，深入解析 epoll_ctl() 中用于设置兴趣集的标志位和 epoll_wait() 返回的活动事件标志位。我们将逐一剖析每一个事件类型（包括 EPOLLIN, EPOLLOUT, EPOLLERR, EPOLLHUP, EPOLLRDHUP, EPOLLPRI, EPOLLET, EPOLLONESHOT, EPOLLWAKEUP, EPOLLEXCLUSIVE）的精确含义、触发条件、底层内核机制、典型应用场景及编程陷阱。此外，本文还将结合大量代码示例、状态转换图、性能对比表格以及实战案例，全面阐述如何在边缘触发（ET）和水平触发（LT）模式下正确高效地处理这些事件，最终为开发者提供一份关于 epoll 事件模型的终极指南。

---

<解析>

Linux epoll 事件模型终极指南：深入解析 epoll_event 与事件类型

在当今高并发网络服务的世界里，C10K（万级并发连接）乃至 C10M（百万级并发连接）问题已成为服务器程序必须面对的挑战。传统的 select 和 poll 模型因其性能瓶颈无法满足需求，而 Linux 的 epoll 接口正是为解决这一问题而生的利器。epoll 的核心在于其高效的事件通知机制，而理解这一机制的关键，就在于深刻理解 epoll_event 结构体及其丰富的事件类型标志位。

1. 背景与核心概念

1.1 I/O 多路复用的演进：从 select/poll 到 epoll

在深入 epoll_event 之前，我们必须理解为什么需要它。

• select & poll： 这两个早期系统调用的工作模式是"无差别轮询"。每次调用时，内核需要完整地扫描 用户传入的所有文件描述符（fd）集合，以判断哪些 fd 就绪。随后，将整个就绪集合完整地拷贝回用户空间。其算法时间复杂度为 O(n)，随着监控的 fd 数量（n）增长，性能会线性下降，这在处理成千上万个连接时是不可接受的。
• epoll： 它的设计哲学是"基于回调的就绪通知"。其核心是创建一个内核事件表（epoll_create），用户通过 epoll_ctl 向表中增删改 需要监控的 fd 及其感兴趣的事件。一旦某个 fd 就绪，内核会通过一个回调机制将其主动插入 到一个就绪链表中。用户调用 epoll_wait 时，只是从这个就绪链表中取出已就绪的 fd，而无需扫描全部集合。这使得其效率几乎与活跃的 fd 数量成正比，而非监控的 fd 总数，算法复杂度为 O(1)。

epoll 的巨大优势源于这种设计，而 epoll_event 就是用户与内核之间沟通事件信息的"语言"。

1.2 epoll_event 结构体：事件信息的载体

epoll_event 结构体定义在 <sys/epoll.h> 中，它是 epoll 操作的基本单位。

typedef union epoll_data {
    void    *ptr;
    int      fd;
    uint32_t u32;
    uint64_t u64;
} epoll_data_t;

struct epoll_event {
    uint32_t     events;    /* Epoll events (bit mask) */
    epoll_data_t data;      /* User data variable */
};

• events (uint32_t)： 这是一个位掩码（bit mask） 字段，是本文的核心。它由一系列以 EPOLL 开头的常量通过"位或"操作（|）组合而成。它用于指定：
  • 在 epoll_ctl(EPOLL_CTL_ADD/EPOLL_CTL_MOD) 时 ：用户感兴趣的事件类型（我们想要监控什么）。
  • 在 epoll_wait 返回时 ：内核报告的已就绪的事件类型（发生了什么）。
• data (epoll_data_t union)： 这是一个联合体，用于存储用户自定义数据。当 epoll_wait 返回一个事件时，data 会原样带回用户之前设置的值。这是 epoll 比 select/poll 更易用的关键之一，它允许你直接将事件与你的业务数据（如连接结构体指针、fd）关联起来，而无需维护额外的映射表。
  • fd：最常用的字段，通常存放对应的文件描述符。
  • ptr：更强大的字段，可以存放任意用户数据的指针（如指向一个连接会话对象的指针）。
  • u32, u64：较少使用，用于存放整型数据。

1.3 核心事件类型概览

在开始详细讲解每个事件前，我们先通过一个表格对最重要的事件类型有一个全局的认识：

事件类型	用途	说明
EPOLLIN	输入/读取	关联的 fd 有数据可读（普通数据或带外数据？见 EPOLLPRI）
EPOLLOUT	输出/写入	关联的 fd 可写入数据（TCP 窗口有空间或非阻塞连接完成）
EPOLLERR	错误	总是监控，表示 fd 发生错误
EPOLLHUP	挂起	总是监控，表示对端关闭连接或本端被挂起
EPOLLRDHUP	对端半关闭	（需手动设置）表示对端关闭了写端（发送了 FIN）
EPOLLPRI	紧急数据	有带外（OOB）数据可读（如 TCP 的 URG 数据）
EPOLLET	边缘触发	设置模式，将 fd 的工作模式设置为边缘触发（默认是水平触发）
EPOLLONESHOT	一次性	设置模式，事件最多被通知一次，之后需重新武装（re-arm）
EPOLLWAKEUP	唤醒锁定	防止系统休眠，确保事件处理时系统不进入低功耗状态
EPOLLEXCLUSIVE	独占唤醒	避免惊群效应，多个 epoll 实例监听同一 fd 时，只唤醒一个

关键区别：

• 状态事件 vs. 模式事件 ：EPOLLIN, EPOLLOUT 等描述的是 fd 的状态 。而 EPOLLET, EPOLLONESHOT 等描述的是 epoll 监控该 fd 的行为模式。
• 总是监控的事件 ：EPOLLERR 和 EPOLLHUP 是总是被监控 的，即无论你是否在 events 中设置它们，当错误或挂起发生时，它们都会由内核返回。这是一个非常重要的特性。

2. 深度剖析：每个事件的含义与机制

现在，让我们深入每一个事件类型，揭开它们的神秘面纱。

2.1 EPOLLIN：可读事件

含义：表示关联的文件描述符存在可读取的数据。

触发条件：

• 对于套接字（socket） ：
  • TCP ：接收缓冲区中的数据大小达到了低水位标记（SO_RCVLOWAT） 。默认情况下，低水位标记是 1 字节，这意味着只要缓冲区中有任何数据 ，就会触发 EPOLLIN。
  • UDP/RAW：接收缓冲区中有数据报。
  • 监听套接字（listening socket） ：有新的连接完成（accept() 队列非空）。
• 对于管道/FIFO：管道读端对应的写端有数据写入。
• 对于终端/TTY：有输入数据。
• 对于其他文件：通常总是可读的（如读取一个普通文件）。

底层机制 ：当数据到达网络栈时，内核负责将其放入对应 socket 的接收缓冲区。一旦缓冲区中的数据量从低于 低水位标记变为不低于 低水位标记，内核就会触发与该 socket 关联的 epoll 实例上的 EPOLLIN 事件。

编程注意事项：

• 在 epoll_wait 返回 EPOLLIN 后，必须调用 read()/recv() 来读取数据。
• 在 LT 模式 下，只要缓冲区中还有数据，下一次 epoll_wait 就会再次报告 EPOLLIN。
• 在 ET 模式 下，只有在缓冲区从空变为非空（即有新的数据到达 ）时，才会报告一次 EPOLLIN。这意味着你必须一次性读完所有数据（循环读取直到 EAGAIN/EWOULDBLOCK），否则可能会丢失事件，导致数据永远"沉睡"在缓冲区中。

2.2 EPOLLOUT：可写事件

含义：表示关联的文件描述符可以写入数据。

触发条件：

• 对于套接字（socket） ：
  • TCP ：发送缓冲区的可用空间大小达到了低水位标记（SO_SNDLOWAT）。默认低水位标记通常是几个 kB 的空间（具体实现相关），但更常见的触发条件是：发送缓冲区从不可写变为可写 。这通常发生在：
    1. 建立非阻塞 TCP 连接时：调用 connect() 会返回 EINPROGRESS，此时 epoll 会监控该 socket。当连接成功建立（或失败）时，EPOLLOUT 会被触发，标志着连接完成，可以开始发送数据。
    2. 大量发送数据后：当发送缓冲区被填满，write() 调用返回 EAGAIN。之后，当对端 ACK 了部分数据，本端发送缓冲区空出空间时，EPOLLOUT 会再次被触发，通知你可以继续写入。
  • UDP ：UDP 没有真正的"发送缓冲区满"的概念（因为它是无连接的），所以 EPOLLOUT 通常总是被触发，除非遇到路由错误等。
• 对于管道/FIFO：管道写端对应的读端有空间（未满）。
• 对于其他文件：通常总是可写的。

底层机制 ：当对端 ACK 数据或应用程序读取数据（对于管道），导致本端发送/写入缓冲区的空闲空间变大，从不足 低水位标记变为足够 时，内核触发 EPOLLOUT 事件。

编程注意事项：

• 不要一开始就监听 EPOLLOUT ：如果一个 socket 可写，epoll 会不停地通知你，导致 CPU 100%。正确的做法是：默认不监听 EPOLLOUT 。当你调用 write()/send() 并得到 EAGAIN 错误时，这才表明发送缓冲区已满 。此时，你再通过 epoll_ctl(EPOLL_CTL_MOD) 添加 EPOLLOUT 监听。一旦 EPOLLOUT 被触发，你写完数据后，应立即再次修改事件，移除 EPOLLOUT 监听，否则又会陷入忙等。
• 连接完成 ：对于非阻塞 connect，EPOLLOUT 的触发标志着连接成功建立。但是，你必须使用 getsockopt(fd, SOL_SOCKET, SO_ERROR, ...) 来检查是否有错误 。因为连接也可能失败，但 epoll 仍然会报告 EPOLLOUT（同时也会报告 EPOLLERR）。

2.3 EPOLLERR：错误事件

含义：表示关联的文件描述符发生了错误。

触发条件：

• TCP 连接错误（如 RST 包、超时）。
• 尝试在已关闭的 fd 上进行操作。
• 其他协议相关的错误。

关键特性：

• 总是监控 ：EPOLLERR 是一个特殊事件。你无法 在 epoll_ctl 的 events 中设置它（即你不能说"我关心错误事件"），因为内核总是会监控它 。当错误发生时，无论你的 events 设置是什么，epoll_wait 都会返回这个事件。
• 优先处理 ：当 EPOLLERR 发生时，通常意味着该 fd 已经不可用。你应该立即关闭这个 fd，并清理相关资源。此时，再检查 EPOLLIN 或 EPOLLOUT 已经没有意义。

如何获取错误码 ：当 EPOLLERR 发生时，你需要调用 getsockopt(fd, SOL_SOCKET, SO_ERROR, &error, &len) 来获取具体的错误代码（如 ECONNRESET, ETIMEDOUT）。

2.4 EPOLLHUP：挂起事件

含义：表示关联的文件描述符上发生了挂起（Hang Up）。

触发条件：

• 对于套接字 ：最常见的场景是对端关闭了连接 （发送了 FIN 包）。在 LT 模式下，当你读取完对端发送的所有数据后（read() 返回 0），下一次 epoll_wait 通常会同时返回 EPOLLHUP 和 EPOLLIN（读取返回 0）。在 ET 模式下，EPOLLHUP 可能随 EPOLLIN 一起返回，表示数据读完且连接已关闭。
• 对于管道 ：当管道的所有写端都被关闭后，读端会收到 EPOLLHUP。
• 其他一些设备特定的挂起条件。

关键特性：

• 总是监控 ：和 EPOLLERR 一样，EPOLLHUP 也是总是被监控的，你无法显式设置它，但它会在条件满足时由内核返回。
• 与 EPOLLRDHUP 的关系 ：EPOLLHUP 通常表示连接完全 关闭。而 EPOLLRDHUP（见下文）更精确地表示"对端关闭了写端"（即半关闭状态）。在很多实现中，对端调用 shutdown(SHUT_WR) 或 close() 会先触发 EPOLLRDHUP，当你读完剩余数据后，再触发 EPOLLHUP。

处理 ：收到 EPOLLHUP 后，你应该关闭 fd 并清理资源。

2.5 EPOLLRDHUP：对端关闭连接事件 (since Linux 2.6.17)

含义：Stream socket 的对端关闭了连接，或者关闭了写半端。

触发条件：

• 对端调用了 shutdown(SHUT_WR)（半关闭）或 close()（全关闭），发送了 FIN 包。

关键特性：

• 非默认监控 ：与 EPOLLERR/EPOLLHUP 不同，EPOLLRDHUP 需要 你显式地在 epoll_ctl 的 events 中设置，内核才会监控并报告它。
• 更精细的控制 ：它是 EPOLLHUP 的一个子集。它专门用于检测 TCP 的对端关闭行为，让你能在对端刚发起关闭时就得知这一事件，而不是等到所有数据都读完、连接完全断开（EPOLLHUP）时才知道。这对于需要及时释放资源的应用程序非常有用。

编程模式：

// 添加监控时，显式设置 EPOLLRDHUP
struct epoll_event ev;
ev.events = EPOLLIN | EPOLLRDHUP; // 监控可读和对端关闭
ev.data.fd = sockfd;
epoll_ctl(epfd, EPOLL_CTL_ADD, sockfd, &ev);

// 在 epoll_wait 循环中
for (...) {
    if (events[i].events & EPOLLRDHUP) {
        // 对端已经关闭了连接（或写端）
        // 可以开始清理资源，可能还需要读取缓冲区中剩余的数据
        printf("Peer closed the connection.\n");
        close(events[i].data.fd);
    } else if (events[i].events & EPOLLIN) {
        // ... 处理数据 ...
    }
}

2.6 EPOLLPRI：紧急/带外数据事件

含义：表示有紧急数据（Out-of-Band data, OOB）可读。

触发条件：

• TCP socket 收到了带有 URG 标志的数据包，并且该紧急数据尚未被读取。

底层机制 ：TCP 提供了"紧急模式"，允许发送端发送一个字节的"带外"数据。这个数据会被接收端网络栈优先处理。当这样的数据到达时，内核会触发 EPOLLPRI 事件，通知应用程序。

编程注意事项：

• 你需要使用 recv(fd, buf, sizeof(buf), MSG_OOB) 来读取紧急数据。
• 紧急数据在实际网络中很少使用，通常用于实现类似 telnet 的中断信号（Ctrl+C）。现代应用程序更倾向于使用单独的连接或带内信令来实现类似功能。
• 和 EPOLLIN 一样，你需要显式设置 EPOLLPRI 来监控它。

2.7 EPOLLET：边缘触发模式 (Epoll's Edge-Triggered Mode)

含义 ：这不是一个状态事件，而是一个模式设置标志 。它要求 epoll 对于当前的文件描述符使用边缘触发（Edge-Triggered） 模式进行监控。

默认模式 ：如果不设置 EPOLLET，epoll 使用水平触发（Level-Triggered, LT） 模式。

两种模式的区别 （这是 epoll 的核心难点和重点）：

特性	水平触发 (LT)	边缘触发 (ET)
行为比喻	状态通知 ：只要条件为真，就持续通知。 好比一个高电平信号。	变化通知 ：只在状态变化时 通知一次。 好比一个上升沿或下降沿脉冲。
EPOLLIN	只要 socket 接收缓冲区不为空 ，每次 epoll_wait 都会返回该事件。	仅当 socket 接收缓冲区由空变为非空（即有新数据到达）时，返回一次。
EPOLLOUT	只要 socket 发送缓冲区不满 （有空间可写），每次 epoll_wait 都会返回该事件。	仅当 socket 发送缓冲区由满变为不满（即有新空间可用）时，返回一次。
编程复杂度	低。你可以选择一次读取部分数据，下次调用 epoll_wait 会再次通知你。	高。你必须 一次性读完所有数据（循环 read 直到返回 EAGAIN），否则剩余的数据将不会再次触发事件，导致连接"饿死"。
性能	可能较低。因为内核需要多次通知，且用户可能多次调用系统调用。	理论上更高。减少了 epoll_wait 返回的次数和用户态-内核态的切换，尤其适合高并发、小数据量突发场景。
适用场景	几乎所有场景，更安全，更简单。	需要极致性能的场景，且开发者能正确处理好读写循环和 EAGAIN。

ET 模式下的正确读写方式：

// ET 模式下的读操作
int n;
while ((n = read(fd, buf, sizeof(buf))) > 0) {
    // 处理读到的数据
    process_data(buf, n);
}
if (n == -1 && errno != EAGAIN && errno != EWOULDBLOCK) {
    // 发生真正的错误，处理错误
    handle_error();
}
// 如果 n == -1 且 errno == EAGAIN，表示本次触发的数据已经全部读完

// ET 模式下的写操作（通常与 EPOLLOUT 的开关监听配合）
// 假设要发送一大块数据
ssize_t nwritten;
size_t total_sent = 0;
const char *data_to_send = ...;
size_t data_len = ...;

while (total_sent < data_len) {
    nwritten = write(fd, data_to_send + total_sent, data_len - total_sent);
    if (nwritten == -1) {
        if (errno == EAGAIN || errno == EWOULDBLOCK) {
            // 发送缓冲区已满，停止循环，设置 EPOLLOUT 监听
            struct epoll_event ev;
            ev.events = EPOLLIN | EPOLLET | EPOLLOUT; // 添加 EPOLLOUT
            ev.data.fd = fd;
            epoll_ctl(epfd, EPOLL_CTL_MOD, fd, &ev);
            break;
        } else {
            // 真正的错误
            handle_error();
            break;
        }
    }
    total_sent += nwritten;
}

if (total_sent == data_len) {
    // 数据全部发送完成，移除 EPOLLOUT 监听以避免忙等
    struct epoll_event ev;
    ev.events = EPOLLIN | EPOLLET; // 移除 EPOLLOUT
    ev.data.fd = fd;
    epoll_ctl(epfd, EPOLL_CTL_MOD, fd, &ev);
}

选择建议：

• 新手或一般应用 ：使用 LT 模式。它更安全，代码更简单，不易出错。
• 高性能服务器专家 ：使用 ET 模式。但必须严格遵守"循环读写直到 EAGAIN"的规则，并妥善管理 EPOLLOUT 的监听状态。

2.8 EPOLLONESHOT：一次性事件

含义 ：这是一个模式设置标志 。它保证被监控的文件描述符上的事件最多被触发一次。

触发条件 ：一旦 epoll_wait 返回了该 fd 的某个事件，该 fd 就会从 epoll 的就绪列表中移除，内核将不再监控它，直到用户显式地通过 epoll_ctl(EPOLL_CTL_MOD) 重新武装（re-arm） 它。

设计意图 ：防止多个线程同时操作同一个文件描述符。在高并发多线程服务器中，如果一个 fd 的事件到来，可能会唤醒多个阻塞在 epoll_wait 上的线程（惊群效应的一种），导致它们都试图去 read() 同一个 socket，造成数据错乱。EPOLLONESHOT 确保了在一个时间段内，只有一个线程能处理这个 fd 的事件。

编程模式：

// 添加监控，设置 EPOLLONESHOT
struct epoll_event ev;
ev.events = EPOLLIN | EPOLLET | EPOLLONESHOT;
ev.data.fd = sockfd;
epoll_ctl(epfd, EPOLL_CTL_ADD, sockfd, &ev);

// 在工作线程中
void worker_thread(struct epoll_event *event) {
    int fd = event->data.fd;
    // 处理这个fd的事件（例如读取数据）
    process_data(fd);

    // 处理完毕后，必须重新武装该fd，否则不会再收到事件
    struct epoll_event new_ev;
    new_ev.events = EPOLLIN | EPOLLET | EPOLLONESHOT; // 重新设置事件
    new_ev.data.fd = fd;
    if (epoll_ctl(epfd, EPOLL_CTL_MOD, fd, &new_ev) == -1) {
        perror("epoll_ctl: rearm");
        close(fd);
    }
}

注意事项 ：在使用 EPOLLONESHOT 时，务必在事件处理完成后重新武装 fd。同时，在处理期间，如果又有新的事件到来（比如又有新数据到达），在 ET 模式下，这个新事件在重新武装前不会被通知，可能会造成延迟。因此，通常与 ET 模式一起使用。

2.9 EPOLLWAKEUP：防止休眠事件 (since Linux 3.5)

含义 ：这是一个模式设置标志 。它的作用是确保当这个事件被排队到 epoll 实例并且系统正在挂起时，系统不会被挂起（进入低功耗状态），或者会被唤醒。

设计意图 ：用于移动设备或需要电源管理的场景。如果一个应用程序正在等待一个事件（例如来自网络的响应），而系统此时决定进入休眠，那么响应可能永远无法到达，应用程序也会一直阻塞。通过设置 EPOLLWAKEUP，你可以告诉内核："这个事件很重要，处理它的时候不要休眠"。

使用条件 ：使用这个标志需要进程具有 CAP_BLOCK_SUSPEND 能力。它通常用于特定的、对实时性要求极高的应用（如 VoIP），在普通服务器环境下很少使用。

2.10 EPOLLEXCLUSIVE：独占唤醒事件 (since Linux 4.5)

含义 ：这是一个模式设置标志 。用于解决 epoll 的"惊群效应"（Thundering Herd Problem）。

问题背景 ：当多个进程或线程使用 epoll 监听同一个 文件描述符（例如一个监听套接字）时，一个新的连接到来（EPOLLIN）会唤醒所有 正在 epoll_wait 的进程/线程，但最终只有一个能成功 accept() 到这个新连接，其他进程/线程被唤醒后发现自己白忙活一场，造成了不必要的上下文切换和CPU资源浪费。

解决方案 ：EPOLLEXCLUSIVE 告诉内核，当事件发生时，只唤醒一个正在 epoll_wait 的进程/线程，而不是全部。这避免了惊群效应，提高了性能。

使用方法：

// 在多个进程中都这样添加监听套接字
struct epoll_event ev;
ev.events = EPOLLIN | EPOLLEXCLUSIVE; // 为监听套接字设置独占唤醒
ev.data.fd = listen_fd;
epoll_ctl(epfd, EPOLL_CTL_ADD, listen_fd, &ev);

注意事项：

• 它只对 EPOLL_CTL_ADD 操作有效，并且通常只用于监听套接字。
• 它不能完全保证只有一个进程被唤醒，内核可能会唤醒多个，但数量是可控的（通常最多一个），这仍然比唤醒所有要好得多。
• 它是解决多进程 epoll 惊群的首选方案，比之前使用 SO_REUSEPORT 等方案更优雅。

3. 实战应用与高级主题

3.1 一个完整的 Epoll 服务器示例

以下是一个使用 LT 模式的简单 TCP 回显服务器，它演示了如何综合运用各种事件。

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <unistd.h>
#include <arpa/inet.h>
#include <sys/socket.h>
#include <sys/epoll.h>
#include <fcntl.h>
#include <errno.h>

#define MAX_EVENTS 1024
#define PORT 8080
#define BUFFER_SIZE 1024

int set_nonblocking(int sockfd) {
    int flags = fcntl(sockfd, F_GETFL, 0);
    if (flags == -1) return -1;
    return fcntl(sockfd, F_SETFL, flags | O_NONBLOCK);
}

int main() {
    int listen_sock, conn_sock, nfds, epoll_fd;
    struct sockaddr_in srv_addr, cli_addr;
    socklen_t cli_len = sizeof(cli_addr);
    struct epoll_event ev, events[MAX_EVENTS];
    char buffer[BUFFER_SIZE];

    // 创建监听套接字
    listen_sock = socket(AF_INET, SOCK_STREAM, 0);
    if (listen_sock == -1) {
        perror("socket");
        exit(EXIT_FAILURE);
    }

    int optval = 1;
    setsockopt(listen_sock, SOL_SOCKET, SO_REUSEADDR, &optval, sizeof(optval));

    memset(&srv_addr, 0, sizeof(srv_addr));
    srv_addr.sin_family = AF_INET;
    srv_addr.sin_addr.s_addr = INADDR_ANY;
    srv_addr.sin_port = htons(PORT);

    if (bind(listen_sock, (struct sockaddr *)&srv_addr, sizeof(srv_addr)) == -1) {
        perror("bind");
        close(listen_sock);
        exit(EXIT_FAILURE);
    }

    if (listen(listen_sock, SOMAXCONN) == -1) {
        perror("listen");
        close(listen_sock);
        exit(EXIT_FAILURE);
    }

    printf("Server listening on port %d...\n", PORT);

    // 创建 epoll 实例
    epoll_fd = epoll_create1(0);
    if (epoll_fd == -1) {
        perror("epoll_create1");
        close(listen_sock);
        exit(EXIT_FAILURE);
    }

    // 添加监听套接字到 epoll，监听 EPOLLIN
    ev.events = EPOLLIN; // LT 模式
    ev.data.fd = listen_sock;
    if (epoll_ctl(epoll_fd, EPOLL_CTL_ADD, listen_sock, &ev) == -1) {
        perror("epoll_ctl: listen_sock");
        close(listen_sock);
        close(epoll_fd);
        exit(EXIT_FAILURE);
    }

    for (;;) {
        nfds = epoll_wait(epoll_fd, events, MAX_EVENTS, -1);
        if (nfds == -1) {
            perror("epoll_wait");
            break;
        }

        for (int n = 0; n < nfds; ++n) {
            if (events[n].data.fd == listen_sock) {
                // 监听套接字可读，表示有新连接
                conn_sock = accept(listen_sock, (struct sockaddr *)&cli_addr, &cli_len);
                if (conn_sock == -1) {
                    perror("accept");
                    continue;
                }

                printf("New connection from %s:%d\n", inet_ntoa(cli_addr.sin_addr), ntohs(cli_addr.sin_port));

                // 将新连接设置为非阻塞并添加到 epoll
                set_nonblocking(conn_sock);
                ev.events = EPOLLIN; // 为新连接监控读事件 (LT)
                ev.data.fd = conn_sock;
                if (epoll_ctl(epoll_fd, EPOLL_CTL_ADD, conn_sock, &ev) == -1) {
                    perror("epoll_ctl: conn_sock");
                    close(conn_sock);
                }
            } else {
                // 已连接套接字有事件
                int fd = events[n].data.fd;

                // 1. 首先检查错误和挂起
                if (events[n].events & (EPOLLERR | EPOLLHUP)) {
                    printf("Error or hang up on fd %d. Closing.\n", fd);
                    close(fd);
                    continue;
                }

                // 2. 处理可读事件
                if (events[n].events & EPOLLIN) {
                    ssize_t read_bytes;
                    // 在 LT 模式下，可以多次读取，但这里一次性读完也没问题
                    read_bytes = read(fd, buffer, BUFFER_SIZE - 1);
                    if (read_bytes > 0) {
                        buffer[read_bytes] = '\0';
                        printf("Received %zd bytes from fd %d: %s\n", read_bytes, fd, buffer);
                        // 回显数据：这里简单地把读事件转为写事件
                        // 在实际应用中，可能需要更复杂的逻辑
                        ev.events = EPOLLOUT; // 修改为监听写事件
                        ev.data.fd = fd;
                        if (epoll_ctl(epoll_fd, EPOLL_CTL_MOD, fd, &ev) == -1) {
                            perror("epoll_ctl: MOD -> OUT");
                            close(fd);
                        }
                    } else if (read_bytes == 0) {
                        // 对端关闭连接
                        printf("Connection closed by peer on fd %d.\n", fd);
                        close(fd);
                    } else { // read_bytes == -1
                        if (errno != EAGAIN && errno != EWOULDBLOCK) {
                            perror("read");
                            close(fd);
                        }
                        // 如果是 EAGAIN，在 LT 模式下不应该发生，因为会持续通知
                    }
                }

                // 3. 处理可写事件
                if (events[n].events & EPOLLOUT) {
                    // 这里简单回显之前读到的数据
                    // 在实际中，你需要管理要发送的数据缓冲区
                    const char *msg = "Echo: ";
                    write(fd, msg, strlen(msg));
                    write(fd, buffer, strlen(buffer)); // 注意：这里假设buffer还有效，实际应用需改进

                    printf("Sent echo to fd %d.\n", fd);

                    // 数据发送完毕，改回监听读事件
                    ev.events = EPOLLIN;
                    ev.data.fd = fd;
                    if (epoll_ctl(epoll_fd, EPOLL_CTL_MOD, fd, &ev) == -1) {
                        perror("epoll_ctl: MOD -> IN");
                        close(fd);
                    }
                }
            }
        }
    }

    close(listen_sock);
    close(epoll_fd);
    return 0;
}

（注意：此示例为教学目的简化，实际生产代码需要更完善的错误处理和缓冲区管理。）

3.2 状态机与事件处理流程

一个健壮的 epoll 服务器通常为每个连接维护一个状态机。事件驱动着状态机的转换。

典型连接状态：

1. 连接建立 ：accept() -> 监控 EPOLLIN。
2. 数据读取 ：EPOLLIN 触发 -> read() -> 处理请求 -> 可能需要监控 EPOLLOUT 来发送响应。
3. 数据发送 ：EPOLLOUT 触发 -> write() -> 发送完成 -> 改回监控 EPOLLIN 等待下一个请求。
4. 连接关闭 ：EPOLLHUP/EPOLLRDHUP/read() == 0 触发 -> close(fd)，清理资源。

Mermaid 状态图：
socket()/bind()/listen() EPOLLIN on listen_sock
accept() Monitor EPOLLIN read() > 0 Need to send reply
Monitor EPOLLOUT write() done
Monitor EPOLLIN EPOLLERR/EPOLLHUP
close() read() error
close() write() error
close() read() == 0 (EOF)
close() Listening Accepted Reading Processing Writing Error Closed

3.3 性能调优与注意事项

1. 文件描述符数量 ：epoll 能高效处理大量 fd，但 epoll_wait 返回的数组大小需要合理设置，太小会导致多次调用，太大会浪费内存。
2. 时间戳 ：epoll_wait 的超时参数 timeout 设置为 -1 表示阻塞，0 表示立即返回，>0 表示阻塞指定毫秒数。根据服务器类型（忙/闲）合理设置。
3. 避免在 ET 模式下 starvation ：确保在读到 EAGAIN 之前读完所有数据。
4. 使用 splice/sendfile 等零拷贝技术 ：对于文件传输，可以避免数据在用户态和内核态之间的拷贝，极大提升性能。当 EPOLLIN 到来且需要发送文件时，可以考虑使用这些技术。
5. 监控系统指标 ：使用 ss, /proc/net/tcp, perf 等工具监控网络栈状态、队列长度和性能瓶颈。

4. 总结

epoll_event 中的事件类型是 Linux 高性能网络编程的罗塞塔石碑。理解每个标志位的精确含义、触发条件和底层机制，是构建稳定、高效并发服务器的前提。

• EPOLLIN/EPOLLOUT 是读写状态的基石，其行为受 LT/ET 模式 fundamentally 影响。
• EPOLLERR 和 EPOLLHUP 是总是监控的错误信号，必须优先处理。
• EPOLLRDHUP 提供了更精细的连接关闭通知。
• EPOLLONESHOT 和 EPOLLEXCLUSIVE 是解决多线程/多进程同步和惊群问题的高级工具。

核心建议 ：从简单的 LT 模式 开始，它是安全且高效的。当你真正理解事件模型并遇到性能瓶颈时，再考虑切换到 ET 模式 ，并务必处理好 EAGAIN 和 EPOLLOUT 的状态管理。始终将 epoll 与你