Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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 runQuick start
understand the designArchitecture, then “Inside the engine” in order
build your own runtime on j8the “Embedding j8” part, from Building a host
run scripts and npm packages with dunedune and dunx
contributeCode 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 Rustoxc parses; everything else is j8’s own code.
🧱 Bytecode firstNo AST interpreter: all JS (eval and Function included) is compiled to bytecode before it runs.
🔣 V8’s bytecodeThe bytecode list, operand encoding, registers and frame layout match V8 Ignition byte for byte; the tables are generated from V8’s headers.
🧬 Speculative JITFeedback from the inline caches turns bytecode into a speculative SSA graph: inlining, escape analysis, loop-invariant code motion, OSR, deoptimization.
♻️ paragc heapImmix-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 stateNo 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

DirectoryContents
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_INSTALLinstall root for the scripts (default ~/.dune; binaries in its bin/)
DUNE_RELEASESwhere the scripts download releases from (default https://github.com/0x00-Community/j8/releases)

Platforms

PlatformRelease archiveJIT
Linux x64 (glibc 2.17+ / musl)dune-linux-x64.tar.gz / dune-linux-x64-musl.tar.gzyes
Linux arm64 (glibc 2.17+ / musl)dune-linux-arm64.tar.gz / dune-linux-arm64-musl.tar.gzno
macOS x64 / arm64dune-darwin-x64.tar.gz / dune-darwin-arm64.tar.gzx64 only
Windows x64 / arm64dune-win32-x64.tar.gz / dune-win32-arm64.tar.gzno

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

featurebrings
runtime (default)executor + builtins + platform
bytecodej8::bytecode: bytecode definitions, encoding / decoding
compilerj8::compiler: JS ⇒ bytecode (includes bytecode)
executorj8::executor: the bytecode executor (includes compiler)
builtins / platformbuilt-in objects / the standard-library platform
jitj8::jit: the JIT (x86-64 Unix, includes executor)
jsonj8::Json<T>: Rust values crossing as JSON-shaped data through serde
napij8::napi: Node-API
taskqueue / lockfreethe task queue / lock-free building blocks
fullall 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
crateRole
j8frameworkthe 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
j8bytecodebytecode definitions, byte for byte V8 Ignition’s; the dependency root, depends on no other j8 crate
j8compilerJS ⇒ bytecode (oxc parses; code generation after V8’s BytecodeGenerator)
j8executorthe bytecode executor: implements Engine, with inline caches, sliced execution and the JIT hook
j8jitthe speculative JIT (x86-64 Unix): implements the executor’s Tier
j8builtinsthe standard built-in objects: implements Intrinsics
j8platformthe standard-library Platform: thread pool, clocks, module loading
j8bindingthe runtime side of Rust ⇄ JS bindings (FromJs / IntoJs, host objects)
j8napiNode-API: the C interface native addons link against
j8taskqueuea lock-free dataflow task queue (no_std); every event loop is one
j8lockfreehand-written lock-free building blocks (no_std)
j8macrosprocedural 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:

traitimplemented bydoes
Platform (supertrait Pool)j8platform::DefaultPlatform, or the host’s ownthread pool, clocks, console.log output, module loading
Intrinsicsj8builtins::Builtinsinstalls the global object and built-in constructors into a new Realm
Enginej8executor::Executorthe execution entry: eval, resumable start / resume
Invokethe executorbuilt-ins calling back into JS (map’s callback, getters …)
Tierj8jit::Jitthe 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':

  1. The host sets up. The runtime dune declares with j8::runtime! creates an Isolate (one GC heap), an Executor and a Context (the global object installed by Builtins) on an event loop thread, and runs the JS preludes (Building a host).
  2. Compile. The executor hands the source to j8compiler: oxc parses and checks it (early errors are SyntaxErrors 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’s BytecodeGenerator. The result is a j8bytecode::Module (a list of SharedFunctions, each with a BytecodeArray). When many runtimes run the same preludes, a CodeCache compiles each source once (Executor).
  3. 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.
  4. 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 (s and i guessed as int32), optimizes it, emits x86-64 directly and enters it at the loop header (OSR).
  5. Deoptimize. When a speculation fails (s outgrows int32), a guard jumps to a cold path; j8_deopt rebuilds the interpreter frames from the recorded frame state and the interpreter goes on. The JIT leaves a hint: next time it uses doubles there.
  6. Finish. The result is a Value (one NaN-boxed machine word); the host gets a Global handle, 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, Call forms by argument count, feedback slots); adopting it is safer than reinventing it;
  • it can be compared with V8 directly: j8bcdbg compile prints the same listing as d8 --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 keyGenerates
bytecodesBytecode (repr(u8), V8’s numbering, 215 of them) with each one’s operand_types() and implicit_register_use()
operand_typesOperandType, OperandTypeInfo
implicit_register_usewhether it reads / writes / clobbers the accumulator, writes a short Star
runtime / intrinsicsthe function ids of CallRuntime / InvokeIntrinsic
function_kinds, feedback_slot_kinds, scope_types, variable_modesthe 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 / ExtraWide prefix (OperandScale); fixed ones always take their size;
  • Encoder picks the smallest scale per instruction, Decoder reads 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):

