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

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