This page describes how the core (quickjs-oxide-core, in core/) runs register bytecode: the loop, its frames and register windows, the inline caches, iteration, suspension and the native ABI. The main files are core/src/vm/interp.rs (the loop), vm/ic.rs (the caches), vm/iter.rs, vm/suspend.rs, vm/native.rs and core/src/bytecode/. The heap, shapes and the collector are in Heap; the core's design record is core/README.md.
The root crate's front end parses and resolves source into stack code; the register lowering (src/engine/compiler/register) turns each function into a CodeUnit of the core. An instruction (Insn) is 8 bytes: a typed Opcode, three 8-bit operands a, b, c and a 32-bit imm (a constant index, an absolute jump target, a property key, a scope slot or an i32 literal, as the opcode's Format says). A unit also holds its exception handlers (start..end, the target and the register the thrown value lands in, innermost first), its register, parameter and local counts, its flags (STRICT, CONSTRUCTOR, ARGUMENTS, GENERATOR, ASYNC, …) and the number of its cache sites.
Runtime::publish runs the validator (bytecode/validate.rs) once per unit and appends it to the CodeStore: every register operand is below register_count, every call window and NewArray range fits, every target, constant, child and capture index is in range. The loop then indexes without further checks of its own; a validator failure is an internal error of the lowering, never a JavaScript exception. qjs --disassemble FILE prints the register code.
New opcodes are appended at the end of Opcode. Inserting one in the middle shifts the discriminants and can change LLVM's dispatch code and arm layout; validate both work and timing rather than assuming an unrelated opcode is free.
The register file (VmStack::registers) is one Vec<Value>; the frame table (VmStack::frames) holds one 32-byte Frame per activation:
| Field | Content |
|---|---|
unit, bytecode, function |
the running code unit, its FunctionBytecode record (constants, children) and the function object (its captured cells) |
base |
the absolute index of the frame's register 0 |
return_pc, return_dst |
where the caller resumes and the absolute register that receives the result |
argc |
the actual argument count |
flags |
ENTRY (entered from Rust: its return leaves the loop), CONSTRUCT, TAIL, and the VIA_* backtrace marks of a rewritten call or apply |
A frame's window is register 0 (this), the parameters, a hidden new.target local when the function reads it, the locals, then the operand temporaries. A function with the ARGUMENTS flag (arguments or a rest parameter) keeps the arguments past its parameters above its registers, where NewArguments and Rest read them. Calls follow the stack code's operand order: Call a, b, c has the callee in b and c arguments from b + 1, and the callee's window starts at b, where the call writes this; CallMethod and New have the receiver or new.target in b and start the window at b + 1. No argument is copied either way.
Entering a frame (enter_frame) reserves the window, clears every register past the arguments to undefined, coerces a sloppy function's undefined or null receiver to the global object (a primitive one to its wrapper), pushes the frame and sets top to the window's end. registers[..top] are roots. Registers above a returned frame are dead; when a frame resumes over registers a collection may have freed since they were last below top (stale_from), raise_top clears them before they become roots again.
VmStack::reserve keeps SPAN (512) values of padding past every frame's end, so the loop takes the running window as a fixed-size &mut [Value; 512] and an 8-bit operand (or a call's b + 1) needs no bounds check. The register file grows by doubling up to DEFAULT_STACK_LIMIT (2^20 values); a call past it throws InternalError: stack overflow.
Register operands address 256 registers (bytecode::WINDOW). A function that needs more is laid out by the lowering's Layout::of:
- Locals past the window live in the slots of a spill scope (
NewSpill,LoadSlot,StoreSlot, andCapture::Slotfor a child that captures one), held in the register after the window's locals, with the temporaries above it. Locals are never placed above the temporaries, where every call's window would overwrite them. - Temporaries past the window live in slots of the same scope after the spilled locals. The window keeps at most a quarter of itself for locals, then the spill register, the temporaries that fit, and eight scratch registers at the top: one carries a value between a slot and a constant or another slot, the other seven take turns as the operands and results of the instruction being built (
LoadSlotbefore,StoreSlotafter). Iterator records,yield's resumption pair and super references are copied into consecutive scratch registers and back. A call of up to seven operands runs on a scratch run; a larger one becomesCallSpreadorNewSpreadover an array of its arguments, and an array literal is built byDefineElem.Gosub,ForInNext, catch handlers and close stubs reach spilled depths through stubs after the code.
A function inside the window lowers exactly as it would without this path. The register-stress feature of the root crate lowers every function with two register temporaries, so the whole corpus and Test262 exercise it. The LoadWide and StoreWide opcodes (registers above the window by absolute index) exist in the core and its tests; the lowering emits neither.
vm::interp::run_at runs the top frame from an instruction until the entry frame returns. It is one 'dispatch: loop over match insn.op with the frame-derived values (code, base, strict, ic_base) in locals and the window in regs.
- Inline arms cover moves and constants,
Int32and double arithmetic and comparisons (an overflow or a non-number takesops), the compare-jumps against registers and againsti16literals,GetField,SetFieldand the global forms' cache hits, dense and typed-array element reads and writes, cells and captures,NewObject, calls and returns. - Arithmetic dispatch. Specialized multiply, divide, remainder, shift and bitwise arms pass a constant operation to
arith_fast. A miss decodes the opcode in the shared out-of-linearith_slow; generic coercions and quotient normalization stay out of the dispatch loop. - The window and the heap.
regsborrows the register file inside the heap, so an arm that calls into the heap copies its operands out first and takes the window again afterwards (theset!andwrite!macros, and the common tail). The cache hits take the heap's arenas as separate fields, disjoint from the register file, and keep the window. - Slow paths are
#[inline(never)]functions inops,property,objectand the other modules, returningResult<_, Throw>. Their result falls into the common tail: success retakes the window and dispatches, a throw unwinds. - The rare-op split. Opcodes no hot path runs share out-of-line arms:
rare_op(accessor and method definitions, the spill scope,arguments, rest,new.target, regular-expression literals,for-insetup, spread elements, the error throws,import(),ConcatN),iter::iter_op(iteration),class::class_op(classes, private names, super and reference forms) andsuspend_op(generators andawait). A new opcode entersrun_atinline only when a profile of a suite program shows it hot. - Unwinding. A thrown value travels as an unrooted
Throw. The tail searches the running unit's handlers for the faulting instruction, stores the value in the handler's register and continues at its target; otherwise it pops the frame and repeats in the caller, until a frame markedENTRYreturns the throw to Rust.error::place_framerecords the faulting position for the backtrace on every throw.
A call or new of a bytecode function stays in the loop: the arm builds the callee's Frame, enters it and continues at the callee's instruction 0, with no Rust recursion. For new, construct_this allocates the receiver through the constructor's cache (below) unless the constructor is derived. Function.prototype.call and apply are natives the call arm rewrites (rewrite_call) into a call of their receiver, moving the window onto thisArg or spreading the argument list. CallSpread and NewSpread expand their array into the registers first. Natives and exotic callables (bound functions and proxies, which run through the re-entrant entry points below) go through the out-of-line call_other.
Return from a frame with none of ENTRY, CONSTRUCT or TAIL set pops it, writes the value into the caller's return_dst and resumes the caller in place. The other frames go through finish_return, which applies the constructor's receiver rule (a non-object result yields the receiver), teaches the New site its receiver size, returns through the frames a tail call left, or leaves the loop at an entry frame. TailCall does not reuse the frame; the compiler emits no tail call.
Rust re-enters JavaScript through vm::call and vm::construct: the receiver and arguments are written above top (rooted from that point), call_from_rust pushes an ENTRY frame and runs a nested run_at on the frames above its own. Each re-entry counts against a native-stack budget (NATIVE_STACK_BUDGET, 1 MiB measured from stack addresses, or a depth limit the embedder sets for a host whose stack cannot be measured); past it the call throws InternalError: stack overflow.
run_at stays under 16,384 bytes, read with nm --size-sort on the release qjs (symbol oxide_core::vm::interp::run_at). Measure each build; size depends on the toolchain and profile. A change that crosses the gate moves code out of line before it merges; see Execution principles.
Each cache site has one 16-byte IcEntry (w0–w3) in the IcStore. The store lives in the Heap, beside the register file, rather than in a CodeUnit: the loop holds the unit's code borrowed across every heap call, and the collector prunes every entry that names a dead shape, object or cell after each marking, before an index is recycled. Entries are weak.
CodeBuilder::finish numbers a unit's sites: named-property and NewObjectLit sites first in instruction order (0 to 254 in c; the rest share the reserved site 255, which is never filled), then the global forms (b | c << 8), then New (imm). Runtime::publish reserves the unit's entries from its ic_base.
| Kind | Opcodes | Entry | Hit |
|---|---|---|---|
| Get | GetField |
receiver shape, holder (NONE for an own property), slot, validity cell |
own: one shape compare and a slot load; prototype or string receiver: also the cell's valid flag, then a load from the holder |
| Set | SetField |
shape before, shape after, slot, validity cell | same shape: a slot store; transition: the shape matches, the slot is within the object's reserved range, the object is extensible and not used as a prototype, and the chain's cell holds; then the new shape and the store |
| Global | GetGlobal, GetGlobalOrUndefined, SetGlobal |
global generation, slot, property flags, holder | one compare of the heap's global_generation and a load (SetGlobal also checks WRITABLE) |
| Construct | New |
constructor shape, prototype slot, receiver slots |
the constructor's shape matches: its prototype slot read live, the receiver allocated with the learned slot count |
| Literal | NewObjectLit |
final shape, learned by FinishObjectLit |
allocate a fresh object with known slots; InitField writes each value after its evaluation |
Details of the hit paths:
- Tagged
GetFieldentries.LENGTH_TAGreads an array's stored length or a string's unit count with no shape to compare;STRING_RECEIVER_TAGcaches a property found on%String.prototype%or above, guarded by that prototype chain's cell. - Polymorphic and megamorphic sites. A
GetFieldorSetFieldsite is monomorphic until a second shape arrives, then keeps four shapes in an out-of-line row (POLY). Its most recent successful entry also occupies the inline slot; a row hit promotes that entry, retaining all its original guards. A lazy side table links sites to rows. A fifth shape turns the site megamorphic. A megamorphicGetFieldsite probes a shared direct-mapped table of 4,096 entries keyed by receiver shape and key, and fills it from its misses. - What is never cached. Accessors are not cached at
GetField; a dictionary-mode receiver is never cached, while a prototype hit on a dictionary-mode holder is (any change to a prototype clears its cell). A transition is cached only when no prototype has the key as an accessor or read-only property. - Globals. Every insert, remove or reflag on the global object's dictionary bumps
global_generation; a value write does not. A wrap of the generation clears every global entry. A miss looks up the global lexical environment first, then the global object's own data property. - Construction. A constructed receiver or empty object literal reserves at least four slots. When a constructor's frame returns to its
New,learn_receiver_sizeraises the entry's slot count to the receiver shape's width (capped at twice the dictionary threshold), so the next construction reserves what the constructor added.
Element access has no cache: GetElem and SetElem read and write an array's or ordinary object's dense elements inline for a non-negative Int32 key, and a typed array's through typed::fast_get and fast_set. A hole is filled inline only while no object used as a prototype has an index property or is exotic (Heap::holes_writable).
The lowering marks an adjacent prefix increment and element read with
IncGetElem. It consumes the read only for a non-overflowing Int32
increment and a present dense element. Coercion, holes and other receivers
execute the original operations at their original PCs.
Constant array literals of at least two elements use NewArrayK: allocate a
fresh array, then copy immutable values from a consecutive pool range. A
straight-line object literal with two to sixteen unique, non-index string
keys uses NewObjectLit, InitField and FinishObjectLit. Its weak literal
cache stores the final shape only after the definitions complete. A miss
defines each property after evaluating its value, preserving allocation and
exception order; a hit initializes known slots. The object allocation still
precedes value evaluation.
Duplicate or computed keys, methods, spreads, prototype definitions and
control-flow joins use the general definition path. Literal initialization
stays outside the hot loop.
With the ic-stats feature (and in debug builds) the store counts inline hits (including the latest shape of a polymorphic site), out-of-line row hits, fills and unfilled misses per kind, misses per site and iteration starts; qjs --ic-stats prints Runtime::ic_report at exit. Release builds without the feature carry no counter.
An iterator record is three consecutive registers. IterStart a, b fills them for the iterable in b:
- Pristine array: an
Arraywhose prototype is%Array.prototype%, with no own@@iterator, while%Array.prototype%[@@iterator]is the intrinsicvaluesand%ArrayIteratorPrototype%.nextthe intrinsicnext(iter::is_pristine_array: two own-slot lookups, no validity cell). The record is the array, the markValue::EMPTYand the index. No iterator object and no{value, done}result is allocated; the length is read live and a hole is read through the property path, so the walk is unobservable. - Protocol: the iterator, its
nextmethod and a done flag.
IterNext a, b, c writes the next value of record b to a and whether it is done to c; IterClose and IterCloseThrow do nothing for a pristine or finished record. for-of takes the pristine form; the front end's other iterator starts set imm and always run the protocol. The natives use the same mechanism through iter::get_iterator, step and close (an Iter::Array or Iter::Protocol): spread, Array.from, the typed-array constructors, Promise combinators, the collection constructors, Object.fromEntries and others. The IterStart counters of ic-stats report how many starts took each form.
Generators, async functions and async generators copy their frame out of the register file when they suspend and back in when they resume (vm/suspend.rs). The activation record is the generator or async-state object itself: internal slot 0 the function, slot 1 the kind's own state (an async function's promise, an async generator's request queue), the saved registers after them, and a SavedFrame header (unit, bytecode record, resume pc, argc, state START, YIELD, EXECUTING, COMPLETED or AWAIT).
InitialYieldcreates a generator's record, saves the frame and returns the generator to the caller.AsyncStartcreates an async function's promise and record, saves the frame and runs the body at once throughresume.Yield,YieldStarandAwaitsave the windowbase..frame_endinto the record found onVmStack::activeand leave the nested loop.Awaitfirst performsPromiseResolveand a reaction whose job resumes the record, so a throw there is catchable at theawait.suspend::resumecopies the registers back at the currenttop, pushes anENTRYframe from the header, writes the delivered value (and at ayield, the resume kind: next, return or throw) into the registers the lowering reserved, and runsrun_atfrom the savedpc; a throw delivery runsrun_throwing, which starts at the resume point's handler.
The cost is a copy of the live window per suspension and per resume. A suspended frame is ordinary heap data, so the collector traces it and the stress mode covers it.
Builtins are natives: one Native enum generated with its table of entry points and constructor flags (builtins::natives!), indexed from the function record. A native is fn(&mut Cx, CallSite) -> Result<Value, Throw>, where Cx holds the heap mutably and the code store and realm shared.
CallSite names where the native finds its inputs in the register file, by index: this, args and argc, whether new called it with which new.target, and the function object called (whose data object holds a native closure's slots, read with data and set_data). arg(i) reads an argument or undefined; args borrows them as a slice. The loop's call_native writes this into the window's first register and raises top over the arguments, which may reach past the caller's registers after an apply, so they stay rooted for the call.
native::call marks the root stack before the native and truncates it after, so a native roots what it holds across an allocation or a call (heap.roots().push) without releasing it. A native calls back into JavaScript as straight-line Rust through vm::call and vm::construct. While a native runs, VmStack::natives records the calling frame and instruction for the backtrace; the natives QuickJS runs without a frame of their own (Native::frameless: promise resolving functions and data closures) are not listed.
- The loop, frames, calls and suspension:
core/tests/vm.rsand the corpus incore/tests/corpus, also undercargo test -p quickjs-oxide-core --features gc-stressandscripts/checks/check-gc-stress.py. - Caches:
core/tests/ic.rsandsrc/engine/compiler/register/ic_tests.rs. - Instruction encoding and validation:
core/tests/bytecode.rs. - The lowering and the register window:
src/engine/compiler/register/run_tests.rsandwindow_tests.rs, with--features register-stress. - Language semantics:
cargo test --locked --workspace --all-targetsand the Test262 guide. - Cost: Measurement method and the gates in Execution principles.