j8V8Contents
Module—every function compiled from one source, the first being the top level
SharedFunctionSharedFunctionInfoname, kind (FunctionKind), strictness, length, formal parameter count, scope info, bytecode
BytecodeArrayBytecodeArraycode bytes, constant pool, handler table, parameter / register counts, feedback slot kinds, the new.target / generator register
Constantconstant pool entrystrings, numbers, scope infos, object / array / class boilerplates, template objects …
HandlerEntryhandler 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 an undefined receiver 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;
  • JumpLoop is 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

FileContentsAfter V8’s
scope.rswhich names each scope level declares (Decls), which bindings inner functions capture (Resolver)scope analysis
compiler.rsscopes, functions, statementsBytecodeGenerator
expr.rsexpressions (results always in acc)BytecodeGenerator
builder.rsemitting one function’s bytecodeBytecodeArrayBuilder / 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:

VariableLives inBytecode
a function’s own variables nobody capturesregisters (parameters a0 …, this the receiver)Ldar / Star
variables inner functions capturecontext slots: one context per scope level that has anyLdaCurrentContextSlot / LdaContextSlot
top-level script vars / functionsproperties of the global object (declared by DeclareGlobals)LdaGlobal / StaGlobal
top-level script let / const / classthe script context (shared across scripts, not on the global object)LdaCurrentContextSlot …
names inside with, or reachable by a sloppy direct evallooked up by nameLdaLookupSlot

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:

  • Star to r0 … r15 is a one-byte short Star, 0 is LdaZero, small integers are LdaSmi;
  • calls pick CallUndefinedReceiver0/1/2, CallProperty0/1/2, CallAnyReceiver … by argument count and receiver;
  • intrinsics go through InvokeIntrinsic, runtime functions through CallRuntime;
  • forward jumps are patched; when an offset doesn’t fit its operand, a reserved constant pool entry backs it (the JumpConstant family);
  • 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_direct compiles 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; sloppy vars / functions in eval land in the calling function (reusing a binding of the same name, otherwise going into an eval variable object looked up like with); lexical conflicts raise SyntaxError.
  • Generator / async function constructors: GeneratorFunction and friends compile a function of that FunctionKind.

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 as Value::context words between CreateFunctionContext / 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 Weak so 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 DEPTH levels 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:

