Skip to main content

Crate bvm_lang

Crate bvm_lang 

Source
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 with Chunk::emit and Chunk::constant; fix up forward branches with Chunk::patch.
  • Vm — the interpreter. Vm::run executes a chunk and returns its result Value.
  • 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.

Type Aliases§

Addr
An instruction address within a chunk’s code array.
Const
A constant-pool index.
Reg
A register index.