ngx_signal_handler

1 定义

ngx_signal_handler 函数 定义在 /nginx-1.24.0/src/os/unix/ngx_process.c

staticvoidngx_signal_handler(intsigno,siginfo_t*siginfo,void*ucontext){char*action;ngx_int_tignore;ngx_err_terr;ngx_signal_t*sig;ignore=0;err=ngx_errno;for(sig=signals;sig->signo!=0;sig++){if(sig->signo==signo){break;}}ngx_time_sigsafe_update();action="";switch(ngx_process){caseNGX_PROCESS_MASTER:caseNGX_PROCESS_SINGLE:switch(signo){casengx_signal_value(NGX_SHUTDOWN_SIGNAL):ngx_quit=1;action=", shutting down";break;casengx_signal_value(NGX_TERMINATE_SIGNAL):caseSIGINT:ngx_terminate=1;action=", exiting";break;casengx_signal_value(NGX_NOACCEPT_SIGNAL):if(ngx_daemonized){ngx_noaccept=1;action=", stop accepting connections";}break;casengx_signal_value(NGX_RECONFIGURE_SIGNAL):ngx_reconfigure=1;action=", reconfiguring";break;casengx_signal_value(NGX_REOPEN_SIGNAL):ngx_reopen=1;action=", reopening logs";break;casengx_signal_value(NGX_CHANGEBIN_SIGNAL):if(ngx_getppid()==ngx_parent||ngx_new_binary>0){/* * Ignore the signal in the new binary if its parent is * not changed, i.e. the old binary's process is still * running. Or ignore the signal in the old binary's * process if the new binary's process is already running. */action=", ignoring";ignore=1;break;}ngx_change_binary=1;action=", changing binary";break;caseSIGALRM:ngx_sigalrm=1;break;caseSIGIO:ngx_sigio=1;break;caseSIGCHLD:ngx_reap=1;break;}break;caseNGX_PROCESS_WORKER:caseNGX_PROCESS_HELPER:switch(signo){casengx_signal_value(NGX_NOACCEPT_SIGNAL):if(!ngx_daemonized){break;}ngx_debug_quit=1;/* fall through */casengx_signal_value(NGX_SHUTDOWN_SIGNAL):ngx_quit=1;action=", shutting down";break;casengx_signal_value(NGX_TERMINATE_SIGNAL):caseSIGINT:ngx_terminate=1;action=", exiting";break;casengx_signal_value(NGX_REOPEN_SIGNAL):ngx_reopen=1;action=", reopening logs";break;casengx_signal_value(NGX_RECONFIGURE_SIGNAL):casengx_signal_value(NGX_CHANGEBIN_SIGNAL):caseSIGIO:action=", ignoring";break;}break;}if(siginfo&&siginfo->si_pid){ngx_log_error(NGX_LOG_NOTICE,ngx_cycle->log,0,"signal %d (%s) received from %P%s",signo,sig->signame,siginfo->si_pid,action);}else{ngx_log_error(NGX_LOG_NOTICE,ngx_cycle->log,0,"signal %d (%s) received%s",signo,sig->signame,action);}if(ignore){ngx_log_error(NGX_LOG_CRIT,ngx_cycle->log,0,"the changing binary signal is ignored: ""you should shutdown or terminate ""before either old or new binary's process");}if(signo==SIGCHLD){ngx_process_get_status();}ngx_set_errno(err);}

ngx_signal_handler 是 Nginx 注册的异步信号处理函数， 主要作用是将接收到的信号转换为对相应全局标志位 并记录日志， 以便主循环或工作循环在同步上下文中实际执行优雅退出、重载配置、日志重开等操作。

2 详解

1 函数签名

staticvoidngx_signal_handler(intsigno,siginfo_t*siginfo,void*ucontext)

返回值 信号处理函数不返回任何值

参数 int signo 收到的信号编号 参数 siginfo_t *siginfo siginfo_t 是 POSIX 定义的结构体，包含信号的附加信息 提供关于信号的详细上下文 参数 void *ucontext void * 泛型指针，实际指向 ucontext_t 结构体 保存信号接收时的进程用户上下文，包括处理器寄存器状态、程序计数器、栈指针等， 可用于实现复杂的用户级上下文切换或调试 来源：内核在中断用户态代码时保存的上下文快照。

2 逻辑流程

1 局部变量 2 初始化 3 根据信号编号查找对应描述信息 4 更新时间 5 处理信号 5-1 主进程与单进程模式 5-2 工作进程与辅助进程 6 记录日志 7 热升级信号 ignore 8 回收子进程 9 恢复 errno

1 局部变量