WhenCall
a call is about to run a frame from its first instruction (asked every 64 calls)Tier::enter
a JumpLoop has been taken many timesTier::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 frameTier::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 --jit and J8_TEST262_JIT=1 (test262 runs its baseline with the JIT) turn it on;
  • Jit::from(n) sets the hotness threshold (default Jit::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

KindWhenHow it runs
Enterthe interpreter calls a hot functionon the frame the interpreter built for it
Osr(at)loop header at has jumped back often enoughon the current frame, entering mid-loop
Native(n)compiled code calls compiled codestraight 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:

KindExamples
constants and parametersI32, F64, Word, Param, Callee, Phi
arithmeticInt(op, a, b, fs) (with a frame state when it can overflow), Float, IntToFloat
boxingBoxInt, BoxFloat, UnboxInt(v, fs) (guard: an int32, not −0), UnboxFloat
guardsCheckObject, CheckShape, CheckFunc (the closure runs a given function), CheckNotHole
memoryLoadWord, LoadPtr, StoreCell (with a write barrier when needed), ContextCell
callsCall(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.rs holds 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:

ReasonHint
int32 speculation faileddoubles there next time (HINT_FLOAT)
type / shape mismatchthe generic path there next time (HINT_GENERIC)
the callee was not the one speculatedno inlining + generic (HINT_NO_INLINE)
bytecode the JIT doesn’t compilethat 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

NameRoleV8
Platform / Poolthe threads and clocks the host lends the enginev8::Platform
Isolatean independent JS world: one GC heap (paragc) and a profilerv8::Isolate
Scopeone entry into an isolate; values in it carry the 'gc brand and can’t leave itHandleScope
Value<'gc>a JS value: V8’s Local, it can’t leave the closureLocal<Value>
Globala persistent handle (paragc Root): survives enter calls, released on dropGlobal<T>
ContextRootthe execution environment kept across slices—
Context / Realmthe execution context: the global object and built-in prototypes (Intrinsics, from j8builtins)Context
Agentthe context of one run; all JS operation semantics hang off it, calls back into JS go through Invoke—
Enginethe entry the execution engine (j8executor) implements; resumable (start / resume)—
Profilercall / back-edge counters—
EventLoop / EventLoopSetJS 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; 'gc is 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’s HandleScope.
  • To keep a value across entries, turn it into a Global with scope.persist(v) / agent.global(v).

Values: one NaN-boxed word

A Value is one 64-bit word (ValueBits):

  • numbers are their own f64 bits (every NaN is stored as CANONICAL_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

VariantMeaning
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::Terminatedstopped 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

FileContents
promise.rspromises and microtasks: resolve / reject, then reactions, driving async coroutines, draining the queue
module.rsmodule records, import / export entries, ResolvedBinding
proxy.rsProxy: internal-method entry points dispatched to traps, with invariant checks
typed.rs, backing.rsTypedArray elements; where an ArrayBuffer’s bytes live (its own, host-mapped, shared between isolates)
text.rsstrings (see the object model)
parallel.rsparallel built-ins: plain-data work on large inputs split into chunks on the platform’s pool (fork–join)
layout.rsbyte offsets into heap objects that machine code reads and writes directly
lazy.rsproperties computed on first read (V8’s AccessorInfo on function maps: name isn’t made with the closure)
private.rsprivate 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 Gc pointers (collection moves objects) and are managed with Arc; the transition table stores Weak, 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>: N ValueCells (N = 2 / 4 / … / 128), the first word its capacity;
  • an inner Node: 128 child slots, the first word NODE plus 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 length and 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 a s += c loop 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 Gc inside: 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:

CellHoldsHow it changes
GcCella 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
ValueCellone Value (environment and property slots)a word plus a slot
Cow, GcQueue, Staticcopy-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 every Gc hangs off a root, and objects move. ⛔ storing a Gc or an object address where Trace doesn’t look (Static, side caches). Things hashed by address (the indexes of Map / Set) are updated in relocate (see Collection). 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); the new that #[heap(new)] generates fills cells before that, without the barrier.
  • Stop-the-world collection only (collect_if_needed / collect, parallel inside): GcCell changes 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 through relocate, and addresses in ValueCell words are rewritten. ⛔ YoungEvacuation::Full: it rewrites the addresses in old objects’ slots but doesn’t know the copy in ValueCell words.

When it collects

  • after Isolate::enter returns, 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 enter returns, 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

FileBuilt-ins
global.rsthe global object, parseInt / parseFloat / isNaN / eval / the URI functions
object.rs, function.rs, reflect.rsObject, Function, Reflect / Proxy
array.rs, typed.rs, buffer.rsArray, TypedArrays (12 kinds, Float16 included), ArrayBuffer / SharedArrayBuffer / DataView / Atomics
string.rs, text.rsString, Symbol
regexp.rs, dfa.rsRegExp (regress plus a DFA fast path)
json.rsJSON
math.rs, bigint.rs, date.rsMath, BigInt, Date
collections.rs, weak.rsMap / Set, WeakMap / WeakSet / WeakRef / FinalizationRegistry
promise.rs, asyncgen.rs, iter.rsPromise, async generators, iterators and iterator helpers
error.rsError, TypeError … AggregateError, cause
helpers.rsshared 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), growable SharedArrayBuffer, DataView, Atomics (single-threaded semantics);
  • Date (the local time zone is UTC); number formatting (toFixed / toPrecision / toExponential with exact decimals), Math.sumPrecise / f16round;
  • RegExp: the Symbol protocol, lastIndex, the d flag, named groups, species, RegExp.escape; the string methods match / 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, so class X extends Map works; 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.rs is a second one: for patterns the regex crate matches exactly like ECMAScript on an all-ASCII subject, it uses finite automata with a literal prefilter instead of backtracking. Dfa::new translates the pattern and refuses everything whose meaning could differ: back references, lookaround, named groups, v mode, anchors under m, 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() without g / y skips lastIndex.

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:

  1. 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;
  2. settlements, which resolve a promise with what host work produced and drain the microtasks;
  3. 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 every set.set_check steps; set.loads(), set.spent() and EventLoop::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).

