Expand description
§bvm_lang
A small, fast bytecode virtual machine — the execution engine an interpreted language runs on once its source has been compiled down to instructions.
bvm-lang is a register machine. Instructions name the registers they read
and write (Add { dst, lhs, rhs }) instead of shuffling an operand stack, so a
program runs in far fewer dispatch steps than the stack-machine equivalent.
Each Op is a fixed-size, already-decoded value; a program is a slice of
them plus a pool of constants, walked by a program counter in a single
match-based dispatch loop. The whole crate is safe Rust — unsafe is
forbidden — and treats the bytecode it runs as untrusted: a malformed program
produces a VmError, never a panic.
The runtime value type is Value from
value-lang: an eight-byte NaN-boxed handle that
represents nil, a boolean, a 32-bit integer, a float, or an interned symbol.
Every register holds one, and the VM speaks the same value as the rest of the
language-construction family.
§The pieces
Op— the instruction set: data movement, arithmetic, comparison, logic, branches, and termination.Chunk— a built program: instructions, a constant pool, and an automatically sized register file. Construct one withChunk::emitandChunk::constant; fix up forward branches withChunk::patch.Vm— the interpreter.Vm::runexecutes a chunk and returns its resultValue.VmError— every way a run can fail, from a type mismatch to a corrupt branch target.
§Example
Compile and run (2 + 3) * 4:
use bvm_lang::{Chunk, Op, Vm};
let mut chunk = Chunk::new();
chunk.emit(Op::LoadInt { dst: 0, val: 2 });
chunk.emit(Op::LoadInt { dst: 1, val: 3 });
chunk.emit(Op::Add { dst: 0, lhs: 0, rhs: 1 }); // r0 = 2 + 3
chunk.emit(Op::LoadInt { dst: 1, val: 4 });
chunk.emit(Op::Mul { dst: 0, lhs: 0, rhs: 1 }); // r0 = 5 * 4
chunk.emit(Op::Return { src: 0 });
let mut vm = Vm::new();
let result = vm.run(&chunk).expect("well-formed program");
assert_eq!(result.as_int(), Some(20));§Semantics
Arithmetic and ordering work over a single numeric tower: integer-with-integer
stays an integer and is overflow-checked (a fault is reported, never a
silent wrap), while any float operand promotes the result to float. Integer
division or remainder by zero is a VmError::DivideByZero; float division by
zero follows IEEE-754. Comparisons and Op::Not produce booleans, and every
branch condition must be a boolean. See Op for per-instruction detail.
§no_std
The crate is no_std-compatible and needs only alloc (the code, constant
pool, and register file are heap-allocated vectors). The default std feature
is additive and forwards to value-lang. The optional serde feature derives
Serialize / Deserialize for Op and Chunk, so compiled bytecode can
be persisted and reloaded.
Structs§
- Chunk
- An assembled sequence of instructions with its constant pool.
- Symbol
- The runtime value every register holds, re-exported from
value-lang. - Value
- The runtime value every register holds, re-exported from
value-lang. - Vm
- A bytecode interpreter.
Enums§
- Op
- A single decoded instruction.
- Unpacked
- The runtime value every register holds, re-exported from
value-lang. - VmError
- An error raised while executing a
Chunk.