ngx_epoll_module是Nginx在Linux下对epoll的高效封装，通过ngx_event_actions_t接口统一抽象add/del/enable/disable/process_events等操作，维护全局epfd和预分配events数组以减少系统调用与内存分配，强制O_NONBLOCK并遵循ET语义，同时进行错误语义归类与自动重试，屏蔽底层细节。

在 Nginx 源码中，ngx_epoll_module 是 Linux 平台下事件驱动模型的核心实现，它对 epoll 系统调用做了轻量、高效且面向生产环境的封装，而非简单直译系统接口。

封装目标：适配 Nginx 的事件循环与内存管理模型

Nginx 不直接暴露 epoll_ctl 或 epoll_wait 给上层模块，而是通过统一的 ngx_event_actions_t 接口抽象。ngx_epoll_module 实现了该结构体中的关键函数指针：

• add：对应 epoll_ctl(EPOLL_CTL_ADD)，但会检查连接是否已存在、复用已有 epoll_event 结构，避免重复注册
• del：对应 epoll_ctl(EPOLL_CTL_DEL)，删除时仅解除监听，不关闭 fd（由连接生命周期管理）
• enable/disable：通过 EPOLL_CTL_MOD 动态开关读/写事件，支持边缘触发（ET）模式下的精细控制
• process_events：封装 epoll_wait 调用，处理超时、中断重试，并将就绪事件批量拷贝到 ngx_cycle_t->events 数组供后续分发

关键数据结构：减少系统调用与内存分配开销

模块内部维护两个核心结构：

• epoll 复用句柄：ep = (ngx_epoll_conf_t *) ngx_event_get_conf(cycle->conf_ctx, ngx_epoll_module); 中的 ep->epfd 是全局单例 epoll 实例，整个 worker 进程共用一个
• 就绪事件缓存：ep->events 是预分配的固定大小数组（默认 NGX_MAX_EVENTS=512），避免每次 epoll_wait 都 malloc；实际大小可通过 worker_connections 配置调整
• 连接与事件绑定：每个 ngx_connection_t 的 read/write 成员内嵌 ngx_event_t，其 data 字段指向该连接，使事件回调能直接访问连接上下文

ET 模式支持：强制非阻塞 + 边缘触发语义保障

Nginx 默认启用 EPOLLET，封装层为此做了三方面约束：

• 所有 socket 必须设为 O_NONBLOCK，否则 ET 下可能因未读完数据导致饥饿
• epoll_wait 返回后，对每个就绪 fd 必须循环调用 recv/send 直到返回 EAGAIN/EWOULDBLOCK
• 写事件启用需谨慎：仅当发送缓冲区有空闲或上次 send 返回 EAGAIN 后才注册 EPOLLOUT，避免频繁唤醒

错误处理与健壮性设计

封装并非简单透传 errno，而是做语义化归类：

• EPOLLIN 就绪但 recv 返回 0 → 视为对端关闭，触发 ngx_http_close_connection
• EPOLLIN 就绪但 recv 返回 ECONNRESET → 标记异常关闭，跳过应用层处理
• epoll_wait 返回 -1 且 errno == EINTR → 自动重试，不中断事件循环
• 注册失败（如 fd 已关闭）时记录日志并跳过，不终止 worker 进程

这种封装让 Nginx 在保持高性能的同时，屏蔽了 Linux epoll 的底层细节和陷阱，把复杂性收敛在模块内部，对外提供稳定、一致、可预测的事件接口。