Raft - A Lightweight Virtual Machine for Concurrent Systems
Raft is a lightweight, interpreted virtual machine (VM) designed to provide
robust concurrency, fault tolerance, and actor-based message-passing models.
Inspired by Erlang’s concurrency model and Rust’s safety principles, Raft
focuses on enabling parallel, resilient execution environments while maintaining
a simple and extensible design.
Key Features
- Actor Model: Supports spawning actors, sending messages, and managing
isolated execution contexts.
- Supervisor Trees: Implements supervision strategies to ensure fault
tolerance by restarting failed processes.
- Stack-Based Execution: Operates on a stack-based virtual machine with a
custom bytecode instruction set.
- Concurrent Execution: Built with asynchronous, non-blocking paradigms
using Tokio.
- Dynamic Heap Management: Allocates and manages memory with garbage
collection and safe reference counting.
- Extensibility: Designed for modular expansion of opcodes, heap structures,
native standard-library bindings, and execution behaviors.
Table of Contents
Getting Started
Prerequisites
- Rust (1.65+)
- Tokio (for asynchronous runtime)
- Clang (for native function compilation, optional)
Installation
Clone the repository and build the project using Cargo:
git clone https://github.com/user/raft-vm.git
cd raft-vm
cargo build --release
Usage
Run a .raft script or start an interactive REPL:
# Execute a Raft script
cargo run -- run script.raft
# Start the REPL
cargo run -- repl
# Display version
cargo run -- --version
Logging is controlled via the RUST_LOG environment variable. Enable info-level
output like so:
RUST_LOG=info cargo run -- run script.raft
Example .raft file:
# push 1 and 2 on the stack and add them
1 2 +
# store the result, load it twice, and clean up the duplicate
StoreVar 0
LoadVar 0
Dup
Swap
Pop
# push a boolean and a float
true 3.14
Numbers may be negative: -5 and -3.14 are literals. Because Raft is postfix,
subtraction always follows its two operands (5 3 -) and is never written flush
against a number, so there is no ambiguity between the two.
The compiler now uses a lexer/parser pipeline that supports integers, floats,
booleans (true/false), string literals with spaces (for example,
"hello raft vm"), # and // comments, textual labels such as .loop,
basic arithmetic like +, and stack/variable keywords such as StoreVar,
LoadVar, Pop, Dup, and Swap. Running the above file will leave 3,
true, and 3.14 on the VM's stack.
Native standard-library functions are injected when a VM starts. For example,
io.print loads the standard io module's print export, and CallNative 1
invokes it with one stack argument:
42 io.print CallNative 1
The REPL keeps running after compiler or runtime errors. Enter a trailing \
or an incomplete instruction such as StoreVar to continue on the next line;
enter exit at a fresh prompt to quit.
Playground
Raft runs in the browser at
https://seanwevans.github.io/raft-vm/ — write a program, press
Ctrl+Enter, and see what it prints, what it left on the
stack, and the bytecode it compiled to.
It is this VM, not a second implementation of it: web/wasm compiles the crate
to wasm32-unknown-unknown and the page loads that module directly, so the
compiler, the opcodes, the heap and the collector are the ones the tests cover.
There is no bindgen and no JavaScript toolchain — the page talks to the module
over a handful of exported functions and instantiates it with plain
WebAssembly.instantiate.
Two things keep a program typed into a text box from taking the tab with it:
- Every run is bounded by
VM::set_instruction_budget, which
stops a program that will not stop itself and reports it as an ordinary
runtime error. An actor inherits the budget of whatever spawned it.
- The VM runs in a web worker with a stopwatch on it. A program that blocks
forever — a
ReceiveMessage with nothing left to send to it — has its worker
terminated and replaced.
io.print has nowhere to go in a browser, so the page installs a sink with
stdlib::set_print_sink and shows what the program wrote.
Building it locally
rustup target add wasm32-unknown-unknown
./web/build.sh # assembles web/dist
python3 -m http.server --directory web/dist 8080
The build takes the .raft files in examples/ along with it, so anything
added there shows up in the playground's example menu.
Deploying it
.github/workflows/playground.yml builds the site on every push to main and
deploys it with GitHub Pages. Pages has to be pointed at the workflow once, by
hand: Settings → Pages → Build and deployment → Source: GitHub Actions. The
site is entirely static — no server, no build step at page load — so any static
host will serve web/dist just as well.
Architecture
Components
- VM (Virtual Machine): Manages bytecode execution, stack, heap, and message
passing.
- Execution Context: Maintains the state of the current program, including
the instruction pointer and call stack.
- Heap: Allocates and manages dynamic memory for arrays, strings, and
modules.
- Opcodes: Define the core instruction set for the VM, such as arithmetic,
stack manipulation, and control flow.
Bounded execution
A host that runs programs it did not write can cap how much work one is allowed
to do:
let (mut vm, _tx) = VM::new(bytecode, None);
vm.set_instruction_budget(Some(5_000_000));
vm.run().await?; // VmError::InstructionBudgetExhausted if it runs on
The budget is per run call, it travels to actors spawned under it, and
vm.instructions_executed() reports what the last run actually spent. Left
unset, a process runs unbounded, which is what the CLI does.
Platform Integration
The VM operates through its runtime, message-passing interfaces, and native
standard-library bindings. Host Rust functions can be registered as heap-backed
native functions and exposed through modules such as io, allowing platform I/O
without adding dedicated I/O bytecode instructions.
Opcodes
Raft uses a custom bytecode instruction set that mirrors fundamental operations:
- Arithmetic:
Add, Sub, Mul, Div, Mod, Neg, Exp
- Comparison:
Eq, Ne, Lt, Le, Gt, Ge
- Logic:
Not, And, Or
- Stack:
PushConst, Pop, Dup, Swap
- Modules/Globals:
LoadGlobal, GetExport, CallNative
- Control Flow:
Jump, JumpIfFalse, Call, CallNative, Return
- Actor Management:
SpawnActor, SendMessage, ReceiveMessage
- Supervision:
SpawnSupervisor, SetStrategy, SuperviseChild,
RestartChild
A supervisor acts on the children registered with it. SuperviseChild <address>
places an already-spawned actor under the supervisor on top of the stack and
leaves the supervisor there so registrations can be chained:
SpawnSupervisor .workers
SetStrategy 1
SuperviseChild 2
SuperviseChild 3
SetStrategy selects what happens when RestartChild fires: 0 restarts only
the failed child (one-for-one), 1 restarts every registered child
(one-for-all), and 2 restarts the failed child and those registered after it
(rest-for-one). The last two act on the registered child list, so a child that
was never registered is never restarted alongside its siblings.
Comparison and control flow
Comparisons push a boolean, which is what JumpIfFalse branches on. Eq and
Ne are defined for every pair of values -- comparing across types answers
false rather than failing, and two references are equal when they name the
same heap object. The ordering operators (Lt, Le, Gt, Ge) require two
integers or two floats, since ordering across types has no meaning.
Not, And and Or take booleans. They cannot short-circuit: both operands
are already on the stack by the time the operator runs.
Together these make a loop that exits on a computed value expressible:
0 StoreVar 0 # total
5 StoreVar 1 # counter
.loop
LoadVar 1 0 Gt # counter > 0 ?
JumpIfFalse .done
LoadVar 0 LoadVar 1 + StoreVar 0
LoadVar 1 1 - StoreVar 1
Jump .loop
.done
LoadVar 0 io.print CallNative 1
See examples/loop.raft, which prints 15.
Testing
Run the test suite with Cargo:
cargo test
Property tests
tests/properties.rs runs generated programs -- both random opcode sequences
and structured fragments -- through the compiler and interpreter, asserting
that they always answer with a VmError or a clean halt, never panic, and never
leave a root pointing at a reclaimed object. They run as part of cargo test.
To search harder than the default 256 cases per property:
PROPTEST_CASES=20000 cargo test --test properties
Inputs that have failed before are recorded in
tests/properties.proptest-regressions and replayed on every run, so keep that
file in source control.
Build the project in release mode:
cargo build --release
CI runs the same checks on every pull request. To reproduce them locally:
cargo test --all
cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
Coverage
Coverage is measured with
cargo-llvm-cov. CI fails if line
coverage drops below the floor set in .github/workflows/ci.yml, and attaches
an lcov.info artifact to each run.
cargo install cargo-llvm-cov
rustup component add llvm-tools-preview
cargo llvm-cov --workspace --summary-only # per-file summary
cargo llvm-cov --workspace --html # browsable report
cargo llvm-cov --workspace --show-missing-lines
Benchmarks
Raft uses Criterion for
statistics-driven benchmarking. Run everything, or one target at a time:
cargo bench # all benchmarks
cargo bench --bench interpreter # opcode dispatch, control flow, messaging
cargo bench --bench heap # allocation, collection, message conversion
cargo bench --bench compiler # lexing, parsing, emission, label resolution
Filter to a single measurement by name, and shorten the sampling window while
iterating:
cargo bench --bench heap -- collect_garbage --measurement-time 2
Criterion compares each run against the previous one stored in
target/criterion, reporting the change and whether it is statistically
significant. To check only that the benchmarks still build, use
cargo bench --no-run.
Benchmarks that allocate take a fresh Heap per iteration. Sharing one lets an
allocating program grow it without bound across the measurement, which measures
heap growth rather than the operation under test.
Contributing
Contributions are welcome! Please open an issue or submit a pull request.
License
Distributed under the MIT License. See LICENSE for details.
