Skip to main content

Module opcode

Module opcode 

Source

Constants§

ADD
Pop b, pop a, push a + b.
ADD_FLOAT
Typed + for two Float operands. as_float decode (raw f64::from_bits), IEEE 754 add, push as NanValue::new_float. Skips arith_add tag-dispatch + cross-type promotion. Hot in numeric loops (Mandelbrot inner step is 3 muls + 1 add per iter).
ADD_INT
Typed + for two Int operands. as_int decode + wrapping_add, boxing back through NanValue::new_int. Skips the tag-dispatch chain in arith_add. Emitted when both operand types resolve to Type::Int.
BUFFER_APPEND_SEP_UNLESS_FIRST
Append separator only when buffer is non-empty. Pop sep, pop buf → push buf. No-op for the first append, so the synthesized __buffered loop body can place the separator before each element uniformly.
BUFFER_APPEND_STR
Append the bytes of a string to a buffer. Pop str, pop buf → push buf (same handle). The String pointed to by buf.handle is mutated in place via String::push_str.
BUFFER_FINALIZE
Drain a buffer into an arena OBJ_STRING. Pop buf → push string. Frees the underlying vm.buffer_pool slot; the handle becomes invalid.
BUFFER_NEW
Allocate a fresh String buffer. Pop cap_hint:i64 → push handle:Int(buffer_idx).
CALL_BUILTIN
Call a builtin service function.
CALL_BUILTIN_OWNED
Like CALL_BUILTIN but with owned-argument bitmask from reuse analysis. Builtins receiving owned args can mutate in-place instead of cloning.
CALL_KNOWN
Call a known function by id. Args already on stack.
CALL_KNOWN_OWNED
Like CALL_KNOWN but with owned-argument bitmask from reuse analysis.
CALL_LEAF
Frameless call to a leaf+thin+args-only function. No CallFrame is pushed — just saves (fn_id, ip) in the dispatch loop, sets bp to the args already on stack, and jumps to the target. On RETURN, restores the caller’s state directly. Format: fn_id:u16, argc:u8 (same as CALL_KNOWN).
CALL_PAR
Parallel function calls for independent products (?! / !). Pops N callable values plus their args from the stack, dispatches them via the same callable resolution rules as CALL_VALUE, then builds the result tuple. Enters/exits replay group around parallel dispatch.
CALL_VALUE
Call a function value on the stack (under args).
CONCAT
Pop b, pop a, push str(a) ++ str(b).
DIV
Pop b, pop a, push a / b.
DIV_FLOAT
Typed / for two Float operands; same shape as ADD_FLOAT. IEEE 754 division — b == 0.0 produces inf/-inf/NaN per the spec, no runtime check.
DUP
Duplicate the top value.
EQ
Pop b, pop a, push a == b.
EQ_INT
Typed == for two Int operands. Skips NanValue::eq_in’s tag dispatch — as_int_unboxed() on both sides, raw i64 compare, push bool. Emitted by the VM compiler when both left.ty() and right.ty() resolve to Type::Int. Hot path in pattern-match-on- Int (match n { 0 -> …; _ -> … }) and arithmetic guards; profile shows eq_in at 10–12% self-time in newtype/match scenarios.
EXTRACT_FIELD
Peek top (record/variant), push fields[field_idx] (non-destructive).
EXTRACT_TUPLE_ITEM
Peek top tuple, push items[item_idx] (non-destructive).
GT
Pop b, pop a, push a > b.
GT_FLOAT
Typed > for two Float operands; same shape as LT_FLOAT.
GT_INT
Typed > for two Int operands; same shape as LT_INT.
JUMP
Unconditional relative jump: ip += offset.
JUMP_IF_FALSE
Pop top, if falsy: ip += offset.
LIST_CONS
Pop tail, pop head, push Cons(head, tail).
LIST_HEAD_TAIL
Pop cons cell, push tail then push head.
LIST_LEN
Pop list, push its length as Int.
LIST_NEW
Pop count items, build cons list from them (first item = head), push list.
LIST_NIL
Push Nil (empty cons list).
LIST_PREPEND
Pop list, pop value, push prepended list.
LOAD_CONST
Push constants[idx] onto the operand stack.
LOAD_FALSE
Push NanValue::FALSE.
LOAD_GLOBAL
Push globals[idx] onto the operand stack.
LOAD_LOCAL
Push stack[bp + slot] onto the operand stack.
LOAD_LOCAL_2
Push two locals in one dispatch. Format: slot_a:u8, slot_b:u8.
LOAD_LOCAL_CONST
Push one local + one constant in one dispatch. Format: slot:u8, const_idx:u16.
LOAD_TRUE
Push NanValue::TRUE.
LOAD_UNIT
Push NanValue::UNIT.
LT
Pop b, pop a, push a < b.
LT_FLOAT
Typed < for two Float operands. as_float (raw f64::from_bits) on both sides, IEEE 754 compare, push bool. Hot in numeric loops (Mandelbrot inner step match curZ2 > 4.0 { … } etc.); profile shows compare_lt at 2.6% self-time on fractal_seahorse.
LT_INT
Typed < for two Int operands. as_int decode on both sides (folds the inline path inline), raw i64 compare, push bool. Skips compare_lt‘s tag-dispatch (is_int/is_float/is_string chain plus cross-type promotion). Emitted when both operands’ Spanned::ty() resolve to Type::Int.
MATCH_CONS
Peek top: if Nil (not a cons), ip += fail_offset.
MATCH_DISPATCH
Unified prefix/exact dispatch on NanValue bits.
MATCH_DISPATCH_CONST
Like MATCH_DISPATCH but every entry carries an inline result instead of a jump offset. When an entry matches, the result is pushed directly onto the stack and the match body is skipped entirely.
MATCH_FAIL
Non-exhaustive match error at source line.
MATCH_INT_LITERAL
Fused match n { LIT -> ...; _ -> ... } arm test: peek the top of stack (subject left in place by the surrounding compile_match), if its Int value equals the inline imm literal — fall through to the arm body; otherwise skip via fail_offset. Replaces the DUP + LOAD_CONST + EQ + JUMP_IF_FALSE sequence the generic compile_pattern emits — one dispatch instead of four in the hot path of every match n { 0 -> ... } shape.
MATCH_NIL
Peek top: if not Nil, ip += fail_offset.
MATCH_TAG
Peek top: if NaN tag != expected, ip += fail_offset.
MATCH_TUPLE
Peek top: if not a tuple of count items, ip += fail_offset.
MATCH_UNWRAP
Peek top: if not wrapper of kind, ip += fail_offset. If matches, replace top with inner value (unwrap in-place). kind: 0=Ok, 1=Err, 2=Some.
MATCH_VARIANT
Peek top (must be variant): if variant_id != expected, ip += fail_offset.
MOD
Pop b, pop a, push a % b.
MOVE_LOCAL
Push stack[bp + slot] and clear the slot (move semantics). Used for last-use variables: caller releases sole ownership so callees and builtins see refcount=1 and can mutate in-place.
MUL
Pop b, pop a, push a * b.
MUL_FLOAT
Typed * for two Float operands; same shape as ADD_FLOAT.
MUL_INT
Typed * for two Int operands; same shape as ADD_INT.
NEG
Pop a, push -a.
NOP
No-op, used as padding after superinstruction fusion.
NOT
Pop a, push !a (boolean not).
POP
Discard the top value.
PROPAGATE_ERR
Propagate Result.Err to caller or unwrap Result.Ok in place.
RECORD_GET
Pop record, push fields[field_idx] (compile-time resolved index).
RECORD_GET_NAMED
Pop record, lookup field by interned field symbol, push value.
RECORD_NEW
Pop count field values, push a new record with type_id.
RECORD_UPDATE
Update selected fields on a record, preserving the rest from the base value. Stack: […, base_record, update_0, …, update_n-1] -> […, updated_record]
RETURN
Return top of stack to caller.
STORE_GLOBAL
Pop top and store into globals[idx].
STORE_LOCAL
Pop top and store into stack[bp + slot].
SUB
Pop b, pop a, push a - b.
SUB_FLOAT
Typed - for two Float operands; same shape as ADD_FLOAT.
SUB_INT
Typed - for two Int operands; same shape as ADD_INT.
TAIL_CALL_KNOWN
Mutual tail-call to a known function: reuse frame, switch target.
TAIL_CALL_SELF
Self tail-call: reuse current frame with new args.
TAIL_CALL_SELF_THIN
Tail-call self for thin frames: no arena finalization needed. The compiler emits this instead of TAIL_CALL_SELF when the function is known to be “thin” (no heap allocations within the frame). Skips finalize_frame_locals_for_tail_call entirely — just copies args in-place and resets ip.
TUPLE_NEW
Pop count items, build a tuple from them, push tuple.
UNWRAP_OR
Inline Option.withDefault: pop default, pop option → push inner or default. Stack: [option, default] → [result] If option is Some → push unwrapped inner value. If option is None → push default.
UNWRAP_RESULT_OR
Inline Result.withDefault: pop default, pop result → push inner or default. Stack: [result, default] → [value] If result is Ok → push unwrapped inner value. If result is Err → push default.
VARIANT_NEW
Pop count field values, push a new variant.
VECTOR_GET
Inline Vector.get: pop index, pop vector → push Option (Some/None). Stack: [vector, index] → [option]
VECTOR_GET_OR
Fused Vector.get + Option.withDefault: pop default, pop index, pop vector → push value. Stack: [vector, index, default] → [value] Combines CALL_BUILTIN(Vector.get) + LOAD_CONST + UNWRAP_OR into one opcode.
VECTOR_SET
Inline Vector.set: pop value, pop index, pop vector → push Option. Stack: [vector, index, value] → [option_vector]
VECTOR_SET_OR_KEEP
Fused Vector.set + Option.withDefault(vec): pop value, pop index, pop vector → push vector. Stack: [vector, index, value] → [vector]
WRAP
Pop value, push wrapped value. kind: 0=Ok, 1=Err, 2=Some.

Functions§

opcode_name
Opcode name for debug/disassembly.
opcode_operand_width
Operand byte width after the opcode byte. Single source of truth — all bytecode traversal functions must use this.