bvm-lang 1.0.0

Bytecode VM and interpreter loop.
Documentation

Performance First

bvm-lang is a decoded-instruction interpreter: each Op is a fixed 8-byte value, so the loop never parses a byte stream at runtime, and the central match lowers to a jump table. A register design issues fewer instructions per unit of work than a stack design, and the Vm pools its register file across runs so steady-state execution is allocation-free.

Latest local Criterion means (cargo bench, Windows x86_64, Rust stable), reusing one Vm:

  • Straight-line expression (10 instructions): ~14 ns/run — roughly 1.4 ns per instruction.
  • Counted loop (sum 1..=1000, ~5 000 instructions executed): ~7 µs/run — again ~1.4 ns per instruction dispatched.

Numbers are indicative and hardware-dependent; run cargo bench to reproduce on your target.

Features

  • Register instruction set — three-address arithmetic, comparison, logic, branches, and termination in one compact Op enum.
  • Automatic register sizing — a Chunk derives its register-file size from the instructions it holds; you never declare or over-provision it.
  • Overflow-checked integers — integer arithmetic never wraps silently; a fault is reported instead. A float operand promotes the expression to float.
  • No panics on bad bytecode — out-of-range registers, constants, and branch targets are checked and returned as typed VmErrors. unsafe is forbidden crate-wide.
  • value-lang values — nil, bool, i32, f64, and interned symbols in one eight-byte Copy type.
  • no_std — needs only alloc. Optional serde support persists compiled bytecode.

Installation

[dependencies]
bvm-lang = "1.0"

Or:

cargo add bvm-lang

To persist compiled bytecode, enable serde:

[dependencies]
bvm-lang = { version = "1.0", features = ["serde"] }

Quick Start

Compile and run (2 + 3) * 4:

use bvm_lang::{Chunk, Op, Vm};

fn main() {
    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));
}

More runnable programs live in examples/ — run them with cargo run --example expression, --example fibonacci, and --example errors. The full surface, instruction reference, and semantics are documented in docs/API.md.

Standards

This crate is built to REPS (Rust Efficiency & Performance Standards): performance as a hard constraint, Result-based error handling with no panics in library code, #![deny(missing_docs)] and a strict Clippy profile, cross-platform parity (Linux, macOS, Windows), and property-tested core invariants. See REPS.md for the full standard.

Contributing

See dev/DIRECTIVES.md for engineering standards and the definition of done. Before a PR: cargo fmt --all, cargo clippy --all-targets --all-features -- -D warnings, and cargo test --all-features must be clean.