NameRole
ITaska task: recursable (may it add tasks or ask to run again), depend (what must finish first), exec (run with a bytecode quota)
ITaskPoll / TaskQueuethe queue: add a task for a TaskId, run to start
Queuethe queue without threads, kept by the host (one per event loop): run on the calling thread, run_on spread over a pool
Poola 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
TaskIda task handle; family finds the family’s root (union-find), cancel cancels the whole family
Quotaa 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 MPMC Fifo) 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::Yield and queues again; each run also has a total budget, after which it returns Stop::Budget;
  • borrowing, not 'static: tasks live in 'a and may borrow the caller’s data; only Send is 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.

TypeWhat it is
Fifomulti-producer multi-consumer FIFO queue (monotonic positions, a segmented slot table)
SegVecappend-only segmented vector: stable indices, concurrent reads; compaction and removal need exclusive access
PushListpush-only Treiber stack: take the whole list, or seal it (pushes after sealing are handed back)
Stocka stock: tidied into a read-only array when exclusive, claimed in batches by an atomic cursor when concurrent
DequeChase–Lev work-stealing deque: the owner (Owner) pushes and pops, others steal
OnceBoxa lazily published value (concurrent initializers each compute, the winner stays)
AtomicRefCella 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

UserUses
j8taskqueueFifo as the ready queue, PushList as downstream lists
j8framework event loopsmessage queues, work stealing
j8binding host objectsAtomicRefCell around Box<dyn Any + Send + Sync>
j8executorinline 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 (through j8framework::Pool). Background tasks and parallel built-ins run on it. The GC heap has collector threads of its own.
  • Clocks: Instant for the monotonic clock, SystemTime for Date.
  • Modules: relative paths resolved against the importing file’s directory, read from disk (no node_modules).
  • console.log goes 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)
PathWhat 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::Runtimea ready execution environment: eval, eval_module, run_until_idle, set, text, enter
j8::Host / j8::HostPlatformthe trait runtime! implements / the platform serving its native modules (stateless: runtimes may share one)
j8::framej8framework: Agent, Error, ErrorKind, Value, Platform, Source …
j8::platform::DefaultPlatformthe standard-library platform
j8::executor::Executorthe bytecode executor; with_tier adds the JIT
j8::Promise<T>a JS promise awaited from Rust
j8::GlueGlue::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:

  1. X::platform(inner) wraps a platform in a HostPlatform for runtime X. Keep it alive as long as the runtime: Runtime<'p> borrows it.
  2. j8::EventLoopSet::scope(&platform, threads, |set| …) starts the loop threads the runtimes live on, for the length of the closure.
  3. 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 as Err here. 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.
  4. rt.eval(text, file) runs a script and returns a Global (a handle that outlives the call); rt.text(&g) turns it into a string with ToString.
  5. rt.run_until_idle() waits until no async host work is left. Call it after every eval if your bindings have async 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:

