Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

前言

这本书完整讲解 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 / arm64dune-darwin-x64.tar.gz / dune-darwin-arm64.tar.gz仅 x64
Windows x64 / arm64dune-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
bytecodej8::bytecode:字节码定义、编码 / 解码
compilerj8::compiler:JS ⇒ 字节码(含 bytecode)
executorj8::executor:字节码执行器(含 compiler)
builtins / platform内建对象 / 标准库平台
jitj8::jit:JIT(x86-64 Unix 和 Windows,含 executor)
jsonj8::Json<T>:经 serde 以 JSON 形状过界的 Rust 值
napij8::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
j8compilerJS ⇒ 字节码(oxc 解析,代码生成照 V8 的 BytecodeGenerator)
j8executor字节码执行器:实现 Engine,带内联缓存、分片执行与 JIT 钩子
j8jit推测式 JIT(x86-64 Unix 和 Windows):实现执行器的 Tier
j8builtins标准内建对象:实现 Intrinsics
j8platformPlatform 的标准库实现:线程池、时钟、模块加载
j8bindingRust ⇄ JS 绑定的运行时(FromJs / IntoJs、宿主对象)
j8napiNode-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 输出、模块加载
Intrinsicsj8builtins::Builtins往新 Realm 装全局对象与内建构造器
Enginej8executor::Executor执行入口:eval,可续跑的 start / resume
Invoke执行器内建函数回调 JS(map 的回调、getter……)
Tierj8jit::Jit执行器问「这个函数 / 循环要不要编」

一段 JS 的一生

以 dune -p 'let s = 0; for (let i = 0; i < 1e6; i++) s += i; s' 为例:

  1. 宿主建环境。 dune 用 j8::runtime! 声明的运行时在一个事件循环线程上建 Isolate(一个 GC 堆)、 Executor、Context(Builtins 装好全局对象),跑完 JS 序言(搭一个宿主)。
  2. 编译。 执行器拿到源码,交给 j8compiler:oxc 解析并做语义检查(早期错误在这里报 SyntaxError), 作用域分析决定每个变量放寄存器、上下文槽还是全局对象,代码生成器照 V8 的 BytecodeGenerator 出字节码, 结果是 j8bytecode::Module(一组 SharedFunction,每个带 BytecodeArray)。 多个运行时跑同样的序言时,CodeCache 让同一份源码只编译一次(执行器)。
  3. 解释。 执行器把字节码解码成「线程化代码」:每条指令带着跑它的处理函数,处理函数之间直接跳转。 属性访问经内联缓存按 shape 命中。每跑一千来条指令检查一次事件队列,每一万条让出一次(分片),让 GC 有机会回收。
  4. 升层。 循环每次往回跳都给 profiler 计数。过阈值后执行器问 Tier:JIT 依据内联缓存的反馈把函数建成 推测性 SSA 图(s、i 猜成 int32),优化后直接出 x86-64 机器码,从循环头切进去跑(OSR)。
  5. 去优化。 推测落空(比如 s 超过 int32),守卫跳到冷路径,j8_deopt 按记下的帧状态重建解释器帧, 解释器接着跑;JIT 留下提示,下次编译那里改用 double。
  6. 结束。 结果是一个 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 键生成什么
bytecodesBytecode(repr(u8),V8 的编号,共 215 个)与每个字节码的 operand_types()、implicit_register_use()
operand_typesOperandType、OperandTypeInfo
implicit_register_use是否读 / 写 / 破坏累加器、是否写短 Star
runtime / intrinsicsCallRuntime / 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):

j8V8内容
Module—一份源码编出的全部函数,第一个是顶层
SharedFunctionSharedFunctionInfo名字、种类(FunctionKind)、是否严格、length、形参个数、作用域信息、字节码
BytecodeArrayBytecodeArray代码字节、常量池、异常处理表、参数 / 寄存器个数、反馈槽种类、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)加一个 profilerv8::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 / EventLoopSetJS 事件循环与跑它们的 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 生命周期替代 V8 HandleScope 的方式。
  • 要跨 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.rsPromise 与微任务:resolve / reject、then 反应、驱动 async 协程、排空队列
module.rs模块记录、导入导出条目、ResolvedBinding
proxy.rsProxy:内部方法入口分派到 trap,带不变式检查
typed.rs、backing.rsTypedArray 元素;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.rsObject、Function、Reflect / Proxy
array.rs、typed.rs、buffer.rsArray、TypedArray(12 种,含 Float16)、ArrayBuffer / SharedArrayBuffer / DataView / Atomics
string.rs、text.rsString、Symbol
regexp.rs、dfa.rsRegExp(regress + 一个 DFA 快路)
json.rsJSON
math.rs、bigint.rs、date.rsMath、BigInt、Date
collections.rs、weak.rsMap / Set、WeakMap / WeakSet / WeakRef / FinalizationRegistry
promise.rs、asyncgen.rs、iter.rsPromise、异步生成器、迭代器与迭代器助手
error.rsError、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 是第二个引擎:对于 regex crate 在全 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 队列。队列就是事件循环, 里面有三种任务:

  1. 脚本:每次跑一个检查间隔的步数(缺省约一千条指令,V8 在函数入口与回跳处的中断检查),然后让回队列;
  2. 兑现:用宿主任务的结果兑现一个 promise,再排空微任务;
  3. 轮询:被唤醒的宿主 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)、并查集父指针、就绪队列(分段 MPMC Fifo)都是原子操作;
  • 图不成环:依赖只能写已经塞进来的任务,依赖表在塞进来时读一次 ⇒ 不会死锁;
  • 配额按字节码条数:用完没做完返回 Flow::Yield,回就绪队列排队;每次 run 还有总预算,花完返回 Stop::Budget;
  • 借用而非 'static:任务活在 'a 里、可借用调用方数据,只要求 Send。

