ngx_output_chain_as_is

1 定义ngx_output_chain_as_is 函数 定义在 src/core/ngx_output_chain.cstaticngx_inlinengx_int_tngx_output_chain_as_is(ngx_output_chain_ctx_t*ctx,ngx_buf_t*buf){ngx_uint_tsendfile;if(ngx_buf_special(buf)){return1;}#if(NGX_THREADS)if(buf-in_file){buf-file-thread_handlerctx-thread_handler;buf-file-thread_ctxctx-filter_ctx;}#endifsendfilectx-sendfile;#if(NGX_SENDFILE_LIMIT)if(buf-in_filebuf-file_posNGX_SENDFILE_LIMIT){sendfile0;}#endif#if!(NGX_HAVE_SENDFILE_NODISKIO)/* * With DIRECTIO, disable sendfile() unless sendfile(SF_NOCACHE) * is available. */if(buf-in_filebuf-file-directio){sendfile0;}#endifif(!sendfile){if(!ngx_buf_in_memory(buf)){return0;}buf-in_file0;}if(ctx-need_in_memory!ngx_buf_in_memory(buf)){return0;}if(ctx-need_in_temp(buf-memory||buf-mmap)){return0;}return1;}2 目的1 设计意图ngx_output_chain_as_is是ngx_output_chain引擎的转发判定器——它回答一个核心问题某个给定的缓冲区ngx_buf_t是否可以原样交给下游output_filter而不需要先拷贝到临时缓冲区。该函数属于 Nginx 输出链基础设施层src/core/ngx_output_chain.c是协议无关的通用组件。该函数本质上是一个逐层收紧的准入过滤器——从一个默认可转发的假设出发依次叠加六层约束条件。只要任何一层判定不通过就返回 0不可转发要求上层执行数据拷贝。这种宽进严出的设计使得缓冲区在绝大多数常规场景下都能走零拷贝路径只有在必须拷贝时才付出拷贝开销。在 Nginx 整体架构中该函数连接了上游数据生产者与下游数据发送者上游模块如静态文件、FastCGI、proxy产出的缓冲区经过此函数判定后要么以原始指针形式传递给write_filter零拷贝适合sendfile场景要么被拷贝到对齐后的临时缓冲区中适合需要修改数据或内存已满的场景。3 详解1 函数签名staticngx_inlinengx_int_tngx_output_chain_as_is(ngx_output_chain_ctx_t*ctx,ngx_buf_t*buf)1 返回值ngx_int_t返回值值含义11缓冲区可原样转发as-is无需拷贝即可直接交给下游output_filter00缓冲区不可直接转发需要先拷贝到临时缓冲区注意该函数本身不返回NGX_ERROR。所有检查都是通过/不通过的二元判定错误由上层ngx_output_chain的拷贝流程如内存分配失败来处理。2 函数名ngx_output_chain_as_is词段含义ngxNginx 源码前缀output_chain属于输出链子系统as_is“照原样”——判定缓冲区是否可以按原始形态直接转发不经过拷贝as_is这个命名精准地传达了函数的核心语义不改变、不复制、照原样传递。与ngx_output_chain_copy_buf执行实际数据拷贝形成互补关系。3 参数列表参数类型含义来源约束ctxngx_output_chain_ctx_t *输出链上下文维护输出通道的全部配置和状态调用方ngx_output_chain传入非 NULL其内部的sendfile、need_in_memory、need_in_temp等字段是本函数判定的核心依据bufngx_buf_t *待判定的单个缓冲区ctx-in-buf内循环中或in-buf快速路径中非 NULL其in_file、memory、mmap、flush等标记位决定判定结果2 逻辑流程ngx_output_chain_as_is(ctx, buf) ├─ [1] 特殊缓冲区检测 │ └─ ngx_buf_special(buf) → return 1标记型缓冲区无条件放行 ├─ [2] 线程模式文件回调设置编译时可选 │ └─ buf-in_file → 将 ctx 的 thread_handler/thread_ctx 挂载到 file 对象上 ├─ [3] sendfile 上限检测编译时可选 │ └─ buf-in_file file_pos NGX_SENDFILE_LIMIT → 强制禁用 sendfile ├─ [4] DirectIO 冲突检测编译时可选 │ └─ buf-in_file file-directio → 禁用 sendfileSF_NOCACHE 不可用时 ├─ [5] 非 sendfile 路径的内存约束 │ ├─ !sendfile !ngx_buf_in_memory(buf) → return 0文件数据 无 sendfile 不可转发 │ └─ !sendfile ngx_buf_in_memory(buf) → buf-in_file 0清除残留文件标记 ├─ [6] need_in_memory 强制内存约束 │ └─ ctx-need_in_memory !ngx_buf_in_memory(buf) → return 0 ├─ [7] need_in_temp 可写性约束 │ └─ ctx-need_in_temp (buf-memory || buf-mmap) → return 0 └─ → return 1全部检查通过可原样转发{ngx_uint_tsendfile;局部变量声明sendfile是一个局部拷贝。它将ctx-sendfile的值复制到栈上然后各编译时条件分支可能在此基础上将其清零。使用局部变量而非直接修改ctx-sendfile的原因每个缓冲区的判定是独立的——对当前缓冲区禁用 sendfile 不应影响后续缓冲区的判定。1 特殊缓冲区检测if(ngx_buf_special(buf)){return1;}进入条件ngx_buf_special(buf)为真。即这是一个纯控制信号缓冲区不携带任何实际数据。例如body filter 链发出的last_buf标记缓冲区通知下游这是最后一段数据flush标记缓冲区要求下游立即刷新。处理逻辑直接返回 1。特殊缓冲区不需要数据拷贝——它们本身就是元信号数据量为零。如果走拷贝流程反而会导致无谓的临时缓冲区分配。为什么放在第一步特殊缓冲区虽然不常见但判定成本极低只检查几个位标记放在第一位可以在所有其他复杂判定之前快速放行2 线程模式文件回调设置#if(NGX_THREADS)if(buf-in_file){buf-file-thread_handlerctx-thread_handler;buf-file-thread_ctxctx-filter_ctx;}#endif进入条件编译时NGX_THREADS宏已定义configure 阶段配置了线程池支持。进入条件运行时buf-in_file 1缓冲区引用了一个文件。处理逻辑将输出链上下文中的线程处理回调函数指针和上下文指针写入到ngx_file_t结构体中buf-file-thread_handler ctx-thread_handler设置文件读取使用的线程处理函数buf-file-thread_ctx ctx-filter_ctx设置线程处理函数的上下文参数3 sendfile 上限检测sendfilectx-sendfile;#if(NGX_SENDFILE_LIMIT)if(buf-in_filebuf-file_posNGX_SENDFILE_LIMIT){sendfile0;}#endif进入条件编译时NGX_SENDFILE_LIMIT宏已定义且非零。该宏仅在一种真实场景下被定义条件NGX_HAVE_SENDFILE64未定义时——即 Linux 内核或 glibc 版本不支持 sendfile64()64 位偏移版本只能使用传统的 32 位 sendfile() 系统调用。NGX_HAVE_SENDFILE64由 configure 脚本自动检测编译测试程序是否能在包含 sys/sendfile.h 后成功调用 sendfile64()。现代 Linux 系统2.6 内核、较新 glibc通常都支持 sendfile64()因此绝大多数生产环境不会定义NGX_SENDFILE_LIMIT。在 Linux 平台上sendfile()系统调用使用 32 位off_t参数即使内核支持 64 位偏移glibc 的sendfile封装仍使用off_t的 32 位版本作为传输偏移参数因此当文件偏移超过 2GB0x80000000时sendfile()将无法正确定位。NGX_SENDFILE_LIMIT标记了这个上限。进入条件运行时buf-in_file 1且buf-file_pos NGX_SENDFILE_LIMIT文件读取偏移已达到或超过 2GB 限制。处理逻辑将局部变量sendfile强制清零。这意味着即使ctx-sendfile为 1全局启用了 sendfile对于这个特定缓冲区也必须走先拷贝到内存再发送的路径而非 sendfile 零拷贝。ctx-sendfile字段src/core/ngx_buf.h中ngx_output_chain_ctx_sunsignedsendfile:1;1 位位域标识输出链是否启用了 sendfile 优化。该值由上层调用者在初始化ngx_output_chain_ctx_t时设置为什么用局部变量而非直接修改ctx-sendfilectx-sendfile是全局开关对后续其他缓冲区也有效。当前缓冲区只是恰好偏移超过了 sendfile 限制不代表后续缓冲区也不能使用 sendfile。局部覆盖保证了判定的逐缓冲区独立性。安全考量如果不做此检查在文件偏移 2GB 时调用sendfile()会导致截断的偏移值、数据错位甚至静默发送错误内容。这是一个必须在进入内核之前拦截的条件。4 DirectIO 冲突检测#if!(NGX_HAVE_SENDFILE_NODISKIO)/* * With DIRECTIO, disable sendfile() unless sendfile(SF_NOCACHE) * is available. */if(buf-in_filebuf-file-directio){sendfile0;}#endif进入条件编译时NGX_HAVE_SENDFILE_NODISKIO宏未定义。该宏仅在 FreeBSD 上可用表示 FreeBSD 的sendfile()支持SF_NOCACHE标志——在发送文件数据后不将其保留在系统页缓存中。进入条件运行时buf-in_file 1且buf-file-directio 1文件以 DirectIO 模式打开即绕过操作系统页缓存直接从磁盘读取。处理逻辑将局部变量sendfile清零强制禁用 sendfile。ngx_file_t的directio字段src/core/ngx_file.hunsigneddirectio:1;1 位位域标识文件是否以 DirectIOO_DIRECT模式打开。设计意图DirectIO 与 sendfile 存在语义冲突。DirectIO 的设计目标是将数据直接从磁盘读到用户空间绕过页缓存。而sendfile()的工作方式是将数据从页缓存直接发送到 socket。如果文件以 DirectIO 打开但数据尚未在页缓存中恰好被 bypass 了sendfile()将无法获取数据。在 FreeBSD 上SF_NOCACHE标志允许sendfile()在 DirectIO 模式下正常工作先读入临时缓冲区再发送发送后丢弃缓存。但在其他平台上缺少这个能力时最安全的做法是直接禁用 sendfile走先读取到内存 → 再发送的两步流程。安全考量如果不做此检查在 DirectIO 文件上尝试 sendfile 可能导致数据发送不完整部分数据不在页缓存中、静默发送错误内容页缓存中有过期数据、甚至 socket 挂起等待页缓存填充但 DirectIO 永远不填充页缓存。5 非 sendfile 路径的内存约束if(!sendfile){if(!ngx_buf_in_memory(buf)){return0;}buf-in_file0;}进入条件经过上述所有检查后局部变量sendfile 0。可能的原因包括ctx-sendfile原始值为 0全局禁用 sendfile文件偏移超过 sendfile 限制分支 [3]DirectIO 冲突分支 [4]处理逻辑——分两步第 1 步内存检查如果缓冲区不含内存数据!ngx_buf_in_memory(buf)即既不是temporary/memory/mmap也不是in_file已经为 0 的情况则返回 0不可转发。这里的逻辑需要结合上下文理解当sendfile被禁用时文件数据无法通过sendfile()零拷贝发送。而纯文件缓冲区in_file 1、数据在磁盘上、尚未读入内存的数据不在内存中下游的write_filter无法直接发送。因此必须返回 0让ngx_output_chain走拷贝流程——在ngx_output_chain_copy_buf中将文件数据先读到临时内存缓冲区再发送。第 2 步清除文件标记buf-in_file 0当缓冲区含内存数据通过第 1 步检查但sendfile被禁用时清除in_file标记。这是一种标记规范化——既然不能走 sendfile 路径文件偏移信息file_pos/file_last对下游已无意义。将in_file清零可以避免下游函数如write_filter被残留的文件标记误导。6 need_in_memory 强制内存约束if(ctx-need_in_memory!ngx_buf_in_memory(buf)){return0;}进入条件ctx-need_in_memory 1输出链上下文要求数据必须在内存中。ctx-need_in_memory字段src/core/ngx_buf.h中ngx_output_chain_ctx_sunsignedneed_in_memory:1;1 位位域。当为 1 时表示下游要求数据必须在内存缓冲区中而非文件引用。此约束比sendfile禁用更强——即使 sendfile 可用如果need_in_memory为真文件型缓冲区也必须先拷贝到内存。为什么need_in_memory优先级高于 sendfilesendfile 的启用/禁用影响的是数据如何到达 socket而need_in_memory影响的是数据在哪个媒介上。某些下游模块如 SSL 模块需要对数据进行加密必须在内存中操作数据sendfile 在此场景下不可行。因此即使 sendfile 全局启用、偏移未超限只要need_in_memory为真文件缓冲区就必须走拷贝流程。注意此检查的位置它位于 sendfile 相关检查[3][4][5]之后。如果 sendfile 未禁用且need_in_memory为真本检查仍然会触发返回 0。这是因为need_in_memory和sendfile是正交的约束维度——前者约束数据媒介后者约束传输方式。7 need_in_temp 可写性约束if(ctx-need_in_temp(buf-memory||buf-mmap)){return0;}进入条件ctx-need_in_temp 1输出链上下文要求数据在可写临时缓冲区中。ctx-need_in_temp字段src/core/ngx_buf.h中ngx_output_chain_ctx_sunsignedneed_in_temp:1;1 位位域。当为 1 时表示下游要求数据必须在可写temporary缓冲区中而不是只读的memory或mmap缓冲区。ngx_buf_t的三种内存类型对比字段含义可写性来源示例temporary:1堆分配的临时缓冲区可读可写ngx_create_temp_buf()分配的结果memory:1静态/只读内存只读不可修改硬编码字符串、只读共享内存段mmap:1内存映射文件只读不可修改ngx_http_static_module对静态文件的 mmap处理逻辑如果缓冲区的类型是memory或mmap只读且上下文要求数据可写返回 0。这两种缓冲区的内容不可修改如果下游需要对数据做变换如 SSL 加密、chunked 编码包装直接转发只读缓冲区会导致段错误或数据损坏。为什么temporary不触发此检查temporary缓冲区是可读可写的堆内存完全可以被下游安全地修改。因此只检查不可写的memory和mmap。设计意图need_in_temp和need_in_memory共同构成一对数据媒介约束need_in_memory要求数据在内存中排除纯文件引用need_in_temp要求数据在可写内存中排除只读内存引用最后一行return1;当缓冲区成功通过了全部六层检查返回 1——可以原样转发。这是最常见的路径对于典型的内存临时缓冲区temporary 1既不涉及文件、也没有只读约束几乎是无条件通过。架构视角为什么判定逻辑要独立成一个函数将是否可转发的判定提取为独立函数而非内联在ngx_output_chain中体现了以下设计考量复用避免代码重复职责单一ngx_output_chain负责调度积压 → 判定 → 拷贝 → 发送ngx_output_chain_as_is只负责判定。两者解耦后修改判定逻辑不需要理解整个输出链的控制流