Preface
This book explains j8 from end to end: a JavaScript engine written from scratch in Rust, layered like V8. JS is compiled to bytecode that matches V8’s Ignition byte for byte, interpreted by the executor, and hot functions and loops go to a speculative JIT that emits x86-64 machine code. The heap is paragc.
Install 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 # anywhere with npm
More in Installing dune.
How to read it
| You want to … | Start here |
|---|---|
| see it run | Quick start |
| understand the design | Architecture, then “Inside the engine” in order |
| build your own runtime on j8 | the “Embedding j8” part, from Building a host |
| run scripts and npm packages with dune | dune and dunx |
| contribute | Code conventions, test262 and testing |
Conventions
- Paths are relative to the j8 repository root, e.g.
crates/j8executor/src/ic.rs. - “V8” means the V8 engine itself; j8 tracks V8 15.2.124, the version inside rusty_v8 152.2.0.
- The book describes the repository’s main branch (November 2026). j8 0.4.0 on crates.io predates the V8 bytecode and the speculative JIT; the next release carries them.
- Numbers (test262 passes, benchmark times) are as of writing; the repository has the current ones.
The book’s source is the repository’s mdbook/ directory, in English (en/) and Chinese (zh-CN/). Pull requests
welcome; please keep both languages in step.
What j8 is
j8 is a JavaScript engine written from scratch in Rust. Apart from the parser (oxc), everything from the bytecode, the executor and the JIT to the garbage collector is its own code: there is no C++ engine underneath.
It follows V8’s layering:
JS source ─ oxc parse ─ j8compiler ─▶ V8 Ignition bytecode ─ j8executor interprets ─┐
├─▶ result
hot functions / hot loops ─ j8jit speculative compile ─▶ x86-64 ────┘
Design choices
| 🦀 All Rust | oxc parses; everything else is j8’s own code. |
| 🧱 Bytecode first | No AST interpreter: all JS (eval and Function included) is compiled to bytecode before it runs. |
| 🔣 V8’s bytecode | The bytecode list, operand encoding, registers and frame layout match V8 Ignition byte for byte; the tables are generated from V8’s headers. |
| 🧬 Speculative JIT | Feedback from the inline caches turns bytecode into a speculative SSA graph: inlining, escape analysis, loop-invariant code motion, OSR, deoptimization. |
| ♻️ paragc heap | Immix-style blocks and lines, young collection plus reference counting of old objects, parallel marking and sweeping; the 'gc brand lifetime keeps handles from escaping at compile time. |
| 🚫 No global state | No static, no 'static; background tasks borrow the caller’s data, and many isolates share one thread pool. |
| 🧩 Embeddable | #[j8::class] / #[j8::object] / #[j8::function] bind a Rust type to JS in one line; j8::runtime! assembles a runtime. |
The main line: test262
j8’s main line is the test262 pass rate. The baseline tests/test262.passing is
42,443 cases (sloppy plus onlyStrict; without Temporal, intl402 and the like, see the Roadmap).
Every commit must keep it with zero regressions, and the same baseline runs with the JIT on.
What is in the repository
| Directory | Contents |
|---|---|
crates/ | the engine itself, a dozen crates (see Architecture) |
src/ | the facade crate j8: re-exports the crates by feature, exports the binding macros |
dune/ | a runtime on par with Node and Bun, plus dunx (npx / bunx) |
samples/ | sample hosts and tools: workerd, jumpheap, j8bcdbg, three benchmark suites |
tests/ | integration tests and the test262 runner |
tools/ | v8bytecodes.py: generates the bytecode tables from V8’s headers |
mdbook/ | this book |
Releases
Every crate is on crates.io: the facade j8 picks components by feature, and the sub-crates (j8bytecode,
j8compiler, j8executor …) are published on their own too. dune is published as j8dune (the name dune is taken).
MIT licensed.
Installing dune
dune (and its package runner dunx) ships as one prebuilt executable per platform, attached to every j8 release on GitHub and published to npm.
macOS and Linux
curl -fsSL https://j8.app238.com/install | bash
The script picks the build for your machine (x64 or arm64; glibc or musl on Linux; the native build under Rosetta),
checks it against the release’s SHA256SUMS, puts dune and the dunx link in ~/.dune/bin and adds that directory
to PATH in your shell’s startup file (bash, zsh or fish).
A given release:
curl -fsSL https://j8.app238.com/install | bash -s v0.4.0
Windows
powershell -c "irm https://j8.app238.com/install.ps1 | iex"
Installs dune.exe and dunx.exe to %USERPROFILE%\.dune\bin and adds it to the user PATH. A given release:
& ([scriptblock]::Create((irm https://j8.app238.com/install.ps1))) -Version v0.4.0
npm
npm install -g @jabberwocky238/dune
npm installs only the platform package that fits (@jabberwocky238/dune-linux-x64, @jabberwocky238/dune-darwin-arm64,
@jabberwocky238/dune-win32-x64 …) and the postinstall script puts its binary in place, so dune starts without Node.
Cargo
cargo install j8dune # the name dune is taken on crates.io; then ln -s dune ~/.cargo/bin/dunx
Upgrading
dune upgrade # the latest release
dune upgrade --tag v0.4.0
dune upgrade downloads the release for its own platform from GitHub, verifies the checksum and replaces itself
(and dunx when it is a copy rather than a link).
Settings
| Variable | |
|---|---|
DUNE_INSTALL | install root for the scripts (default ~/.dune; binaries in its bin/) |
DUNE_RELEASES | where the scripts download releases from (default https://github.com/0x00-Community/j8/releases) |
Platforms
| Platform | Release archive | JIT |
|---|---|---|
| Linux x64 (glibc 2.17+ / musl) | dune-linux-x64.tar.gz / dune-linux-x64-musl.tar.gz | yes |
| Linux arm64 (glibc 2.17+ / musl) | dune-linux-arm64.tar.gz / dune-linux-arm64-musl.tar.gz | no |
| macOS x64 / arm64 | dune-darwin-x64.tar.gz / dune-darwin-arm64.tar.gz | x64 only |
| Windows x64 / arm64 | dune-win32-x64.tar.gz / dune-win32-arm64.tar.gz | no |
The JIT emits x86-64 machine code on Unix; elsewhere --jit prints a notice and runs on the interpreter.
Uninstalling
Delete ~/.dune (or %USERPROFILE%\.dune) and the lines the script added to your shell’s startup file (marked
# dune), or npm uninstall -g @jabberwocky238/dune.
Quick start
As a library
cargo add j8 # default feature `runtime`: executor + built-ins + standard platform
cargo add j8 --features jit # plus the x86-64 JIT (x86-64 Unix)
cargo add j8 --no-default-features --features compiler # only JS ⇒ bytecode
The smallest evaluation:
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" })?;
Real hosts rarely handle isolates directly; they declare a runtime with j8::runtime!, see
Building a host.
Features
| feature | brings |
|---|---|
runtime (default) | executor + builtins + platform |
bytecode | j8::bytecode: bytecode definitions, encoding / decoding |
compiler | j8::compiler: JS ⇒ bytecode (includes bytecode) |
executor | j8::executor: the bytecode executor (includes compiler) |
builtins / platform | built-in objects / the standard-library platform |
jit | j8::jit: the JIT (x86-64 Unix, includes executor) |
json | j8::Json<T>: Rust values crossing as JSON-shaped data through serde |
napi | j8::napi: Node-API |
taskqueue / lockfree | the task queue / lock-free building blocks |
full | all of the above |
Running JS with dune
curl -fsSL https://j8.app238.com/install | bash # or npm i -g @jabberwocky238/dune, see Installing dune
dune app.js # Node-compatible layer (default)
dune --web app.mjs # Web-standard APIs only
dune -p '[1, 2, 3].map(x => x * 2)'
dune --jit bench.js # with the JIT
dune # REPL
dunx cowsay hello # run an npm package's executable
See dune and dunx.
From source
git clone https://github.com/0x00-Community/j8 && cd j8
cargo build --release
git submodule update --init # fetch test262
cargo test --release --test test262 # the regression baseline
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/ and samples/* are packages of their own, outside the workspace, and depend on the published j8 by version,
as an embedder would.
Architecture: the life of a script
The crates
j8 (facade: re-exports by feature, binding macros and runtime!)
│
┌──────────────┬───────────────┬─────┴──────┬─────────────┬────────────┐
j8jit j8executor j8builtins j8platform j8binding j8napi
│ ╲ │ ╲ │ │ │ │
│ ╲ j8compiler ╲ │ │ │ │
│ ╲ │ ╲ │ │ │ │
│ └── j8bytecode ──┴───────┼────────────┼─────────────┼────────────┘
│ │ │ │
└───────────────────────── j8framework ──────┴─────────────┘
│
paragc · j8taskqueue · j8lockfree · j8macros
| crate | Role |
|---|---|
j8framework | the core: the traits each layer implements (Platform, Engine, Invoke, Intrinsics) and the shared structs (Isolate, Scope, Agent, Context / Realm, Value, the object model, event loops). JS operation semantics hang off Agent. Depends on no other layer |
j8bytecode | bytecode definitions, byte for byte V8 Ignition’s; the dependency root, depends on no other j8 crate |
j8compiler | JS ⇒ bytecode (oxc parses; code generation after V8’s BytecodeGenerator) |
j8executor | the bytecode executor: implements Engine, with inline caches, sliced execution and the JIT hook |
j8jit | the speculative JIT (x86-64 Unix): implements the executor’s Tier |
j8builtins | the standard built-in objects: implements Intrinsics |
j8platform | the standard-library Platform: thread pool, clocks, module loading |
j8binding | the runtime side of Rust ⇄ JS bindings (FromJs / IntoJs, host objects) |
j8napi | Node-API: the C interface native addons link against |
j8taskqueue | a lock-free dataflow task queue (no_std); every event loop is one |
j8lockfree | hand-written lock-free building blocks (no_std) |
j8macros | procedural macros: bytecode tables, heap types, binding macros |
The rule for dependencies: each layer depends only on j8framework (the executor also on the compiler and the
bytecode, the JIT on the executor), and j8framework depends on no layer, only on paragc and two building blocks. So
the built-ins don’t know the executor and the platform doesn’t know the built-ins: they are all written against the
traits in j8framework.
Traits are the seams
j8framework defines the interfaces, the layers implement them, the host puts them together:
| trait | implemented by | does |
|---|---|---|
Platform (supertrait Pool) | j8platform::DefaultPlatform, or the host’s own | thread pool, clocks, console.log output, module loading |
Intrinsics | j8builtins::Builtins | installs the global object and built-in constructors into a new Realm |
Engine | j8executor::Executor | the execution entry: eval, resumable start / resume |
Invoke | the executor | built-ins calling back into JS (map’s callback, getters …) |
Tier | j8jit::Jit | the executor asks “compile this function / loop?” |
The life of a script
Take dune -p 'let s = 0; for (let i = 0; i < 1e6; i++) s += i; s':
- The host sets up. The runtime dune declares with
j8::runtime!creates anIsolate(one GC heap), anExecutorand aContext(the global object installed byBuiltins) on an event loop thread, and runs the JS preludes (Building a host). - Compile. The executor hands the source to
j8compiler: oxc parses and checks it (early errors areSyntaxErrors here), scope analysis decides whether each variable lives in a register, a context slot or on the global object, and the generator emits bytecode after V8’sBytecodeGenerator. The result is aj8bytecode::Module(a list ofSharedFunctions, each with aBytecodeArray). When many runtimes run the same preludes, aCodeCachecompiles each source once (Executor). - Interpret. The executor decodes the bytecode into threaded code: every instruction carries the handler that runs it, and handlers jump straight to each other. Property accesses hit inline caches keyed by shape. Every thousand or so instructions it checks the event queue, every ten thousand it yields (slicing), giving the heap a chance to collect.
- Tier up. Every backward jump of the loop is counted. Past the threshold the executor asks the
Tier: the JIT builds the function into a speculative SSA graph from the inline caches’ feedback (sandiguessed as int32), optimizes it, emits x86-64 directly and enters it at the loop header (OSR). - Deoptimize. When a speculation fails (
soutgrows int32), a guard jumps to a cold path;j8_deoptrebuilds the interpreter frames from the recorded frame state and the interpreter goes on. The JIT leaves a hint: next time it uses doubles there. - Finish. The result is a
Value(one NaN-boxed machine word); the host gets aGlobalhandle, applies ToString and prints it. No host work is left on the event loop, so the process exits.
The following chapters walk that path: bytecode → compiler → executor → JIT, then what they all stand on: the framework, the object model and the heap.
Bytecode: V8 Ignition, byte for byte
crates/j8bytecode only defines the bytecode; JS ⇒ bytecode belongs to the compiler. It is j8’s
dependency root: it depends on no other j8 crate (it only uses the j8macros procedural macros for its tables).
Why V8’s bytecode
j8 used to have a bytecode of its own (generated from an insn.json). It was replaced wholesale by V8’s Ignition
bytecode, byte for byte:
- the design is the result of years of tuning in V8 (accumulator machine, short
Stars,Callforms by argument count, feedback slots); adopting it is safer than reinventing it; - it can be compared with V8 directly:
j8bcdbg compileprints the same listing asd8 --print-bytecode; - what the JIT speculates on (the kinds and numbering of feedback slots) follows V8 too, so there is a reference to read.
j8 tracks V8 15.2.124 (the one in rusty_v8 152.2.0).
Tables generated from V8’s headers
V8 checkout ─ tools/v8bytecodes.py ─▶ crates/j8bytecode/v8.json ─ j8macros::bytecodes! ─▶ Rust types
v8.json comes from V8’s src/interpreter/bytecodes.h, bytecode-operands.h, interpreter-intrinsics.h,
src/runtime/runtime.h, function-kind.h, feedback-vector.h and others:
| JSON key | Generates |
|---|---|
bytecodes | Bytecode (repr(u8), V8’s numbering, 215 of them) with each one’s operand_types() and implicit_register_use() |
operand_types | OperandType, OperandTypeInfo |
implicit_register_use | whether it reads / writes / clobbers the accumulator, writes a short Star |
runtime / intrinsics | the function ids of CallRuntime / InvokeIntrinsic |
function_kinds, feedback_slot_kinds, scope_types, variable_modes | the matching V8 enums |
⛔ editing the JSON or the generated tables by hand: for a new V8 version, rerun tools/v8bytecodes.py on a checkout.
Encoding
As in V8:
- an instruction is a bytecode byte followed by its operands, little-endian;
- scalable operands take 1 byte, or 2 / 4 bytes after a
Wide/ExtraWideprefix (OperandScale); fixed ones always take their size; Encoderpicks the smallest scale per instruction,Decoderreads instructions back.
OperandScale::for_signed / for_unsigned are V8’s ScaleForSignedOperand / ScaleForUnsignedOperand.
Registers and the frame
An accumulator register machine: most operations leave their result in the implicit accumulator acc; a binary
operation is acc = reg op acc.
A register operand is its slot relative to the frame pointer (Register, V8’s x64 interpreter frame,
InterpreterFrameConstants):
fp + 2 … parameters (the receiver, i.e. this, first)
fp + 1 caller pc
fp + 0 caller fp
fp − 1 context
fp − 2 closure (the current function)
fp − 3 argument count
fp − 4 bytecode array
fp − 5 bytecode offset
fp − 6 feedback vector
fp − 7 … r0, r1, r2 …
In listings, a0, a1 are parameters and r0 up are locals. Star0 … Star15 are the sixteen short Stars:
one-byte instructions without operands that write r0 … r15 (Bytecode::short_star).
The shape of compiled code
After V8’s objects (function.rs):
| j8 | V8 | Contents |
|---|---|---|
Module | — | every function compiled from one source, the first being the top level |
SharedFunction | SharedFunctionInfo | name, kind (FunctionKind), strictness, length, formal parameter count, scope info, bytecode |
BytecodeArray | BytecodeArray | code bytes, constant pool, handler table, parameter / register counts, feedback slot kinds, the new.target / generator register |
Constant | constant pool entry | strings, numbers, scope infos, object / array / class boilerplates, template objects … |
HandlerEntry | handler table entry | [start, end), handler offset, context register, catch prediction |
The layouts of Flag8 operands (CreateClosureFlags, CreateObjectLiteralFlags …) follow V8’s
bytecode-flags-and-tokens.h.
Real bytecode
function add(a, b) { return a + b; }
let s = 0;
for (let i = 0; i < 10; i++) s = add(s, i);
s
What j8bcdbg compile prints (the format of V8’s --print-bytecode):
== #0 NormalFunction params 1 regs 5
@ 0 LdaConstant [0]
@ 2 Star1
@ 3 Mov <closure>, r2
@ 6 CallRuntime #375, r1, #2 ; DeclareGlobals: declares the top-level function add
@ 11 LdaZero
@ 12 StaCurrentContextSlot #2 ; let s = 0 (top-level lets live in the script context)
@ 14 LdaZero
@ 15 Star1 ; i = 0, in register r1
@ 16 LdaSmi [10]
@ 18 TestLessThan r1, #0 ; i < 10, #0 is the feedback slot
@ 21 JumpIfFalse [28]
@ 23 LdaGlobal [1], FBV[0] ; read the global 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] ; the back edge: where OSR enters
@ 49 LdaCurrentContextSlot #2
@ 51 Star0
@ 52 Return
== add NormalFunction params 3 regs 0
@ 0 Ldar a1
@ 2 Add a0, #0
@ 5 Return
Worth noticing:
CallUndefinedReceiver2: a call with two arguments and anundefinedreceiver has a bytecode of its own;- every operation carries a feedback slot (
#0,FBV[2]): the executor records the types and shapes it sees there, and the JIT speculates on them; JumpLoopis the only backward jump; the executor counts it, and when it is hot asks the JIT whether to enter machine code there (OSR).
Tests
tests/v8.rs decodes 738 instructions that V8 15.2.124 printed with --print-bytecode and checks each one’s name,
length and register operands.
Compiler: JS ⇒ bytecode
crates/j8compiler compiles JavaScript to V8 bytecode (j8bytecode::Module), parsing with
oxc. Every piece of JS goes through it before running: scripts, ES modules and dynamic code
(eval, Function). j8 has no AST interpreter.
source ─ oxc parse + semantic checks ─▶ AST ─ scope resolution ─▶ codegen (BytecodeGenerator) ─ BytecodeArrayBuilder ─▶ Module
Files
| File | Contents | After V8’s |
|---|---|---|
scope.rs | which names each scope level declares (Decls), which bindings inner functions capture (Resolver) | scope analysis |
compiler.rs | scopes, functions, statements | BytecodeGenerator |
expr.rs | expressions (results always in acc) | BytecodeGenerator |
builder.rs | emitting one function’s bytecode | BytecodeArrayBuilder / BytecodeArrayWriter / BytecodeRegisterAllocator / ConstantArrayBuilder / HandlerTableBuilder / FeedbackVectorSpec |
Parsing and early errors
oxc produces the AST and oxc_semantic checks it. The early errors the spec requires (duplicate declarations,
bad break targets, strict-mode restrictions …) are reported here as SyntaxError; regex literals are validated at
parse time too. Syntax j8 does not support yet is reported as Error::Unsupported with file:line:column.
Where variables live
As in V8, by who can see the variable:
| Variable | Lives in | Bytecode |
|---|---|---|
| a function’s own variables nobody captures | registers (parameters a0 …, this the receiver) | Ldar / Star |
| variables inner functions capture | context slots: one context per scope level that has any | LdaCurrentContextSlot / LdaContextSlot |
top-level script vars / functions | properties of the global object (declared by DeclareGlobals) | LdaGlobal / StaGlobal |
top-level script let / const / class | the script context (shared across scripts, not on the global object) | LdaCurrentContextSlot … |
names inside with, or reachable by a sloppy direct eval | looked up by name | LdaLookupSlot |
The pre-scan and code generation use the same Decls, so name resolution agrees. A for (let …) copies its context
every iteration, so closures each get their own iteration.
The temporal dead zone: reading or writing a let / const / class before initialization throws a
ReferenceError. Uses proven initialized at compile time skip the check.
Instruction selection
builder.rs picks bytecodes the way V8 does:
Starto r0 … r15 is a one-byte shortStar, 0 isLdaZero, small integers areLdaSmi;- calls pick
CallUndefinedReceiver0/1/2,CallProperty0/1/2,CallAnyReceiver… by argument count and receiver; - intrinsics go through
InvokeIntrinsic, runtime functions throughCallRuntime; - forward jumps are patched; when an offset doesn’t fit its operand, a reserved constant pool entry backs it (the
JumpConstantfamily); - registers are allocated in stack order, feedback slots numbered in order of appearance.
Exceptions and finally
A try block registers its [start, end) and handler in the handler table; a throw looks it up, and unwinds to the
caller when nothing covers it. finally uses a pair of registers, completion kind and value: a return / break /
continue crossing it detours through the finally and then carries on as recorded (ContinuationToken).
Dynamic code
- Indirect eval /
Function: compiled as a new script, run in the global scope. - Direct eval:
Compile::compile_directcompiles against the call site’s scope table. Every binding visible at the call site goes into the environment and the eval code runs chained onto the call site’s environment; sloppyvars / functions in eval land in the calling function (reusing a binding of the same name, otherwise going into an eval variable object looked up likewith); lexical conflicts raiseSyntaxError. - Generator / async function constructors:
GeneratorFunctionand friends compile a function of thatFunctionKind.
Use
Hosts rarely call the compiler; the executor does:
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)?; // an ES module, with its imports / exports
Executor: interpreting bytecode
crates/j8executor runs V8 bytecode and implements j8framework::Engine. It is j8’s last layer for now:
it always carries the compiler, and scripts, modules and eval / Function are all compiled to bytecode
before they run.
One executor per isolate
An Executor holds the loaded functions (Loaded), and closures on the heap point back to them by FuncId. So an
executor serves one isolate only; isolates share compiled code through a CodeCache (below).
Frames and registers
- An explicit frame stack: JS calling JS doesn’t recurse on the host (Rust) stack; the executor keeps its own frame
stack. The call depth limit is 10,000 (counting JS re-entered from host functions); beyond it,
RangeError. - One register file shared by all frames. A frame owns a stretch of it: the receiver, the formal parameters, the registers from r0. Register operands in the bytecode are V8 frame slots (r0 is −7, the receiver +2, the context −1, the closure −2) and are mapped onto that stretch at load time.
- Contexts are heap
Envs: registers and the accumulator carry them asValue::contextwords betweenCreateFunctionContext/PushContext/PopContext.
Threaded code
A function’s bytecode is decoded once, at load time, and every decoded instruction carries the handler that runs
it (Handler in threaded.rs):
handler(cx, pc, regs, acc) ─ done ─▶ jumps straight to the next instruction's handler
Handlers get the hot state (the instruction, the frame’s r0, the accumulator) in machine registers. With a nightly
compiler the jump is a guaranteed tail call (become; build.rs turns on cfg(tail_calls) when it sees a nightly);
on stable it returns to the loop in Executor::run, which calls the next one.
Hot bytecodes have handlers of their own; the rest, and hot ones off their fast path, go through slow, which syncs the
state and runs the general Executor::step. The chain is left when the frame changes (calls and returns), on an
exception, or when the execution ends.
Inline caches
ic.rs: one cache per GetNamedProperty / SetNamedProperty / DefineNamedOwnProperty site.
- Keyed only by shape address: the GC moves objects, so a cache must not hold object pointers; it also holds a
Weakso a recognized address is not reused by another shape. - Dictionary shapes mutate in place (same address, different contents), so they are never cached.
- Read: a data property owned by the receiver, or by a prototype 1 to
DEPTHlevels up (the shape of every level on the way is checked). - Write: a writable data property owned by the receiver.
- Add property: old shape ⇒ new shape; assignments also check the shape of every level of the prototype chain (nobody has since added a setter / read-only property of the same name).
The caches are also the JIT’s type feedback: it speculates on the shapes they saw and emits shape guards plus direct slot loads and stores.
Sliced execution
Engine::eval takes &mut Isolate and enters it in slices: at most ten thousand instructions each; between slices the
execution state is rooted, the heap gets to collect, and the run continues. The environment survives slices in a
ContextRoot. Every 1024 instructions the budget and termination requests are checked; inside an event loop that is
when the task queue is checked (Event loops).
Known deviation: JS re-entered from a host function (map’s callback) runs to completion inside the current slice,
without collection. Function.prototype.call / apply are unrolled by the executor into ordinary calls and don’t count
as re-entry.
Exceptions
The bytecode’s handler table: a throw looks for an entry covering the current offset in the frame; if found, it restores the context register and jumps to the handler, otherwise it unwinds to the caller.
Generators and async
Generators, async functions and async generators share the same bytecodes (SuspendGenerator / ResumeGenerator /
SwitchOnGeneratorState); suspending saves the registers into the generator object. await drives the coroutine
through j8framework’s promise machinery; after a script, the microtask queue is drained.
ES modules
module.rs: loading, linking and evaluation (synchronous: dependencies are read through Platform::load_module).
Import bindings read the exporter’s slots live; ResolveExport handles indirect exports, export * and ambiguity;
namespace objects, dynamic import() and import.meta are supported. Top-level await is not yet.
CodeCache
When many isolates run the same preludes and import the same module files, give their executors one shared
CodeCache:
- each source is parsed and compiled once, and every executor loads its own copy;
- only what is meant to be shared goes in (scripts run as
ScriptKind::Shared, and ES modules); one-off scripts don’t; - no source text is kept: entries are found by file name, length and a 128-bit hash of the text (two randomly keyed SipHash, so collisions can’t be crafted).
let code = CodeCache::shared();
let executor = Executor::default().with_cache(Arc::clone(&code));
The JIT hook
Executor::with_tier(tier) attaches a Tier (JIT). The executor asks it:
| When | Call |
|---|---|
| a call is about to run a frame from its first instruction (asked every 64 calls) | Tier::enter |
a JumpLoop has been taken many times | Tier::osr |
| a frame continues mid-way (after a pause, or a hand-over from machine code) | Tier::resume |
| an ordinary call between compiled functions, without an interpreter frame | Tier::call |
Interpret means interpret as usual; Resumed means machine code ran and the frames were set with Entry::resume, so
the interpreter continues with the top one; Threw means the machine code threw. jit.rs defines everything a JIT sees:
the decoded bytecode and its feedback (Function), the frame about to run (Entry), and how machine code hands an
execution back (DeoptFrame).
Use
let mut executor = j8executor::Executor::default();
let result = isolate.run(&mut executor, &cx, &j8framework::Source { text: "1 + 2", file: "a.js" })?;
The javascript_semantics test is a table of exactly determined JS semantics.
JIT: the speculative optimizing tier
crates/j8jit is j8’s JIT (x86-64 Unix). It implements the executor’s Tier: hot functions and hot loops are built
into a speculative SSA graph from the inline caches’ feedback, optimized, and emitted as x86-64 machine code that
runs directly on the interpreter’s frames; when a speculation fails, it deoptimizes back to the interpreter.
hot function / loop ─ build (bytecode + inline caches ⇒ speculative graph) ─ opt ─ codegen ─▶ x86-64, on the interpreter's frame
a guard fails ─▶ j8_deopt rebuilds the interpreter frames; the hint it leaves shapes the next compilation
j8’s plan is to skip a baseline compiler and go straight to a speculative optimizing tier (inlining, escape analysis, deoptimization, OSR), aiming to match V8 with its JIT on common benchmarks.
Turning it on
use std::rc::Rc;
let executor = j8executor::Executor::default().with_tier(Rc::new(j8jit::Jit::default()));
dune --jitandJ8_TEST262_JIT=1(test262 runs its baseline with the JIT) turn it on;Jit::from(n)sets the hotness threshold (defaultJit::THRESHOLD= 64); 0 compiles every function on its first call;- debugging:
J8_JIT_LOG(compilations and deopts),J8_JIT_IR(prints the graph),J8_JIT_BIN=<dir>(writes the machine code to files).
Three entries
Kind | When | How it runs |
|---|---|---|
Enter | the interpreter calls a hot function | on the frame the interpreter built for it |
Osr(at) | loop header at has jumped back often enough | on the current frame, entering mid-loop |
Native(n) | compiled code calls compiled code | straight through the callee’s trampoline, no interpreter frame |
Plain functions (not class constructors, not called with new, at most 3 formals) get a native entry: arguments in
registers, int32 results back unboxed through a second return register. Every function has a trampoline
jmp [rip + cell]: its machine code when it has some, otherwise the interpreter.
Script and eval top-level code runs once: it isn’t compiled on entry, only its hot loops are (OSR).
build: bytecode ⇒ speculative graph
build.rs is an abstract interpretation of the bytecode: for every interpreter register it keeps the IR value it
holds, speculating on what the inline caches saw.
- Numbers start as int32, guarded; a failed guard records a hint, and the next compilation uses doubles there;
- small functions are inlined (depth at most 4, bodies of at most 80 instructions, recursion unrolled at most 2 levels), their frames rebuilt on a deopt; other calls go to compiled code or the runtime;
- objects stay virtual: fields of objects made here are only tracked by the compiler until something needs the object itself (escape analysis);
- context slots read and written here are kept in values and written back only when someone else could look;
- a loop entered on-stack is peeled once: what one iteration allocates and the next replaces never exists.
The bytecode is walked region by region (Region), each region’s blocks in order: forward edges always go to blocks
not walked yet, so a block’s state is the merge of its predecessors’; a loop header speculates on its back edges (phis
for everything live), and the walk restarts with a hint when a back edge disagrees (at most 12 times).
cfg.rs gives the blocks, loops and liveness: for the analysis, the receiver and parameters are 0 .. P, ri is
P + i, the accumulator P + R; the context register is always live (not tracked).
The IR
ir.rs: basic blocks in SSA form, each instruction one value with a representation (Rep: int32, double, word …).
Block { phis…, insts…, terminator } a terminator is Jump / Branch / Return / Deopt
Inst { op, rep } operands are value ids
FrameState { func, pc, slots…, parent } what each interpreter register holds at a guard (virtual objects too)
Typical Ops:
| Kind | Examples |
|---|---|
| constants and parameters | I32, F64, Word, Param, Callee, Phi |
| arithmetic | Int(op, a, b, fs) (with a frame state when it can overflow), Float, IntToFloat |
| boxing | BoxInt, BoxFloat, UnboxInt(v, fs) (guard: an int32, not −0), UnboxFloat |
| guards | CheckObject, CheckShape, CheckFunc (the closure runs a given function), CheckNotHole |
| memory | LoadWord, LoadPtr, StoreCell (with a write barrier when needed), ContextCell |
| calls | Call(helper, …) (runtime functions), CallJit (compiled code) |
Every guard carries a FrameState: which instruction, and which register contents, the interpreter resumes with.
opt and codegen
opt.rs: phis that pick one value go away, and so does whatever nothing needs;- loop-invariant code motion, path facts across loops, constant modulus as multiplication and so on happen while building and optimizing;
codegen.rs: graph ⇒ x86-64 directly: linear-scan register allocation over the blocks in reverse postorder, then one pass of instruction selection;asm.rsholds the x86-64 encodings used.
rbp frame saved rbx r12 r13 r14 r15 at −8 … −40, entry pointers at −48 … −88, spill slots below
r15 the JIT context (Ctx) the whole time
scratch rax rcx rdx r11 xmm14 xmm15 (never allocated)
allocated rsi rdi r8 r9 r10 (caller-saved), rbx r12 r13 r14 (callee-saved), xmm0 … xmm13
Guards jump to cold stubs that store the frame state’s values into Ctx::BUF and call j8_deopt.
The runtime
runtime.rs: what machine code calls and reads.
Ctx +0 budget +8 pending +16 global +24 script scope +32 Object.prototype +40 ret +48 ret pc +56 acc
+64 depth +72 depth limit +128 ARGS (16 words) +256 BUF (deopt values)
j8_helper: slow-path runtime functions (property access, allocation, generic operators);j8_poll: loops check the budget and termination requests, so machine code can be interrupted like the interpreter;j8_deopt: the deoptimization entry;- executable memory comes from
mmap.
Deopts and learning
When a guard fails, j8_deopt rebuilds the interpreter frames from the frame state (inlined callees included) and the
interpreter goes on. The JIT leaves a hint by reason:
| Reason | Hint |
|---|---|
| int32 speculation failed | doubles there next time (HINT_FLOAT) |
| type / shape mismatch | the generic path there next time (HINT_GENERIC) |
| the callee was not the one speculated | no inlining + generic (HINT_NO_INLINE) |
| bytecode the JIT doesn’t compile | that inlined call isn’t inlined next time; a function’s own code is given up |
The code that failed is dropped and recompiled with the hints when it is hot again. After 24 deopts of one function, the JIT gives up on it, and it is interpreted from then on.
The MLIR path
j8jit also exports Compiler / Backend / MachineCode (compile.rs, x86_64.rs): MLIR (llvm dialect) through
mlirpass (mem2reg, canonicalize, cse), then j8jit’s own x86-64 back end,
without LLVM. That was the road of the earlier first-tier JIT; the hot path today is the graph ⇒ machine code above,
and lowering V8 bytecode to MLIR is being rewritten.
Framework: Isolate, Agent and values
crates/j8framework is the core layer: the traits the other layers implement and the structs / enums they share. It
depends on no other j8 layer; implementations live in the layer crates (j8platform implements Platform, and so on).
Core types
| Name | Role | V8 |
|---|---|---|
Platform / Pool | the threads and clocks the host lends the engine | v8::Platform |
Isolate | an independent JS world: one GC heap (paragc) and a profiler | v8::Isolate |
Scope | one entry into an isolate; values in it carry the 'gc brand and can’t leave it | HandleScope |
Value<'gc> | a JS value: V8’s Local, it can’t leave the closure | Local<Value> |
Global | a persistent handle (paragc Root): survives enter calls, released on drop | Global<T> |
ContextRoot | the execution environment kept across slices | — |
Context / Realm | the execution context: the global object and built-in prototypes (Intrinsics, from j8builtins) | Context |
Agent | the context of one run; all JS operation semantics hang off it, calls back into JS go through Invoke | — |
Engine | the entry the execution engine (j8executor) implements; resumable (start / resume) | — |
Profiler | call / back-edge counters | — |
EventLoop / EventLoopSet | JS event loops and the loop threads they run on (Event loops) | — |
Entering an 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>, valid only in this closure
});
Isolate::enter(|scope| …)enters once;'gcis that entry’s brand. Nothing is collected during the closure; after it returns, a collection runs if enough was allocated (usually young, a full one every few).Value<'gc>can’t leave the closure, checked at compile time: Rust lifetimes stand in for V8’sHandleScope.- To keep a value across entries, turn it into a
Globalwithscope.persist(v)/agent.global(v).
Values: one NaN-boxed word
A Value is one 64-bit word (ValueBits):
- numbers are their own
f64bits (every NaN is stored asCANONICAL_NAN); - everything else lives in the negative NaN space: the top 16 bits are
0xFFF0 | (tag + 1), the low 48 bits the payload, a bool or a GC address (user-space addresses fit in 48 bits).
The ValueTags: UNDEFINED, NULL, BOOL, NUMBER, UNINIT (a binding in its temporal dead zone; only in registers
and environment slots, checked away before reads and writes, it never reaches JS), LAZY (a property value computed on
first read), STRING, SYMBOL, BIGINT, OBJECT, ACCESSOR, CONTEXT.
“Is it a number”, “is it an object” are one compare each, without a full decode. Registers, the accumulator,
environment slots and property slots all hold the same word, so JIT code reads and writes it directly and a ValueCell
stores it as is.
let v = Value::Number(1.5);
match v.kind() {
ValueKind::Number(n) => …,
ValueKind::Object(o) => …,
_ => …,
}
Agent: operation semantics
An Agent is the context of one run: the current realm, the heap’s mutator and the engine’s Invoke. The spec’s
abstract operations are its methods (ops.rs): conversions (ToNumber, ToString, ToPrimitive …), operators
(BinaryOp, CompareOp, UnaryOp), property access (along the prototype chain, through the
internal methods). The executor, the built-ins and binding code share them, so semantics are written once.
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"); // an Error; `?` it out of a host function to throw
Built-ins and host functions all have the signature fn(&mut Agent, this, &[Value]) -> Result<Value, Error>.
Error
| Variant | Meaning |
|---|---|
Error::Exception(g) | JS threw the value g |
Error::Syntax(msg) | the source doesn’t parse (early errors included) |
Error::Unsupported(msg) | syntax j8 doesn’t support yet, with file:line:column |
Error::Terminated | stopped by IsolateHandle::terminate |
Terminating execution
IsolateHandle::terminate stops JS from another thread (V8’s TerminateExecution): the execution layers notice the
request at checkpoints (function entries, back edges; in JIT code, back edges) and throw Error::Terminated. It is not
a JS exception: catch / finally can’t catch it, and it goes all the way out. Leaving the outermost entry resets it,
so the isolate stays usable.
Other parts
| File | Contents |
|---|---|
promise.rs | promises and microtasks: resolve / reject, then reactions, driving async coroutines, draining the queue |
module.rs | module records, import / export entries, ResolvedBinding |
proxy.rs | Proxy: internal-method entry points dispatched to traps, with invariant checks |
typed.rs, backing.rs | TypedArray elements; where an ArrayBuffer’s bytes live (its own, host-mapped, shared between isolates) |
text.rs | strings (see the object model) |
parallel.rs | parallel built-ins: plain-data work on large inputs split into chunks on the platform’s pool (fork–join) |
layout.rs | byte offsets into heap objects that machine code reads and writes directly |
lazy.rs | properties computed on first read (V8’s AccessorInfo on function maps: name isn’t made with the closure) |
private.rs | private class members #x |
Object model: shapes, stores, properties
Object layout
Object + OBJECT_SHAPE *const Shape (null: empty, or a dictionary)
+ OBJECT_INLINE ValueCell × INLINE_PROPS (the first properties live in the object)
+ OBJECT_STORE GC slot of the store tree: a leaf { capacity, ValueCell × capacity }
Objects keep what the hot paths touch outside their mutable data (GcCell): the prototype, the properties (a shape plus
a value store), array elements, and the immutable data of functions and regexps. The JIT reads and writes these fields
at the offsets j8framework::Layout gives.
j8’s own heap structs are declared with #[j8framework::heap]; #[mutable] fields get the cell their type calls for
(Value ⇒ ValueCell, Gc ⇒ a paragc Slot, bools and integers ⇒ atomics) plus a getter and 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>>,
}
Shapes (hidden classes)
shape.rs: a shape is the layout of an object’s own string-keyed properties, keys and attributes in insertion
order; the values are stored separately in the object’s slots.
- Objects built the same way share shapes: adding a property follows the transition table to (or creates) a child shape;
- the execution layer keeps inline caches keyed by “shape ⇒ slot index”;
- shapes hold no
Gcpointers (collection moves objects) and are managed withArc; the transition table storesWeak, so shapes no object uses are freed naturally; - deleting a property, changing attributes or having too many keys turns the object’s properties into a
dictionary (
Dict, modified in place); inline caches don’t accept those.
The value store
store.rs: property values and array elements live in fixed-capacity leaves on the GC heap; large ones are a 128-ary
tree (300,000 elements in three levels). paragc only allocates fixed-size objects, so capacities come in classes:
- a leaf
Leaf<N>:NValueCells (N= 2 / 4 / … / 128), the first word its capacity; - an inner
Node: 128 child slots, the first wordNODEplus its level.
All #[repr(C)]: whatever N, the cells start after the head word, so they can be indexed with the type erased.
Reads don’t borrow or lock; writes go through ValueCell::set and its write barrier.
Internal methods
property.rs implements the spec’s internal methods for ordinary objects (10.1) and arrays and string wrappers (10.4):
[[GetOwnProperty]]/[[DefineOwnProperty]](ValidateAndApplyPropertyDescriptor, ArraySetLength);[[OwnPropertyKeys]], extensibility, the prototype;- arrays have a dense part plus ordinary properties stored by index (holes, elements with different attributes);
read-only
lengthand non-extensibility follow the spec.
Property access (ops.rs) walks the prototype chain through these. Proxy (proxy.rs) dispatches the same entry points
to its traps and checks the invariants.
Strings
text.rs: the representation shared by property keys and JS string values.
- short strings of at most 22 bytes are stored inline, without an allocation;
- long ones share one heap copy, and a piece cut out of one (
split,slice, a regex match) points into it instead of copying (V8’s sliced strings); - when
+produces something long enough, it is first a rope (two halves plus the total length), flattened and cached when the content is first needed, so as += cloop doesn’t copy the whole string every time; flattening and dropping are iterative, so ropes hundreds of thousands of levels deep don’t overflow the stack; - no
Gcinside: the GC doesn’t manage them.
Strings are stored as UTF-8 for now, so lone surrogates are lost; comparisons go by UTF-16 code units.
Host objects
ObjectKind::Host: JS objects holding a Rust value (HostData, a Box<dyn Any + Send + Sync> behind a borrow flag).
Binding methods take it as &self / &mut self; a re-entrant &mut self call throws a TypeError instead of
panicking (see Binding macros).
Heap and GC: built on paragc
j8’s heap is paragc, and j8 uses only its public interface (Gc / Slot /
Mutator / Root), never its internals. j8framework/src/gc.rs adds what a JS engine needs on top.
paragc
A standalone Rust GC library from the same community:
- an Immix-style heap of blocks and lines;
- young collection plus reference counting of old objects (LXR-style), evacuation of sparse blocks;
- parallel marking and sweeping, lock-free inside;
- collector threads of its own (as many as the platform’s pool);
- public heaps and cross-process heaps (jumpheap uses them).
j8’s GC layer
In paragc the only mutable edge inside an object is a Slot (with a write barrier), so j8 keeps its mutable heap data in
two kinds of cell:
| Cell | Holds | How it changes |
|---|---|---|
GcCell | a block of mutable data (ObjectState …) | the current version lives in a snapshot a slot points to: a snapshot allocated this cycle (since the last collection) is changed in place; an older one is first moved into a new snapshot, and swapping the slot records it in the write barrier. Each block moves at most once per cycle |
ValueCell | one Value (environment and property slots) | a word plus a slot |
Cow, GcQueue, Static | copy-on-write, a queue on the heap, untraced data | — |
Heap types use #[derive(Collect)] (in j8macros, generating paragc’s Trace); #[collect(require_static)] skips a
field (on a type: the whole type has no GC edges). Types with edges may not implement Drop.
Single-threaded isolates
An isolate runs JS on one thread at a time (V8’s model), and only that thread reads and writes the objects in its heap,
so borrow flags and scalar fields are plain loads and stores (IsoCell), ⛔ atomic read-modify-write. Only paragc’s
Slot is atomic (the write barrier needs it).
Heap types must be Send + Sync (paragc’s rule): host data is a Box<dyn Any + Send + Sync>, shapes and ropes use Arc.
Rules
These are written in the code; breaking them dangles pointers or loses marks:
- Collection happens only outside
enter, when everyGchangs off a root, and objects move. ⛔ storing aGcor an object address whereTracedoesn’t look (Static, side caches). Things hashed by address (the indexes of Map / Set) are updated inrelocate(seeCollection). This is also why inline caches key on shapes (Arc), not objects. - ⛔ writing a slot of a value not yet on the heap: the barrier records the slot’s address. Allocate first, then fill
(see
Scope::context); thenewthat#[heap(new)]generates fills cells before that, without the barrier. - Stop-the-world collection only (
collect_if_needed/collect, parallel inside):GcCellchanges young snapshots in place without the barrier, so ⛔mark_concurrently. - Young collection uses paragc’s default
YoungEvacuation::SkipRemembered: young objects old ones point to directly stay, fields of moved objects go throughrelocate, and addresses inValueCellwords are rewritten. ⛔YoungEvacuation::Full: it rewrites the addresses in old objects’ slots but doesn’t know the copy inValueCellwords.
When it collects
- after
Isolate::enterreturns, if enough was allocated (usually young, a full one every few); - the executor runs in slices: at most ten thousand instructions, then the execution state is rooted and a collection
can run when
enterreturns, before the run continues; - JS re-entered from a host function runs to completion inside the current slice, without collection.
Persistent handles and cycles
Global, and j8::Persistent / j8::Function in bindings, are GC roots. A host object that stores a value pointing
back to itself keeps both alive until it is dropped from Rust. WeakRef / FinalizationRegistry hold strong references
for now.
Built-in objects
crates/j8builtins holds JavaScript’s standard built-in objects and implements j8framework::Intrinsics: when a
Realm is created, Builtins::install puts in the global object, the global functions and every built-in constructor,
prototype and method.
let cx = isolate.enter(|scope| scope.persist(scope.context(&j8builtins::Builtins)));
j8framework only defines Intrinsics; this is the default implementation, and hosts can replace or trim it.
j8builtins depends only on j8framework, not on the executor: every built-in is a host function
fn(&mut Agent, this, &[Value]) -> Result<Value, Error> written with the semantics on Agent, calling back into JS
through Invoke.
Files
| File | Built-ins |
|---|---|
global.rs | the global object, parseInt / parseFloat / isNaN / eval / the URI functions |
object.rs, function.rs, reflect.rs | Object, Function, Reflect / Proxy |
array.rs, typed.rs, buffer.rs | Array, TypedArrays (12 kinds, Float16 included), ArrayBuffer / SharedArrayBuffer / DataView / Atomics |
string.rs, text.rs | String, Symbol |
regexp.rs, dfa.rs | RegExp (regress plus a DFA fast path) |
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, async generators, iterators and iterator helpers |
error.rs | Error, TypeError … AggregateError, cause |
helpers.rs | shared spec steps |
Coverage
- Object / Array: every method; Array methods generic over array-likes, species;
from/flat/toSorted/with… - Reflection:
Reflect,Proxy(revocable too); - Iterator helpers: the global
Iterator,Iterator.from,map/filter/take/drop/flatMap/reduce…; Set methods (union…),Map.groupBy/Object.groupBy; - Binary data: resizable
ArrayBuffer(transfer, detach), growableSharedArrayBuffer,DataView,Atomics(single-threaded semantics); - Date (the local time zone is UTC); number formatting (
toFixed/toPrecision/toExponentialwith exact decimals),Math.sumPrecise/f16round; - RegExp: the Symbol protocol,
lastIndex, thedflag, named groups, species,RegExp.escape; the string methodsmatch/matchAll/replace/replaceAll/search/split; - Promise built on NewPromiseCapability: subclassing,
all/race/allSettled/any/withResolvers/try; - built-in constructors take the prototype from
new.target, soclass X extends Mapworks; host functions tell constructible from not.
Out of scope: Temporal, intl402, ShadowRealm and others (see the Roadmap).
Regexps: two engines
- The main engine is regress, a backtracking engine matching UTF-16 code units;
dfa.rsis a second one: for patterns theregexcrate matches exactly like ECMAScript on an all-ASCII subject, it uses finite automata with a literal prefilter instead of backtracking.Dfa::newtranslates the pattern and refuses everything whose meaning could differ: back references, lookaround, named groups,vmode, anchors underm, capture groups inside a quantifier (ECMAScript resets them every iteration), Annex B oddities, non-ASCII pattern text. regress handles the rest and non-ASCII subjects.- Regex literals share the realm’s compiled entry and strings;
test()withoutg/yskipslastIndex.
Fast paths
Hot built-ins have fast paths that skip the full spec steps when no observable behavior could differ: an untouched
RegExp.prototype (the pristine check), appending to the end of a dense array, string-and-number concatenation, JSON
parsing repeated key sequences into one shape. test262 is the judge of correctness.
Pure computation over large data (sort keys, number conversions) can be split into chunks on the platform’s thread pool
through j8framework::Par, with the results written back afterwards.
Event loops and the task queue
j8 has no async runtime (no tokio). Its event loop is its own: j8framework::EventLoop is built on a j8taskqueue
queue, and an EventLoopSet pins thousands of event loops onto a few loop threads.
One event loop
An EventLoop is one JS event loop: its own isolate, engine and context, and a j8taskqueue queue. The queue is the
event loop. It holds three kinds of tasks:
- scripts, which run a check interval of steps at a time (about a thousand instructions by default; V8’s interrupt check at frame entries and back edges) and then yield back to the queue;
- settlements, which resolve a promise with what host work produced and drain the microtasks;
- polls of host futures that were woken (no JS runs in them; a ready future queues its settlement).
Scripts and settlements are chained: each waits for the one before, so JS runs one task at a time, to completion. Polls wait for nothing. So every time the bytecode advances, the queue is checked: host work that became ready meanwhile, from any thread, is polled before the script goes on, and its JS runs right after the script.
When nothing can run, the thread parks until a waker fires. run_until_idle returns once no script and no future
of the event loop is outstanding.
Many event loops: EventLoopSet
j8::EventLoopSet::scope(&platform, NonZeroUsize::new(8).unwrap(), |set| {
// 8 loop threads for the length of the closure
let rt = j8::Runtime::on::<MyHost>(set, Executor::default())?;
…
});
- Pinned, no claiming. An event loop lives on one thread at a time and isn’t shared, so a thread runs its event loops with no locks: 8 threads and 1000 event loops make 125 each. A thread keeps a local queue of its event loops that have work and gives each a turn in turn.
- Messages only. Other threads reach a loop thread by a wake (an event loop has something new; deduplicated by a flag) or a message (create an event loop, work in its context, move one in or out), and wait for the answer. A message for an event loop that has moved is forwarded.
- Load balancing. New event loops go to the least loaded thread. A thread with nothing to run asks the busiest one
for half the difference, which hands over the event loops waiting in its queue first (work stealing).
set.rebalance()evens the threads out on demand,set.split(thread)starts a new thread and gives it half of another’s. Event loops move only between turns, with their isolate, engine, paused script and pending futures. - One quota. Every turn runs the set’s slice of steps (
set.set_slice) times the event loop’s weight (EventLoop::set_weight), checking the queue everyset.set_checksteps;set.loads(),set.spent()andEventLoop::spent()show where the work went. A long script doesn’t hold up the other event loops on its thread.
How hosts write async bindings on it: Async and promises.
j8taskqueue
crates/j8taskqueue: a lock-free dataflow task queue (no_std + alloc, depending on nothing but j8lockfree).
| Name | Role |
|---|---|
ITask | a task: recursable (may it add tasks or ask to run again), depend (what must finish first), exec (run with a bytecode quota) |
ITaskPoll / TaskQueue | the queue: add a task for a TaskId, run to start |
Queue | the queue without threads, kept by the host (one per event loop): run on the calling thread, run_on spread over a pool |
Pool | a thread pool (some threads; runs a batch of closures and returns when all are done), implemented by the host; j8framework’s Pool is this one |
TaskId | a task handle; family finds the family’s root (union-find), cancel cancels the whole family |
Quota | a bytecode quota: the executor spends one per instruction |
The design:
- dataflow, no barriers: when a task finishes, the tasks depending on it that have everything go straight to the ready queue, taken by threads still in their loop. a and b both needed by c, independent of each other ⇒ a and b run in parallel, and c runs the moment both are done, waiting for nothing unrelated;
- no spinning: a thread that finds no work leaves; work that becomes ready later is run by the thread that made it ready;
- lock-free throughout: dependency counts, downstream lists (a sealable
PushList), union-find parents and the ready queue (a segmented MPMCFifo) are all atomics; - no cycles: dependencies can only name tasks already added, read once when added ⇒ no deadlock;
- quotas count bytecodes: a task out of quota returns
Flow::Yieldand queues again; eachrunalso has a total budget, after which it returnsStop::Budget; - borrowing, not
'static: tasks live in'aand may borrow the caller’s data; onlySendis required.
Lock-free building blocks
crates/j8lockfree: j8’s hand-written lock-free building blocks (no_std + alloc), shared by j8framework and
j8taskqueue. j8’s rule is that the heap and scheduling are lock-free throughout, with the structures written by
hand, ⛔ crossbeam.
| Type | What it is |
|---|---|
Fifo | multi-producer multi-consumer FIFO queue (monotonic positions, a segmented slot table) |
SegVec | append-only segmented vector: stable indices, concurrent reads; compaction and removal need exclusive access |
PushList | push-only Treiber stack: take the whole list, or seal it (pushes after sealing are handed back) |
Stock | a stock: tidied into a read-only array when exclusive, claimed in batches by an atomic cursor when concurrent |
Deque | Chase–Lev work-stealing deque: the owner (Owner) pushes and pops, others steal |
OnceBox | a lazily published value (concurrent initializers each compute, the winner stays) |
AtomicRefCell | a RefCell usable across threads: a borrow conflict is an error, never a wait |
The common trick: only grow, free when exclusive
While concurrent, the structures only add memory (new segments; old buffers stay), and freeing waits for exclusive
access (&mut or drop). So there is:
- no need for hazard pointers;
- no need for epoch-based reclamation;
- no ABA problem.
The cost is memory that only grows while concurrent, but the way these structures are used (event loop queues, the downstream lists of a task graph) always has natural exclusive moments to tidy up in.
Users
| User | Uses |
|---|---|
| j8taskqueue | Fifo as the ready queue, PushList as downstream lists |
| j8framework event loops | message queues, work stealing |
| j8binding host objects | AtomicRefCell around Box<dyn Any + Send + Sync> |
| j8executor | inline caches and load tables |
Platform
A Platform is what the host lends the engine: a thread pool, clocks, where console.log goes, and module loading.
crates/j8platform is the standard-library implementation, DefaultPlatform.
DefaultPlatform
- Thread pool: moremath’s
ThreadMulti, started once and reused; tasks may borrow the caller’s data (throughj8framework::Pool). Background tasks and parallel built-ins run on it. The GC heap has collector threads of its own. - Clocks:
Instantfor the monotonic clock,SystemTimeforDate. - Modules: relative paths resolved against the importing file’s directory, read from disk (no
node_modules). console.loggoes to standard output.
let platform = j8platform::DefaultPlatform::default(); // one worker thread per CPU
let small = j8platform::DefaultPlatform::from(NonZeroUsize::MIN); // one thread
let mut isolate = j8framework::Isolate::new(&platform, Default::default());
The traits
pub trait Pool: Sync {
fn threads(&self) -> usize;
fn run(&self, jobs: Vec<Task<'_>>); // returns when the batch is done; tasks borrow the caller's data
}
pub trait Platform: Pool {
fn now(&self) -> Duration; // monotonic clock
fn wall_clock(&self) -> Duration; // for Date
fn print(&self, line: &str); // console.log
fn load_module(&self, referrer: &str, specifier: &str) -> Option<(String, String)>; // (normalized name, source)
}
(A sketch; the full signatures are in j8framework/src/platform.rs.)
Stacking platforms
No platform holds async work (that lives in each runtime’s isolate), so platforms stack in any order and runtimes can
share one. dune’s NodePlatform wraps DefaultPlatform: it answers the specifiers of node: built-in modules and
passes the rest to the inner one:
let platform = Dune::platform(NodePlatform::from(DefaultPlatform::default()));
Methods worth overriding: print (send console.log elsewhere), now / wall_clock (a fake clock for tests),
load_module (packages, URLs, a virtual file system). See Modules.
Building a host
This part shows how to build your own JavaScript runtime on the j8 crate, the way dune and
workerd are built. The macros attribute by attribute: Binding macros.
Setup
[dependencies]
j8 = "0.4" # default feature `runtime`: executor + built-ins + platform
# j8 = { version = "0.4", features = ["jit"] } # + the x86-64 JIT (x86-64 Unix)
# j8 = { version = "0.4", features = ["json"] } # + j8::Json<T> (serde)
| Path | What it is |
|---|---|
#[j8::object] / #[j8::class] / #[j8::function] / #[j8::module] | bind Rust to JS |
j8::runtime! | declare a runtime: which bound types go where, plus a JS prelude |
j8::Runtime | a ready execution environment: eval, eval_module, run_until_idle, set, text, enter |
j8::Host / j8::HostPlatform | the trait runtime! implements / the platform serving its native modules (stateless: runtimes may share one) |
j8::frame | j8framework: Agent, Error, ErrorKind, Value, Platform, Source … |
j8::platform::DefaultPlatform | the standard-library platform |
j8::executor::Executor | the bytecode executor; with_tier adds the JIT |
j8::Promise<T> | a JS promise awaited from Rust |
j8::Glue | Glue::spawn / Glue::settle: hand-made promises |
j8::NATIVE | "__j8_native", the name of the hidden registry object |
The smallest host
use std::num::NonZeroUsize;
use std::process::ExitCode;
use j8::executor::Executor;
use j8::frame::{Agent, Error, ErrorKind};
use j8::platform::DefaultPlatform;
/// Machine access, kept in `__j8_native.env`
struct Env;
#[j8::object("env")]
impl Env {
fn var(name: &str) -> Option<String> {
std::env::var(name).ok()
}
/// Throws a TypeError when the variable is missing
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")))
}
}
/// The public API is JavaScript, built on the natives
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());
// One loop thread is enough for one runtime; give more for many
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
}
}
})
}
The steps are always the same:
X::platform(inner)wraps a platform in aHostPlatformfor runtimeX. Keep it alive as long as the runtime:Runtime<'p>borrows it.j8::EventLoopSet::scope(&platform, threads, |set| …)starts the loop threads the runtimes live on, for the length of the closure.X::runtime(set, executor)creates the isolate and the context on the least loaded loop thread, installs everything and runs the preludes. A prelude that throws comes back asErrhere. Every later call (eval,enter,run_until_idle) is a message to that thread and waits for its answer; any host thread may make it.rt.eval(text, file)runs a script and returns aGlobal(a handle that outlives the call);rt.text(&g)turns it into a string with ToString.rt.run_until_idle()waits until no async host work is left. Call it after everyevalif your bindings haveasync fns or return promises; otherwise those promises never settle.
The split: Rust bindings + a JS prelude
Both samples split the work the same way:
- Rust does only what needs the machine (files, sockets, clocks, processes), small and flat.
- JavaScript (the prelude) builds the real API on top: classes, argument checking, Node / Web semantics. Much less code than doing it all through bindings.
runtime! has four sections, all optional, in this order, each followed by a comma:
| Section | Takes | Ends up at |
|---|---|---|
globals: [..] | #[j8::class] / #[j8::object] types | the global object: globalThis.Process |
modules: [..] | #[j8::module("node:x", "x")] types | import … from "node:x" and __j8_native["node:x"] |
natives: [..] | #[j8::class] / #[j8::object] types | the hidden registry: __j8_native.env, __j8_native.KvStore |
prelude: EXPR | JavaScript (a &'static str) | run once, as a script, after everything is installed |
The JS name is the macro argument (#[j8::object("env")] ⇒ env), else the Rust type name. Methods are renamed to
camelCase (exists_sync ⇒ existsSync) unless #[js(name = "…")] says otherwise.
__j8_native is a non-enumerable property of the global object. User code can still reach it: treat it as out of casual
reach, not as a security boundary. The usual prelude is an IIFE taking it:
(function (native) {
'use strict';
const { clock, Timer } = native; // natives bound in Rust
globalThis.setTimeout = (f, ms) => { /* … */ };
native.runMain = (file) => { /* … */ }; // entry points the host calls
})(globalThis.__j8_native);
A long prelude can be split into files joined with concat!(include_str!("a.js"), include_str!("b.js")), as
dune/src/node/mod.rs does.
Passing data in: Runtime::set
rt.set("a.b.c", value) defines c on globalThis.a.b, converting value with IntoJs. Numbers, strings, Vec<T>,
BTreeMap<String, T>, Option<T> all work:
rt.set("process.argv", args)?; // Vec<String> ⇒ array
rt.set("process.env", std::env::vars().collect::<BTreeMap<_, _>>())?; // map ⇒ object
The parent object must exist already (the prelude makes it). That is how dune sets process.argv and friends without
the prelude knowing about Rust.
Calling into the prelude
Put a function on __j8_native and eval a call to it, quoting the arguments as JS string literals (see dune’s
Session::quote):
let call = format!("__j8_native.runMain({})", quote(file));
rt.eval(&call, file)?;
rt.run_until_idle()?;
For lower-level work, rt.enter(|a| …) gives you the context’s Agent (a.get_named, a.call, a.local,
a.to_string …). Values can’t leave the closure; keep a Global (a.global(v)) for later.
What an Error means
| Variant | Meaning | What hosts do |
|---|---|---|
Error::Exception(g) | JS threw; g is the thrown value | rt.text(&g) ⇒ Uncaught … |
Error::Syntax(msg) | the source doesn’t parse | print msg |
Error::Unsupported(msg) | syntax j8 doesn’t support yet | print msg |
Building on another runtime
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 installs everything Web does first, then its own types, and runs Web’s prelude before its own. Module lookups
try the child’s modules first, then the parent’s. The parent doesn’t change, so a third party can extend Dune without
forking it.
The JIT
let executor = Executor::default().with_tier(j8::jit::Jit::default());
let rt = MyHost::runtime(set, executor)?;
Where to look in the samples
| You want to … | Look at |
|---|---|
| set up a runtime, run a file, report errors, exit codes | dune/src/cli/, dune/src/session.rs |
a REPL (several evals sharing one global object) | dune/src/repl.rs |
| Node-style errors with codes; blocking work off-thread | dune/src/host.rs |
bind plain objects (stdio, clock, codec, random) | dune/src/web/mod.rs |
a cancellable promise (Glue::spawn) | dune/src/web/timer.rs |
| an async file system | dune/src/node/fs.rs + fs.js |
a custom Platform for JS-written modules; Runtime::set | dune/src/node/mod.rs |
a module loader in JS (require, node_modules, package.json) | dune/src/node/loader.js |
| a class with Rust state, used only by the prelude | samples/workerd/src/main.rs (KvStore) + prelude.js |
| call a JS-defined entry point per request | samples/workerd/src/main.rs (Worker) |
Binding macros
The macros are in crates/macros (j8macros), written #[j8::class] and so on through the facade crate; their runtime
side is crates/j8binding, V8’s FunctionTemplate / ObjectTemplate. Each macro has its own file (class.rs /
object.rs / function.rs); reading #[js(…)], analyzing signatures and generating the conversion wrapper is shared in
method.rs.
#[j8::class]: a Rust type as a JS class
On an impl block: generates a conversion wrapper (fn(agent, this, args) -> Result<Value>) for each method and
implements j8::Class. The type needs no changes; instances are host objects (ObjectKind::Host) holding a Rust value.
struct Counter { n: f64 }
#[j8::class] // or #[j8::class("name")]; defaults to the type name
impl Counter {
#[js(constructor)] // `new Counter(…)`; a plain call throws a 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 } // prototype method, 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 } // no self: a static method on the constructor
}
let handle = Counter::install(&mut agent, global); // global `Counter`; returns the constructor and prototype
let obj = handle.instance(&agent, Counter { n: 1.0 }); // an instance made from Rust
Inheritance: #[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’s prototype is Animal.prototype and Dog’s is Animal (installed on the same target first if it isn’t
there yet), so instanceof works and Animal’s methods run on a Dog through AsRef / AsMut. Chains of any length
work.
#[j8::object]: associated functions as a plain object
struct Fs;
#[j8::object("fs")]
impl Fs {
fn exists_sync(path: &str) -> bool { … } // fs.existsSync
#[js(getter)]
fn sep() -> String { "/".into() } // fs.sep (an accessor)
}
#[j8::function]: one function
#[j8::function] // or #[j8::function("name")]
fn greet(name: &str) -> String { format!("hi {name}") }
greet::install(&mut agent, global); // the function stays; a module of the same name holds `greet::NATIVE`
#[j8::module]: native modules
Like #[j8::object], but it answers one or more module specifiers (the first is canonical). In a runtime declared with
j8::runtime! it is served to import (a default export plus a named export per member) and kept in the hidden
registry __j8_native["node:fs"] for a prelude’s require.
#[j8::module("node:fs", "fs")]
impl Fs {
fn exists_sync(path: &str) -> bool { … }
}
import fs, { existsSync } from "node:fs";
Attributes
| Attribute | Meaning |
|---|---|
#[js(constructor)] | the constructor (returns Self or Result<Self, Error>); without one the class can’t be newed |
#[js(getter)] / #[js(setter)] | accessors; a getter and a setter of the same name form a pair |
#[js(static)] | a static method (the default for methods without self) |
#[js(name = "…")] | the name in JS |
#[js(skip)] | not exported |
Parameters and return values
Parameters are taken by type:
| Parameter type | Receives |
|---|---|
&mut Agent<'_, '_> | the current agent (not a JS argument; any position) |
This | the raw this |
Rest | all remaining arguments |
&str | ToString, then borrowed |
| anything else | converted in order with FromJs: f64 / i32 / u32 / usize / bool / String / JsString / JsObject / Value / Option<T> / Vec<T> |
Return values go through IntoJs; Result<T, Error> throws on Err. Write lifetimes in parameters as 'gc.
Handle types:
| Type | As a parameter | As a return value |
|---|---|---|
j8::Persistent | keeps any JS value across enter calls (store it in the host struct; .get(a) reads it) | &Persistent gives the value back |
j8::Function | a callable Persistent (TypeError if not callable); .call(a, this, args) | &Function |
j8::Bytes | the bytes of an ArrayBuffer / TypedArray / DataView | a new Uint8Array |
j8::Promise<T> | a JS promise (taken like await takes it), .awaited in Rust | — |
j8::Json<T> (feature json) | any serde::Deserialize type, read through JSON.stringify | any serde::Serialize type, made through JSON.parse |
Throwing
Take &mut Agent, return Result<T, Error>, build the error with 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")))
}
When the error is only known later, or you want structured errors (Node’s err.code), return a type of your own whose
IntoJs throws. dune’s host.rs does this with 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'"
}
}
}
The prelude reads the code off the front of the message and sets err.code. Since IntoJs runs on the runtime thread,
this works for the results of async fns too.
What a bound type must be
- A
#[j8::class]type is stored inside the JS object, so it must beSend + Sync + 'static. UseArc/ atomics for state shared with threads (seeTimerindune/src/web/timer.rs). - A method that calls back into JS that reaches the same object again (
&mut selfwhile already borrowed) throws aTypeErrorinstead of panicking. - ⛔ keeping a
Value/JsObjectin a struct: it would outlive itsenter. Keep aj8::Persistent(orj8::Function). Each is a GC root: a cycle through a host object is only freed when that object is dropped.
Async and promises
j8 has no async runtime (no tokio). Each j8::Runtime is one event loop, driven by eval and
run_until_idle.
The core rule: a future must wake its waker
When nothing can run, the loop thread parks until a waker fires. So a future must wake its waker when it can make progress, or the loop sleeps forever. Futures from crates that need their own reactor (tokio’s sockets and timers) don’t work as they are: run that work on a thread or a reactor of your own, and wake the waker from there.
async fn bindings
An async fn takes owned parameters only: no self, &str, &mut Agent, This or Rest. Its future runs after
the call has returned. The call returns a promise at once, and the result is converted with IntoJs when the promise
settles (so Io<T>-style errors reject it).
#[j8::object("later")]
impl Later {
async fn fetch_text(url: String) -> String { … }
}
Blocking work: offload to a thread
dune runs every blocking call (files, sockets, sleep) on a thread of its own (host::Offload). The core:
fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<T> {
let this = self.get_mut();
if let Some(work) = this.work.take() { // first poll: start the thread
let (tx, rx) = mpsc::channel();
let waker = cx.waker().clone();
std::thread::spawn(move || {
let _ = tx.send(work());
waker.wake(); // ⇐ without this, run_until_idle never returns
});
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
}
}
Hand-made promises: j8::Glue
When the async work needs &self, the Agent, or should be cancellable, write a normal method and make the promise
yourself:
Glue::spawn(a, future)creates a pending promise, handsfutureto the event loop and returns the promise;Glue::settle(value)is what the future must produce:valueis converted withIntoJswhen the promise settles.
#[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);
}
}
The future must be Send + 'static: clone what it needs out of self (here an Arc<AtomicBool>). A future that
becomes ready because of JS (like cancel above) needs no wake-up: the loop polls everything again after every
settlement, before it parks.
Async work belongs to the isolate that started it: each Runtime has its own queue, settled only by its own
run_until_idle, so runtimes can share a platform. An isolate made without an event loop (by hand, without
CreateParams { event_loop: true, .. }) refuses the work, and the call throws a TypeError.
Awaiting a JS promise from Rust: j8::Promise<T>
The other direction: a parameter of this type takes a JS promise, and Rust .awaits it. It is an owned parameter, so
async fn bindings can take it:
#[j8::object("math")]
impl Math {
async fn double(p: j8::Promise<f64>) -> Result<f64, Error> {
Ok(p.await? * 2.0) // a rejection passes on to this function's own promise
}
}
- It takes its argument the way
awaitdoes: a promise is watched directly (athenpatched onto it is not called), a thenable is adopted, any other value counts as already fulfilled; - the fulfilled value is converted with
FromJsintoTon the runtime thread; a rejection, or a value that doesn’t convert, comes out asErr(Error::Exception(reason)), so?rejects the binding’s own promise with the same reason; - settling wakes the future, so it works with
run_until_idle, and when polled elsewhere; - a promise that never settles keeps the future pending, like
awaitin JS: the event loop keeps waiting.
For a JS callback that runs more than once (an event handler), keep a j8::Function and call it inside rt.enter or
another binding.
Keeping the process alive
run_until_idle returns once nothing is pending. Repeating timers, servers and the like stay alive by always keeping a
future pending, and stop by settling it. A cleared timer should settle its promise (dune’s Timer::cancel), or the
loop waits for it.
Not yet
- No reactor: futures needing tokio’s (or another runtime’s) reactor never wake.
- Settlements follow the polling order: futures ready in the same turn settle in the order they were polled, not finished; JS that cares (timers) sorts it out itself.
- No timers in the loop: a timer is host work like any other (a sleeping thread that wakes its future).
- No cancellation from JS: a future can’t be dropped from the JS side; watch a flag of your own (dune’s
Timer::cancel). async fncan’t take&self: useGlue::spawn.- A panic in a future propagates out of the loop (out of
eval/run_until_idle); an error while settling stops the loop with the remaining work still queued. - Microtasks aren’t sliced: a settlement drains its microtasks in one turn.
- Not supported yet: reporting unhandled rejections, top-level
await.
Modules
ES modules from files
rt.eval_module(text, file) runs text as an ES module. DefaultPlatform resolves import relative to the importing
file (canonical paths, no node_modules). For other rules (packages, URLs, a virtual file system), write your own
Platform::load_module.
On the executor’s side, loading, linking and evaluation are synchronous; import bindings read the exporter’s slots live;
ResolveExport handles indirect exports, export * and ambiguity; namespace objects, dynamic import() and
import.meta are supported. Top-level await is not yet.
Native modules in 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" works through HostPlatform. A prelude reaches the same object as
__j8_native["myhost:kv"], for example to implement require.
A custom platform
dune’s node: modules are JavaScript objects built by the prelude, not Rust types. dune serves them to import with a
platform of its own, NodePlatform (dune/src/node/mod.rs): load_module returns a small generated ES module that
re-exports an object from __j8_native, and passes every other specifier to the inner platform.
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 requires Pool: forward it too
fn threads(&self) -> usize { self.inner.threads() }
fn run(&self, jobs: Vec<Task<'_>>) { self.inner.run(jobs); }
}
The first element of the pair is the module’s normalized name, and modules are cached by it: a second import that
resolves to the same name gets the same module. A specifier that resolves to None fails the import with
Error::Syntax("… Cannot find module '…'").
CommonJS
j8 itself doesn’t know CommonJS. dune’s require, module, and node_modules / package.json resolution (main /
exports / imports) are JavaScript in the prelude (dune/src/node/loader.js); bare specifiers on the ESM side are
resolved in dune/src/node/esm.rs. See dune.
Node-API
crates/j8napi implements Node-API on j8: the C interface native addons (including
modules written with napi-rs) link against. The napi_* functions are exported under their own names;
embedders link them in (statically, or exported from the executable for addons loaded at run time).
Use
// inside an `Isolate::enter`, with the agent of the context the addon belongs to
let exports = j8napi::Env::open(&mut agent, napi_register_module_v1)?;
agent.set_named(agent.realm.global.into(), "addon", exports)?;
Env::open makes the addon’s environment (living as long as the context’s global object), calls the register function
and gives back its exports.
How it maps onto j8
- A
napi_valueis a cell on the environment’s handle stack holding the value’s raw word; handles are valid for one entry into the isolate, during which nothing is collected. - An addon’s functions are constructible
NativeClosures: the engine makesthisfromnew.target.prototype, so JS classes can extend the addon’s classes. napi_wrapand type tags live in the object’s private members; a collected host object queues its finalizer, which runs on the JS thread at the next callback.napi_ref, pending exceptions and deferreds hold persistent handles.
Differences from Node
- A
napi_refwhose count drops to 0 is still strong (the heap has no weak references yet). - Strings are stored as UTF-8: lone surrogates in UTF-16 input are replaced.
- A Buffer is a plain
Uint8Array(there is no NodeBufferclass). - Async work and thread-safe functions need an isolate with an event loop (
EventLoopSet); each async work runs on a thread of its own.napi_unref_threadsafe_functiondoesn’t let the event loop end early; there is no libuv loop (napi_get_uv_event_loopfails).
Turn it on in the facade with feature napi: j8::napi.
dune and dunx
dune/ is a JavaScript runtime built on j8, on par with Node and Bun; dunx (the same as dune x) runs the
executables in npm packages, like npx / bunx. It is a package of its own, outside j8’s workspace, and depends on the
published j8 as an embedder would: it is itself the complete example of embedding j8.
Install
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 # the name dune is taken on crates.io; then ln -s dune ~/.cargo/bin/dunx
dune upgrade # replace itself with the latest GitHub release
See Installing dune for every option. The npm channel works the way Bun’s does (dune/npm/): the main package @jabberwocky238/dune carries placeholders and
depends, through optionalDependencies, on one package per platform (@jabberwocky238/dune-linux-x64, @jabberwocky238/dune-linux-x64-musl,
@jabberwocky238/dune-darwin-arm64, @jabberwocky238/dune-win32-x64 …). npm installs only the one that fits, and the postinstall script hard-links its
binary over the placeholders and links dunx to it, so dune starts without Node. With --ignore-scripts the
placeholders start the binary through Node. npm/pack.js lays out every package of a release from the built binaries.
One executable
There is one executable. dunx is a link to dune, which picks its command line by the name it was started under
(dunx / dunx.exe), as bun / bunx do.
Command line
dune app.js [args] # Node layer (default): CommonJS or an ES module, by Node's rules
dune run app.js [args] # the same
dune --web app.mjs # Web layer only: files run as ES modules
dune -e 'code' # run source
dune -p 'code' # run source and print the result
dune - < app.js # read stdin
dune # REPL (.help / .exit)
dune repl
dune --jit app.js # with the JIT
dune x <pkg> [args] # the same as dunx
Each folder under dune/src/cli/ is one level of subcommands: run/ is dune run, repl/ is dune repl, x/ is
dune x (the package installer lives in x/ too). --jit and --web go before or after the subcommand; everything
after the script path goes to the script as is (dune a.js run x gives run x to a.js).
Two layers
Each layer is one j8::runtime! declaration, Node on top of 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, } }
| Layer | Directory | Provides |
|---|---|---|
| Web | src/web/ | the WinterTC minimum common API: console, setTimeout / setInterval / queueMicrotask, structuredClone, EventTarget / Event / CustomEvent, AbortController / AbortSignal, DOMException, TextEncoder / TextDecoder, atob / btoa, URL / URLSearchParams, Blob / File, Headers / Request / Response / fetch (plain http: and data:), performance, crypto.getRandomValues / randomUUID, navigator, reportError |
| Node | src/node/ | process (an EventEmitter; argv, env, exit, exitCode, nextTick, hrtime, stdout / stderr), require / module resolved by Node’s rules, ES modules, Buffer, global, setImmediate, and the modules fs (with fs/promises), path, os, events, util, buffer, assert, url, timers, child_process (sync), crypto, module, string_decoder, perf_hooks |
How it is built:
- What needs the machine is Rust, bound with
#[j8::object]/#[j8::class](web/mod.rs,web/timer.rs,web/http.rs,node/mod.rs,node/fs.rs). Blocking work (files, sockets, sleeping) isasync fns that run on threads of their own and settle promises on the event loop (host.rs). Nothing touches the GC directly. - The APIs themselves are JavaScript, one file per family (
web/*.js,node/*.js), run as the prelude. - Built-in modules register with
requirethrough__j8_native.define(name, factory);NodePlatformserves them toimport(node:fsorfs, with named exports). - The event loop is
j8::Runtime::run_until_idle: the process ends when no timers and no host work are left, withprocess.exitCode. An uncaught error printsUncaught …and exits with 1, unlessprocess.on('uncaughtException')takes it.
dunx
dunx cowsay hello # the package's own executable
dunx semver@^7 1.2.3 -r '>1.0.0' # a version or range; options after the command are the executable's
dunx -p typescript tsc --version # an executable whose name differs from its package
dunx --no-install json5 --version # never touch the registry
Lookup order:
- the nearest
node_modulesup from the current directory (.bin/<command>first when no version is asked for); - the cache (
$DUNE_CACHE, default~/.cache/dune/x); - otherwise, install from the registry (
$DUNE_REGISTRY/$npm_config_registry, default registry.npmjs.org) into the cache.
The installer (src/cli/x/: spec.rs parses specifiers, registry.rs fetches metadata, tree.rs resolves the tree,
manifest.rs reads package.json) installs dependencies, optional dependencies for this platform and peers into a
hoisted node_modules, checks every tarball against its integrity, and runs no lifecycle scripts. JavaScript
executables (by the #! line or the extension) run in this process on the Node layer; others (native programs, shell
scripts) run as child processes.
Known to work: cowsay, semver, json5, esbuild, biome, tsc 7.
Not yet
Top-level await, named exports when an ES module imports CommonJS (only default), reporting unhandled rejections,
https: in fetch, http / net servers, streams, async child_process.spawn, worker_threads, zlib, hashing and
ciphers in crypto, Error.stack.
workerd and jumpheap
workerd
samples/workerd: a sample host that loads Cloudflare Workers (ES modules with export default { fetch }) and Durable
Objects on j8.
cargo run -- examples/counter.js --bind COUNTER=Counter --request "GET /c/inc?name=a"
cargo run -- examples/counter.js --bind COUNTER=Counter --port 8787 # an HTTP server
cargo run -- examples/chat.js --bind ROOM=ChatRoom --port 8787 --storage .chat # a WebSocket chat room
- the Fetch API subset, WebSocket and Durable Objects are JavaScript in
src/prelude.js; - every Durable Object has key-value storage (Rust’s
KvStore) and SQL storage (ctx.storage.sql, one SQLite file per object under--storage, or in memory without it;src/sql.rs); --bind NAME=Classhands a Durable Object class to the worker’senv.
WebSocket
The API follows workerd: new WebSocketPair(), server.accept() (or the hibernation API ctx.acceptWebSocket(ws, tags),
whose events go to the object’s webSocketMessage / webSocketClose, with ctx.getWebSockets(tag) and
serializeAttachment), send, close, addEventListener, and new Response(null, { status: 101, webSocket: client }).
The network layer (src/ws.rs) is one epoll reactor thread for the whole process (mio): it accepts, reads requests,
parses frames and writes, without blocking, and never runs JS. Requests and messages reach the event loop through
single-consumer streams that JS awaits (net.accept(server), net.recv(id)); replies, upgrades and frames go back to
the reactor as commands. With no messages, the event loop sleeps.
examples/chat.js is a chat room: a message is written to the object’s SQLite table, then sent to everyone in the room;
newcomers get the stored history first. tests/chat.rs stresses it: eight clients, two rounds of concurrent messages,
five seconds of silence in between (the server must not burn CPU), the same order seen by every client, then a restart on
the same storage replaying the history in order.
A thousand Workers in one process
--instances N starts N Workers in one process, each with its own runtime (isolate, context, Durable Objects,
<storage>/<i>) and port, all on one event loop set with --threads loop threads. tests/workerds.rs
runs a thousand chat rooms this way: every room talks at once for two rounds, five seconds of silence in between (the
whole process must not burn CPU), then a restart and every room’s history replayed.
All instances share one CodeCache (the prelude and the Worker’s modules compile once) and one epoll reactor thread.
jumpheap
samples/jumpheap: resident j8 workers in separate processes whose JS objects reference each other’s heaps.
Each process owns a paragc public heap (a memory file in /dev/shm); its worker (a workerd-style
export default { fetch }) makes JS matrices there, sends them to other workers over HTTP, and listens for theirs. What
arrives is an object event carrying a JS Matrix: the object is in the receiver’s own isolate heap, and its rows are
Float64Arrays over the sender’s heap, not copies. Everything computed on it is plain JS.
cargo run --release -- examples/matrix.js --name wa --dir /dev/shm/jumpheap # prints its port
| JS API | |
|---|---|
await heaps.matrix(rows) | a new all-zero rows × 100000 Matrix in this process’s heap |
matrix.data[i] | row i: a Float64Array over public heap memory (this process’s or another’s) |
matrix.rows, matrix.cols, matrix.local | the shape; whether it is in this process’s heap |
await heaps.send(url, matrix, name, task) | hand matrix to the worker at url, get its answer |
heaps.addEventListener('object', e => …) | a matrix arrived: e.object, e.name, e.task; e.respondWith(value) answers the sender |
A received matrix holds an entry in the sender’s heap, and its rows stay alive as long as the receiver holds any row’s
buffer; after the sender dies, what it wrote into other heaps remains. tests/three.rs starts three workers that send
each other matrices, kills one mid-way, and checks the results are still right.
Debugging and benchmark tools
j8bcdbg: reading bytecode
samples/j8bcdbg compiles JS and lists the bytecode per function in the format of V8’s --print-bytecode (example in
Bytecode).
cd samples/j8bcdbg
cargo run -- compile a.js # `-` reads stdin
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 # write to a file
JIT switches
| Variable | Effect |
|---|---|
J8_JIT_LOG=1 | prints every compilation (instructions, bytes, time) and every deopt (reason, place) |
J8_JIT_IR=1 | prints the compiled graph |
J8_JIT_BIN=<dir> | writes each piece of machine code to f<function>-<entry>.bin, for objdump |
J8_NOJIT=1 | interpreter only, in the benchmark samples |
Three benchmark suites
The same JS benchmarks (samples/benchv8/bench/*.js, 11 of them) run on several engines; every script’s completion
value is a checksum that must match on all of them:
| Sample | Compared with | Notes |
|---|---|---|
samples/benchv8 | V8 (JIT) and V8 --jitless | through rusty_v8 152.2.0; downloads V8’s prebuilt library |
samples/benchjsc | JavaScriptCore (JIT) and JSC_useJIT=false | the system’s WebKitGTK library (C API) |
samples/benchquickjs | QuickJS (quickjs-ng 0.16.2) | built from source by rquickjs; QuickJS has no JIT |
cd samples/benchv8
cargo run --release # every engine once, comparison table
cargo run --release -- --engine j8 # only one
cargo run --release -- --runs 10 # runs per benchmark, the shortest kept (default 5)
- each engine runs in its own child process (
--jitlessis process-wide); - timing covers compile + execute, each run in a fresh environment, the shortest kept;
- each is a workspace of its own, so a plain
cargo build --workspacedoesn’t pull V8’s prebuilt library.
Results and analysis: Performance.
test262 and testing
test262
tests/test262 is the tc39/test262 submodule (a shallow clone; fetch it with
git submodule update --init), and the runner tests/test262.rs is a test of the root package (harness = false, not
published).
cargo test --release --test test262 # only the baseline; fails on any loss
cargo test --release --test test262 -- language/expressions/addition built-ins/Math # these directories
J8_TEST262_JIT=1 cargo test --release --test test262 # with the JIT (every function compiled on its first call)
J8_TEST262_VERBOSE=1 cargo test --release --test test262 -- <path> # why each failing case failed
J8_TEST262_UPDATE=1 cargo test --release --test test262 -- <path> # write the results into the baseline
- one child process per case, 10 s timeout; results are pass / fail / unsupported (j8 reported
Error::Unsupported) / skip / timeout / crash, summarized by directory; - the baseline
tests/test262.passinglists passing cases one per line, 42,443 now; without arguments only those run, as the regression check; - sloppy mode plus
onlyStrict(run strict); module cases run the harness scripts first, then the module; - the
$262host object providesglobal/evalScript/gc/detachArrayBuffer(createRealmthrows TypeError); - line numbers in errors from unsupported syntax include the prepended harness.
Zero regressions on every commit is a hard rule, and the same baseline must pass with the JIT on (threshold 0, every function compiled on its first call, for the widest coverage).
Other tests
| Test | Covers |
|---|---|
tests/runtime.rs, tests/event_loop.rs, tests/terminate.rs | runtimes, event loops, termination |
tests/binding.rs, tests/bindings_more.rs | the binding macros |
crates/j8bytecode/tests/v8.rs | decodes 738 instructions V8 printed, checking each |
javascript_semantics in crates/j8executor | a table of exactly determined JS semantics |
crates/j8jit/tests, j8taskqueue/tests, j8lockfree/tests, j8napi/tests | each crate’s own |
samples/workerd/tests | the chat room stress test, a thousand Workers |
samples/jumpheap/tests/three.rs | matrices across three processes’ heaps |
Adding a feature
Each roadmap phase goes:
- add cases to the semantics table;
- clippy clean;
- run the test262 baseline in a snapshot, zero regressions;
- record newly passing cases of the relevant directories with
J8_TEST262_UPDATE=1; - commit and push (j8 uses branches and pull requests on GitHub).
Unit tests only pin facts that are certain; run one at a time, under timeout 15.
Performance
Against V8
samples/benchv8 (j8 with its JIT, --runs 10, pinned to performance cores, load below 1). All 11 benchmarks produce
matching checksums on the three engines.
| Benchmark | 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× |
| Geometric mean | 0.6× | 1.7× |
(A ratio below 1 means j8 is faster. From samples/benchv8/benchmark.md; the repository has the current numbers.)
What the JIT does for them
- fib: a native function per JS function, called directly (arguments in registers, results unboxed through a second
return register), the recursive call inlined two levels deep; the global
fibread through an epoch cache; - closures: the closure inlined into the loop (checked by function identity), its context slots in registers,
% 100000as a multiplication; - classes / objects: constructors and methods inlined, objects that don’t escape never allocated (fields as values, across loop iterations too: the loop entered on-stack is peeled once), shape checks and loads hoisted out of the loop;
- loop:
(s + i * i) % 1000003withi * ipast int32 runs as an int64 remainder of doubles.
array, sort, string, collections, json and regexp spend their time in built-ins (and the GC); the JIT doesn’t help them yet, and they are next.
Measuring
- timing covers compile + execute, a fresh environment per run, the shortest kept;
- pin to performance cores (
taskset -c 0-3) and run with low load; - judge a change by all the benchmarks, not just the one it targets;
- callgrind for line-level hot spots;
perf stat -e instructions:ufor instruction counts.
Code conventions
j8 has explicit code rules; pull requests follow them.
Structure
- Private submodules (
mod), flattened bypub useat the crate root, ⛔pub mod; visibility comes from private modules, and items are plainpub. - Dependency direction: every layer depends only on
j8framework;j8frameworkdepends on no layer;j8bytecodeis the root. dune/andsamples/*are packages of their own (with an empty[workspace]) depending on the publishedj8by version, ⛔ path dependencies. When a new API isn’t published yet, patch locally with--configon the command line ([patch.crates-io]), ⛔ committing the patch or a lock file generated with it.
Rust
- ⛔
staticand the'staticlifetime (except&'static strnames in enums); no global or static storage. Background tasks borrow the caller’s data throughTask<'t>. - Strings are turned into enums right after deserializing, ⛔ deciding on strings.
- Conversions use
From/TryFrom/Into, ⛔ hand-writtento_xxxconversions (unless extra arguments are needed). - Functions are methods of a type wherever possible: of the one mutable type among the parameters, or of the big struct.
- Prefer references, borrows and slices.
- Coefficients, thresholds and field encodings are named
consts, ⛔ bare numbers. - No provenance in code (measurement dates, machines, commit ids): that goes in commit messages.
- Reduce code with macros and generators: the bytecode tables come from V8’s headers, heap structs use
#[heap], bindings use#[j8::class]. - Source code carries no comments; documentation lives in the READMEs, the guides and this book.
The heap
- Collection moves objects: ⛔ storing a
Gcor an object address where it isn’t traced. - Write a value’s slots only once it is on the heap.
- Stop-the-world collection only, ⛔
mark_concurrently. - Lock-free structures are hand-written in j8lockfree, ⛔ crossbeam.
See Heap and GC.
Tests
- Unit tests pin only certain facts backed by real data; nothing uncertain (otherwise they pin wrong behavior).
- One unit test at a time, under
timeout 15. - Zero test262 regressions.
Documentation
- English first: the repository and every published sub-package have a
README.md(English, the default) and aREADME.zh-CN.mdtranslation, linked to each other. - This book is English with a Chinese translation; change both together.
Commits
- j8 lives on GitHub (0x00-Community/j8): branches and pull requests, main is protected, and merged branches are deleted automatically.
Roadmap
j8’s main line is the test262 pass rate (PLAN.md). Every phase: add cases to the semantics table → clippy clean → run
the baseline in a snapshot with zero regressions → record the newly passing cases → commit.
Out of scope: Temporal, intl402, ShadowRealm, explicit resource management (using / DisposableStack), import
defer, decorators, source phase imports.
Done
| Phase | Contents |
|---|---|
| 1 Infrastructure | dynamic code (eval, Function, generator / async constructors), early errors, strict mode, global declaration checks, $262 |
| 2 Object / Array / property model | the spec’s internal methods, dense arrays with holes, Object completed, Array methods generic over array-likes, length of built-ins, prototypes from new.target |
| 3 Reflection and iterators | Reflect, Proxy (revocable too), iterator helpers, Set methods, Map.groupBy |
| 4 Binary data | ArrayBuffer (resizable, transfer, detach), SharedArrayBuffer, DataView, 12 TypedArrays (Float16 included), Atomics |
| 5 Date / RegExp / strings and numbers | Date (local time as UTC), RegExp’s Symbol protocol and d flag, String completed, exact number formatting, Math.sumPrecise, Promise rewritten on NewPromiseCapability |
| 6 The dynamic parts of the language | direct eval, with, Annex B block-level function hoisting, generator parameter initialization, arguments linked to parameters, modules and dynamic import() |
Still to do
- top-level
awaitin modules, import defer / source phase; - the conflict rule for
var argumentsdeclared by eval in parameter expressions; - Annex B block-level functions inside eval code;
- string storage that can represent lone surrogates (UTF-8 for now);
- real weak references for
WeakRef/FinalizationRegistry(strong for now); - Date’s local time zone.
JIT
The plan is to skip a baseline compiler and go straight to a speculative optimizing tier: inlining, escape analysis, deoptimization and OSR are in; next, make the built-in-heavy benchmarks (array, sort, string, collections, json, regexp) benefit, aiming to beat V8 with its JIT on common benchmarks.
Runtimes
- dune: top-level
await,https:,http/netservers, streams, async child processes,worker_threads,zlib,cryptohashes and more; publishing the npm package@jabberwocky238/dune; - Node-API: real weak references.
Glossary
| Term | Meaning |
|---|---|
| acc (accumulator) | the implicit result register of the bytecode; most instructions read or write it |
| Agent | the context of one run; JS operation semantics hang off it |
| Context | an execution context: the global object and built-in prototypes |
| context slot / Env | the heap environment holding variables that closures capture |
| CodeCache | bytecode shared by several executors |
| deopt | a failed speculation: machine code goes back to the interpreter |
| EventLoop / EventLoopSet | one JS event loop / the loop threads running many of them |
| feedback slot | where bytecode records types and shapes it saw; the JIT speculates on them |
| FrameState | what each interpreter register holds at a guard; frames are rebuilt from it on a deopt |
| ’gc brand | the lifetime of one Isolate::enter; values carrying it can’t leave that entry |
| GcCell / ValueCell | j8’s mutable cells on paragc: a snapshot of a block of data / a single value |
| Global | a persistent handle, surviving enter calls |
| IC (inline cache) | per property-access site, results cached by shape |
| Ignition | V8’s interpreter; j8’s bytecode matches it byte for byte |
| Intrinsics | the interface that installs built-ins into a Realm, implemented by j8builtins |
| Isolate | an independent JS world: one GC heap |
| NaN-boxing | one 64-bit word per value, non-numbers packed into NaN bit patterns |
| OSR (on-stack replacement) | entering machine code in the middle of a loop |
| paragc | the GC library j8 uses |
| Platform | the thread pool, clocks, output and module loading the host lends the engine |
| prelude | JS a runtime runs after installing its bindings, to build its public API |
| Realm | the spec’s realm: a set of global object and built-ins |
| rope | a lazy string concatenation: two halves plus the total length |
| Shape (hidden class) | the layout of an object’s properties, shared by objects built the same way |
| short Star | Star0 … Star15: one-byte register stores without operands |
| Tier | the executor’s JIT hook |
| TDZ (temporal dead zone) | the region before a let / const / class is initialized |
| trampoline | one jump per function, to its machine code or the interpreter |
__j8_native | a runtime’s hidden registry object |