一、功能概述

Hot reload 是 FluffOS 提供的一套 自动热更新机制——当磁盘上的 LPC 源文件发生修改时,驱动程序能够自动检测变化并重新编译受影响的程序,保留对象身份、变量状态和所有克隆体,开发者无需手动执行 update 命令即可看到修改效果。

这个功能由三层组成:

  1. 驱动层:两个编译期 master apply(inherit_program / include_file)
  2. 核心 efun:recompile_object()——原地热替换
  3. Mudlib 层:热重载守护进程(daemon),依赖图记录 + 文件变更轮询

二、为什么"文件改了"不够——依赖图问题

一个编译好的 LPC 程序不仅仅是它自己的源文件:

/widget.lpc
  └── inherit "/std/base"
        └── #include "/include/colors.h"

如果只修改了 /include/colors.h,仅重载 /std/base 是不够的——/widget 的字节码里绑定了旧的父程序。正确的热重载需要完整的依赖传递闭包:一个程序的字节码是由哪些文件构建的。


三、驱动层机制:两个编译期 Master Apply

inherit_program

mixed inherit_program(string from, string path, int priv);
  • 在编译 from 时,每遇到一条 inherit "path"; 语句被调用
  • priv 非零表示 private inherit
  • 返回 path 不变 = 保持默认行为;返回字符串 = 重定向继承路径;返回数组 = 提供内联源码;其他值 = 禁止继承

include_file

mixed include_file(string compiled, string from, string path);
  • 每遇到一个 #include 指令被调用
  • compiled 是正在编译的主文件,from 是包含该指令的文件(嵌套 include 时与 compiled 不同),path 是 include 的路径
  • 返回语义与 inherit_program 类似

关键约束:这两个 apply 运行在编译过程中间,不能触发另一次编译(不能 load_object / clone_object),只能记录并返回。


四、核心 efun:recompile_object()

int recompile_object(object master_copy);

这是整个热重载的核心驱动能力:

工作原理

  1. 从源文件重新编译程序
  2. 将新程序原地替换到 master copy 和所有活跃的克隆体
  3. 不销毁对象——对象身份完全保留(指针、名称、物品栏、阴影、交互状态、heart_beat、call_out 全部存活)
  4. 全局变量按名称迁移:先运行新程序的初始化器,然后每个同名变量保留旧值;新变量用初始化器,消失的变量被丢弃

约束条件

  • 不能传入克隆体(必须传 master copy)
  • 正在执行的对象不能热更新——不能自己重编译自己
  • replace_program() 挂起时不能重编译
  • 编译失败时对象保持原状

函数指针失效

更新前创建的 FP_LOCAL / FP_FUNCTIONAL 函数指针会变"陈旧"——调用时会抛出干净的错误而非执行错误索引的代码。efun 和 simul_efun 指针不受影响。


五、守护进程实现(参考实现)

testsuite/single/hot_reload.lpc 是一个完整的参考实现,约300行 LPC 代码。

数据结构

// 程序名 -> ([ 源文件路径 : 1 ]) — 自身源码 + 所有 #include 的文件
private mapping file_deps = ([]);
// 程序名 -> ([ 继承的程序名 : 1 ])
private mapping inherit_deps = ([]);
// 注册的监视列表,值为 WATCH_PLAIN 或 WATCH_KEEP_STATE
private mapping watched = ([]);
// 文件路径 -> ({ size, mtime }) 上次加载时的快照
private mapping snapshot = ([]);

核心流程

1. enable(interval)
   ├── 注册为 master 的 compile hooks
   └── 启动 call_out 轮询器

2. watch(prog)
   ├── 加载目标对象(触发编译,apply 记录依赖图)
   └── 快照所有依赖文件的 size + mtime

3. poll() / check_now()
   ├── 遍历所有 watched 程序
   ├── 计算每个程序的依赖传递闭包
   ├── 对比 size/mtime 检测变化
   └── 对变化的程序执行 reload()

4. reload(prog)
   ├── ancestors(prog) — 获取传递闭包中的所有祖先
   ├── 最深优先:先重编译祖父,再父,再子
   ├── recompile_object(ob) — 原地热替换
   └── 更新快照基线

依赖传递闭包计算

private mapping closure_files(string prog, mapping seen) {
    mapping out = ([]);
    if (seen[prog]) return out;
    seen[prog] = 1;
    string src = source_of(prog);
    if (src) out[src] = 1;
    if (file_deps[prog]) out += file_deps[prog];
    if (inherit_deps[prog])
        foreach (string parent in keys(inherit_deps[prog]))
            out += closure_files(parent, seen);
    return out;
}

递归收集:自身源文件 + 直接 include 的文件 + 所有继承的父程序的传递闭包。

变更检测

private int file_changed(string f) {
    mixed *now = stat_file(f);
    mixed *old = snapshot[f];
    if (!old) return now != 0;
    return !now || now[0] != old[0] || now[1] != old[1];
}

同时比较 size 和 mtime——mtime 精度只有一秒,同秒内两次编辑仅靠 mtime 会漏掉。

重载顺序:最深优先