SectionTakesEnds up at
globals: [..]#[j8::class] / #[j8::object] typesthe global object: globalThis.Process
modules: [..]#[j8::module("node:x", "x")] typesimport … from "node:x" and __j8_native["node:x"]
natives: [..]#[j8::class] / #[j8::object] typesthe hidden registry: __j8_native.env, __j8_native.KvStore
prelude: EXPRJavaScript (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

VariantMeaningWhat hosts do
Error::Exception(g)JS threw; g is the thrown valuert.text(&g) ⇒ Uncaught …
Error::Syntax(msg)the source doesn’t parseprint msg
Error::Unsupported(msg)syntax j8 doesn’t support yetprint 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 codesdune/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-threaddune/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 systemdune/src/node/fs.rs + fs.js
a custom Platform for JS-written modules; Runtime::setdune/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 preludesamples/workerd/src/main.rs (KvStore) + prelude.js
call a JS-defined entry point per requestsamples/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

AttributeMeaning
#[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 typeReceives
&mut Agent<'_, '_>the current agent (not a JS argument; any position)
Thisthe raw this
Restall remaining arguments
&strToString, then borrowed
anything elseconverted 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:

TypeAs a parameterAs a return value
j8::Persistentkeeps any JS value across enter calls (store it in the host struct; .get(a) reads it)&Persistent gives the value back
j8::Functiona callable Persistent (TypeError if not callable); .call(a, this, args)&Function
j8::Bytesthe bytes of an ArrayBuffer / TypedArray / DataViewa 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.stringifyany 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 be Send + Sync + 'static. Use Arc / atomics for state shared with threads (see Timer in dune/src/web/timer.rs).
  • A method that calls back into JS that reaches the same object again (&mut self while already borrowed) throws a TypeError instead of panicking.
  • ⛔ keeping a Value / JsObject in a struct: it would outlive its enter. Keep a j8::Persistent (or j8::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, hands future to the event loop and returns the promise;
  • Glue::settle(value) is what the future must produce: value is converted with IntoJs when 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 await does: a promise is watched directly (a then patched onto it is not called), a thenable is adopted, any other value counts as already fulfilled;
  • the fulfilled value is converted with FromJs into T on the runtime thread; a rejection, or a value that doesn’t convert, comes out as Err(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 await in 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 fn can’t take &self: use Glue::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_value is 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 makes this from new.target.prototype, so JS classes can extend the addon’s classes.
  • napi_wrap and 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_ref whose 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 Node Buffer class).
  • 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_function doesn’t let the event loop end early; there is no libuv loop (napi_get_uv_event_loop fails).

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, } }
LayerDirectoryProvides
Websrc/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
Nodesrc/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) is async 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 require through __j8_native.define(name, factory); NodePlatform serves them to import (node:fs or fs, with named exports).
  • The event loop is j8::Runtime::run_until_idle: the process ends when no timers and no host work are left, with process.exitCode. An uncaught error prints Uncaught … and exits with 1, unless process.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:

  1. the nearest node_modules up from the current directory (.bin/<command> first when no version is asked for);
  2. the cache ($DUNE_CACHE, default ~/.cache/dune/x);
  3. 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=Class hands a Durable Object class to the worker’s env.

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.localthe 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

VariableEffect
J8_JIT_LOG=1prints every compilation (instructions, bytes, time) and every deopt (reason, place)
J8_JIT_IR=1prints the compiled graph
J8_JIT_BIN=<dir>writes each piece of machine code to f<function>-<entry>.bin, for objdump
J8_NOJIT=1interpreter 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:

