Nginx事件管理之epoll模块
1. epoll 原理
假设有 100 万用户同时与一个进程保持着 TCP 连接，而每一时刻只有几十个或几百个 TCP 连接时活跃的（接收到 TCP
包），也就是说，在每一时刻，进程只需要处理这 100 万连接中的一小部分连接。
select 和 poll 的做法是：进程每次收集事件的连接（其实这 100 万连接中的大部分都是没有事件发生的）都把这 100 万连
接的套接字传给操作系统（这首先就是用户态内存到内核态内存的大量复制），而由操作系统内核寻找这些连接上有没有未
处理的事件，将会是巨大的资源浪费，因此 select 和 poll 最多只能处理几千个并发连接。
而 epoll 则是在 Linux 内核中申请了一个简易的文件系统，把原先的一个 select 或者 poll 调用分成了 3 个部分：
- 调用 epoll_create 建立 1 个 epoll 对象（在 epoll 文件系统中给这个句柄分配资源）；
- 调用 epoll_ctl 向 epoll 对象中添加这 100 万个连接的套接字；
- 调用 epoll_wait 收集发生事件的连接。
Linux 2.6.35内核对 epoll 的实现
当某一个进程调用 epoll_create 方法时，Linux 内核会创建一个 eventpoll 结构体：
struct eventpoll {
...
/* 红黑树的根节点，这棵树中存储着所有添加到 epoll 中的事件，也就是这个 epoll 监控的事件 */
struct rb_root rbr;
/* 双向链表 rdllist 保存着将要通过 epoll_wait 返回给用户的、满足条件的事件 */
struct list_head rdllist;
};
每一个 epoll 对象都有一个独立的 eventpoll 结构体，这个结构体会在内核空间中创造独立的内存，用于存储使用
epoll_ctl 方法向 epoll 对象中添加进来的事件。这些事件都会挂到 rbr 红黑树中，这样，重复添加的事件就可以通过红黑
树而高效地识别出来。
所有添加到 epoll 中的事件都会与设备（如网卡）驱动程序建立回调关系，即相应的事件发生时会调用 ep_poll_callback 回调
方法，它会把这样的事件放到上面的 rdllist 双向链表中。
在 epoll 中，对于每一个事件都会建立一个 epitem 结构体：
struct epitem {
...
/* 红黑树节点 */
struct rb_node rbn;
/* 双向链表节点 */
struct list_head rdllink;
/* 事件句柄等信息 */
struct epoll_filefd ffd;
/* 指向所属的 eventpoll 对象 */
struct eventpoll *ep;
/* 期待的事件类型 */
struct epoll_event event;
...
};
这里包含每一个事件对应着的信息。
当调用 epoll_wait 检查是否有事件的连接时，只是检查 eventpoll 对象中的 rdllist 双向链表是否有 epitem 元素，如果
rdllist 链表不为空，则把这里的事件复制到用户态内存中，同时将事件数量返回给用户。
2. epoll 的使用
2.1 epoll 的接口
2.1.1 epoll_create()
int epoll_create(int size);
系统调用 epoll_create() 创建一个 epoll 的句柄，之后 epoll 的使用都将依靠这个句柄来标识。参数 size 是告知 epoll 所
要处理的大致事件数目。不再使用 epoll 时，必须调用 close 关闭这个句柄。
2.1.2 epoll_ctl()
int epoll_ctl(int epfd, int op, int fd, struct epoll_event* event);
epoll_ctl 向 epoll 对象中添加、修改或者删除感兴趣的事件，返回 0 表示成功，否则返回 -1，此时需要根据 errno 错误码
判断错误类型。
- epfd：是 epoll_create() 返回的句柄；
- op：表示动作，可取的值有：
- EPOLL_CTL_ADD: 添加新的事件到 epoll 中
- EPOLL_CTL_MOD: 修改 epoll 中的事件
- EPOLL_CTL_DEL：删除 epoll 中的事件
- fd: 需要监听的描述符；
- event: 是 epoll_event 结构体类型，用于告诉内核需要监听什么事件。epoll_event 的定义：
struct epoll_event {
__uint32_t events;
epoll_data_t data;
};
- events：的取值有
- EPOLLIN: 表示对应的连接上有数据可读（TCP 连接的远端主动关闭连接，也相当于可读事件，因为需要处理发送来的 FIN）
- EPOLLOUT: 表示对应的连接上可以写入数据发送（主动向上游服务器发起非阻塞的 TCP 连接，连接建立成功的事件相当于可写事件）
- EPOLLRDHUP：表示 TCP 连接的远端关闭或半关闭连接
- EPOLLLPRI：表示对应的连接上有紧急数据需要读
- EPOLLERR: 表示对应的连接发生错误
- EPOLLHUP: 表示对应的连接被挂起
- EPOLLLET: 表示将触发方式设置为边缘触发（ET），系统默认为水平触发(LT)
- EPOLLONESHOT: 表示对这个事件只处理一次，下次需要处理时需重新加入 epoll
- data：是一个 epoll_data 联合，定义如下：
typedef union epoll_data {
void *ptr;
int fd;
uint32_t u32;
uint64_t u64;
}epoll_data_t;
2.1.3 epoll_wait()
int epoll_wait(int epfd, struct epoll_event *events, int maxevents, int timeout);
收集在 epoll 监控的事件中已经发生的事件，如果 epoll 中没有任何一个事件发生，则最多等待 timeout 毫秒后返回。
epoll_wait 的返回值表示当前发生的事件个数，如果返回 0，则表示本次调用中没有事件发生，如果返回 -1，则表示发生错
误，需要检查 errno 判断错误类型。
- epfd：是 epoll_create() 返回的句柄；
- events：是分配好的 epoll_event 结构体数组，epoll 将会把发生的事件复制到 events 数组中（events 不可以是空指针，
内核只负责把数据复制到这个 events 数组中，不会去帮助我们在用户态中分配内存） - maxevents：表示本次可以返回的最大事件数目，通常 maxevents 参数与预分配的 events 数组的大小是相等的；
- timeout：表示在没有检测到事件发生时最多等待的时间（单位为毫秒），如果 timeout 为 0，则表示 epoll_wait 在
rdllist 链表为空时，立刻返回，不会等待。
2.2 epoll 的工作模式
epoll 有两种工作模式：LT（水平触发）模式和 ET（边缘触发）模式。
默认情况下，epoll 采用 LT 模式工作，这时可以处理阻塞和非阻塞套接字。ET 模式的效率要比 LT 模式高，它只支持非阻塞
字。ET 和 LT 模式的区别在于，当一个新的事件到来时，ET 模式下当然可以从 epoll_wait调用中获取这个事件，可是如果这
次没有把这个事件对应的套接字缓冲区处理完，在这个套接字没有新的事件再次到来时，在 ET 模式下是无法再次从
epoll_wait 调用中获取这个事件的；而 LT 模式则相反，只要一个事件对应的套接字缓冲区还有数据，就总能从 epoll_wait
中获取这个事件。因此，LT 模式相对简单，而在 ET 模式下事件发生时，如果没有彻底地将缓冲区数据处理完，则会导致缓冲
区中的用户请求得不到响应。默认情况下，Nginx 是通过 ET 模式使用 epoll 的。
3. ngx_epoll_module 模块
3.1 配置项
static ngx_command_t ngx_epoll_commands[] = {
/* 在调用 epoll_wait 时，将由第 2 和第 3 个参数告诉 Linux 内核一次最多可返回多少个事件。这个配置项
* 表示调用一次 epoll_wait 时最多可以返回的事件数，当然，它也会预分配那么多 epoll_event 结构体用于
* 存储事件 */
{ ngx_string("epoll_events"),
NGX_EVENT_CONF|NGX_CONF_TAKE1,
ngx_conf_set_num_slot,
0,
offsetof(ngx_epoll_conf_t, events),
NULL },
/* 指明在开启异步 I/O 且使用 io_setup 系统调用初始化异步 I/O 上下文环境时，初始分配的异步 I/O
* 事件个数 */
{ ngx_string("worker_aio_requests"),
NGX_EVENT_CONF|NGX_CONF_TAKE1,
ngx_conf_set_num_slot,
0,
offsetof(ngx_epoll_conf_t, aio_requests),
NULL },
ngx_null_command
};
存储配置项的配置结构体：
typedef struct {
ngx_uint_t events;
ngx_uint_t aio_requests;
} ngx_epoll_conf_t;
3.2 上下文结构体：ngx_epoll_module_ctx
static ngx_event_module_t ngx_epoll_module_ctx = {
&epoll_name,
ngx_epoll_create_conf, /* create configuration */
ngx_epoll_init_conf, /* init configuration */
{
ngx_epoll_add_event, /* add an event */
ngx_epoll_del_event, /* delete an event */
ngx_epoll_add_event, /* enable an event */
ngx_epoll_del_event, /* disable an event */
ngx_epoll_add_connection, /* add an connection */
ngx_epoll_del_connection, /* delete an connection */
#if (NGX_HAVE_EVENTFD)
ngx_epoll_notify, /* trigger a notify */
#else
NULL, /* trigger a notify */
#endif
ngx_epoll_process_events, /* process the events */
ngx_epoll_init, /* init the events */
ngx_epoll_done, /* done the events */
}
};
3.2.1 ngx_epoll_init
static ngx_int_t ngx_epoll_init(ngx_cycle_t *cycle, ngx_msec_t timer)
{
ngx_epoll_conf_t *epcf;
/* 获取配置项结构体 */
epcf = ngx_event_get_conf(cycle->conf_ctx, ngx_epoll_module);
if (ep == -1)
{
/* 创建一个 epoll 句柄 */
ep = epoll_create(cycle->connection_n / 2);
if (ep == -1)
{
ngx_log_error(NGX_LOG_EMERG, cycle->log, ngx_errno,
"epoll_create() failed");
return NGX_ERROR;
}
#if (NGX_HAVE_EVENTFD)
if (ngx_epoll_notify_init(cycle->log) != NGX_OK) {
ngx_epoll_module_ctx.actions.notify = NULL;
}
#endif
#if (NGX_HAVE_FILE_AIO)
ngx_epoll_aio_init(cycle, epcf);
#endif
#if (NGX_HAVE_EPOLLRDHUP)
ngx_epoll_test_rdhup(cycle);
#endif
}
if (nevents < epcf->events) {
if (event_list) {
ngx_free(event_list);
}
/* 创建 event_list 数组，用于进行 epoll_wait 调用时传递内核态的事件 */
event_list = ngx_alloc(sizeof(struct epoll_event) * epcf->events,
cycle->log);
if (event_list == NULL) {
return NGX_ERROR;
}
}
/* 将配置项epoll_events的参数赋给nevents */
nevents = epcf->events;
/* 指明读写I/O的方法 */
ngx_io = ngx_os_io;
/* 一旦设定Nginx使用某个事件处理模块，经过事件处理模块的初始化函数后，就把全局变量
* ngx_event_actions指向了该模块的封装 */
ngx_event_actions = ngx_epoll_module_ctx.actions;
#if (NGX_HAVE_CLEAR_EVENT)
/* 默认是采用ET模式来使用epoll的，NGX_USE_CLEAR_EVENT宏实际上就是在告诉Nginx使用ET模式 */
ngx_event_flags = NGX_USE_CLEAR_EVENT
#else
ngx_event_flags = NGX_USE_LEVEL_EVENT
#endif
|NGX_USE_GREEDY_EVENT
|NGX_USE_EPOLL_EVENT;
return NGX_OK;
}
3.2.2 ngx_epoll_add_event
static ngx_int_t ngx_epoll_add_event(ngx_event_t *ev, ngx_int_t event, ngx_uint_t flags)
{
int op;
uint32_t events, prev;
ngx_event_t *e;
ngx_connection_t *c;
struct epoll_event ee;
/* 每个事件的 data 成员都存放着其对应的 ngx_connection_t 连接 */
c = ev->data;
/* 下面会根据event参数确定当前事件时读事件还是写事件，
* 这会决定events是加上EPOLLIN标志还是EPOLLOUT标志位 */
events = (uint32_t) event;
if (event == NGX_READ_EVENT) {
e = c->write;
prev = EPOLLOUT;
#if (NGX_READ_EVENT != EPOLLIN|EPOLLRDHUP)
events = EPOLLIN|EPOLLRDHUP;
#endif
} else {
e = c->read;
prev = EPOLLIN|EPOLLRDHUP;
#if (NGX_WRITE_EVENT != EPOLLOUT)
events = EPOLLOUT;
#endif
}
/* 根据active标志位确定是否为活跃事件，以决定到底是修改还是添加事件 */
if (e->active) {
op = EPOLL_CTL_MOD;
events |= prev;
} else {
op = EPOLL_CTL_ADD;
}
#if (NGX_HAVE_EPOLLEXCLUSIVE && NGX_HAVE_EPOLLRDHUP)
if (flags & NGX_EXCLUSIVE_EVENT) {
events &= ~EPOLLRDHUP;
}
#endif
/* 加入flags参数到events标志位中 */
ee.events = events | (uint32_t) flags;
/* ptr成员存储的是ngx_connection_t连接 */
ee.data.ptr = (void *) ((uintptr_t) c | ev->instance);
ngx_log_debug3(NGX_LOG_DEBUG_EVENT, ev->log, 0,
"epoll add event: fd:%d op:%d ev:%08XD",
c->fd, op, ee.events);
/* 调用 epoll_ctl 方法向 epoll 中添加事件或者在 epoll 中修改事件 */
if (epoll_ctl(ep, op, c->fd, &ee) == -1) {
ngx_log_error(NGX_LOG_ALERT, ev->log, ngx_errno,
"epoll_ctl(%d, %d) failed", op, c->fd);
return NGX_ERROR;
}
/* 将事件的 active 标志位置为 1，表示当前事件是活跃的 */
ev->active = 1;
#if 0
ev->oneshot = (flags & NGX_ONESHOT_EVENT) ? 1 : 0;
#endif
return NGX_OK;
}
3.2.3 ngx_epoll_process_events
static ngx_int_t ngx_epoll_process_events(ngx_cycle_t *cycle, ngx_msec_t timer, ngx_uint_t flags)
{
int events;
uint32_t revents;
ngx_int_t instance, i;
ngx_uint_t level;
ngx_err_t err;
ngx_event_t *rev, *wev;
ngx_queue_t *queue;
ngx_connection_t *c;
/* NGX_TIMER_INFINITE == INFTIM */
ngx_log_debug1(NGX_LOG_DEBUG_EVENT, cycle->log, 0,
"epoll timer: %M", timer);
/* 调用 epoll_wait 获取事件。注意，timer 参数是在 process_events 调用时传入的 */
events = epoll_wait(ep, event_list, (int) nevents, timer);
err = (events == -1) ? ngx_errno : 0;
/* 判断flags标志位是否指示要更新时间或ngx_event_timer_alarm是否为1 */
if (flags & NGX_UPDATE_TIME || ngx_event_timer_alarm) {
ngx_time_update();
}
if (err) {
if (err == NGX_EINTR) {
if (ngx_event_timer_alarm) {
ngx_event_timer_alarm = 0;
return NGX_OK;
}
level = NGX_LOG_INFO;
} else {
level = NGX_LOG_ALERT;
}
ngx_log_error(level, cycle->log, err, "epoll_wait() failed");
return NGX_ERROR;
}
if (events == 0) {
if (timer != NGX_TIMER_INFINITE) {
return NGX_OK;
}
ngx_log_error(NGX_LOG_ALERT, cycle->log, 0,
"epoll_wait() returned no events without timeout");
return NGX_ERROR;
}
/* 遍历本次 epoll_wait 返回的所有事件 */
for (i = 0; i < events; i++) {
c = event_list[i].data.ptr;
/* uintptr_t 在 64 位平台上为：typedef unsigned long int upintptr_t;
* 在 32 位平台上为：typedef unsigned int uintptr_t;
* 该类型主要是为了跨平台，其长度总是所在平台的位数，常用于存放地址. */
/* 将地址的最后一位取出来，用 instance 变量标识 */
instance = (uintptr_t) c & 1;
/* 无论是 32 位还是 64 位机器，其地址的最后 1 位肯定是 0，可以用下面这行语句把
* ngx_connection_t 的地址还原到真正的地址值 */
c = (ngx_connection_t *) ((uintptr_t) c & (uintptr_t) ~1);
/* 取出读事件 */
rev = c->read;
/* 判断这个读事件是否是过期事件 */
if (c->fd == -1 || rev->instance != instance) {
/* 当 fd 套接字描述符为 -1 或者 instance 标志位不相等时，
* 表示这个事件已经过期了，不用处理 */
/*
* the stale event from a file descriptor
* that was just closed in this iteration
*/
ngx_log_debug1(NGX_LOG_DEBUG_EVENT, cycle->log, 0,
"epoll: stale event %p", c);
continue;
}
/* 取出事件类型 */
revents = event_list[i].events;
ngx_log_debug3(NGX_LOG_DEBUG_EVENT, cycle->log, 0,
"epoll: fd:%d ev:%04XD d:%p",
c->fd, revents, event_list[i].data.ptr);
/* 若事件发生错误或被挂起 */
if (revents & (EPOLLERR|EPOLLHUP)) {
ngx_log_debug2(NGX_LOG_DEBUG_EVENT, cycle->log, 0,
"epoll_wait() error on fd:%d ev:%04XD",
c->fd, revents);
/*
* if the error events were returned, add EPOLLIN and EPOLLOUT
* to handle the events at least in one active handler
*/
revents |= EPOLLIN|EPOLLOUT;
}
#if 0
if (revents & ~(EPOLLIN|EPOLLOUT|EPOLLERR|EPOLLHUP)) {
ngx_log_error(NGX_LOG_ALERT, cycle->log, 0,
"strange epoll_wait() events fd:%d ev:%04XD",
c->fd, revents);
}
#endif
/* 如果是读事件且该事件是活跃的 */
if ((revents & EPOLLIN) && rev->active) {
#if (NGX_HAVE_EPOLLRDHUP)
if (revents & EPOLLRDHUP) {
rev->pending_eof = 1;
}
rev->available = 1;
#endif
rev->ready = 1;
/* flags 参数中含有 NGX_POST_EVENTS 表示这批事件要延后处理 */
if (flags & NGX_POST_EVENTS) {
/* 如果要在 post 队列中延后处理该事件，首先要判断它是新连接事件还是普通事件，
* 以决定把它加入到 ngx_posted_accept_events 队列或者 ngx_posted_events 队列
* 中 */
queue = rev->accept ? &ngx_posted_accept_events
: &ngx_posted_events;
/* 将这个事件添加到相应的延后执行队列中 */
ngx_post_event(rev, queue);
} else {
/* 立即调用读事件的回调方法来处理这个事件 */
rev->handler(rev);
}
}
/* 取出写事件 */
wev = c->write;
/* 如果写事件且事件是活跃的 */
if ((revents & EPOLLOUT) && wev->active) {
/* 检测该事件是否是过期的 */
if (c->fd == -1 || wev->instance != instance) {
/* 如果 fd 描述符为 -1 或者 instance 标志位不相等时，表示这个
* 事件是过期的，不用处理 */
/*
* the stale event from a file descriptor
* that was just closed in this iteration
*/
ngx_log_debug1(NGX_LOG_DEBUG_EVENT, cycle->log, 0,
"epoll: stale event %p", c);
continue;
}
wev->ready = 1;
#if (NGX_THREADS)
wev->complete = 1;
#endif
/* 若该事件要延迟处理 */
if (flags & NGX_POST_EVENTS) {
/* 将该写事件添加到延迟执行队列中 */
ngx_post_event(wev, &ngx_posted_events);
} else {
/* 立即调用这个写事件的回调方法来处理这个事件 */
wev->handler(wev);
}
}
}
return NGX_OK;
}
ngx_epoll_process_events 方法会收集当前触发的所有事件，对于不需要加入到 post 队列延后处理的事件，该方法会立即执行
它们的回调方法，这其实是在做分发事件的工作，只是它会在自己的进程中调用这些回调方法而已，因此，每一个回调方法都不能
导致进程休眠或者消耗太多时间，以免 epoll 不能即时地处理其他事件.
什么是过期事件？
假设 epoll_wait 一次返回 3 个事件，在第 1 个事件的处理过程中，由于业务的需要，所以关闭了一个连接，而这个连接恰好对
应第 3 个事件。这样的话，在处理到第 3 个事件时，这个事件就已经是过期事件了，一旦处理必然出错。但是单纯把这个连接
的 fd 套接字置为 -1 是不能解决问题的。
如下场景：
假设第 3 个事件对应的 ngx_connection_t 连接中的 fd 套接字原先是 50，处理第 1 个事件时把这个连接的套接字关闭了，同
时置为 -1，并且调用 ngx_free_connection 将该连接归还给连接池。在 ngx_epoll_process_events 方法的循环中开始处理第 2
个事件，恰好第 2 个事件是建立新连接事件，调用 ngx_get_connection 从连接池中取出的连接非常可能就是刚刚释放的第 3 个
事件对应的连接。由于套接字 50 刚刚被释放，Linux 内核非常有可能把刚刚释放的套接字 50 又分配给新建立的连接。因此，
在循环中处理第 3 个事件时，这个事件就是过期的了。它对应的事件是关闭的连接，而不是新建立的连接。
因此，解决这个问题，依靠于 instance 标志位。当调用 ngx_get_connection 从连接池中获取一个新连接时，instance 标志位
就会置反。这样，当这个 ngx_connection_t 连接重复使用时，它的 instance 标志位一定是不同的。因此，在
ngx_epoll_process_events 方法中一旦判断 instance 发生了变化，就认为是过期事件而不予处理。
3.3 模块的定义
ngx_module_t ngx_epoll_module = {
NGX_MODULE_V1,
&ngx_epoll_module_ctx, /* module context */
ngx_epoll_commands, /* module directives */
NGX_EVENT_MODULE, /* module type */
NULL, /* init master */
NULL, /* init module */
NULL, /* init process */
NULL, /* init thread */
NULL, /* exit thread */
NULL, /* exit process */
NULL, /* exit master */
NGX_MODULE_V1_PADDING
};
