一、功能概述
Hot reload 是 FluffOS 提供的一套 自动热更新机制——当磁盘上的 LPC 源文件发生修改时,驱动程序能够自动检测变化并重新编译受影响的程序,保留对象身份、变量状态和所有克隆体,开发者无需手动执行 update 命令即可看到修改效果。
这个功能由三层组成:
- 驱动层:两个编译期 master apply(
inherit_program/include_file) - 核心 efun:
recompile_object()——原地热替换 - 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);
这是整个热重载的核心驱动能力:
工作原理
- 从源文件重新编译程序
- 将新程序原地替换到 master copy 和所有活跃的克隆体
- 不销毁对象——对象身份完全保留(指针、名称、物品栏、阴影、交互状态、heart_beat、call_out 全部存活)
- 全局变量按名称迁移:先运行新程序的初始化器,然后每个同名变量保留旧值;新变量用初始化器,消失的变量被丢弃
约束条件
- 不能传入克隆体(必须传 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 覆盖了以下场景:
- 依赖传递:修改
#include的文件 → 被继承的父程序 → 被监视的子程序全部更新 - 自身源码修改:直接修改被监视程序的源文件
- 共享依赖:多个 watched 程序共享一个 include,修改后一次性全部更新
- 编译错误恢复:写入非法语法 → 重载失败 → 修复后自愈
- 多级继承链:祖父 → 父 → 子,最深优先重载顺序
- 正在执行的保护:被监视对象自身调用
check_now()时触发"正在执行"保护,依赖记录不丢失 - 变量状态保持:
recompile_object()后hits计数器保留,新变量用初始值 - 克隆体跟随更新:所有克隆体运行新代码,各自保留自己的状态
- 协作式状态对:
hot_reload_state()/hot_reload_restore()控制哪些状态保留 - 不保持状态模式:
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();
十二、注意事项
- 只有在守护进程注册后编译的程序才有完整的依赖记录——所以
watch()会自己加载目标 - apply 中不能编译——只能记录并返回,加载从
check_now()/poll()中做 - 函数指针会失效——热更新后需要重建
- 正在执行的对象不能更新——守护进程的
call_out轮询天然在空闲时运行 - include 解析——守护进程的
resolve_include()需要匹配编译器的实际搜索逻辑(绝对路径、相对路径、include 目录) recompile_object()不能更新继承它的程序——子程序仍然绑定到旧的父程序,需要单独更新(先父后子,守护进程自动处理)