心智模型：代、租约与零包装透传

本章导读

3.1 引入：三个疑问

第一次接触"运行时编译 C"的人，通常会问出三个直击要害的问题：

• 我的代码什么时候变成机器码？——启动时和每次热重载时，由内嵌 TCC 编译为原生代码，之后的执行速度与你预编译的 C 一致（routebench 实测与 Go 同档）。
• 谁拥有连接、监听、定时器这些资源？——宿主拥有。脚本只在回调里"借用"它们。
• 改代码的瞬间，正在处理的请求怎么办？——新旧两代代码并存，老请求由老代码服务到结束，这就是本章的主角。

第 2 章日志里的 script loaded ... gen 1 已经暴露了答案的入口：代（generation）。下面把它讲透。

3.2 三个概念

概念一：generation（代）

每完成一次脚本装载——无论是启动还是热重载——就产生一个新代。一代 = 一份完整的脚本运行时：编译产物、静态变量、ServiceInit 建立的一切。所以重启后看到 gen 2 并不奇怪：代的编号在进程内单调递增，重启只是"没有旧代在场的一次换代"。

概念二：lease（租约）

每个进入处理的请求 / 连接 / 定时器，都会对"它开始工作时所在的那一代"取一个租约（引用）。租约保证了：只要还有工作在旧代上未完成，旧代的代码与数据就不会被释放。这就是"改代码不断线"的机制本质——不是延迟销毁的技巧，而是引用计数的语义保证。

概念三：引用归零回收

旧代的引用归零后，由专职的 GC 线程按固定顺序析构：ServiceUnit（脚本清理）→ TCC 状态 → 驱动运行时 → 配置树。XServer 的测试套件里有专门的三循环 8080↔8081 换代实测：全部旧代回收，零泄漏、零崩溃。你不需要写任何 GC 代码——但你需要知道它存在，才能理解第 28 章的状态交接为什么那样设计。

3.3 分工与透传

宿主管什么，脚本管什么

零包装透传

多数框架会把连接、请求包装成框架对象，你在框架的抽象里工作。XServer 刻意不包装：回调拿到的 XS_HttpReq 是一组 xrt 原生指针的视图——传输层裸指针、解析后的请求头、分帧状态机。你可以直接调用 xrt 的 3,030 个 API 操作它们，没有隐藏层、没有适配损耗。

"零包装"是自由也是责任：视图不能存到回调之外（见常见错误①），但也没有框架魔法挡在你和协议之间。

3.4 示例：看见代

代不需要特殊工具观察——启动日志本身就是证据。回顾第 2 章的实机输出：

[xs] engine started, workers=12
[xs] script loaded: .../main.c (2.6 KB gen 1)   /* ← 第一代诞生：编译 2.6KB 源码，编号 1 */
[demo] database opened: .../db\main.db              /* ← gen1 的 ServiceInit 在跑 */

刚才发生了什么：TCC 把 2.6KB 源码编译为原生代码，创建"第 1 代"脚本运行时；随后 [demo] 前缀的日志证明应用自己的 ServiceInit 已在这代上执行。当你在第 2 章练习里修改 route.h 并重启，日志变成 gen 2——一个新代诞生，旧进程退出，没有旧代需要回收。而热重载（卷四）做的是同一件事，但旧代还在服务：新代发布后，旧代等自己的最后一个租约归还。

3.5 契约

• 线程线：脚本回调在引擎 worker 线程执行（workers=12 意味着回调可能并发）；ServiceInit / ServiceSwap 在装配 / reload 控制线程；ServiceUnit 在 GC 线程。跨线程共享状态要自己负责同步。
• 所有权线：回调参数里的视图（XS_HttpReq、头指针、消息视图）只在回调栈内有效；想保存先拷贝。资源（连接、监听、定时器）归宿主，脚本只借用。
• 生命周期线：退役后的代不再接受新请求；静态变量按代隔离——换代即全新的静态状态，跨代传递必须走 ServiceSwap（第 28 章）。

常见错误

static xhttp1head* G_Head;
XS_RequestResult RequestProc(XS_HttpReq* pReq)
{
    G_Head = pReq->head;  /* 回调外再读 → UAF */

/* 在回调内取走需要的值 */
const char* sUA = ...;   /* 拷贝字符串 */
G_iCount++;              /* 值可以带出，指针不行 */

/* "脚本崩了宿主还能活" —— 不成立
 * 野指针一样打穿整个进程 */

/* devfile 只放可信运维维护的代码；
 * 需要隔离的能力放到独立进程 */

void ServiceInit(XS_HostInfo* pHost)
{
    BigIndexLoad();   /* 阻塞 8 秒 */

/* 轻初始化 + 首请求惰性加载，
 * 或后台线程构建、就绪位发布 */

编程练习