无锁基础件

crates/j8lockfree:j8 手写的无锁基础件(no_std + alloc),j8framework 与 j8taskqueue 共用。j8 的规矩是 堆与调度全程无锁,无锁结构自己写,⛔ 引入 crossbeam。

类型是什么
Fifo多生产者多消费者先进先出队列(位置单调递增、分段槽表)
SegVec只追加的分段向量:下标稳定、可并发读;整理与取出要独占
PushList只压入的 Treiber 栈:整表取走或封口(封口后压入被退回)
Stock库存:独占时整理成只读数组,并发时原子游标成批领取
DequeChase–Lev 工作窃取双端队列:主人凭据 Owner 压 / 弹,别人偷
OnceBox只发布一次的惰性值(并发初始化各算各的,赢的留下)
AtomicRefCell可跨线程的 RefCell:借用冲突时报错,从不等待

共同的做法:只增不减,独占时释放

并发期间只增加内存(新段、旧缓冲留着),释放推迟到独占(拿到 &mut 或析构)时。所以:

  • 不需要危险指针(hazard pointer);
  • 不需要纪元回收(epoch-based reclamation);
  • 没有 ABA 问题。

代价是并发期间内存只涨不落,但这些结构的使用方式(事件循环的队列、任务图的下游表)都有天然的独占时刻可以整理。

谁在用

使用方用什么
j8taskqueueFifo 作就绪队列、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::HostPlatformruntime! 实现的 trait / 给它供原生模块的平台(无状态,运行时可共享)
j8::framej8framework:Agent、Error、ErrorKind、Value、Platform、Source ……
j8::platform::DefaultPlatform标准库平台
j8::executor::Executor字节码执行器;with_tier 加 JIT
j8::Promise<T>在 Rust 里 await 的 JS promise
j8::GlueGlue::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
            }
        }
    })
}

步骤总是一样的:

  1. X::platform(inner) 把一个平台包成运行时 X 的 HostPlatform。它要活得和运行时一样久:Runtime<'p> 借用它。
  2. j8::EventLoopSet::scope(&platform, threads, |set| …) 在闭包期间起好运行时要住的 loop 线程。
  3. X::runtime(set, executor) 在负载最轻的 loop 线程上建 isolate 和上下文、装好一切、跑序言。序言抛异常在这里以 Err 返回。之后的每次调用(eval、enter、run_until_idle)都是发给那个线程的消息,并等它回答;任何宿主线程都能发。
  4. rt.eval(text, file) 跑一段脚本,返回 Global(活过这次调用的句柄),rt.text(&g) 按 ToString 转成字符串。
  5. 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::setdune/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剩下的全部实参
&strToString 后借用
其他依次用 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::BytesArrayBuffer / 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, } }
层目录提供什么
Websrc/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
Nodesrc/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

查找顺序:

  1. 从当前目录往上找最近的 node_modules(没指定版本时先看 .bin/<命令>);
  2. 缓存($DUNE_CACHE,缺省 ~/.cache/dune/x);
  3. 都没有就从 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/benchv8V8(带 JIT)与 V8 --jitless经 rusty_v8 152.2.0,会下载 V8 预编译库
samples/benchjscJavaScriptCore(带 JIT)与 JSC_useJIT=false用系统的 WebKitGTK 库(C API)
samples/benchquickjsQuickJS(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三进程跨堆矩阵

怎么加一个特性

路线图里每一阶段的流程:

  1. 先往语义表加用例;
  2. clippy 干净;
  3. 在快照里跑 test262 基线,零回归;
  4. 用 J8_TEST262_UPDATE=1 把相关目录里新通过的用例记进基线;
  5. 提交、推送(j8 在 GitHub 上走分支 + PR)。

单元测试只钉确定的事实,每次只跑一个,用 timeout 15 限时。

性能

对 V8

samples/benchv8 的结果(j8 带 JIT,--runs 10,钉在性能核上,负载低于 1)。11 个基准在三种引擎上的校验和全部一致。

基准j8 msV8 jitless msV8 msj8 / jitlessj8 / V8
fib1.29.01.30.1×0.9×
loop58.3185.082.80.3×0.7×
objects0.913.62.50.1×0.4×
array40.813.06.53.1×6.3×
sort65.832.116.52.1×4.0×
string27.811.711.32.4×2.5×
closures2.117.22.30.1×0.9×
classes1.423.32.80.1×0.5×
collections52.827.921.31.9×2.5×
json24.911.611.52.2×2.2×
regexp12.43.01.84.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 / ValueCellj8 在 paragc 上的可变单元:整块数据的快照 / 单个值
Global持久句柄,跨多次 enter 存活
IC(内联缓存)每个属性访问点按 shape 缓存的结果
IgnitionV8 的解释器;j8 的字节码与它逐字节一致
Intrinsics往 Realm 装内建对象的接口,j8builtins 实现
Isolate独立的 JS 世界:一个 GC 堆
NaN-boxing把非数的值塞进 NaN 位模式的一个 64 位字表示
OSR(栈上替换)从循环中途切进机器码
paragcj8 用的 GC 库
Platform宿主借给引擎的线程池、时钟、输出、模块加载
序言(prelude)运行时装好绑定后跑的 JS,用来搭公开接口
Realm规范里的领域:一套全局对象与内建
rope字符串拼接的延迟表示:两半加总长
Shape(隐藏类)对象属性的布局,相同建法的对象共享
短 StarStar0 … Star15:不带操作数的单字节寄存器写
Tier执行器的 JIT 钩子
TDZ(暂时性死区)let / const / class 初始化之前的区域
蹦床(trampoline)每个函数一个跳转,指向它的机器码或解释器
__j8_native运行时的隐藏注册表对象