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 的底层细节和陷阱，把复杂性收敛在模块内部，对外提供稳定、一致、可预测的事件接口。