{char*action;ngx_int_tignore;ngx_err_terr;ngx_signal_t*sig;

2 初始化

ignore=0;err=ngx_errno;

将局部变量 ignore 初始化为 0。 该变量是一个 ngx_int_t 类型的标志位， 用于指示是否应当忽略本次收到的信号 保存进入信号处理函数前一刻的全局错误码 信号是异步中断，可能在任何系统调用或库函数执行中途触发 函数末尾执行 ngx_set_errno(err); 将保存的值恢复， 确保信号返回后，被中断的原始代码看到的 errno 与中断前完全一致。

3 根据信号编号查找对应描述信息

for(sig=signals;sig->signo!=0;sig++){if(sig->signo==signo){break;}}

4 更新时间

ngx_time_sigsafe_update();action="";

#1 调用 Nginx 专门设计的 异步信号安全 时间更新函数，刷新全局缓存时间变量 Nginx 为追求极致性能，不实时调用系统时间 API，而是在主事件循环中周期性缓存时间 但信号是异步触发的，可能打断事件循环。 若直接使用旧缓存时间打日志，会导致时间戳严重滞后。 #2 将局部字符指针 action 初始化为一个空字符串常量 ""。 action 变量的用途 后续代码会依据收到的信号和当前进程类型，将 action 指向不同的描述性字符串。例如： ", shutting down" ", exiting" ", reconfiguring" ", ignoring" 这些字符串会被拼接到日志消息的末尾，告知管理员该信号触发了什么行为。

5 处理信号

switch(ngx_process){

它根据当前进程的角色和收到的信号编号， 设置相应的全局标志位和动作描述字符串， 从而将异步信号转化为进程主循环稍后可同步处理的“待办事项”。

按进程角色分流 ngx_process： 全局变量，在 Nginx 启动时确定，标识当前进程的类型。 NGX_PROCESS_MASTER： 主进程（负责管理子进程） NGX_PROCESS_SINGLE： 单进程模式（开发或调试用，既当 master 又当 worker） NGX_PROCESS_WORKER： 工作进程（处理实际请求） NGX_PROCESS_HELPER： 辅助进程（如缓存管理器 cache manager、缓存加载器 cache loader） 设计意义： 不同进程角色对同一信号的处理逻辑可能完全不同

5-1 主进程与单进程模式

caseNGX_PROCESS_MASTER:caseNGX_PROCESS_SINGLE:

switch(signo){

按信号编号处理

casengx_signal_value(NGX_SHUTDOWN_SIGNAL):ngx_quit=1;action=", shutting down";break;

设置全局优雅退出标志 将动作描述字符串置为 ", shutting down"，后续日志中将显示该动作。

casengx_signal_value(NGX_TERMINATE_SIGNAL):caseSIGINT:ngx_terminate=1;action=", exiting";break;

SIGINT 通常由终端 Ctrl+C 产生。两个信号都导致强制退出。 ngx_terminate = 1; 设置强制终止标志。 主循环检测后立即向工作进程发送 SIGTERM，并快速退出，不等待连接处理完毕。 action = ", exiting"; 动作描述为强制退出。

casengx_signal_value(NGX_NOACCEPT_SIGNAL):if(ngx_daemonized){ngx_noaccept=1;action=", stop accepting connections";}break;

#1 仅在 Nginx 以守护进程方式运行时才处理此信号 #2 通知工作进程停止接受新连接，但不退出。 用于平滑升级场景： 旧主进程收到 SIGWINCH 后设置此标志， 工作进程随后关闭监听套接字， 新启动的 master 可以接管监听 #3 动作描述为 停止接受连接

casengx_signal_value(NGX_RECONFIGURE_SIGNAL):ngx_reconfigure=1;action=", reconfiguring";break;

设置重读配置标志。 设置 动作描述

casengx_signal_value(NGX_REOPEN_SIGNAL):ngx_reopen=1;action=", reopening logs";break;

设置重开日志文件标志。 设置 动作描述

casengx_signal_value(NGX_CHANGEBIN_SIGNAL):if(ngx_getppid()==ngx_parent||ngx_new_binary>0){/* * Ignore the signal in the new binary if its parent is * not changed, i.e. the old binary's process is still * running. Or ignore the signal in the old binary's * process if the new binary's process is already running. */action=", ignoring";ignore=1;break;}ngx_change_binary=1;action=", changing binary";break;

用于平滑升级可执行文件（热升级）。 #1 ngx_getppid() == ngx_parent： ngx_parent 是升级时保存的旧主进程 PID。 若当前进程的父进程 ID 仍是旧主进程， 意味着新主进程已经启动但旧主进程尚未退出， 此时再次收到 SIGUSR2 应忽略，防止嵌套升级。 ngx_new_binary > 0： 若旧主进程已检测到新版本正在运行，则忽略后续升级信号。 满足任一条件，则设置 ignore = 1 和 action = ", ignoring"，并 break，不设置 ngx_change_binary。 若未冲突，则 ngx_change_binary = 1;， 主循环将执行 execve() 替换自身为新二进制文件，完成升级。

caseSIGALRM:ngx_sigalrm=1;break;

caseSIGIO:ngx_sigio=1;break;

caseSIGCHLD:ngx_reap=1;break;}break;

这三个信号仅设置标志，不设置 action（保持为空字符串）。 SIGALRM： 由 setitimer 定时器产生，主循环检查 ngx_sigalrm 后执行定时事件（如 epoll_wait 超时处理）。 SIGIO： 异步 I/O 信号（Nginx 中较少使用，主要用于某些特殊事件驱动模型）。 SIGCHLD： 子进程状态改变（终止或停止），主循环检查 ngx_reap 后调用 waitpid 回收子进程。

5-2 工作进程与辅助进程

caseNGX_PROCESS_WORKER:caseNGX_PROCESS_HELPER:switch(signo){casengx_signal_value(NGX_NOACCEPT_SIGNAL):if(!ngx_daemonized){break;}ngx_debug_quit=1;/* fall through */casengx_signal_value(NGX_SHUTDOWN_SIGNAL):ngx_quit=1;action=", shutting down";break;

#1 if (!ngx_daemonized)： 若非守护模式，直接 break 跳出内层 switch，即忽略该信号。 #2 ngx_debug_quit = 1;： 设置调试退出标志（特定场景下用于协调退出过程）。 #3 /* fall through */：注释表明这是有意穿透到下一个 case 标签，不加 break。 #4 紧接着是 case ngx_signal_value(NGX_SHUTDOWN_SIGNAL):， 所以收到 SIGWINCH 的工作进程会执行与收到 SIGQUIT 完全相同的操作： ngx_quit = 1; 和 action = ", shutting down";。 意义： 对于工作进程，SIGWINCH 不仅停止接受新连接，还会优雅退出。 这与主进程仅停止接受连接而不退出的语义不同，因为工作进程退出后可由主进程重新拉起。

casengx_signal_value(NGX_TERMINATE_SIGNAL):caseSIGINT:ngx_terminate=1;action=", exiting";break;

强制退出

casengx_signal_value(NGX_REOPEN_SIGNAL):ngx_reopen=1;action=", reopening logs";break;

工作进程也需重新打开日志文件，实现日志切割后更新文件描述符。

casengx_signal_value(NGX_RECONFIGURE_SIGNAL):casengx_signal_value(NGX_CHANGEBIN_SIGNAL):caseSIGIO:action=", ignoring";break;}break;}

NGX_RECONFIGURE_SIGNAL 和 NGX_CHANGEBIN_SIGNAL： 管理类信号，工作进程无权处理，直接忽略。 SIGIO： 异步 I/O 信号在工作进程中也忽略（由事件驱动模型自行处理，无需工作进程关注）。 action = ", ignoring"：日志中会显示 , ignoring，明确告知该信号被忽略。

6 记录日志

if(siginfo&&siginfo->si_pid){ngx_log_error(NGX_LOG_NOTICE,ngx_cycle->log,0,"signal %d (%s) received from %P%s",signo,sig->signame,siginfo->si_pid,action);}else{ngx_log_error(NGX_LOG_NOTICE,ngx_cycle->log,0,"signal %d (%s) received%s",signo,sig->signame,action);}

7 热升级信号 ignore

if(ignore){ngx_log_error(NGX_LOG_CRIT,ngx_cycle->log,0,"the changing binary signal is ignored: ""you should shutdown or terminate ""before either old or new binary's process");}

#1 if (ignore)： ignore 是在前面 NGX_CHANGEBIN_SIGNAL 分支中设置的标志。 若为 1，表示热升级信号由于状态冲突而被忽略。 ngx_log_error(NGX_LOG_CRIT, ...) 使用 CRIT 级别，表明该情况需要管理员介入处理，否则升级流程无法继续。 日志内容： 明确告知“切换二进制文件的信号被忽略”，并给出解决方案： “应当先关闭或终止旧二进制或新二进制的进程”。 防止死锁状态： 热升级要求旧 master 和新 master 不能同时存在并处理信号。 当出现冲突时，Nginx 主动忽略信号并记录关键错误，避免进程状态混乱。

8 回收子进程

if(signo==SIGCHLD){ngx_process_get_status();}

若收到的信号是 SIGCHLD（子进程状态改变），则立即执行特定操作

9 恢复 errno

ngx_set_errno(err);}

将 errno 恢复为信号到达前的状态