SampleCompared withNotes
samples/benchv8V8 (JIT) and V8 --jitlessthrough rusty_v8 152.2.0; downloads V8’s prebuilt library
samples/benchjscJavaScriptCore (JIT) and JSC_useJIT=falsethe system’s WebKitGTK library (C API)
samples/benchquickjsQuickJS (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 (--jitless is 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 --workspace doesn’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.passing lists 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 $262 host object provides global / evalScript / gc / detachArrayBuffer (createRealm throws 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

TestCovers
tests/runtime.rs, tests/event_loop.rs, tests/terminate.rsruntimes, event loops, termination
tests/binding.rs, tests/bindings_more.rsthe binding macros
crates/j8bytecode/tests/v8.rsdecodes 738 instructions V8 printed, checking each
javascript_semantics in crates/j8executora table of exactly determined JS semantics
crates/j8jit/tests, j8taskqueue/tests, j8lockfree/tests, j8napi/testseach crate’s own
samples/workerd/teststhe chat room stress test, a thousand Workers
samples/jumpheap/tests/three.rsmatrices across three processes’ heaps

Adding a feature

Each roadmap phase goes:

  1. add cases to the semantics table;
  2. clippy clean;
  3. run the test262 baseline in a snapshot, zero regressions;
  4. record newly passing cases of the relevant directories with J8_TEST262_UPDATE=1;
  5. 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.

Benchmarkj8 msV8 jitless msV8 msj8 / jitlessj8 / V8
fib1.29.01.30.1×0.9×
loop58.3185.082.80.3×0.7×
objects0.913.62.50.1×0.4×
array40.813.06.53.1×6.3×
sort65.832.116.52.1×4.0×
string27.811.711.32.4×2.5×
closures2.117.22.30.1×0.9×
classes1.423.32.80.1×0.5×
collections52.827.921.31.9×2.5×
json24.911.611.52.2×2.2×
regexp12.43.01.84.2×7.0×
Geometric mean0.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 fib read through an epoch cache;
  • closures: the closure inlined into the loop (checked by function identity), its context slots in registers, % 100000 as 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) % 1000003 with i * i past 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:u for instruction counts.

Code conventions

j8 has explicit code rules; pull requests follow them.

Structure

  • Private submodules (mod), flattened by pub use at the crate root, ⛔ pub mod; visibility comes from private modules, and items are plain pub.
  • Dependency direction: every layer depends only on j8framework; j8framework depends on no layer; j8bytecode is the root.
  • dune/ and samples/* are packages of their own (with an empty [workspace]) depending on the published j8 by version, ⛔ path dependencies. When a new API isn’t published yet, patch locally with --config on the command line ([patch.crates-io]), ⛔ committing the patch or a lock file generated with it.

Rust

  • ⛔ static and the 'static lifetime (except &'static str names in enums); no global or static storage. Background tasks borrow the caller’s data through Task<'t>.
  • Strings are turned into enums right after deserializing, ⛔ deciding on strings.
  • Conversions use From / TryFrom / Into, ⛔ hand-written to_xxx conversions (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 Gc or 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 a README.zh-CN.md translation, 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

PhaseContents
1 Infrastructuredynamic code (eval, Function, generator / async constructors), early errors, strict mode, global declaration checks, $262
2 Object / Array / property modelthe 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 iteratorsReflect, Proxy (revocable too), iterator helpers, Set methods, Map.groupBy
4 Binary dataArrayBuffer (resizable, transfer, detach), SharedArrayBuffer, DataView, 12 TypedArrays (Float16 included), Atomics
5 Date / RegExp / strings and numbersDate (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 languagedirect eval, with, Annex B block-level function hoisting, generator parameter initialization, arguments linked to parameters, modules and dynamic import()

Still to do

  • top-level await in modules, import defer / source phase;
  • the conflict rule for var arguments declared 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 / net servers, streams, async child processes, worker_threads, zlib, crypto hashes and more; publishing the npm package @jabberwocky238/dune;
  • Node-API: real weak references.

Glossary

TermMeaning
acc (accumulator)the implicit result register of the bytecode; most instructions read or write it
Agentthe context of one run; JS operation semantics hang off it
Contextan execution context: the global object and built-in prototypes
context slot / Envthe heap environment holding variables that closures capture
CodeCachebytecode shared by several executors
deopta failed speculation: machine code goes back to the interpreter
EventLoop / EventLoopSetone JS event loop / the loop threads running many of them
feedback slotwhere bytecode records types and shapes it saw; the JIT speculates on them
FrameStatewhat each interpreter register holds at a guard; frames are rebuilt from it on a deopt
’gc brandthe lifetime of one Isolate::enter; values carrying it can’t leave that entry
GcCell / ValueCellj8’s mutable cells on paragc: a snapshot of a block of data / a single value
Globala persistent handle, surviving enter calls
IC (inline cache)per property-access site, results cached by shape
IgnitionV8’s interpreter; j8’s bytecode matches it byte for byte
Intrinsicsthe interface that installs built-ins into a Realm, implemented by j8builtins
Isolatean independent JS world: one GC heap
NaN-boxingone 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
paragcthe GC library j8 uses
Platformthe thread pool, clocks, output and module loading the host lends the engine
preludeJS a runtime runs after installing its bindings, to build its public API
Realmthe spec’s realm: a set of global object and built-ins
ropea 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 StarStar0 … Star15: one-byte register stores without operands
Tierthe executor’s JIT hook
TDZ (temporal dead zone)the region before a let / const / class is initialized
trampolineone jump per function, to its machine code or the interpreter
__j8_nativea runtime’s hidden registry object