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 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)