private string *ancestors(string prog, mapping seen) {
    string *out = ({});
    if (!inherit_deps[prog]) return out;
    foreach (string parent in keys(inherit_deps[prog])) {
        if (seen[parent]) continue;
        seen[parent] = 1;
        out += ancestors(parent, seen) + ({ parent });
    }
    return out;
}

返回深度优先、最深在前的顺序。重编译一个子程序时会找到已加载的父程序——如果祖父已经变了但还没更新,子程序会把陈旧的祖父程序烘焙进去。

错误恢复

if (catch(reload(prog))) continue;

一个编译错误(比如编辑到一半的语法错误)不会中止整个轮询。快照保持不变,下一轮重试,文件修好后自愈。


六、三种重载模式

模式 调用方式 机制 变量状态 克隆体
默认(保持状态) watch(prog) 或 watch(prog, 1) recompile_object() 按名称迁移,包含 private 全部更新
不保持状态 watch(prog, 0) destruct() + load_object() 重置为初始值 不触及,需手动处理
协作式 对象定义了 hot_reload_state() destruct() + load_object() + 状态对 仅保留对选择的状态 不触及

协作式状态对

// 对象中定义:
mixed hot_reload_state() { return secret; }
void hot_reload_restore(mixed s) { secret = s; }

当对象定义了这对 apply 时,守护进程走 destruct+load 路径,让对象自己决定哪些状态需要保留。适合需要"故意丢弃某些状态"的场景。


七、recompile_object() vs reload_object()

特性 recompile_object() reload_object()
重新编译 是(从源文件) 否
保留变量 是(按名称迁移) 否(重置为初始值)
触及克隆体 是(所有克隆体一起更新) 否
调用 create() 否 是
保持对象身份 是 是
磁盘访问 是(重新读源文件并编译) 否

八、Simul_efun 和 Master 对象的热重载

recompile_object() 对 master 对象和 simul_efun 对象也有效:

  • Master 对象:缓存的 dispatch 表在替换期间重建
  • Simul_efun 对象:simul_efun 索引按名称保持稳定——其他程序中编译好的 SIMUL(n) 调用在重建后继续工作;被移除的 simul_efun 会报运行时错误

同样受"不能正在执行"的约束——必须从 call_out 或其他空闲上下文中调用。


九、Virtual Object 的热重载

Virtual Object(通过 master 的 compile_object() hook 物化的对象)更新方式相同:重编译针对的是底层真实文件的程序。守护进程的依赖记录以编译程序名为键,所以应通过底层文件来监视 virtual object。


十、测试覆盖

测试文件 testsuite/single/tests/applies/hot_reload.lpc 覆盖了以下场景:

  1. 依赖传递:修改 #include 的文件 → 被继承的父程序 → 被监视的子程序全部更新
  2. 自身源码修改:直接修改被监视程序的源文件
  3. 共享依赖:多个 watched 程序共享一个 include,修改后一次性全部更新
  4. 编译错误恢复:写入非法语法 → 重载失败 → 修复后自愈
  5. 多级继承链:祖父 → 父 → 子,最深优先重载顺序
  6. 正在执行的保护:被监视对象自身调用 check_now() 时触发"正在执行"保护,依赖记录不丢失
  7. 变量状态保持:recompile_object() 后 hits 计数器保留,新变量用初始值
  8. 克隆体跟随更新:所有克隆体运行新代码,各自保留自己的状态
  9. 协作式状态对:hot_reload_state() / hot_reload_restore() 控制哪些状态保留
  10. 不保持状态模式:watch(prog, 0) 重置为初始值,克隆体需手动处理

十一、使用示例

// 启动守护进程
object d = load_object("/daemon/hot_reload");
d->enable(2);    // 每 2 秒轮询一次

// 注册监视
d->watch("/obj/widget");           // 默认:保持状态
d->watch("/obj/sword", 0);         // 不保持状态
d->watch("/obj/armor");            // 协作式(如果对象定义了 hot_reload_state)

// ... 在磁盘上编辑 /include/colors.h ...

// 在下一个轮询周期内自动生效:
// 1. 守护进程检测到 colors.h 变化
// 2. 计算依赖闭包:colors.h → base → widget
// 3. 最深优先重载:base(colors.h 在其闭包中),然后 widget
// 4. 所有 widget 克隆体运行新代码,各自状态不变

// 手动触发一次检查
d->check_now();

// 停止
d->disable();

十二、注意事项

  1. 只有在守护进程注册后编译的程序才有完整的依赖记录——所以 watch() 会自己加载目标
  2. apply 中不能编译——只能记录并返回,加载从 check_now() / poll() 中做
  3. 函数指针会失效——热更新后需要重建
  4. 正在执行的对象不能更新——守护进程的 call_out 轮询天然在空闲时运行
  5. include 解析——守护进程的 resolve_include() 需要匹配编译器的实际搜索逻辑(绝对路径、相对路径、include 目录)
  6. recompile_object() 不能更新继承它的程序——子程序仍然绑定到旧的父程序,需要单独更新(先父后子,守护进程自动处理)