1. 引言Nginx 作为高性能 Web 服务器其核心在于非阻塞、异步的事件驱动模型。而这一切都建立在ngx_event_module这套精巧的内部基础设施之上。很多开发者熟悉 Nginx 的配置却对底层事件处理机制一知半解导致自己编写的模块性能不佳或行为诡异。本教程将带你直接从源代码出发剖析 Nginx event 模块的工作原理并配合实际代码示例详细讲解I/O 读写事件、定时器与超时的注册、触发和管理。读完后你将有能力编写稳定高效的 Nginx 事件驱动模块。2. Nginx 事件驱动架构一览在开始源码之旅前我们先通过一张流程图建立整体认知读事件写事件主进程 fork 工作进程ngx_worker_process_cyclengx_process_events_and_timers调用 ngx_event_actions-process_events(epoll_wait 等)遍历就绪事件链表事件类型?调用 ev-handler(rev)调用 ev-handler(wev)检查定时器红黑树处理超时事件Nginx 工作进程的核心循环就是反复调用ngx_process_events_and_timers()该函数内部完成调用平台相关的事件收集器epoll_wait/kqueue等遍历就绪事件并执行对应的回调handler处理定时器红黑树执行超时事件下一节我们将聚焦事件模块的核心数据结构理解这一切是如何串联起来的。3. 事件模块核心数据结构源码剖析3.1 事件基类ngx_event_t在src/event/ngx_event.h中定义了整个事件系统的灵魂structngx_event_s{void*data;// 通常指向 ngx_connection_tunsignedwrite:1;// 1 写事件0 读事件unsignedaccept:1;// 标记为 accept 事件unsignedinstance:1;// 用于检测过期事件unsignedactive:1;// 是否已加入事件收集器unsigneddisabled:1;unsignedready:1;// 事件就绪标记unsignedoneshot:1;unsignedcomplete:1;unsignedeof:1;unsignederror:1;unsignedtimedout:1;// 超时标记unsignedtimer_set:1;// 是否已加入定时器红黑树unsigneddelayed:1;unsigneddeferred_accept:1;unsignedpending_eof:1;unsignedposted:1;ngx_int_tindex;// 模块索引上下文ngx_log_t*log;ngx_rbtree_node_ttimer;// 定时器红黑树节点ngx_queue_tqueue;// 用于 post 链表ngx_event_handler_pt handler;// 回调函数指针};逐字段解释data关联的ngx_connection_t这样在回调中就能极快地拿到连接上下文active该事件是否已被添加到 epoll 中。防止重复添加ready当 epoll_wait 返回后设为 1表示该事件已就绪timedout当超时发生时例如读取客户端请求太慢框架将该标志置 1回调里检测到此标志后可终止或清理timer_set该事件是否已挂载到红黑树中handler这才是我们要关注的重点——事件就绪时执行的函数指针3.2 连接封装ngx_connection_t每个 TCP 连接都对应一个ngx_connection_t其中内嵌了两个事件structngx_connection_s{void*data;ngx_event_t*read;// 读事件ngx_event_t*write;// 写事件ngx_socket_tfd;ngx_recv_pt recv;ngx_send_pt send;// ...};关键点read-handler和write-handler即我们模块中需要设置的读写回调函数。Nginx 在就绪时会自动调用。4. 事件处理主循环ngx_process_events_and_timers该函数位于src/event/ngx_event.c是整个事件引擎的调度中心。简化后的流程如下voidngx_process_events_and_timers(ngx_cycle_t*cycle){ngx_uint_tflags;ngx_msec_ttimer;// 1. 从红黑树获得最近超时时间timerngx_event_find_timer();// 2. 调用平台实现等待 IO 事件(void)ngx_process_events(cycle,timer,flags);// 3. 执行延迟的事件链表posted eventsngx_event_process_posted(cycle,ngx_posted_accept_events);ngx_event_process_posted(cycle,ngx_posted_events);// 4. 处理超时事件ngx_event_expire_timers();}这里的ngx_process_events实际上是一个宏最终调用的是平台相关的ngx_event_actions.process_events在 Linux 下即ngx_epoll_process_events。整个过程清晰诠释了事件驱动的精髓等待 I/O → 处理 I/O → 处理超时 → 循环。5. I/O 读写事件详解5.1 读事件从 fd 读取数据读事件主要用于接收客户端数据或 upstream 响应。通常的注册流程为// 假设 c 是已经建立好的 ngx_connection_t *cc-read-handlerngx_http_my_read_handler;// 自定义回调// 将事件添加到 epollif(ngx_handle_read_event(c-read,0)!NGX_OK){ngx_close_connection(c);return;}在回调ngx_http_my_read_handler中我们需要自己处理具体的 recv 以及连接管理staticvoidngx_http_my_read_handler(ngx_event_t*rev){ssize_tn;ngx_connection_t*crev-data;u_char buf[1024];if(rev-timedout){// 检查超时标志ngx_log_error(NGX_LOG_INFO,c-log,0,read timeout);ngx_close_connection(c);return;}nc-recv(c,buf,sizeof(buf));if(nNGX_AGAIN){return;// 暂无数据等待下次通知}if(nNGX_ERROR||n0){ngx_close_connection(c);return;}// 处理接收到的 buf ...// 然后重新添加读事件如果还想继续读if(ngx_handle_read_event(rev,0)!NGX_OK){ngx_close_connection(c);}}注意rev-timedout标志由事件框架在ngx_event_expire_timers()中设置这是检测 I/O 超时的标准方法。如果你的模块没有任何读活跃框架会自动触发该事件的 handler 并置timedout1。5.2 写事件将数据发送出去写事件的触发时机是在数据无法一次写完socket 缓冲区满时由 epoll 通知我们可以继续写。以发送一段缓冲区为例staticvoidngx_http_my_write_handler(ngx_event_t*wev){ssize_tn,size;ngx_connection_t*cwev-data;if(wev-timedout){ngx_log_error(NGX_LOG_INFO,c-log,0,write timeout);ngx_close_connection(c);return;}// 假设 my_buf 是需要发送的 ngx_buf_tsizengx_buf_size(my_buf);nc-send(c,my_buf-pos,size);if(nNGX_AGAIN){return;}if(nNGX_ERROR){ngx_close_connection(c);return;}my_buf-posn;if(nsize){ngx_log_debug0(NGX_LOG_DEBUG_HTTP,c-log,0,write finished);// 删除写事件写完了就不再需要监听可写if(ngx_handle_write_event(wev,0)!NGX_OK){ngx_close_connection(c);return;}// ... 后续处理例如关闭连接或等待下一个请求}}初读这里可能会困惑为什么要删除写事件因为 epoll 默认是水平触发LT只要缓冲区不满就会反复通知可写造成 CPU 空转。所以 Nginx 推荐只在需要写入数据时才临时添加写事件写完后立刻删除。6. 定时器与超时机制6.1 设置超时每个ngx_event_t都内嵌了一个红黑树节点timer只需设置超时毫秒数并调用添加接口即可// 为读事件设置 30 秒超时ngx_add_timer(c-read,30000);或者使用更通用的宏ngx_event_add_timer(ev, timer)作用相同。当时间到达后框架会在主循环中自动调用handler并将ev-timedout设为 1。我们只需在回调里检查该标志。6.2 取消超时在事件正常完成或主动关闭连接前务必取消定时器否则可能导致悬挂指针if(c-read-timer_set){ngx_del_timer(c-read);}6.3 两种超时场景连接空闲超时长时间无数据交互。可通过ngx_add_timer设置在 read handler 中检测timedout后关闭连接。写超时发送数据对端迟迟不收包。同样在 write handler 中检查timedout防止资源泄漏。7. 实战示例一个最简单的事件驱动模块下面我们编写一个 Nginx 模块它会在接收到 HTTP 请求后先睡眠模拟耗时操作然后返回响应。通过这个例子你将完整看到读事件、定时器、写事件的组合用法。7.1 模块配置与上下文typedefstruct{ngx_msec_tdelay;// 模拟延迟时间毫秒}ngx_http_delay_loc_conf_t;在配置解析时获取delay指令。模块指令定义略。7.2 请求处理入口staticngx_int_tngx_http_delay_handler(ngx_http_request_t*r){ngx_http_delay_loc_conf_t*dlcf;// 非 GET 请求不处理if(r-method!NGX_HTTP_GET){returnNGX_DECLINED;}dlcfngx_http_get_module_loc_conf(r,ngx_http_delay_module);// 创建一个定时事件延迟后写响应ngx_event_t*evngx_pcalloc(r-pool,sizeof(ngx_event_t));if(evNULL){returnNGX_HTTP_INTERNAL_SERVER_ERROR;}ev-datar;ev-handlerngx_http_delay_timeout_handler;ev-logr-connection-log;ngx_add_timer(ev,dlcf-delay);// 注意这里返回 NGX_DONE 告诉 Nginx 不要完成请求后续由我们手动调用 ngx_http_finalize_requestreturnNGX_DONE;}7.3 定时器回调生成响应并发送staticvoidngx_http_delay_timeout_handler(ngx_event_t*ev){ngx_http_request_t*rev-data;ngx_buf_t*b;ngx_chain_tout;// 构造响应体bngx_create_temp_buf(r-pool,1024);if(bNULL){ngx_http_finalize_request(r,NGX_HTTP_INTERNAL_SERVER_ERROR);return;}b-lastngx_sprintf(b-last,Delay response after %M ms\n,(ngx_msec_t)ev-timer.key);// 简化 demo 使用 key 演示// 设置响应头r-headers_out.statusNGX_HTTP_OK;r-headers_out.content_length_nb-last-b-pos;ngx_http_send_header(r);out.bufb;out.nextNULL;// 发送响应并设置写事件处理如有必要ngx_int_trcngx_http_output_filter(r,out);if(rcNGX_AGAIN||rcNGX_ERROR){ngx_http_finalize_request(r,rc);return;}// 主动完成请求ngx_http_finalize_request(r,NGX_OK);}7.4 结合读超时的健壮版写法上面的例子仅为演示定时器。在实际网络通信中我们往往需要在读写事件上叠加超时。以读取客户端额外数据为例// 某读事件回调staticvoidmy_read_handler(ngx_event_t*rev){ngx_connection_t*crev-data;if(rev-timedout){ngx_log_error(NGX_LOG_ERR,c-log,0,client read timeout);ngx_close_connection(c);return;}// 读取并处理...if(ngx_handle_read_event(rev,0)!NGX_OK){ngx_close_connection(c);return;}// 续订超时重置30秒计时ngx_del_timer(rev);ngx_add_timer(rev,30000);}这样客户端若在 30 秒内无新数据timedout就会被置位连接得以安全关闭。9. 总结编译与配置前面我们实现了延迟响应模块的核心逻辑本节将补全模块的编译与集成细节让你能够真正跑起来。8.1 config 文件Nginx 的第三方模块通过一个config文件告知构建系统模块名称、源文件集合。在项目根目录下创建ngx_http_delay_module/文件夹并新建config文件ngx_addon_namengx_http_delay_moduleHTTP_MODULES$HTTP_MODULESngx_http_delay_moduleNGX_ADDON_SRCS$NGX_ADDON_SRCS$ngx_addon_dir/ngx_http_delay_module.cngx_addon_name模块名称通常与目录名一致。HTTP_MODULES将该模块追加到 HTTP 模块链表中Nginx 才能在启动时加载它。NGX_ADDON_SRCS需要编译的源文件路径中的$ngx_addon_dir会被自动展开为当前模块目录。如果需要支持动态模块可在config中额外添加if[-n$auto_configure];thenhaveNGX_HTTP_DELAY.auto/havefi本文以静态编译为主动态编译部分可参考 Nginx 官方文档。8.2 模块结构定义与指令解析将以下完整代码追加到ngx_http_delay_module.c中即可完成模块注册与指令解析前文的 handler 等函数保留在原文件中/* 模块指令定义 */staticngx_command_tngx_http_delay_commands[]{{ngx_string(delay),NGX_HTTP_LOC_CONF|NGX_CONF_TAKE1,ngx_http_delay,NGX_HTTP_LOC_CONF_OFFSET,0,NULL},ngx_null_command};/* 模块上下文 */staticngx_http_module_tngx_http_delay_module_ctx{NULL,/* preconfiguration */NULL,/* postconfiguration */NULL,/* create main configuration */NULL,/* init main configuration */NULL,/* create server configuration */NULL,/* merge server configuration */ngx_http_delay_create_loc_conf,/* create location configuration */ngx_http_delay_merge_loc_conf/* merge location configuration */};/* 模块定义 */ngx_module_tngx_http_delay_module{NGX_MODULE_V1,ngx_http_delay_module_ctx,/* module context */ngx_http_delay_commands,/* module directives */NGX_HTTP_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};紧接着实现指令解析函数与 location 配置的创建/合并函数/* delay 指令解析函数 */staticngx_int_tngx_http_delay(ngx_conf_t*cf,ngx_command_t*cmd,void*conf){ngx_http_delay_loc_conf_t*dlcfconf;ngx_str_t*value;ngx_int_tms;valuecf-args-elts;msngx_parse_time(value[1],0);if(msNGX_ERROR){ngx_conf_log_error(NGX_LOG_EMERG,cf,0,invalid value \%V\,value[1]);returnNGX_CONF_ERROR;}dlcf-delay(ngx_msec_t)ms;returnNGX_CONF_OK;}/* 创建 location 配置 */staticvoid*ngx_http_delay_create_loc_conf(ngx_conf_t*cf){ngx_http_delay_loc_conf_t*conf;confngx_pcalloc(cf-pool,sizeof(ngx_http_delay_loc_conf_t));if(confNULL){returnNULL;}conf-delayNGX_CONF_UNSET_MSEC;returnconf;}/* 合并 location 配置 */staticchar*ngx_http_delay_merge_loc_conf(ngx_conf_t*cf,void*parent,void*child){ngx_http_delay_loc_conf_t*prevparent;ngx_http_delay_loc_conf_t*confchild;ngx_conf_merge_msec_value(conf-delay,prev-delay,1000);returnNGX_CONF_OK;}要点说明delay指令仅允许在location块内出现NGX_HTTP_LOC_CONF接收一个时间参数。ngx_parse_time()可以解析5000、5s、5000ms等形式统一转为毫秒存入delay。合并配置时默认延迟为1000 毫秒1 秒若用户未指定delay则使用该默认值。8.3 nginx.conf 配置示例动态编译先通过--add-dynamic-module将模块编译为.so再在nginx.conf中用load_module加载load_module modules/ngx_http_delay_module.so; events { worker_connections 1024; } http { server { listen 80; server_name localhost; location /delay { delay 5000; # 延迟 5 秒后返回响应 } } }静态编译在 Nginx 源码目录执行./configure --add-module/path/to/ngx_http_delay_module然后make make install。此时nginx.conf中无需load_module直接使用delay指令即可。编译完成后启动 Nginx访问http://localhost/delay大约 5 秒后即可看到 “Delay response after …” 的响应内容证明你的事件驱动模块已经可以正常工作了。8. 总结通过本文的源码剖析和实战示例你应该已经掌握Nginx 事件模块的三大核心数据结构ngx_event_t、ngx_connection_t及定时红黑树。I/O 读写事件的注册、回调处理与水平触发下的**“写即删”**策略。利用ngx_add_timer/ngx_del_timer精确控制超时并在回调中通过timedout标志做出响应。如何将这些知识点组合成一个完整的 Nginx 事件驱动模块。事件模型是 Nginx 高性能的根基理解并善用它将让你的 C 模块开发水平迈上一个新台阶。建议你在实际开发中多翻阅src/event/和src/http/下的源码结合本文的脉络很快就能写出生产级别的事件处理代码。