前言
这本书完整讲解 j8:一个用 Rust 从头写的 JavaScript 引擎,照着 V8 的分层来—— JS 先编成与 V8 Ignition 逐字节一致的字节码,由执行器解释,热函数和热循环交给推测式 JIT 出 x86-64 机器码;堆是 paragc。
安装 dune
curl -fsSL https://j8.app238.com/install | bash # macOS、Linux
powershell -c "irm https://j8.app238.com/install.ps1 | iex" # Windows
npm install -g @jabberwocky238/dune # 有 npm 的地方
详见安装 dune。
怎么读
| 你想…… | 从这里读 |
|---|---|
| 先跑起来看看 | 快速开始 |
| 理解整体设计 | 总体架构,然后按「引擎内部」顺序读 |
| 用 j8 搭自己的运行时 | 搭一个宿主 起的「嵌入 j8」部分 |
| 用 dune 跑脚本、跑 npm 包 | dune 与 dunx |
| 给 j8 贡献代码 | 代码约定、test262 与测试 |
约定
- 路径都相对 j8 仓库根,如
crates/j8executor/src/ic.rs。 - 文中「V8」指 V8 引擎本身;j8 对齐的版本是 rusty_v8 152.2.0 里的 V8 15.2.124。
- 本书描述的是仓库 main 分支(2026 年 11 月)。crates.io 上的 j8 0.4.0 早于 V8 字节码与推测式 JIT,下一个版本才包含它们。
- 数字(test262 通过数、基准耗时)写的是本书编写时的状态,以仓库为准。
本书源码在仓库的 mdbook/ 目录,发现错误欢迎直接提 PR。
j8 是什么
j8 是用 Rust 从头写的 JavaScript 引擎。除了解析器用 oxc,从字节码、执行器、JIT 到垃圾回收都是自己写的, 下面没有 C++ 引擎。
它照着 V8 的分层来:
JS 源码 ─ oxc 解析 ─ j8compiler ─▶ V8 Ignition 字节码 ─ j8executor 解释 ─┐
├─▶ 结果
热函数 / 热循环 ─ j8jit 推测式编译 ─▶ 机器码 ─────┘
设计取向
| 🦀 全 Rust | 解析用 oxc,其余都是自己的代码。 |
| 🧱 字节码先行 | 不设 AST 解释层:所有 JS(包括 eval、Function)都先编成字节码再跑。 |
| 🔣 V8 的字节码 | 字节码表、操作数编码、寄存器与帧布局都与 V8 Ignition 逐字节一致,表格直接从 V8 头文件生成。 |
| 🧬 推测式 JIT | 依据内联缓存收集的反馈,把字节码建成推测性的 SSA 图:内联、逃逸分析、循环不变量外提、OSR、去优化。 |
| ♻️ paragc 堆 | Immix 式块 / 行堆,年轻回收 + 老对象引用计数,标记与清扫并行;'gc 品牌生命周期在编译期保证句柄不逃逸。 |
| 🚫 没有全局状态 | 不用 static 与 'static;后台任务借用调用方的数据,多个 Isolate 共用一个线程池。 |
| 🧩 可嵌入 | #[j8::class] / #[j8::object] / #[j8::function] 一行把 Rust 类型绑成 JS,j8::runtime! 拼出一个运行时。 |
主线:test262
j8 的主线是 test262 通过率。基线 tests/test262.passing 当前是 42,443 条用例
(非严格 + onlyStrict;不含 Temporal、intl402 等,见路线图),每次提交都要零回归,开着 JIT 也跑同一份基线。
仓库里有什么
| 目录 | 内容 |
|---|---|
crates/ | 引擎本身,十几个 crate(见总体架构) |
src/ | 门面包 j8:按 feature 汇总各 crate,导出绑定宏 |
dune/ | 对标 Node 与 Bun 的运行时,附带 dunx(对标 npx / bunx) |
samples/ | 样例宿主与工具:workerd、jumpheap、j8bcdbg、三组基准 |
tests/ | 集成测试与 test262 运行器 |
tools/ | v8bytecodes.py:从 V8 头文件生成字节码表 |
mdbook/ | 本书 |
发布
全部 crate 发在 crates.io:门面包 j8(0.4.0)按 feature 选组件,子 crate(j8bytecode、j8compiler、j8executor ……)
也单独发布。dune 以 j8dune 的名字发布(dune 已被占用)。许可证 MIT。
安装 dune
dune(连同跑包的 dunx)每个平台一个预编译的可执行文件,挂在每次 j8 的 GitHub Release 上,同时发到 npm。
macOS 和 Linux
curl -fsSL https://j8.app238.com/install | bash
脚本按本机选包(x64 或 arm64;Linux 上分 glibc 和 musl;Rosetta 下装原生版),用 Release 里的 SHA256SUMS 校验,
把 dune 和 dunx 链接放进 ~/.dune/bin,再把这个目录写进 shell 启动文件的 PATH(bash、zsh 或 fish)。
装指定版本:
curl -fsSL https://j8.app238.com/install | bash -s v0.4.0
Windows
powershell -c "irm https://j8.app238.com/install.ps1 | iex"
把 dune.exe 和 dunx.exe 装到 %USERPROFILE%\.dune\bin 并加进用户 PATH。装指定版本:
& ([scriptblock]::Create((irm https://j8.app238.com/install.ps1))) -Version v0.4.0
npm
npm install -g @jabberwocky238/dune
npm 只装符合本机的平台包(@jabberwocky238/dune-linux-x64、@jabberwocky238/dune-darwin-arm64、
@jabberwocky238/dune-win32-x64 ……),postinstall 脚本把其中的二进制放到位,dune 启动时不经过 Node。
Cargo
cargo install j8dune # crates.io 上 dune 已被占用;然后 ln -s dune ~/.cargo/bin/dunx
升级
dune upgrade # 最新版
dune upgrade --tag v0.4.0
dune upgrade 从 GitHub 下载本平台的 Release、校验后替换自己(dunx 是副本而不是链接时一起换)。
环境变量
| 变量 | |
|---|---|
DUNE_INSTALL | 安装脚本的安装根目录(缺省 ~/.dune,二进制在其 bin/) |
DUNE_RELEASES | 安装脚本从哪下载 Release(缺省 https://github.com/0x00-Community/j8/releases) |
平台
| 平台 | Release 包 | JIT |
|---|---|---|
| Linux x64(glibc 2.17+ / musl) | dune-linux-x64.tar.gz / dune-linux-x64-musl.tar.gz | 有 |
| Linux arm64(glibc 2.17+ / musl) | dune-linux-arm64.tar.gz / dune-linux-arm64-musl.tar.gz | 无 |
| macOS x64 / arm64 | dune-darwin-x64.tar.gz / dune-darwin-arm64.tar.gz | 仅 x64 |
| Windows x64 / arm64 | dune-win32-x64.tar.gz / dune-win32-arm64.tar.gz | 无 |
JIT 只在 Unix 上出 x86-64 机器码;其他平台 --jit 打一行提示后用解释器跑。
卸载
删掉 ~/.dune(或 %USERPROFILE%\.dune)和脚本写进 shell 启动文件的几行(# dune 标记),或者
npm uninstall -g @jabberwocky238/dune。
快速开始
作为库
cargo add j8 # 缺省 feature `runtime`:执行器 + 内建对象 + 标准平台
cargo add j8 --features jit # 再加 x86-64 JIT(x86-64 Unix 和 Windows)
cargo add j8 --no-default-features --features compiler # 只要 JS ⇒ 字节码
最小的求值:
use j8::builtins::Builtins;
use j8::executor::Executor;
use j8::frame::{CreateParams, Isolate, Source};
use j8::platform::DefaultPlatform;
let platform = DefaultPlatform::default();
let mut isolate = Isolate::new(&platform, CreateParams::default());
let mut executor = Executor::default();
let cx = isolate.enter(|scope| scope.persist(scope.context(&Builtins)));
let result = isolate.run(&mut executor, &cx, &Source { text: "1 + 2 * 3", file: "a.js" })?;
真正的宿主一般不直接摆弄 Isolate,而是用 j8::runtime! 声明一个运行时,见搭一个宿主。
feature 一览
| feature | 带上什么 |
|---|---|
runtime(缺省) | executor + builtins + platform |
bytecode | j8::bytecode:字节码定义、编码 / 解码 |
compiler | j8::compiler:JS ⇒ 字节码(含 bytecode) |
executor | j8::executor:字节码执行器(含 compiler) |
builtins / platform | 内建对象 / 标准库平台 |
jit | j8::jit:JIT(x86-64 Unix 和 Windows,含 executor) |
json | j8::Json<T>:经 serde 以 JSON 形状过界的 Rust 值 |
napi | j8::napi:Node-API |
taskqueue / lockfree | 任务队列 / 无锁基础件 |
full | 以上全部 |
用 dune 跑 JS
curl -fsSL https://j8.app238.com/install | bash # 或 npm i -g @jabberwocky238/dune,见「安装 dune」
dune app.js # Node 兼容层(缺省)
dune --web app.mjs # 只要 Web 标准接口
dune -p '[1, 2, 3].map(x => x * 2)'
dune --jit bench.js # 打开 JIT
dune # REPL
dunx cowsay hello # 跑 npm 包里的可执行文件
详见 dune 与 dunx。
从源码
git clone https://github.com/0x00-Community/j8 && cd j8
cargo build --release
git submodule update --init # 拉 test262
cargo test --release --test test262 # 跑回归基线
cd dune && cargo run --release -- examples/node.js
cd samples/j8bcdbg && cargo run -- compile -e 'let s = 0; for (let i = 0; i < 10; i++) s += i; s'
dune/ 与 samples/* 各自成包、不在 workspace 里,像嵌入方一样按版本依赖 crates.io 上的 j8。
总体架构:一段 JS 的一生
crate 分层
j8(门面:按 feature 汇总、导出绑定宏与 runtime!)
│
┌──────────────┬───────────────┬─────┴──────┬─────────────┬────────────┐
j8jit j8executor j8builtins j8platform j8binding j8napi
│ ╲ │ ╲ │ │ │ │
│ ╲ j8compiler ╲ │ │ │ │
│ ╲ │ ╲ │ │ │ │
│ └── j8bytecode ──┴───────┼────────────┼─────────────┼────────────┘
│ │ │ │
└───────────────────────── j8framework ──────┴─────────────┘
│
paragc · j8taskqueue · j8lockfree · j8macros
| crate | 职责 |
|---|---|
j8framework | 核心框架层:定义各层要实现的 trait(Platform、Engine、Invoke、Intrinsics)和共用的结构体(Isolate、Scope、Agent、Context / Realm、Value、对象模型、事件循环)。JS 运算语义挂在 Agent 上。不依赖任何其他层 |
j8bytecode | 字节码定义,与 V8 Ignition 逐字节一致;依赖根,不依赖其他 j8 crate |
j8compiler | JS ⇒ 字节码(oxc 解析,代码生成照 V8 的 BytecodeGenerator) |
j8executor | 字节码执行器:实现 Engine,带内联缓存、分片执行与 JIT 钩子 |
j8jit | 推测式 JIT(x86-64 Unix 和 Windows):实现执行器的 Tier |
j8builtins | 标准内建对象:实现 Intrinsics |
j8platform | Platform 的标准库实现:线程池、时钟、模块加载 |
j8binding | Rust ⇄ JS 绑定的运行时(FromJs / IntoJs、宿主对象) |
j8napi | Node-API:原生插件链接的 C 接口 |
j8taskqueue | 无锁数据流任务队列(no_std),每个事件循环就是一个队列 |
j8lockfree | 手写的无锁基础件(no_std) |
j8macros | 过程宏:字节码表生成、堆类型、绑定宏 |
依赖方向的规矩:各层只依赖 j8framework(执行器另外依赖编译器与字节码,JIT 依赖执行器),j8framework
不依赖任何层,只依赖 paragc 与两个基础件。所以内建对象不知道执行器,平台不知道内建对象——它们都只对着
j8framework 里的 trait 写。
trait 是接缝
j8framework 定义接口、各层实现,宿主把它们拼起来:
| trait | 谁实现 | 干什么 |
|---|---|---|
Platform(父 trait Pool) | j8platform::DefaultPlatform、宿主自己的平台 | 线程池、时钟、console.log 输出、模块加载 |
Intrinsics | j8builtins::Builtins | 往新 Realm 装全局对象与内建构造器 |
Engine | j8executor::Executor | 执行入口:eval,可续跑的 start / resume |
Invoke | 执行器 | 内建函数回调 JS(map 的回调、getter……) |
Tier | j8jit::Jit | 执行器问「这个函数 / 循环要不要编」 |
一段 JS 的一生
以 dune -p 'let s = 0; for (let i = 0; i < 1e6; i++) s += i; s' 为例:
- 宿主建环境。 dune 用
j8::runtime!声明的运行时在一个事件循环线程上建Isolate(一个 GC 堆)、Executor、Context(Builtins装好全局对象),跑完 JS 序言(搭一个宿主)。 - 编译。 执行器拿到源码,交给
j8compiler:oxc 解析并做语义检查(早期错误在这里报SyntaxError), 作用域分析决定每个变量放寄存器、上下文槽还是全局对象,代码生成器照 V8 的BytecodeGenerator出字节码, 结果是j8bytecode::Module(一组SharedFunction,每个带BytecodeArray)。 多个运行时跑同样的序言时,CodeCache让同一份源码只编译一次(执行器)。 - 解释。 执行器把字节码解码成「线程化代码」:每条指令带着跑它的处理函数,处理函数之间直接跳转。 属性访问经内联缓存按 shape 命中。每跑一千来条指令检查一次事件队列,每一万条让出一次(分片),让 GC 有机会回收。
- 升层。 循环每次往回跳都给 profiler 计数。过阈值后执行器问
Tier:JIT 依据内联缓存的反馈把函数建成 推测性 SSA 图(s、i猜成 int32),优化后直接出 x86-64 机器码,从循环头切进去跑(OSR)。 - 去优化。 推测落空(比如
s超过 int32),守卫跳到冷路径,j8_deopt按记下的帧状态重建解释器帧, 解释器接着跑;JIT 留下提示,下次编译那里改用 double。 - 结束。 结果是一个
Value(一个 NaN-boxing 的机器字),宿主拿到Global句柄,ToString后打印。 事件循环里没有剩下的宿主任务,进程退出。
接下来的章节按这条路逐段展开:字节码 → 编译器 → 执行器 → JIT,然后是它们共同站着的框架层、对象模型与堆。
字节码:与 V8 Ignition 逐字节一致
crates/j8bytecode 只定义字节码,JS ⇒ 字节码归 j8compiler。它是 j8 的依赖根:不依赖任何其他 j8
crate(只用 j8macros 过程宏生成表格)。
为什么用 V8 的字节码
j8 早期有自己的字节码(由一份 insn.json 生成)。后来整套换成了 V8 Ignition 的字节码,逐字节一致:
- 字节码设计是 V8 多年调出来的结果:累加器式、短
Star、按参数个数分的Call变体、反馈槽……照搬比重新发明可靠; - 能和 V8 对拍:同一段 JS,
j8bcdbg compile的输出可以直接和d8 --print-bytecode比; - JIT 的推测依据(反馈槽的种类与编号)也照 V8 排,读起来有现成的参照。
当前对齐 V8 15.2.124(rusty_v8 152.2.0 里的那一版)。
表格从 V8 头文件生成
V8 检出 ─ tools/v8bytecodes.py ─▶ crates/j8bytecode/v8.json ─ j8macros::bytecodes! ─▶ Rust 类型
v8.json 的来源是 V8 的 src/interpreter/bytecodes.h、bytecode-operands.h、interpreter-intrinsics.h、
src/runtime/runtime.h、function-kind.h、feedback-vector.h 等头文件,包括:
| JSON 键 | 生成什么 |
|---|---|
bytecodes | Bytecode(repr(u8),V8 的编号,共 215 个)与每个字节码的 operand_types()、implicit_register_use() |
operand_types | OperandType、OperandTypeInfo |
implicit_register_use | 是否读 / 写 / 破坏累加器、是否写短 Star |
runtime / intrinsics | CallRuntime / InvokeIntrinsic 的函数编号 |
function_kinds、feedback_slot_kinds、scope_types、variable_modes | 对应的 V8 枚举 |
⛔ 手改 JSON 或生成的表格:要换 V8 版本,就拿新检出重新跑 tools/v8bytecodes.py。
编码
和 V8 一样:
- 一条指令是一个字节码字节,后面跟小端的操作数;
- 可放宽的操作数缺省占 1 字节,前面加
Wide/ExtraWide前缀时占 2 / 4 字节(OperandScale); 固定大小的操作数总是占它的大小; Encoder为每条指令选最小的放宽,Decoder把字节读回指令。
OperandScale::for_signed / for_unsigned 对应 V8 的 ScaleForSignedOperand / ScaleForUnsignedOperand。
寄存器与帧布局
累加器式寄存器机:大多数运算的结果进隐式的累加器 acc,二元运算是 acc = reg op acc。
寄存器操作数是它相对帧指针的槽号(Register,V8 的 x64 解释器帧,InterpreterFrameConstants):
fp + 2 … 参数(第一个是 receiver,即 this)
fp + 1 调用者 pc
fp + 0 调用者 fp
fp − 1 上下文
fp − 2 闭包(当前函数)
fp − 3 实参个数
fp − 4 字节码数组
fp − 5 字节码偏移
fp − 6 反馈向量
fp − 7 … r0, r1, r2 …
所以反汇编里看到的 a0、a1 是参数,r0 起是局部寄存器。Star0 … Star15 是十六个「短 Star」:
不带操作数、直接写 r0 … r15 的单字节指令(Bytecode::short_star)。
编译产物的形状
照 V8 的对象来(function.rs):
| j8 | V8 | 内容 |
|---|---|---|
Module | — | 一份源码编出的全部函数,第一个是顶层 |
SharedFunction | SharedFunctionInfo | 名字、种类(FunctionKind)、是否严格、length、形参个数、作用域信息、字节码 |
BytecodeArray | BytecodeArray | 代码字节、常量池、异常处理表、参数 / 寄存器个数、反馈槽种类、new.target / 生成器寄存器 |
Constant | 常量池项 | 字符串、数、作用域信息、对象 / 数组 / 类的样板、模板对象…… |
HandlerEntry | 处理表项 | [start, end) 范围、处理位置、上下文寄存器、捕获预测 |
Flag8 操作数(如 CreateClosureFlags、CreateObjectLiteralFlags)的位布局照 V8 的 bytecode-flags-and-tokens.h。
看一眼真实的字节码
function add(a, b) { return a + b; }
let s = 0;
for (let i = 0; i < 10; i++) s = add(s, i);
s
j8bcdbg compile 的输出(格式照 V8 的 --print-bytecode):
== #0 NormalFunction params 1 regs 5
@ 0 LdaConstant [0]
@ 2 Star1
@ 3 Mov <closure>, r2
@ 6 CallRuntime #375, r1, #2 ; DeclareGlobals:声明顶层函数 add
@ 11 LdaZero
@ 12 StaCurrentContextSlot #2 ; let s = 0(顶层 let 在脚本上下文里)
@ 14 LdaZero
@ 15 Star1 ; i = 0,放寄存器 r1
@ 16 LdaSmi [10]
@ 18 TestLessThan r1, #0 ; i < 10,#0 是反馈槽
@ 21 JumpIfFalse [28]
@ 23 LdaGlobal [1], FBV[0] ; 读全局 add
@ 26 Star2
@ 27 LdaCurrentContextSlot #2
@ 29 Star3
@ 30 Ldar r1
@ 32 Star4
@ 33 CallUndefinedReceiver2 r2, r3, r4, FBV[2]
@ 38 StaCurrentContextSlot #2
@ 40 Ldar r1
@ 42 Inc FBV[4]
@ 44 Star1
@ 45 JumpLoop [29], [0], FBV[5] ; 回跳:OSR 的入口
@ 49 LdaCurrentContextSlot #2
@ 51 Star0
@ 52 Return
== add NormalFunction params 3 regs 0
@ 0 Ldar a1
@ 2 Add a0, #0
@ 5 Return
几个值得注意的地方:
CallUndefinedReceiver2:两个实参、receiver 是undefined的调用,有专门的字节码;- 每个运算都带反馈槽(
#0、FBV[2]):执行器在这里记录见过的类型与 shape,JIT 据此推测; JumpLoop是唯一往回跳的指令,执行器在这里计数,热了就问 JIT 要不要从这里切进机器码(OSR)。
测试
tests/v8.rs 解码 V8 15.2.124 用 --print-bytecode 打印的 738 条指令,逐条核对名字、长度和寄存器操作数。
编译器:JS ⇒ 字节码
crates/j8compiler 把 JavaScript 编成 V8 字节码(j8bytecode::Module),用 oxc 解析。
所有 JS 运行前都先过这里——脚本、ES 模块、动态代码(eval、Function)。j8 不设 AST 解释层。
源码 ─ oxc 解析 + 语义检查 ─▶ AST ─ 作用域解析 ─▶ 代码生成(BytecodeGenerator)─ BytecodeArrayBuilder ─▶ Module
文件
| 文件 | 内容 | 照 V8 的 |
|---|---|---|
scope.rs | 每层作用域声明了哪些名字(Decls),哪些绑定被内层函数捕获(Resolver) | Scope 分析 |
compiler.rs | 作用域、函数、语句 | BytecodeGenerator |
expr.rs | 表达式(结果总是留在 acc) | BytecodeGenerator |
builder.rs | 发射一个函数的字节码 | BytecodeArrayBuilder / BytecodeArrayWriter / BytecodeRegisterAllocator / ConstantArrayBuilder / HandlerTableBuilder / FeedbackVectorSpec |
解析与早期错误
oxc 解析出 AST,再用 oxc_semantic 做语义检查。规范要求的早期错误(重复声明、非法的 break 目标、
严格模式下的禁用写法……)在这里报 SyntaxError;正则字面量也在解析时校验。j8 还不支持的写法报
Error::Unsupported,带 文件:行:列。
变量放哪里
和 V8 一样,变量按「谁会看到它」决定位置:
| 变量 | 位置 | 字节码 |
|---|---|---|
| 函数自己的、没被捕获的变量 | 寄存器(参数是 a0 …,this 是 receiver) | Ldar / Star |
| 被内层函数捕获的变量 | 上下文槽:每个有捕获的作用域层一个上下文 | LdaCurrentContextSlot / LdaContextSlot |
脚本顶层的 var / 函数 | 全局对象的属性(DeclareGlobals 声明) | LdaGlobal / StaGlobal |
脚本顶层的 let / const / class | 脚本上下文(跨脚本共享,不挂在全局对象上) | LdaCurrentContextSlot … |
with 体内、或可能被宽松模式直接 eval 看到的名字 | 按名字查 | LdaLookupSlot |
预扫和代码生成用同一份 Decls,保证两边的名字解析一致。for (let …) 每一轮复制一份上下文,闭包各拿各的那一轮。
暂时性死区(TDZ):let / const / class 在初始化之前读写要抛 ReferenceError。能在编译期证明已经初始化的使用处,
检查直接省掉。
指令选择
builder.rs 按 V8 的方式挑字节码:
Star到 r0 … r15 用单字节的短Star,0 用LdaZero,小整数用LdaSmi;- 调用按参数个数和 receiver 选
CallUndefinedReceiver0/1/2、CallProperty0/1/2、CallAnyReceiver……; - 内建的固有操作走
InvokeIntrinsic,运行时函数走CallRuntime; - 前向跳转先占位、再回填;偏移装不进操作数时,用一个预留的常量池项撑着(
JumpConstant系列); - 寄存器按栈的次序分配,反馈槽按出现顺序编号。
异常与 finally
try 块在处理表里登记 [start, end) 范围与处理位置;抛出时执行器查表,找不到就展开到调用者。
finally 用「完成类型 + 值」一对寄存器实现:穿过它的 return / break / continue 先绕进 finally,再按记下的
完成类型接着走(ContinuationToken)。
动态代码
- 间接 eval /
Function:当作新脚本编译,跑在全局作用域。 - 直接 eval:
Compile::compile_direct按调用点的作用域表编译。调用点能看到的每个绑定都进环境, eval 代码接在调用点的环境上跑;宽松模式下 eval 里的var/ 函数落进调用它的函数(已有同名绑定就复用, 否则进一个像with一样按名字查的 eval 变量对象);词法冲突报SyntaxError。 - 生成器 / async 函数构造器:
GeneratorFunction等同理,编出对应FunctionKind的函数。
用法
宿主一般不直接调编译器,由执行器自己调用:
use j8compiler::Compile;
use j8framework::{CodeKind, Source};
let module = j8bytecode::Module::compile(&Source { text: "1 + 2", file: "a.js" }, CodeKind::Script)?;
let (module, info) = j8bytecode::Module::compile_module(&source)?; // ES 模块,连同导入 / 导出信息
执行器:解释字节码
crates/j8executor 执行 V8 字节码,实现 j8framework::Engine。它目前是 j8 的最后一层:固定带着
编译器,脚本、模块、eval / Function 都先编成字节码再跑。
一个 Executor 服务一个 isolate
Executor 持有加载过的函数(Loaded),堆上的闭包按 FuncId 指回来。所以一个 executor 只服务一个 isolate;
多个 isolate 要共享编译结果,用 CodeCache(见下文)。
帧与寄存器
- 显式帧栈:JS 调 JS 不靠宿主(Rust)递归,执行器自己维护帧栈。调用深度上限 10,000(含宿主函数里重入的 JS),
超了抛
RangeError。 - 一个寄存器文件:全部帧共用。一帧占其中一段:receiver、形参、r0 起的寄存器。字节码里的寄存器操作数是 V8 的帧槽号(r0 是 −7、receiver 是 +2、上下文 −1、闭包 −2),加载时映射到这段上。
- 上下文就是堆上的
Env:寄存器与累加器在CreateFunctionContext/PushContext/PopContext之间以Value::context字携带它们。
线程化代码
函数加载时字节码只解码一次,每条解码后的指令带着跑它的处理函数(threaded.rs 的 Handler):
handler(cx, pc, regs, acc) ─ 做完 ─▶ 直接跳到下一条指令的 handler
处理函数把热状态(当前指令、本帧 r0 指针、累加器)放在机器寄存器里传。用 nightly 编译器时是有保证的尾调用
(become,build.rs 探测到 nightly 就打开 cfg(tail_calls));稳定版编译器上则返回到 Executor::run 的循环,
由它调下一个。
热门字节码有自己的处理函数;其余字节码、以及热门字节码离开快路时,经 slow 同步状态后走通用的 Executor::step。
帧变化(调用、返回)、异常、执行结束时离开处理函数链。
内联缓存
ic.rs:每个 GetNamedProperty / SetNamedProperty / DefineNamedOwnProperty 点一个缓存。
- 只按 shape 地址识别:GC 会搬对象,缓存里不能存对象指针;另存一个
Weak,防止认出的地址被别的 shape 复用。 - 字典模式的 shape 原地修改(地址不变、内容变了),所以从不缓存。
- 读:自有数据属性,或往上 1 到
DEPTH层原型上的数据属性(路上每一层的 shape 都检查)。 - 写:自有的可写数据属性。
- 加属性:旧 shape ⇒ 新 shape;赋值还要检查原型链每一层的 shape(没有谁后来加了同名 setter 或只读属性)。
这些缓存同时就是 JIT 的类型反馈:JIT 按缓存见过的 shape 推测,生成 shape 守卫加直接的槽读写。
分片执行
Engine::eval 拿 &mut Isolate,自己分片进入:每片最多一万条指令,停下时把执行状态挂到根上、让堆回收一段,
再接着跑。执行环境用 ContextRoot 跨片保留。每 1024 条指令检查一次预算与终止请求——在事件循环里,这就是检查
任务队列的时机(事件循环)。
已知偏差:宿主函数里重入的 JS(如 map 的回调)在当前片里跑完,期间不回收。Function.prototype.call / apply
由执行器直接展开成普通调用,不算重入。
异常
查字节码的处理表:抛出时在本帧找覆盖当前偏移的处理项,找到就恢复上下文寄存器、跳到处理位置;找不到就展开到调用者。
生成器与 async
生成器、async 函数、async 生成器都是同一套字节码(SuspendGenerator / ResumeGenerator / SwitchOnGeneratorState),
挂起时把寄存器存进生成器对象。await 经 j8framework 的 Promise 机制驱动协程;脚本跑完后排空微任务队列。
ES 模块
module.rs:加载、链接、求值(同步:依赖经 Platform::load_module 读进来)。import 绑定实时读导出方的槽,
ResolveExport 处理间接导出、export * 与歧义;命名空间对象、动态 import()、import.meta 都支持。
模块的顶层 await 还不支持。
CodeCache
很多 isolate 跑同样的序言、导入同样的模块文件时,给它们的 executor 一个共享的 CodeCache:
- 每份源码只解析、编译一次,每个 executor 加载自己的一份拷贝;
- 只放该共享的东西(以
ScriptKind::Shared运行的脚本与 ES 模块),一次性的脚本不入缓存; - 不存源码:按文件名、长度和文本的 128 位哈希(两个随机密钥的 SipHash,碰撞造不出来)查找。
let code = CodeCache::shared();
let executor = Executor::default().with_cache(Arc::clone(&code));
JIT 钩子
Executor::with_tier(tier) 挂上一个 Tier(JIT)。执行器在这些地方问它:
| 时机 | 调用 |
|---|---|
| 一次调用即将从第一条指令跑一帧(每 64 次调用问一次) | Tier::enter |
某个 JumpLoop 回跳了很多次 | Tier::osr |
| 帧从中途继续(暂停后、机器码交回来后) | Tier::resume |
| 已编译函数之间的普通调用,不建解释器帧 | Tier::call |
回答 Interpret 就照常解释;Resumed 表示机器码跑过了,帧已经按 Entry::resume 设好,解释器从栈顶那帧接着跑;
Threw 表示机器码里抛了异常。jit.rs 定义了 JIT 能看到的全部东西:解码后的字节码与反馈(Function)、
即将跑的帧(Entry)、机器码把执行交回解释器的方式(DeoptFrame)。
用法
let mut executor = j8executor::Executor::default();
let result = isolate.run(&mut executor, &cx, &j8framework::Source { text: "1 + 2", file: "a.js" })?;
javascript_semantics 测试是一张逐条确定的 JS 语义表。
JIT:推测式优化层
crates/j8jit 是 j8 的 JIT(x86-64 Unix 和 Windows、AArch64 Linux)。它实现执行器的 Tier:热函数与热循环依据内联缓存的反馈建成推测性的
SSA 图,优化后出 x86-64 或 AArch64 机器码,在解释器的帧上直接跑;推测落空就去优化回解释器。
热函数 / 热循环 ─ build(字节码 + 内联缓存 ⇒ 推测图)─ opt ─ codegen ─▶ 机器码,跑在解释器的帧上
守卫失败 ─▶ j8_deopt 重建解释器帧;留下的提示决定下次怎么编
j8 的路线是跳过基线编译器、直接做推测式优化层(内联、逃逸分析、去优化、OSR),目标是在常用基准上追上带 JIT 的 V8。
打开它
use std::rc::Rc;
let executor = j8executor::Executor::default().with_tier(Rc::new(j8jit::Jit::default()));
dune --jit、J8_TEST262_JIT=1(test262 开着 JIT 跑同一份基线)打开它;Jit::from(n)设热度阈值(缺省Jit::THRESHOLD= 64),0 表示每个函数第一次调用就编;- 调试环境变量:
J8_JIT_LOG(编译与去优化日志)、J8_JIT_IR(打印图)、J8_JIT_BIN=<目录>(把机器码写成文件)。
三种入口
Kind | 什么时候 | 怎么跑 |
|---|---|---|
Enter | 解释器调用一个热函数 | 在解释器给它建的帧上跑 |
Osr(at) | 循环头 at 回跳得够多 | 在当前帧上从循环中途切进去 |
Native(n) | 已编译代码调用已编译代码 | 经被调者的蹦床(trampoline)直接调,不建解释器帧 |
普通函数(非类构造器、非 new 调用、形参不超过 3 个)编成 native 入口:参数放寄存器,int32 结果经第二个返回寄存器
不装箱地传回。每个函数有一个蹦床 jmp [rip + cell](AArch64 上是 ldr x16, cell; br x16):有机器码时指向机器码,否则指向解释器。
脚本 / eval 的顶层代码只跑一次,进入时不编,只编它里面的热循环(OSR)。
build:字节码 ⇒ 推测图
build.rs 对字节码做抽象解释:为每个解释器寄存器记下它当前对应的 IR 值,同时依据内联缓存看到的东西推测。
- 数先当 int32,带守卫;守卫失败会留下提示,下次编译那里用 double;
- 内联小函数:已知的小函数调用直接内联(深度上限 4,函数体不超过 80 条指令,递归最多展开 2 层), 去优化时连被内联的帧一起重建;别的调用走已编译代码或运行时;
- 对象先虚拟化:这里新建的对象字段只记在编译器里,直到有谁需要对象本身才真正分配(逃逸分析);
- 上下文槽读写都留在值里,只在别人可能看到时才写回;
- OSR 进来的循环剥一次皮:一轮分配、下一轮就替换掉的东西根本不会存在。
字节码按区域(Region)走,每个区域内的块按顺序:前向边总是指向还没走过的块,所以一个块的状态就是它所有前驱的
合并;循环头对回边做推测(所有活跃值都有 phi),回边不一致就带着提示重新走(最多 12 次)。
cfg.rs 给出块、循环与活跃性:分析里寄存器编号为 receiver 和参数 0 .. P、ri 是 P + i、累加器是 P + R;
上下文寄存器总是活跃(不跟踪)。
IR
ir.rs:SSA 形式的基本块,每条指令是一个值,带表示(Rep:int32、double、word……)。
Block { phis…, insts…, terminator } terminator 是 Jump / Branch / Return / Deopt
Inst { op, rep } 操作数是值的编号
FrameState { func, pc, slots…, parent } 守卫处每个解释器寄存器存着什么(虚拟对象也算)
几类典型的 Op:
| 类别 | 例子 |
|---|---|
| 常量与参数 | I32、F64、Word、Param、Callee、Phi |
| 算术 | Int(op, a, b, fs)(可能溢出时带帧状态)、Float、IntToFloat |
| 装箱 / 拆箱 | BoxInt、BoxFloat、UnboxInt(v, fs)(守卫:是 int32 且不是 −0)、UnboxFloat |
| 守卫 | CheckObject、CheckShape、CheckFunc(闭包跑的是某个函数)、CheckNotHole |
| 内存 | LoadWord、LoadPtr、StoreCell(必要时带写屏障)、ContextCell |
| 调用 | Call(helper, …)(运行时函数)、CallJit(调已编译代码) |
每个守卫带一个 FrameState:失败时解释器从哪条指令、以什么寄存器内容继续。
opt 与 codegen
opt.rs:只选一个值的 phi 去掉,没人用的指令去掉;- 循环不变量外提(LICM)、跨循环的路径事实、常数取模变乘法等在构建与优化中完成;
codegen.rs:图直接到机器码:按逆后序在块上做线性扫描寄存器分配,然后一遍指令选择。它按 x86-64 的寄存器角色 (RAX … R15)和标志条件来写;asm.rs按目标选编码器:asm/x64.rs(x86-64)或asm/a64.rs(AArch64:每个角色映射到 一个 AAPCS64 寄存器,在 NZCV 上模拟 x86 的标志条件,每次调用后把x0/x1搬进 RAX/RDX 角色)。建帧和调用者保存寄存器的 进出栈是编码器的enter/leave/save/restore。
rbp 帧 −8 … −40 存 rbx r12 r13 r14 r15,−48 … −88 入口指针,下面是溢出槽
r15 始终是 JIT 上下文(Ctx)
临时 rax rcx rdx r11 xmm14 xmm15(不参与分配)
可分配 rsi rdi r8 r9 r10(调用者保存),rbx r12 r13 r14(被调者保存),xmm0 … xmm13
守卫跳到冷桩:把帧状态里的值存进 Ctx::BUF,调 j8_deopt。
运行时
runtime.rs:机器码调用和读取的东西。
Ctx +0 预算 +8 待处理 +16 全局对象 +24 脚本作用域 +32 Object.prototype +40 返回值 +48 返回 pc +56 acc
+64 深度 +72 深度上限 +128 ARGS(16 个字) +256 BUF(去优化的值)
j8_helper:慢路运行时函数(属性访问、分配、各种运算的通用路径);j8_poll:循环里定期检查预算与终止请求,和解释器一样能被事件循环打断;j8_deopt:去优化入口;- 可执行内存在 Unix 上用
mmap分配,在 Windows 上用VirtualAlloc。
去优化与学习
守卫失败时,j8_deopt 按帧状态重建解释器帧(包括内联掉的被调者),解释器接着跑。JIT 按失败原因留下提示:
| 原因 | 提示 |
|---|---|
| int32 推测失败 | 那里下次用 double(HINT_FLOAT) |
| 类型 / shape 不符 | 那里下次走通用路径(HINT_GENERIC) |
| 被调函数不是推测的那个 | 不内联 + 通用(HINT_NO_INLINE) |
| 遇到 JIT 不编的字节码 | 被内联的调用下次不内联;函数自己的代码就此放弃 |
失败的那份机器码作废,下次热起来再按提示重编。一个函数去优化 24 次后 JIT 放弃它,以后一直解释。
MLIR 那条路
j8jit 还导出 Compiler / Backend / MachineCode(compile.rs、x86_64.rs):MLIR(llvm 方言)经
mlirpass(mem2reg、canonicalize、cse)再由 j8jit 自己的 x86-64 后端出机器码,
不需要 LLVM。这是更早的第一档 JIT 走的路;现在热路径上用的是上面的图 ⇒ 机器码直出,V8 字节码到 MLIR 的下降正在重写。
框架层:Isolate、Agent 与值
crates/j8framework 是核心框架层:定义其余各层要实现的 trait 和它们共用的结构体 / 枚举,不依赖任何其他 j8 层。
具体实现在各层 crate 里(比如 j8platform 实现 Platform)。
核心类型
| 名字 | 作用 | 对应 V8 |
|---|---|---|
Platform / Pool | 宿主借给引擎的线程池与时钟 | v8::Platform |
Isolate | 独立的 JS 世界:一个 GC 堆(paragc)加一个 profiler | v8::Isolate |
Scope | 进入 isolate 的一次;里面的值带 'gc 品牌,出不了这次进入 | HandleScope |
Value<'gc> | 一个 JS 值,就是 V8 的 Local,出不了闭包 | Local<Value> |
Global | 持久句柄(paragc Root),跨多次 enter 存活,drop 即放掉 | Global<T> |
ContextRoot | 跨分片保留的执行环境 | — |
Context / Realm | 执行上下文:全局对象与内建原型(Intrinsics 由 j8builtins 实现) | Context |
Agent | 一次运行的上下文;全部 JS 运算语义挂在它上面,回调 JS 经 Invoke | — |
Engine | 执行引擎(j8executor)实现的统一入口;可续跑(start / resume) | — |
Profiler | 调用 / 回跳计数器 | — |
EventLoop / EventLoopSet | JS 事件循环与跑它们的 loop 线程(见事件循环) | — |
进入 isolate
let platform = DefaultPlatform::default();
let mut isolate = Isolate::new(&platform, CreateParams::default());
let mut executor = Executor::default();
let cx = isolate.enter(|scope| scope.persist(scope.context(&Builtins))); // Global<Context>
let result = isolate.run(&mut executor, &cx, &Source { text: "1 + 2 * 3", file: "a.js" })?;
isolate.enter(|scope| {
let v = scope.local(&result); // Global ⇒ Value<'gc>,只在这个闭包里有效
});
Isolate::enter(|scope| …)进入一次,'gc是这次进入的品牌。闭包期间不回收;返回后如果分配得够多就回收 (通常是年轻回收,每隔几轮一次完整回收)。Value<'gc>出不了闭包,编译期保证——这是 j8 用 Rust 生命周期替代 V8HandleScope的方式。- 要跨
enter保留一个值,就scope.persist(v)/agent.global(v)换成Global。
值:一个 NaN-boxing 的机器字
Value 是一个 64 位字(ValueBits):
- 数就是它自己的
f64位(所有 NaN 都规范成CANONICAL_NAN); - 其余都在负 NaN 空间里:高 16 位是
0xFFF0 | (tag + 1),低 48 位是载荷——布尔值,或 GC 地址(用户态地址装得进 48 位)。
ValueTag 的取值:UNDEFINED、NULL、BOOL、NUMBER、UNINIT(TDZ 里还没初始化的绑定,只出现在寄存器与环境槽里,
读写前被检查掉,永远到不了 JS)、LAZY(首次读才计算的属性值)、STRING、SYMBOL、BIGINT、OBJECT、ACCESSOR、CONTEXT。
判断「是不是数」「是不是对象」都是一次比较,不必完整解码。寄存器、累加器、环境槽、属性槽存的都是同一个字,
所以 JIT 的机器码直接读写它,ValueCell 原样存它。
let v = Value::Number(1.5);
match v.kind() {
ValueKind::Number(n) => …,
ValueKind::Object(o) => …,
_ => …,
}
Agent:运算语义
Agent 是「一次运行」的上下文,持有当前 realm、堆的 mutator 与引擎的 Invoke。规范里的抽象操作都是它的方法
(ops.rs):类型转换(ToNumber、ToString、ToPrimitive……)、运算符(BinaryOp、CompareOp、UnaryOp)、
属性访问(沿原型链,经对象的内部方法)。执行器、内建对象、绑定代码共用这一套,所以语义只写一次。
let s = a.to_string(v)?;
let f = a.get_named(obj, "then")?;
let r = a.call(f, this, &[arg])?;
let err = a.throw(ErrorKind::Type, "x is not a function"); // 返回 Error,宿主函数 `?` 出去即抛出
内建函数与宿主函数的签名统一是 fn(&mut Agent, this, &[Value]) -> Result<Value, Error>。
反复调用同一个函数的内建(map、filter、reduce、sort 的比较函数……)先用 a.callback(f, this) 解析一次,
循环里调用返回的 Callback。引擎经 Invoke::callback 填好它:开了 JIT 时,不超过三个形参的普通函数直接进编译好的机器码
(经函数的跳板,之后重编或去优化都能跟上);其余情况退回 Agent::call。
let cb = a.callback(f, this_arg);
for (k, v) in items {
let r = cb.call(a, &[v, k.into(), o.into()])?;
}
Error
| 变体 | 含义 |
|---|---|
Error::Exception(g) | JS 抛出了值 g |
Error::Syntax(msg) | 源码解析不了(含早期错误) |
Error::Unsupported(msg) | j8 还不支持的写法,带 文件:行:列 |
Error::Terminated | 被 IsolateHandle::terminate 中止 |
中止执行
IsolateHandle::terminate 从别的线程中止 JS(V8 的 TerminateExecution):执行层在检查点(函数入口、回跳;JIT 机器码在回跳)
看到请求后抛 Error::Terminated。它不是 JS 异常,catch / finally 都接不住,一路传到最外层;传出最外层时自动复位,
isolate 接着能用。
其他部件
| 文件 | 内容 |
|---|---|
promise.rs | Promise 与微任务:resolve / reject、then 反应、驱动 async 协程、排空队列 |
module.rs | 模块记录、导入导出条目、ResolvedBinding |
proxy.rs | Proxy:内部方法入口分派到 trap,带不变式检查 |
typed.rs、backing.rs | TypedArray 元素;ArrayBuffer 的字节放在哪(自己的、宿主映射的、几个 isolate 共享的) |
text.rs | 字符串(见对象模型) |
parallel.rs | 内建函数的并行:大数据时把纯数据的活切块放到平台线程池上(fork–join) |
layout.rs | 机器码要直接读写的堆对象字节偏移 |
lazy.rs | 首次读才计算的属性(V8 函数 map 上的 AccessorInfo:建闭包时不造 name) |
private.rs | 类的私有成员 #x |
对象模型:Shape、存储与属性
对象布局
Object + OBJECT_SHAPE *const Shape(null:空对象,或字典模式)
+ OBJECT_INLINE ValueCell × INLINE_PROPS(前几个属性直接放在对象里)
+ OBJECT_STORE 存储树的 GC 槽:叶子 { 容量, ValueCell × 容量 }
对象把热路径要碰的东西放在可变数据(GcCell)外面:原型、属性(shape 加值存储)、数组元素、函数与正则的不可变数据。
JIT 按 j8framework::Layout 给的偏移直接读写这些字段。
j8 自己的堆结构体用 #[j8framework::heap] 声明,#[mutable] 字段按类型自动选单元(Value ⇒ ValueCell、
Gc ⇒ paragc Slot、布尔与整数 ⇒ 原子量),并生成 getter / setter:
#[j8framework::heap]
pub struct Object<'gc> {
#[mutable(set = write_proto)]
proto: Option<JsObject<'gc>>, // proto() / write_proto(mc, p)
#[mutable]
non_extensible: bool, // non_extensible() / set_non_extensible(mc, b)
data: GcCell<'gc, ObjectState<'gc>>,
}
Shape(隐藏类)
shape.rs:shape 是对象自有字符串键属性的布局——键与特性,按插入顺序;值另外放在对象的槽里。
- 以同样方式建出的对象共享 shape:加属性沿转移表走到(或新建)子 shape;
- 执行层按「shape ⇒ 槽下标」做内联缓存;
- shape 里没有
Gc指针(回收会搬对象),用Arc管理;转移表存Weak,没有对象用的 shape 自然释放; - 删属性、改特性或键太多时,对象的属性转成字典(
Dict,原地修改),内联缓存不接收字典。
值存储
store.rs:属性值与数组元素放在 GC 堆里固定容量的叶子中,大了就是 128 叉树(30 万个元素三层)。
paragc 只分配定长对象,所以按容量分档:
- 叶子
Leaf<N>:N个ValueCell(N= 2 / 4 / … / 128),头一个字是容量; - 内部节点
Node:128 个子槽,头一个字是NODE加层数。
全部 #[repr(C)]:不管 N 多大,格子都从头字之后开始,抹掉类型后也能按下标找到。读不借用、不加锁;
写经 ValueCell::set 走写屏障。
内部方法
property.rs 实现规范第 10.1 节(普通对象)与 10.4 节(数组、字符串包装对象)的内部方法:
[[GetOwnProperty]]/[[DefineOwnProperty]](ValidateAndApplyPropertyDescriptor、ArraySetLength);[[OwnPropertyKeys]]、可扩展性、原型;- 数组有稠密部分,加上按下标存的普通属性(空洞、特性各异的元素);
length只读、不可扩展都按规范。
属性访问(ops.rs)经这些内部方法沿原型链走。Proxy 在 proxy.rs 里把同样的入口分派到 trap,并检查不变式。
字符串
text.rs:属性键与 JS 字符串值共用的表示。
- 不超过 22 字节的短串内联存放,不单独分配;
- 长串共享一份堆拷贝,从长串切出的片段(
split、slice、正则匹配)指向那份拷贝而不复制(V8 的 sliced string); - 字符串
+产生足够长的结果时先存成 rope(两半加总长),第一次需要内容时才拍平并缓存——s += c的循环 不再每次复制整串;拍平与释放都是迭代的,几十万层的 rope 也不会爆栈; - 不含
Gc,GC 不需要管它。
当前字符串按 UTF-8 存储,所以落单的代理项(lone surrogate)会丢失;比较按 UTF-16 码元进行。
宿主对象
ObjectKind::Host:持有 Rust 值的 JS 对象(HostData,Box<dyn Any + Send + Sync>,外面是借用标志)。
绑定方法里以 &self / &mut self 取出;重入的 &mut self 调用抛 TypeError 而不是 panic(见绑定宏)。
堆与 GC:建在 paragc 上
j8 的堆是 paragc,j8 只用它的公开接口(Gc / Slot / Mutator / Root),
不碰它的内部。j8framework/src/gc.rs 在上面补 JS 引擎需要的东西。
paragc 是什么
一个独立的 Rust GC 库(同属 0x00 社区):
- Immix 式的块 / 行堆;
- 年轻回收 + 老对象引用计数(LXR 式),稀疏块疏散;
- 标记与清扫并行,内部无锁;
- 堆有自己的回收线程(数目同平台线程池);
- 公开堆、跨进程堆等扩展能力(jumpheap 用到)。
j8 的 GC 层
paragc 里对象中能改的边只有 Slot(带写屏障),所以 j8 的可变堆数据分两种放:
| 单元 | 放什么 | 怎么改 |
|---|---|---|
GcCell | 一整块可变数据(ObjectState 等) | 当前版本放在槽指着的快照里:快照是本轮(上次回收后)新分配的就原地改;否则先挪进一份新快照再改,槽换过去时写屏障就记下了它。每块数据每个回收周期最多挪一次 |
ValueCell | 一个 Value(环境槽、属性槽) | 字 + 槽 |
Cow、GcQueue、Static | 写时复制、堆上队列、跳过追踪的数据 | — |
堆类型用 #[derive(Collect)](在 j8macros,生成 paragc 的 Trace);#[collect(require_static)] 跳过一个字段
(放在类型上表示整个类型没有 GC 边)。有边的类型不许实现 Drop。
单线程的 isolate
一个 isolate 同一时刻只在一个线程上跑 JS(V8 的模型),它堆里的对象只由这个线程读写,所以借用标志、标量字段都是
普通读写(IsoCell),⛔ 原子读改写。只有 paragc 的 Slot 自带原子(写屏障需要)。
堆里的类型都要 Send + Sync(paragc 的规矩):宿主数据是 Box<dyn Any + Send + Sync>,Shape 与 rope 用 Arc。
规矩
这些规矩写在代码注释里,违反会造成悬垂或漏标:
- 回收只在
enter之外、所有Gc都挂在根上时发生,而且对象会被搬。⛔ 把Gc或对象地址存进Trace不遍历的地方(Static、旁路缓存)。按地址哈希的东西(Map / Set 的索引)在relocate里更新(见Collection)。 这也是内联缓存只按 shape(Arc)而不按对象识别的原因。 - ⛔ 给还没进堆的值写槽:写屏障记的是槽的地址。先分配进堆再填(见
Scope::context);#[heap(new)]生成的new在进堆之前填单元,不经屏障。 - 只做停顿式回收(
collect_if_needed/collect,内部并行):GcCell原地改年轻快照不经写屏障, 所以 ⛔mark_concurrently。 - 年轻回收用 paragc 缺省的
YoungEvacuation::SkipRemembered:老对象直接指着的年轻对象不动,被搬的对象字段都走relocate,ValueCell字里的地址随之改写。⛔YoungEvacuation::Full:它会改老对象槽里的地址,但不知道ValueCell字里另存的那一份。
什么时候回收
Isolate::enter返回后,分配够多就回收(通常年轻回收,每隔几轮一次完整回收);- 执行器分片执行:每片最多一万条指令,停下时把执行状态挂到根上,
enter返回时回收一段再接着跑; - 宿主函数里重入的 JS 在当前片里跑完,期间不回收。
持久句柄与环
Global、绑定里的 j8::Persistent / j8::Function 都是 GC 根。宿主对象里存的值如果又指回这个宿主对象,
两者会一直活到宿主对象从 Rust 侧被丢掉为止。WeakRef / FinalizationRegistry 目前按强引用实现。
内建对象
crates/j8builtins 是 JavaScript 标准内建对象,实现 j8framework::Intrinsics:新建 Realm 时由 Builtins::install
把全局对象、全局函数和全部内建构造器、原型、方法装进去。
let cx = isolate.enter(|scope| scope.persist(scope.context(&j8builtins::Builtins)));
j8framework 只定义 Intrinsics 接口,这里是缺省实现;宿主可以换掉或裁剪。j8builtins 只依赖 j8framework,
不依赖执行器:每个内建函数都是宿主函数 fn(&mut Agent, this, &[Value]) -> Result<Value, Error>,用
Agent 上的运算语义写成;需要回调 JS 时经 Invoke。
文件
| 文件 | 内建对象 |
|---|---|
global.rs | 全局对象、parseInt / parseFloat / isNaN / eval / URI 函数 |
object.rs、function.rs、reflect.rs | Object、Function、Reflect / Proxy |
array.rs、typed.rs、buffer.rs | Array、TypedArray(12 种,含 Float16)、ArrayBuffer / SharedArrayBuffer / DataView / Atomics |
string.rs、text.rs | String、Symbol |
regexp.rs、dfa.rs | RegExp(regress + 一个 DFA 快路) |
json.rs | JSON |
math.rs、bigint.rs、date.rs | Math、BigInt、Date |
collections.rs、weak.rs | Map / Set、WeakMap / WeakSet / WeakRef / FinalizationRegistry |
promise.rs、asyncgen.rs、iter.rs | Promise、异步生成器、迭代器与迭代器助手 |
error.rs | Error、TypeError … AggregateError,cause |
helpers.rs | 共用的规范步骤 |
覆盖范围
- Object / Array 的全部方法:Array 方法对类数组通用、species;
from/flat/toSorted/with…… - 反射:
Reflect、Proxy(含 revocable); - 迭代器助手:全局
Iterator、Iterator.from、map/filter/take/drop/flatMap/reduce……; Set 方法(union等)、Map.groupBy/Object.groupBy; - 二进制数据:可调大小的
ArrayBuffer(transfer、detach)、可增长的SharedArrayBuffer、DataView、Atomics(单线程语义); - Date(本地时区按 UTC 处理);数的格式化(
toFixed/toPrecision/toExponential精确到十进制)、Math.sumPrecise/f16round; - RegExp:Symbol 协议、
lastIndex、d标志、具名分组、species、RegExp.escape;字符串的match/matchAll/replace/replaceAll/search/split; - Promise 建在 NewPromiseCapability 上:子类化、
all/race/allSettled/any/withResolvers/try; - 内建构造器按
new.target定原型,所以class X extends Map之类能工作;宿主函数区分能否new。
范围外:Temporal、intl402、ShadowRealm 等(见路线图)。
正则:两个引擎
- 主引擎是 regress:按 UTF-16 码元匹配的回溯引擎;
dfa.rs是第二个引擎:对于regexcrate 在全 ASCII 输入上能与 ECMAScript 完全一致匹配的模式,用有限自动机加字面量 预过滤代替回溯。Dfa::new翻译模式,拒绝一切语义可能不同的东西:反向引用、环视、具名分组、v模式、m下的锚点、 量词里的捕获组(ECMAScript 每轮重置它们)、Annex B 的怪写法、非 ASCII 的模式文本。其余情况和非 ASCII 输入仍走 regress。- 正则字面量共享 realm 里编译好的入口与字符串;没有
g/y的test()跳过lastIndex。
快路
热点内建函数有快路:可观察的行为不可能不同时跳过完整的规范步骤——比如 RegExp.prototype 没被动过(pristine 检查)、
往稠密数组末尾追加、字符串与数字的拼接、JSON 解析时重复的键序列直接解析成同一个 shape。正确性以 test262 为准。
大数据的纯计算(排序的键、数的转换)可以经 j8framework::Par 切块放到平台线程池上并行,再把结果写回。
事件循环与任务队列
j8 不带异步运行时(没有 tokio)。事件循环是 j8 自己的:j8framework::EventLoop 建在 j8taskqueue 的队列上,
EventLoopSet 把成千上万个事件循环钉在少数几个 loop 线程上跑。
一个事件循环
EventLoop 是一个 JS 事件循环:自己的 isolate、引擎、一个上下文,以及一个 j8taskqueue 队列。队列就是事件循环,
里面有三种任务:
- 脚本:每次跑一个检查间隔的步数(缺省约一千条指令,V8 在函数入口与回跳处的中断检查),然后让回队列;
- 兑现:用宿主任务的结果兑现一个 promise,再排空微任务;
- 轮询:被唤醒的宿主 future 的 poll(里面不跑 JS;就绪的 future 把它的兑现排进队列)。
脚本与兑现串成一条链:每个等前一个做完,所以 JS 一次只跑一个任务、跑到完。轮询不等任何东西。于是字节码每前进一段, 队列就被检查一次:这期间(从任何线程)变成就绪的宿主任务先被 poll,它的 JS 紧接着当前脚本之后跑。
什么都跑不了时,线程停泊,直到有 waker 被唤醒。run_until_idle 在这个事件循环没有剩下的脚本与 future 时返回。
很多事件循环:EventLoopSet
j8::EventLoopSet::scope(&platform, NonZeroUsize::new(8).unwrap(), |set| {
// set 上有 8 个 loop 线程,闭包结束时停掉
let rt = j8::Runtime::on::<MyHost>(set, Executor::default())?;
…
});
- 钉住,不抢。 一个事件循环某一时刻只住在一个线程上、不共享,所以线程跑它的事件循环不用任何锁:8 个线程、1000 个 事件循环,每个线程 125 个。线程维护一个本地队列,里面是有活要干的事件循环,轮流给每个一个回合。
- 只用消息。 别的线程经唤醒(某个事件循环有新东西了,用标志去重)或消息(建事件循环、在它的上下文里干活、 迁入迁出)找到 loop 线程,并等它回答。发给已经搬走的事件循环的消息会被转发。
- 负载均衡。 新事件循环去负载最轻的线程。没活干的线程向最忙的线程要一半差额,对方先交出排队等着的事件循环(工作窃取)。
set.rebalance()按需拉平,set.split(thread)新起一个线程、分走某线程一半的事件循环。事件循环只在回合之间迁移, 它的 isolate、引擎、暂停的脚本和挂起的 future 一起走。 - 统一配额。 每个回合跑集合的切片步数(
set.set_slice)乘以事件循环的权重(EventLoop::set_weight),每set.set_check步检查一次队列;set.loads()、set.spent()、EventLoop::spent()显示活都花在了哪里。长脚本不会 卡住同线程的其他事件循环。
宿主怎么用它写异步绑定,见异步与 Promise。
j8taskqueue
crates/j8taskqueue:无锁的数据流任务队列(no_std + alloc,除 j8lockfree 外不依赖别的)。
| 名字 | 作用 |
|---|---|
ITask | 一个任务:recursable(执行时能不能塞新任务、能不能要求再跑)、depend(要等谁先做完)、exec(带字节码配额执行) |
ITaskPoll / TaskQueue | 队列:add 塞一个任务拿到 TaskId,run 启动 |
Queue | 不带线程的队列本体,宿主长期持有(每个事件循环一个):run 在调用线程上跑,run_on 铺到线程池上 |
Pool | 线程池(几个线程、跑完一批闭包才返回),宿主实现;j8framework 的 Pool 就是它 |
TaskId | 任务句柄;family 找家族的根(并查集),cancel 取消整个家族 |
Quota | 字节码配额:执行器每跑一条字节码 spend 一次 |
设计要点:
- 数据流、无屏障:一个任务做完,依赖它且已等齐的任务立刻进就绪队列,被还在取活循环里的线程拿走。a、b 都被 c 依赖 而互不依赖 ⇒ a、b 并行,两个都做完 c 马上跑,不等不相干的任务;
- 不空转:取不到活的线程直接离开,不自旋;之后才就绪的活由让它就绪的线程接着跑;
- 全程无锁:依赖计数、下游表(可封口的
PushList)、并查集父指针、就绪队列(分段 MPMCFifo)都是原子操作; - 图不成环:依赖只能写已经塞进来的任务,依赖表在塞进来时读一次 ⇒ 不会死锁;
- 配额按字节码条数:用完没做完返回
Flow::Yield,回就绪队列排队;每次run还有总预算,花完返回Stop::Budget; - 借用而非
'static:任务活在'a里、可借用调用方数据,只要求Send。
无锁基础件
crates/j8lockfree:j8 手写的无锁基础件(no_std + alloc),j8framework 与 j8taskqueue 共用。j8 的规矩是
堆与调度全程无锁,无锁结构自己写,⛔ 引入 crossbeam。
| 类型 | 是什么 |
|---|---|
Fifo | 多生产者多消费者先进先出队列(位置单调递增、分段槽表) |
SegVec | 只追加的分段向量:下标稳定、可并发读;整理与取出要独占 |
PushList | 只压入的 Treiber 栈:整表取走或封口(封口后压入被退回) |
Stock | 库存:独占时整理成只读数组,并发时原子游标成批领取 |
Deque | Chase–Lev 工作窃取双端队列:主人凭据 Owner 压 / 弹,别人偷 |
OnceBox | 只发布一次的惰性值(并发初始化各算各的,赢的留下) |
AtomicRefCell | 可跨线程的 RefCell:借用冲突时报错,从不等待 |
共同的做法:只增不减,独占时释放
并发期间只增加内存(新段、旧缓冲留着),释放推迟到独占(拿到 &mut 或析构)时。所以:
- 不需要危险指针(hazard pointer);
- 不需要纪元回收(epoch-based reclamation);
- 没有 ABA 问题。
代价是并发期间内存只涨不落,但这些结构的使用方式(事件循环的队列、任务图的下游表)都有天然的独占时刻可以整理。
谁在用
| 使用方 | 用什么 |
|---|---|
| j8taskqueue | Fifo 作就绪队列、PushList 作下游表 |
| j8framework 事件循环 | 消息队列、工作窃取 |
| j8binding 宿主对象 | AtomicRefCell 包着 Box<dyn Any + Send + Sync> |
| j8executor | 内联缓存与加载表 |
平台
Platform 是宿主借给引擎的东西:线程池、时钟、console.log 的输出、模块加载。crates/j8platform 是它的标准库实现
DefaultPlatform。
DefaultPlatform
- 线程池:moremath 的
ThreadMulti,起一次反复用,任务可借用调用方数据 (经j8framework::Pool);后台任务与并行内建函数跑在上面。GC 堆有自己的回收线程。 - 时钟:单调时钟用
Instant,Date用SystemTime。 - 模块:相对路径按引用方所在目录解析,从磁盘读(不处理
node_modules)。 console.log打到标准输出。
let platform = j8platform::DefaultPlatform::default(); // 每个 CPU 一个工作线程
let small = j8platform::DefaultPlatform::from(NonZeroUsize::MIN); // 单线程
let mut isolate = j8framework::Isolate::new(&platform, Default::default());
trait
pub trait Pool: Sync {
fn threads(&self) -> usize;
fn run(&self, jobs: Vec<Task<'_>>); // 跑完一批才返回;任务借用调用方数据
}
pub trait Platform: Pool {
fn now(&self) -> Duration; // 单调时钟
fn wall_clock(&self) -> Duration; // Date 用
fn print(&self, line: &str); // console.log
fn load_module(&self, referrer: &str, specifier: &str) -> Option<(String, String)>; // (规范化名字, 源码)
}
(示意,完整签名见 j8framework/src/platform.rs。)
叠平台
平台都不持有异步任务(那些住在每个运行时的 isolate 里),所以可以任意叠加、也可以被多个运行时共享。dune 的
NodePlatform 包着 DefaultPlatform:拦下 node: 内建模块的说明符,其余转给里面那层:
let platform = Dune::platform(NodePlatform::from(DefaultPlatform::default()));
可以覆盖的方法:print(把 console.log 接到别处)、now / wall_clock(测试用假时钟)、load_module(包、URL、
虚拟文件系统)。写法见模块。
搭一个宿主
这一部分讲怎么在 j8 crate 上搭自己的 JavaScript 运行时,像 dune 和 workerd 那样。
宏的逐项说明见绑定宏。
依赖
[dependencies]
j8 = "0.4" # 缺省 feature `runtime`:执行器 + 内建对象 + 平台
# j8 = { version = "0.4", features = ["jit"] } # + x86-64 JIT(x86-64 Unix 和 Windows)
# j8 = { version = "0.4", features = ["json"] } # + j8::Json<T>(serde)
| 路径 | 是什么 |
|---|---|
#[j8::object] / #[j8::class] / #[j8::function] / #[j8::module] | 把 Rust 绑成 JS |
j8::runtime! | 声明一个运行时:哪些绑定类型放哪里,加一段 JS 序言 |
j8::Runtime | 准备好的执行环境:eval、eval_module、run_until_idle、set、text、enter |
j8::Host / j8::HostPlatform | runtime! 实现的 trait / 给它供原生模块的平台(无状态,运行时可共享) |
j8::frame | j8framework:Agent、Error、ErrorKind、Value、Platform、Source …… |
j8::platform::DefaultPlatform | 标准库平台 |
j8::executor::Executor | 字节码执行器;with_tier 加 JIT |
j8::Promise<T> | 在 Rust 里 await 的 JS promise |
j8::Glue | Glue::spawn / Glue::settle:手工做的 promise |
j8::NATIVE | "__j8_native",隐藏注册表对象的名字 |
最小的宿主
use std::num::NonZeroUsize;
use std::process::ExitCode;
use j8::executor::Executor;
use j8::frame::{Agent, Error, ErrorKind};
use j8::platform::DefaultPlatform;
/// 碰机器的部分,放在 `__j8_native.env`
struct Env;
#[j8::object("env")]
impl Env {
fn var(name: &str) -> Option<String> {
std::env::var(name).ok()
}
/// 变量不存在时抛 TypeError
fn must(a: &mut Agent<'_, '_>, name: &str) -> Result<String, Error> {
std::env::var(name).map_err(|_| a.throw(ErrorKind::Type, &format!("{name} is not set")))
}
}
/// 公开接口是 JavaScript,建在原生绑定之上
const PRELUDE: &str = r#"
(function (native) {
'use strict';
globalThis.home = () => native.env.var('HOME');
})(globalThis.__j8_native);
"#;
j8::runtime! {
pub Hello {
natives: [Env],
prelude: PRELUDE,
}
}
fn main() -> ExitCode {
let platform = Hello::platform(DefaultPlatform::default());
// 一个运行时一个 loop 线程就够;运行时多了再加
j8::EventLoopSet::scope(&platform, NonZeroUsize::MIN, |set| {
let rt = match Hello::runtime(set, Executor::default()) {
Ok(rt) => rt,
Err(e) => {
eprintln!("prelude failed: {e}");
return ExitCode::FAILURE;
}
};
match rt.eval("home()", "main.js").and_then(|g| rt.run_until_idle().map(|()| g)) {
Ok(g) => {
println!("{}", rt.text(&g));
ExitCode::SUCCESS
}
Err(Error::Exception(g)) => {
eprintln!("Uncaught {}", rt.text(&g));
ExitCode::FAILURE
}
Err(e) => {
eprintln!("{e}");
ExitCode::FAILURE
}
}
})
}
步骤总是一样的:
X::platform(inner)把一个平台包成运行时X的HostPlatform。它要活得和运行时一样久:Runtime<'p>借用它。j8::EventLoopSet::scope(&platform, threads, |set| …)在闭包期间起好运行时要住的 loop 线程。X::runtime(set, executor)在负载最轻的 loop 线程上建 isolate 和上下文、装好一切、跑序言。序言抛异常在这里以Err返回。之后的每次调用(eval、enter、run_until_idle)都是发给那个线程的消息,并等它回答;任何宿主线程都能发。rt.eval(text, file)跑一段脚本,返回Global(活过这次调用的句柄),rt.text(&g)按 ToString 转成字符串。rt.run_until_idle()等到没有剩下的异步宿主任务。绑定里有async fn或返回 promise 时,每次eval之后都要调它, 否则那些 promise 永远不会兑现。
分工:Rust 绑定 + JS 序言
两个样例都这样分工:
- Rust 只做必须碰机器的事(文件、套接字、时钟、进程),保持小而平。
- JavaScript(序言)在上面搭真正的接口:类、参数检查、Node / Web 语义。代码量比全用绑定写少得多。
runtime! 有四段,都是可选的,必须按这个顺序、每段后面带逗号:
| 段 | 收什么 | 落在哪里 |
|---|---|---|
globals: [..] | #[j8::class] / #[j8::object] 类型 | 全局对象:globalThis.Process |
modules: [..] | #[j8::module("node:x", "x")] 类型 | import … from "node:x" 与 __j8_native["node:x"] |
natives: [..] | #[j8::class] / #[j8::object] 类型 | 隐藏注册表:__j8_native.env、__j8_native.KvStore |
prelude: EXPR | 一段 JavaScript(&'static str) | 全部装好之后作为脚本跑一次 |
JS 名字是宏参数(#[j8::object("env")] ⇒ env),没给就是 Rust 类型名。方法名转成 camelCase(exists_sync ⇒ existsSync),
除非 #[js(name = "…")] 另有指定。
__j8_native 是全局对象上不可枚举的属性。用户代码仍然拿得到它,所以只当作「随手碰不到」,不是安全边界。惯用的序言形状是
一个接收它的 IIFE:
(function (native) {
'use strict';
const { clock, Timer } = native; // Rust 里绑定的原生对象
globalThis.setTimeout = (f, ms) => { /* … */ };
native.runMain = (file) => { /* … */ }; // 宿主调用的入口
})(globalThis.__j8_native);
长序言可以拆成几个文件,用 concat!(include_str!("a.js"), include_str!("b.js")) 拼起来(dune/src/node/mod.rs 就是这样)。
往运行时里传数据:Runtime::set
rt.set("a.b.c", value) 在 globalThis.a.b 上定义 c,value 经 IntoJs 转换。数、字符串、Vec<T>、
BTreeMap<String, T>、Option<T> 都行:
rt.set("process.argv", args)?; // Vec<String> ⇒ 数组
rt.set("process.env", std::env::vars().collect::<BTreeMap<_, _>>())?; // map ⇒ 对象
父对象必须已经存在(由序言建)。dune 就这样设置 process.argv 等,序言不需要知道 Rust 的存在。
调用序言里的入口
把函数挂到 __j8_native 上,再 eval 一个对它的调用;参数要写成 JS 字符串字面量(见 dune 的 Session::quote):
let call = format!("__j8_native.runMain({})", quote(file));
rt.eval(&call, file)?;
rt.run_until_idle()?;
更底层的活用 rt.enter(|a| …),拿到上下文的 Agent(a.get_named、a.call、a.local、a.to_string ……)。
Value 出不了闭包,之后还要用就换成 Global(a.global(v))。
Error 的含义
| 变体 | 含义 | 宿主怎么做 |
|---|---|---|
Error::Exception(g) | JS 抛了,g 是抛出的值 | rt.text(&g) ⇒ Uncaught … |
Error::Syntax(msg) | 源码解析不了 | 打印 msg |
Error::Unsupported(msg) | j8 还不支持的写法 | 打印 msg |
在别的运行时上扩展
j8::runtime! { pub Web { natives: [Stdio, Clock, Codec, Random, Timer, Http], prelude: WEB_PRELUDE, } }
j8::runtime! { pub Dune: Web { globals: [Process], natives: [Fs, Os, Child], prelude: NODE_PRELUDE, } }
Dune 先装 Web 的全部东西,再装自己的,先跑 Web 的序言再跑自己的。模块查找先试子运行时的模块、再试父运行时的。
父运行时不变,所以第三方可以在不 fork 的情况下扩展 Dune。
打开 JIT
let executor = Executor::default().with_tier(j8::jit::Jit::default());
let rt = MyHost::runtime(set, executor)?;
样例里去哪找
| 你想…… | 看 |
|---|---|
| 建运行时、跑文件、报错、退出码 | dune/src/cli/、dune/src/session.rs |
REPL(多次 eval 共享一个全局对象) | dune/src/repl.rs |
| 抛带 code 的 Node 式错误;把阻塞活放到别的线程 | dune/src/host.rs |
绑定普通对象(stdio、clock、codec、random) | dune/src/web/mod.rs |
可取消的 promise(Glue::spawn) | dune/src/web/timer.rs |
| 异步文件系统 | dune/src/node/fs.rs + fs.js |
给 JS 写的模块配自定义 Platform;Runtime::set | dune/src/node/mod.rs |
用 JS 写的模块加载器(require、node_modules、package.json) | dune/src/node/loader.js |
| 带 Rust 状态、只给序言用的类 | samples/workerd/src/main.rs(KvStore)+ prelude.js |
| 每个请求调一次 JS 定义的入口 | samples/workerd/src/main.rs(Worker) |
绑定宏
宏在 crates/macros(j8macros),经门面 crate 写成 #[j8::class] 等;运行时支撑在 crates/j8binding,对应 V8 的
FunctionTemplate / ObjectTemplate。三个宏各一个文件(class.rs / object.rs / function.rs),读 #[js(…)]、
分析签名、生成转换包装的共用代码在 method.rs。
#[j8::class]:Rust 类型导出为 JS 类
放在 impl 块上:为每个方法生成转换包装(fn(agent, this, args) -> Result<Value>)并实现 j8::Class。类型本身不用改;
实例是持有 Rust 值的宿主对象(ObjectKind::Host)。
struct Counter { n: f64 }
#[j8::class] // 或 #[j8::class("name")];缺省是类型名
impl Counter {
#[js(constructor)] // `new Counter(…)`;直接调用抛 TypeError
fn new(start: Option<f64>) -> Self { Self { n: start.unwrap_or(0.0) } }
fn inc(&mut self, by: f64) -> f64 { self.n += by; self.n } // 原型方法,名字转 camelCase
#[js(getter)]
fn value(&self) -> f64 { self.n }
#[js(setter, name = "value")]
fn set_value(&mut self, v: f64) { self.n = v }
fn zero() -> f64 { 0.0 } // 没有 self:构造器上的静态方法
}
let handle = Counter::install(&mut agent, global); // 全局 `Counter`,返回构造器与原型
let obj = handle.instance(&agent, Counter { n: 1.0 }); // 从 Rust 建实例
继承:#[j8::class(extends = Base)]
struct Dog { base: Animal, tricks: u32 }
impl AsRef<Animal> for Dog { fn as_ref(&self) -> &Animal { &self.base } }
impl AsMut<Animal> for Dog { fn as_mut(&mut self) -> &mut Animal { &mut self.base } }
#[j8::class(extends = Animal)]
impl Dog { … }
Dog.prototype 的原型是 Animal.prototype,Dog 的原型是 Animal(还没装的话先装到同一目标上),所以 instanceof
成立,Animal 的方法经 AsRef / AsMut 在 Dog 上跑。链多长都行。
#[j8::object]:只有关联函数的 impl 导出为普通对象
struct Fs;
#[j8::object("fs")]
impl Fs {
fn exists_sync(path: &str) -> bool { … } // fs.existsSync
#[js(getter)]
fn sep() -> String { "/".into() } // fs.sep(访问器)
}
#[j8::function]:导出一个函数
#[j8::function] // 或 #[j8::function("name")]
fn greet(name: &str) -> String { format!("hi {name}") }
greet::install(&mut agent, global); // 原函数保留,旁边生成同名模块,`greet::NATIVE` 是宿主函数
#[j8::module]:原生模块
和 #[j8::object] 一样,但应答一个或多个模块说明符(第一个是规范名)。在 j8::runtime! 声明的运行时里,它供给
import(一个缺省导出加每个成员一个具名导出),并放进隐藏注册表 __j8_native["node:fs"],供序言的 require 使用。
#[j8::module("node:fs", "fs")]
impl Fs {
fn exists_sync(path: &str) -> bool { … }
}
import fs, { existsSync } from "node:fs";
属性
| 属性 | 含义 |
|---|---|
#[js(constructor)] | 构造器(返回 Self 或 Result<Self, Error>);没有它,这个类不能 new |
#[js(getter)] / #[js(setter)] | 访问器;同名的 getter 与 setter 组成一对 |
#[js(static)] | 静态方法(没有 self 的方法缺省就是) |
#[js(name = "…")] | JS 里的名字 |
#[js(skip)] | 不导出 |
参数与返回值
参数按类型取:
| 参数类型 | 拿到什么 |
|---|---|
&mut Agent<'_, '_> | 当前 agent(不算 JS 实参,放在哪个位置都行) |
This | 原始的 this |
Rest | 剩下的全部实参 |
&str | ToString 后借用 |
| 其他 | 依次用 FromJs 转换:f64 / i32 / u32 / usize / bool / String / JsString / JsObject / Value / Option<T> / Vec<T> |
返回值用 IntoJs 转换;Result<T, Error> 在 Err 时抛出。参数里的生命周期写成 'gc。
句柄类型:
| 类型 | 作参数 | 作返回值 |
|---|---|---|
j8::Persistent | 跨 enter 保留任意 JS 值(存进宿主结构体;.get(a) 读) | &Persistent 把值还回去 |
j8::Function | 可调用的 Persistent(不可调用抛 TypeError);.call(a, this, args) | &Function |
j8::Bytes | ArrayBuffer / TypedArray / DataView 的字节 | 新 Uint8Array |
j8::Promise<T> | JS promise(像 await 那样接收),在 Rust 里 .await | — |
j8::Json<T>(feature json) | 任何 serde::Deserialize 类型,经 JSON.stringify 读 | 任何 serde::Serialize 类型,经 JSON.parse 造 |
抛异常
拿 &mut Agent、返回 Result<T, Error>,用 a.throw(kind, message) 造错误:
fn must(a: &mut Agent<'_, '_>, name: &str) -> Result<String, Error> {
std::env::var(name).map_err(|_| a.throw(ErrorKind::Type, &format!("{name} is not set")))
}
错误要晚些才知道、或者想要结构化的错误(Node 的 err.code)时,返回一个自己的类型,让它的 IntoJs 去抛。dune 的
host.rs 用 Io<T> 这样做:
pub struct Io<T>(pub Result<T, Failure>);
impl<'gc, T: IntoJs<'gc>> IntoJs<'gc> for Io<T> {
fn into_js(self, a: &mut Agent<'gc, '_>) -> Result<Value<'gc>, Error> {
match self.0 {
Ok(v) => v.into_js(a),
Err(f) => Err(a.throw(f.kind, &f.message)), // "ENOENT: no such file or directory, open 'a.txt'"
}
}
}
序言再从消息开头读出 code、设到 err.code 上。因为 IntoJs 在运行时线程上跑,这对 async fn 的结果也适用。
绑定类型的要求
#[j8::class]类型存在 JS 对象里,所以必须Send + Sync + 'static。和线程共享的状态用Arc/ 原子量 (见dune/src/web/timer.rs的Timer)。- 方法回调 JS、JS 又碰到同一个对象(已借用时再要
&mut self)会抛TypeError,不会 panic。 - ⛔ 在结构体里存
Value/JsObject:它会活过它的enter。存j8::Persistent(或j8::Function)。它们都是 GC 根: 经由宿主对象形成的环,要等那个宿主对象被丢掉才释放。
异步与 Promise
j8 不带异步运行时(没有 tokio)。每个 j8::Runtime 就是一个事件循环:eval 与 run_until_idle 驱动它。
核心规则:future 必须唤醒它的 waker
事件循环什么都跑不了时线程会停泊,直到 waker 被唤醒。所以一个 future 能推进时必须唤醒它的 waker,否则循环永远睡下去。 需要自己反应堆的 crate 的 future(tokio 的套接字和定时器)直接拿来用是不会醒的:把那种活放到线程上、或放到你自己的反应堆上, 从那里唤醒 waker。
async fn 绑定
async fn 只收拥有所有权的参数:不能有 self、&str、&mut Agent、This、Rest。它的 future 在调用返回之后才跑。
调用立刻返回一个 promise,兑现时结果用 IntoJs 转换(所以 Io<T> 式的错误会拒绝它)。
#[j8::object("later")]
impl Later {
async fn fetch_text(url: String) -> String { … }
}
阻塞的活:放到线程上
dune 把每个阻塞调用(文件、套接字、sleep)放到单独的线程上跑(host::Offload)。核心是:
fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<T> {
let this = self.get_mut();
if let Some(work) = this.work.take() { // 第一次 poll:起线程
let (tx, rx) = mpsc::channel();
let waker = cx.waker().clone();
std::thread::spawn(move || {
let _ = tx.send(work());
waker.wake(); // ⇐ 没有这一行,run_until_idle 永远不返回
});
this.done = Some(rx);
}
match this.done.as_ref().map(Receiver::try_recv) {
Some(Ok(v)) => Poll::Ready(v),
Some(Err(TryRecvError::Empty)) => Poll::Pending,
_ => panic!("offloaded work panicked"),
}
}
#[j8::object("fs")]
impl Fs {
async fn read_file(path: String) -> Io<j8::Bytes> {
Offload::new(move || Io::new(std::fs::read(&path).map(j8::Bytes), "open", &path)).await
}
}
自己造 promise:j8::Glue
异步活需要 &self、Agent、或者要能取消时,写普通方法,用 j8::Glue 自己造 promise:
Glue::spawn(a, future)建一个待定的 promise,把future交给事件循环,返回这个 promise;Glue::settle(value)是 future 必须产出的东西:兑现时value用IntoJs转换。
#[j8::class]
impl Timer {
fn wait<'gc>(&self, a: &mut Agent<'gc, '_>, ms: f64) -> Result<Value<'gc>, Error> {
let sleep = Sleep { cancelled: self.cancelled.clone(), /* … */ };
Glue::spawn(a, async move { Glue::settle(sleep.await) })
}
fn cancel(&self) {
self.cancelled.store(true, Ordering::Release);
}
}
future 必须 Send + 'static:从 self 里克隆出它要的东西(这里是 Arc<AtomicBool>)。因 JS 而就绪的 future(如上面的
cancel)不需要唤醒:每次兑现之后、停泊之前,循环会把所有 future 再 poll 一遍。
异步活属于发起它的 isolate:每个 Runtime 有自己的队列,只有它自己的 run_until_idle 兑现它,所以多个运行时可以共享一个平台。
没有事件循环的 isolate(手工建、没有 CreateParams { event_loop: true, .. })拒绝这种活,调用抛 TypeError。
在 Rust 里 await JS promise:j8::Promise<T>
反方向:这种类型的参数接收一个 JS promise,Rust 侧 .await 它。它是拥有所有权的参数,所以 async fn 绑定可以收:
#[j8::object("math")]
impl Math {
async fn double(p: j8::Promise<f64>) -> Result<f64, Error> {
Ok(p.await? * 2.0) // 拒绝原样传给这个函数自己的 promise
}
}
- 像
await一样接收参数:promise 直接监视(补丁上去的then不会被调用),thenable 被采纳,别的值算已经兑现; - 兑现的值在运行时线程上用
FromJs转成T;拒绝、或者转不过来,都以Err(Error::Exception(reason))出来, 所以?用同一个理由拒绝绑定自己的 promise; - 兑现会唤醒 future,所以它能配合
run_until_idle,在别处 poll 也行; - 永不兑现的 promise 让 future 一直待定,和 JS 里的
await一样,事件循环会一直等。
会被多次调用的 JS 回调(事件处理器),存一个 j8::Function,在 rt.enter 或另一个绑定里调用。
保持进程存活
run_until_idle 在没有待定的东西时返回。重复定时器、服务器之类靠一直留着一个待定的 future 保活,靠兑现它停止。
清掉的定时器应该兑现它的 promise(dune 的 Timer::cancel),否则循环会一直等它。
事件循环还不做的事
- 没有反应堆:需要 tokio(或别的运行时)反应堆的 future 永远不醒。
- 兑现按 poll 的顺序:同一回合就绪的 future 按被 poll 的顺序兑现,而不是完成的顺序;在乎顺序的 JS(定时器)要自己排。
- 循环里没有定时器:定时器和别的宿主任务一样(一个睡觉的线程,醒来唤醒它的 future)。
- 不能从 JS 取消:future 不能从 JS 一侧丢掉;用你自己的标志(dune 的
Timer::cancel)。 async fn不能收&self:用Glue::spawn。- future 里的 panic 会传出循环(从
eval/run_until_idle出去);兑现时出错会停下循环,剩下的活留在队列里。 - 微任务不分片:一次兑现把它的微任务一口气排空。
- 还不支持:报告未处理的拒绝、顶层
await。
模块
文件里的 ES 模块
rt.eval_module(text, file) 把 text 当 ES 模块跑。DefaultPlatform 按引用方的文件解析 import(规范化路径,不处理
node_modules)。别的规则(包、URL、虚拟文件系统)就自己写 Platform::load_module。
执行器侧:加载、链接、求值都是同步的;import 绑定实时读导出方的槽;ResolveExport 处理间接导出、export *、歧义;
支持命名空间对象、动态 import()、import.meta。顶层 await 还不支持。
Rust 写的原生模块:#[j8::module]
#[j8::module("myhost:kv", "kv")]
impl Kv {
fn get(key: &str) -> Option<String> { /* … */ }
}
j8::runtime! { pub MyHost { modules: [Kv], } }
import kv, { get } from "myhost:kv" 经 HostPlatform 工作。序言可以用 __j8_native["myhost:kv"] 拿到同一个对象,
比如用来实现 require。
自定义平台
dune 的 node: 模块是序言建的 JavaScript 对象,不是 Rust 类型。它用自己的平台 NodePlatform(dune/src/node/mod.rs)
把它们供给 import:load_module 返回一小段生成的 ES 模块,从 __j8_native 重新导出一个对象;别的说明符交给里面那层平台。
impl<P: Platform> Platform for NodePlatform<P> {
fn load_module(&self, referrer: &str, specifier: &str) -> Option<(String, String)> {
match Builtin::try_from(specifier) {
// "const m = globalThis.__j8_native.builtin(\"fs\"); export default m; export const readFileSync = m.readFileSync; …"
Ok(b) => Some((format!("node:{}", b.spec().0), b.source())),
Err(()) => self.inner.load_module(referrer, specifier),
}
}
fn now(&self) -> Duration { self.inner.now() }
fn wall_clock(&self) -> Duration { self.inner.wall_clock() }
fn print(&self, line: &str) { self.inner.print(line); }
}
impl<P: Pool> Pool for NodePlatform<P> { // Platform 要求 Pool:也转发
fn threads(&self) -> usize { self.inner.threads() }
fn run(&self, jobs: Vec<Task<'_>>) { self.inner.run(jobs); }
}
返回值的第一个元素是模块的规范名,模块按它缓存:第二次解析到同一个名字的 import 拿到同一个模块。解析成 None 的说明符让
import 失败,报 Error::Syntax("… Cannot find module '…'")。
CommonJS
j8 本身不知道 CommonJS。dune 的 require、module、node_modules 与 package.json(main / exports / imports)解析
都是序言里的 JavaScript(dune/src/node/loader.js),ESM 侧的裸说明符解析在 dune/src/node/esm.rs。见 dune。
Node-API
crates/j8napi 是 Node-API 在 j8 上的实现:原生插件(包括
napi-rs 写的模块)链接的那套 C 接口。napi_* 函数按原名导出;嵌入方把它们链接进来(静态链接,或者从
可执行文件导出给运行时加载的插件)。
用法
// 在某次 `Isolate::enter` 里,拿着插件所属 context 的 agent
let exports = j8napi::Env::open(&mut agent, napi_register_module_v1)?;
agent.set_named(agent.realm.global.into(), "addon", exports)?;
Env::open 建插件的环境(和 context 的全局对象一样长寿),调注册函数,给出它的 exports。
怎么落到 j8 上
napi_value是环境句柄栈上的一格,存值的原始字;句柄只在一次进入 isolate 里有效,期间不回收。- 插件的函数是能
new的NativeClosure:引擎按new.target.prototype造好this,所以 JS 类能继承插件的类。 napi_wrap与类型标签放在对象的私有成员里;被回收的宿主对象把终结回调排进队列,下次进回调时在 JS 线程上跑。napi_ref、挂起的异常、deferred 都用持久句柄。
与 Node 的差异
- 计数降到 0 的
napi_ref仍是强引用(堆还没有弱引用)。 - 字符串按 UTF-8 存:UTF-16 输入里落单的代理项会被替换。
- Buffer 就是普通的
Uint8Array(没有 Node 的Buffer类)。 - 异步工作与线程安全函数要求 isolate 带事件循环(
EventLoopSet);异步工作各开一个线程跑。napi_unref_threadsafe_function不会让事件循环提前结束;没有 libuv 循环(napi_get_uv_event_loop失败)。
门面包里用 feature napi 打开:j8::napi。
dune 与 dunx
dune/ 是建在 j8 上的 JavaScript 运行时,对标 Node 和 Bun;dunx(等同 dune x)跑 npm 包里的可执行文件,
对标 npx / bunx。它自成一包、不在 j8 的 workspace 里,像嵌入方一样依赖 crates.io 上发布的 j8——它本身就是
嵌入 j8 的完整范例。
安装
curl -fsSL https://j8.app238.com/install | bash # macOS、Linux
powershell -c "irm https://j8.app238.com/install.ps1 | iex" # Windows
npm install -g @jabberwocky238/dune
cargo install j8dune # crates.io 上 dune 已被占用;然后 ln -s dune ~/.cargo/bin/dunx
dune upgrade # 用 GitHub 上的最新 Release 替换自己
全部方式见安装 dune。npm 渠道照 Bun 的做法(dune/npm/):主包 @jabberwocky238/dune 只带占位脚本,用 optionalDependencies 依赖每个平台一个包
(@jabberwocky238/dune-linux-x64、@jabberwocky238/dune-linux-x64-musl、@jabberwocky238/dune-darwin-arm64、@jabberwocky238/dune-win32-x64 ……);npm 只装符合本机的那个,
postinstall 脚本把其中的二进制硬链接到占位脚本的位置、再把 dunx 链过去,所以 dune 启动时不经过 Node。
--ignore-scripts 时占位脚本经 Node 启动二进制。npm/pack.js 用编好的二进制排出一次发版的全部包。
一个二进制
只有一个可执行文件。dunx 是 dune 的链接,程序按启动时的文件名(dunx / dunx.exe)决定按哪套命令行解析,
和 bun / bunx 一样。
命令行
dune app.js [args] # Node 层(缺省):按 Node 规则当 CommonJS 或 ES 模块跑
dune run app.js [args] # 同上
dune --web app.mjs # 只要 Web 层:文件当 ES 模块跑
dune -e 'code' # 跑源码
dune -p 'code' # 跑源码并打印结果
dune - < app.js # 从标准输入读
dune # REPL(.help / .exit)
dune repl
dune --jit app.js # 打开 JIT
dune x <pkg> [args] # 等同 dunx
dune/src/cli/ 下每一层文件夹就是一层子命令:run/ 是 dune run,repl/ 是 dune repl,x/ 是 dune x
(包安装器也在 x/ 里)。--jit、--web 写在子命令前后都行;脚本路径之后的参数全部原样交给脚本
(dune a.js run x 把 run x 给 a.js)。
两层
每层是一个 j8::runtime! 声明,Node 层叠在 Web 层上:
j8::runtime! { pub Web { natives: [Stdio, Clock, Codec, Random, Timer, Http], prelude: PRELUDE, } }
j8::runtime! { pub Dune: Web { globals: [Process], natives: [Fs, Os, Child], prelude: PRELUDE, } }
| 层 | 目录 | 提供什么 |
|---|---|---|
| Web | src/web/ | WinterTC 最小公共 API:console、setTimeout / setInterval / queueMicrotask、structuredClone、EventTarget / Event / CustomEvent、AbortController / AbortSignal、DOMException、TextEncoder / TextDecoder、atob / btoa、URL / URLSearchParams、Blob / File、Headers / Request / Response / fetch(明文 http: 与 data:)、performance、crypto.getRandomValues / randomUUID、navigator、reportError |
| Node | src/node/ | process(是 EventEmitter;argv、env、exit、exitCode、nextTick、hrtime、stdout / stderr)、按 Node 规则解析的 require / module、ES 模块、Buffer、global、setImmediate,以及 fs(含 fs/promises)、path、os、events、util、buffer、assert、url、timers、child_process(同步)、crypto、module、string_decoder、perf_hooks |
搭法:
- 碰机器的部分写在 Rust 里,用
#[j8::object]/#[j8::class]绑定(web/mod.rs、web/timer.rs、web/http.rs、node/mod.rs、node/fs.rs)。会阻塞的活(文件、套接字、睡眠)写成async fn,在单独的线程上跑,到事件循环里兑现 promise(host.rs)。没有任何地方直接碰 GC。 - 接口本身是 JavaScript,一族一个文件(
web/*.js、node/*.js),作为序言运行。 - 内置模块用
__j8_native.define(name, factory)登记给require,NodePlatform把它们供给import(node:fs或fs, 带具名导出)。 - 事件循环是
j8::Runtime::run_until_idle:没有定时器和宿主任务时进程结束,退出码取process.exitCode。没人接住的错误 打印Uncaught …并以 1 退出,除非process.on('uncaughtException')接走了。
dunx
dunx cowsay hello # 包自己的可执行文件
dunx semver@^7 1.2.3 -r '>1.0.0' # 指定版本或范围;命令之后的选项都给可执行文件
dunx -p typescript tsc --version # 可执行文件名和包名不同
dunx --no-install json5 --version # 不访问 registry
查找顺序:
- 从当前目录往上找最近的
node_modules(没指定版本时先看.bin/<命令>); - 缓存(
$DUNE_CACHE,缺省~/.cache/dune/x); - 都没有就从 registry(
$DUNE_REGISTRY/$npm_config_registry,缺省 registry.npmjs.org)装进缓存。
安装器(src/cli/x/:spec.rs 解析说明符、registry.rs 取元数据、tree.rs 解依赖树、manifest.rs 读 package.json)
把依赖、适合本平台的可选依赖和 peer 依赖装成提升式的 node_modules,每个 tarball 都校验 integrity,不跑生命周期脚本。
JavaScript 可执行文件(按 #! 行或扩展名判断)在本进程的 Node 层里跑,其余(原生程序、shell 脚本)作为子进程跑。
实测能跑:cowsay、semver、json5、esbuild、biome、tsc 7。
还没有的
顶层 await、ES 模块 import CommonJS 时的具名导出(只有 default)、未处理的 promise 拒绝的报告、fetch 的 https:、
http / net 服务端、流、异步的 child_process.spawn、worker_threads、zlib、crypto 的哈希与加解密、Error.stack。
workerd 与 jumpheap
workerd
samples/workerd:用 j8 加载 Cloudflare Worker(export default { fetch } 的 ES 模块)与 Durable Object 的样例宿主。
cargo run -- examples/counter.js --bind COUNTER=Counter --request "GET /c/inc?name=a"
cargo run -- examples/counter.js --bind COUNTER=Counter --port 8787 # 起 HTTP 服务
cargo run -- examples/chat.js --bind ROOM=ChatRoom --port 8787 --storage .chat # WebSocket 聊天室
- Fetch API 子集、WebSocket 与 Durable Object 是
src/prelude.js里的 JavaScript; - 每个 Durable Object 有键值存储(Rust 的
KvStore)和 SQL 存储(ctx.storage.sql,每个对象一个 SQLite 文件,放在--storage目录下,不给就在内存里;src/sql.rs); --bind NAME=Class把一个 Durable Object 类交给 worker 的env。
WebSocket
接口照 workerd:new WebSocketPair()、server.accept()(或休眠式的 ctx.acceptWebSocket(ws, tags),事件交给对象的
webSocketMessage / webSocketClose,配 ctx.getWebSockets(tag)、serializeAttachment)、send、close、
addEventListener,以及 new Response(null, { status: 101, webSocket: client })。
网络层(src/ws.rs)是整个进程一个 epoll 反应堆线程(mio):非阻塞地 accept、读请求、解析帧、写出,从不跑 JS。请求与消息
经单消费者的流交给事件循环,JS 去 await(net.accept(server)、net.recv(id));答复、升级、帧作为命令回到反应堆。
没有消息时事件循环睡着。
examples/chat.js 是聊天室:消息先写进对象的 SQLite 表,再发给房间里所有人,新来的人先收到存下的历史。tests/chat.rs
加压跑它:八个客户端、两轮并发发言、中间全场沉默五秒(服务器不能占 CPU)、每个客户端看到的次序一致、最后在同一份存储上重启、
历史按原次序重放。
一个进程跑一千个 Worker
--instances N 在一个进程里起 N 份 Worker:各自一个运行时(isolate、上下文、Durable Object、<storage>/<i>),各自一个端口,
都在同一个事件循环集合上,--threads 个 loop 线程。tests/workerds.rs 照此跑一千个聊天室:所有房间同时发言
两轮、中间全场沉默五秒(整个进程不能占 CPU)、最后重启、每间重放历史。
所有实例共用一份 CodeCache(序言与 Worker 的模块只编译一次)和一个 epoll 反应堆线程。
jumpheap
samples/jumpheap:几个常驻的 j8 worker 分在不同进程里,JS 对象互相引用对方的堆。
每个进程有一个 paragc 公开堆(/dev/shm 里的内存文件);它的 worker(workerd 式的 export default { fetch })在那里建
JS 矩阵,经 HTTP 发给别的 worker,也监听别人发来的。收到的是一个 object 事件,带一个 JS Matrix:对象在接收方自己的
isolate 堆里,各行是指着发送方堆的 Float64Array,不是拷贝。上面的所有计算都是普通 JS。
cargo run --release -- examples/matrix.js --name wa --dir /dev/shm/jumpheap # 打印端口
| JS 接口 | |
|---|---|
await heaps.matrix(rows) | 本进程堆里新建 rows × 100000 的全零 Matrix |
matrix.data[i] | 第 i 行:公开堆内存(本进程的或别的进程的)上的 Float64Array |
matrix.rows、matrix.cols、matrix.local | 形状;是否在本进程堆里 |
await heaps.send(url, matrix, name, task) | 把 matrix 交给 url 处的 worker,得到它的回应 |
heaps.addEventListener('object', e => …) | 收到矩阵:e.object、e.name、e.task;e.respondWith(value) 回给发送方 |
收到的矩阵在发送方堆里占一个入口,只要接收方还持有它任何一行的 buffer,各行就活着;发送方进程死后,它写进别的堆的内容还在。
tests/three.rs 起三个 worker 互相发矩阵、中途杀掉一个,检查结果仍然正确。
调试与基准工具
j8bcdbg:看字节码
samples/j8bcdbg:编译 JS、按函数列出字节码,格式照 V8 的 --print-bytecode(例子见字节码)。
cd samples/j8bcdbg
cargo run -- compile a.js # `-` 读标准输入
cargo run -- compile -e 'let s = 0; for (let i = 0; i < 10; i++) s += i; s'
cargo run -- compile a.js -o a.txt # 写到文件
JIT 的调试开关
| 环境变量 | 作用 |
|---|---|
J8_JIT_LOG=1 | 打印每次编译(指令数、字节数、耗时)与每次去优化(原因、位置) |
J8_JIT_IR=1 | 打印编译出的图 |
J8_JIT_BIN=<目录> | 把每份机器码写成 f<函数号>-<入口>.bin,可以用 objdump 反汇编 |
J8_NOJIT=1 | 基准样例里只用解释器 |
三组基准
同一组 JS 基准(samples/benchv8/bench/*.js,11 个)在不同引擎上比,每个脚本的完成值是校验和,所有引擎必须一致:
| 样例 | 对比对象 | 说明 |
|---|---|---|
samples/benchv8 | V8(带 JIT)与 V8 --jitless | 经 rusty_v8 152.2.0,会下载 V8 预编译库 |
samples/benchjsc | JavaScriptCore(带 JIT)与 JSC_useJIT=false | 用系统的 WebKitGTK 库(C API) |
samples/benchquickjs | QuickJS(quickjs-ng 0.16.2) | 经 rquickjs 从源码编;QuickJS 没有 JIT |
cd samples/benchv8
cargo run --release # 三种引擎各跑一遍,打印对比表
cargo run --release -- --engine j8 # 只跑一个
cargo run --release -- --runs 10 # 每个基准跑几次,取最短(缺省 5)
- 每个引擎在自己的子进程里跑(
--jitless是进程级的开关); - 计时只算编译 + 执行,每次用新的执行环境,取最短的一次;
- 都是自成一包的 workspace,普通的
cargo build --workspace不会拉 V8 的预编译库。
结果与分析见性能。
test262 与测试
test262
tests/test262 是 tc39/test262 子模块(浅克隆,git submodule update --init 拉取),
运行器 tests/test262.rs 是根包的测试(harness = false,不发布)。
cargo test --release --test test262 # 只跑基线里的用例,掉了就失败
cargo test --release --test test262 -- language/expressions/addition built-ins/Math # 跑这些目录
J8_TEST262_JIT=1 cargo test --release --test test262 # 开 JIT(每个函数第一次调用就编)对拍
J8_TEST262_VERBOSE=1 cargo test --release --test test262 -- <路径> # 逐条列出没过的原因
J8_TEST262_UPDATE=1 cargo test --release --test test262 -- <路径> # 结果写回基线
- 每个用例一个子进程、10 秒超时;结果分 pass / fail / unsupported(j8 报
Error::Unsupported)/ skip / timeout / crash,按目录汇总; - 基线
tests/test262.passing:过了的用例一行一个,当前 42,443 行;不带参数时只跑它做回归检查; - 非严格模式与
onlyStrict(严格模式跑);模块用例先跑 harness 脚本再跑模块; $262宿主对象提供global/evalScript/gc/detachArrayBuffer(createRealm抛 TypeError);- 不支持写法的报错行号含拼进去的 harness。
每次提交零回归是 j8 的硬规矩,开着 JIT 也要过同一份基线(JIT 阈值设成 0,每个函数第一次调用就编,最大化覆盖)。
其他测试
| 测试 | 内容 |
|---|---|
tests/runtime.rs、tests/event_loop.rs、tests/terminate.rs | 运行时、事件循环、中止执行 |
tests/binding.rs、tests/bindings_more.rs | 绑定宏 |
crates/j8bytecode/tests/v8.rs | 解码 V8 打印的 738 条指令,逐条核对 |
crates/j8executor 的 javascript_semantics | 逐条确定的 JS 语义表 |
crates/j8jit/tests、j8taskqueue/tests、j8lockfree/tests、j8napi/tests | 各 crate 自己的测试 |
samples/workerd/tests | 聊天室压测、一千个 Worker |
samples/jumpheap/tests/three.rs | 三进程跨堆矩阵 |
怎么加一个特性
路线图里每一阶段的流程:
- 先往语义表加用例;
- clippy 干净;
- 在快照里跑 test262 基线,零回归;
- 用
J8_TEST262_UPDATE=1把相关目录里新通过的用例记进基线; - 提交、推送(j8 在 GitHub 上走分支 + PR)。
单元测试只钉确定的事实,每次只跑一个,用 timeout 15 限时。
性能
对 V8
samples/benchv8 的结果(j8 带 JIT,--runs 10,钉在性能核上,负载低于 1)。11 个基准在三种引擎上的校验和全部一致。
| 基准 | j8 ms | V8 jitless ms | V8 ms | j8 / jitless | j8 / V8 |
|---|---|---|---|---|---|
| fib | 1.2 | 9.0 | 1.3 | 0.1× | 0.9× |
| loop | 58.3 | 185.0 | 82.8 | 0.3× | 0.7× |
| objects | 0.9 | 13.6 | 2.5 | 0.1× | 0.4× |
| array | 40.8 | 13.0 | 6.5 | 3.1× | 6.3× |
| sort | 65.8 | 32.1 | 16.5 | 2.1× | 4.0× |
| string | 27.8 | 11.7 | 11.3 | 2.4× | 2.5× |
| closures | 2.1 | 17.2 | 2.3 | 0.1× | 0.9× |
| classes | 1.4 | 23.3 | 2.8 | 0.1× | 0.5× |
| collections | 52.8 | 27.9 | 21.3 | 1.9× | 2.5× |
| json | 24.9 | 11.6 | 11.5 | 2.2× | 2.2× |
| regexp | 12.4 | 3.0 | 1.8 | 4.2× | 7.0× |
| 几何平均 | 0.6× | 1.7× |
(比值 < 1 表示 j8 更快。数字来自 samples/benchv8/benchmark.md,以仓库为准。)
JIT 对它们做了什么
- fib:每个 JS 函数一个 native 函数,直接调用(参数在寄存器里、结果经第二个返回寄存器不装箱),递归调用内联两层;
全局
fib经纪元缓存读; - closures:闭包内联进循环(按函数身份检查),它的上下文槽住在寄存器里,
% 100000变成乘法; - classes / objects:构造器与方法内联,不逃逸的对象从不分配(字段当值、跨循环轮次也是:OSR 进来的循环剥一次皮), shape 检查与读取外提到循环外;
- loop:
(s + i * i) % 1000003里i * i超出 int32,按 double 的 int64 取余跑。
array、sort、string、collections、json、regexp 的时间花在内建函数(和 GC)里,JIT 暂时帮不上,是下一步的重点。
怎么量
- 计时只算编译 + 执行,每次新环境,取最短;
- 钉在性能核上(
taskset -c 0-3)、负载低时跑; - 看单个改动的影响要看全部基准,不只看目标那一个;
- 逐行热点可以用 callgrind;量指令数用
perf stat -e instructions:u。
代码约定
j8 的代码风格有一套明确的规矩,PR 要遵守。
结构
- 子模块私有
mod,crate 根pub use平铺导出,⛔pub mod;可见性靠私有mod,只写pub。 - 依赖方向:各层只依赖
j8framework;j8framework不依赖任何层;j8bytecode是根。 dune/与samples/*各自成包(自带空[workspace]),按版本依赖发布的j8,⛔ 路径依赖。新接口还没发版时, 本地用命令行--config打[patch.crates-io],⛔ 把 patch 或带 patch 生成的锁文件提交进仓库。
Rust
- ⛔
static与'static生命周期(枚举里的&'static str名字除外);不留全局 / 静态存储。后台任务用Task<'t>借用调用方数据。 - 字符串反序列化后立即转枚举,⛔ 拿字符串做判断。
- 转换走
From/TryFrom/Into,⛔ 手写to_xxx式转换函数(需要额外参数时除外)。 - 函数尽量是某个类型的方法:参数里只有一个可变类型就挂给它,有大结构体就挂给大结构体。
- 尽量用引用、借用、切片。
- 系数、阈值、字段编码一律具名
const,⛔ 裸数字。 - 代码里不写出处(量测时间、机器、提交号):这些进提交说明。
- 能用宏与生成器减少代码就用:字节码表从 V8 头文件生成,堆结构体用
#[heap],绑定用#[j8::class]。 - 源码里不写注释;文档放在 README、指南和本书里。
堆
- 回收会搬对象:⛔ 把
Gc或对象地址存进不被追踪的地方。 - 值进堆之后才能写它的槽。
- 只做停顿式回收,⛔
mark_concurrently。 - 无锁结构手写在 j8lockfree,⛔ crossbeam。
详见堆与 GC。
测试
- 单元测试只钉确定的、有真实数据背书的事实,不确定的不写(否则钉住的全是错误的特征)。
- 每次只跑一个单元测试,
timeout 15。 - test262 基线零回归。
文档
- 英文为主:仓库和每个发布的子包都有
README.md(英文,缺省)+README.zh-CN.md译本,互相链接。 - 本书以英文为主、附中文译本,改一种语言时请同步另一种。
提交
- j8 在 GitHub(0x00-Community/j8)上走分支 + PR,main 受保护;PR 合并后分支自动删除。
路线图
j8 的主线是 test262 通过率(PLAN.md)。每一阶段:往语义表加用例 → clippy 干净 → 在快照里跑基线零回归 → 记下新通过的用例 → 提交。
范围外:Temporal、intl402、ShadowRealm、显式资源管理(using / DisposableStack)、import defer、装饰器、source phase imports。
已完成
| 阶段 | 内容 |
|---|---|
| 1 基础设施 | 动态代码(eval、Function、生成器 / async 构造器)、早期错误、严格模式、全局声明检查、$262 |
| 2 Object / Array / 属性模型 | 规范的内部方法、数组的稠密部分与空洞、Object 补全、Array 方法对类数组通用、内建函数的 length、按 new.target 定原型 |
| 3 反射与迭代器 | Reflect、Proxy(含 revocable)、迭代器助手、Set 方法、Map.groupBy |
| 4 二进制数据 | ArrayBuffer(可调大小、transfer、detach)、SharedArrayBuffer、DataView、12 种 TypedArray(含 Float16)、Atomics |
| 5 Date / RegExp / 字符串与数 | Date(本地时区按 UTC)、RegExp 的 Symbol 协议与 d 标志、String 补全、精确的数格式化、Math.sumPrecise、Promise 重写在 NewPromiseCapability 上 |
| 6 语言的动态部分 | 直接 eval、with、annexB 块级函数提升、生成器参数初始化、arguments 与形参联动、模块与动态 import() |
还差的
- 模块的顶层
await、import defer / source phase; - 形参表达式里 eval 声明
var arguments的冲突规则; - eval 代码里的 annexB 块级函数;
- 字符串改为能表示落单代理项的存储(当前 UTF-8);
WeakRef/FinalizationRegistry的真弱引用(当前强引用);- Date 的本地时区。
JIT
路线是跳过基线编译器,直接做推测式优化层:内联、逃逸分析、去优化、OSR 已经落地;接下来是让内建函数密集的基准 (array、sort、string、collections、json、regexp)受益,目标是在常用基准上超过带 JIT 的 V8。
运行时
- dune:补齐顶层
await、https:、http/net服务端、流、异步子进程、worker_threads、zlib、crypto哈希等; npm 包@jabberwocky238/dune发布; - Node-API:真弱引用。
术语表
| 术语 | 含义 |
|---|---|
| acc(累加器) | 字节码隐式的结果寄存器,大多数指令读写它 |
| Agent | 一次运行的上下文;JS 运算语义挂在它上面 |
| Context | 执行上下文:全局对象与内建原型 |
| 上下文槽 / Env | 被闭包捕获的变量所在的堆上环境 |
| CodeCache | 多个 executor 共享的字节码缓存 |
| deopt(去优化) | 推测落空,从机器码回到解释器 |
| EventLoop / EventLoopSet | 一个 JS 事件循环 / 跑很多事件循环的 loop 线程组 |
| 反馈槽(feedback slot) | 字节码上记录类型 / shape 信息的位置,JIT 据此推测 |
| FrameState | 守卫处每个解释器寄存器存着什么,去优化时据此重建帧 |
| ’gc 品牌 | 一次 Isolate::enter 的生命周期;带它的值出不了这次进入 |
| GcCell / ValueCell | j8 在 paragc 上的可变单元:整块数据的快照 / 单个值 |
| Global | 持久句柄,跨多次 enter 存活 |
| IC(内联缓存) | 每个属性访问点按 shape 缓存的结果 |
| Ignition | V8 的解释器;j8 的字节码与它逐字节一致 |
| Intrinsics | 往 Realm 装内建对象的接口,j8builtins 实现 |
| Isolate | 独立的 JS 世界:一个 GC 堆 |
| NaN-boxing | 把非数的值塞进 NaN 位模式的一个 64 位字表示 |
| OSR(栈上替换) | 从循环中途切进机器码 |
| paragc | j8 用的 GC 库 |
| Platform | 宿主借给引擎的线程池、时钟、输出、模块加载 |
| 序言(prelude) | 运行时装好绑定后跑的 JS,用来搭公开接口 |
| Realm | 规范里的领域:一套全局对象与内建 |
| rope | 字符串拼接的延迟表示:两半加总长 |
| Shape(隐藏类) | 对象属性的布局,相同建法的对象共享 |
| 短 Star | Star0 … Star15:不带操作数的单字节寄存器写 |
| Tier | 执行器的 JIT 钩子 |
| TDZ(暂时性死区) | let / const / class 初始化之前的区域 |
| 蹦床(trampoline) | 每个函数一个跳转,指向它的机器码或解释器 |
__j8_native | 运行时的隐藏注册表对象 |