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.

• 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, and execution behaviors.

• Getting Started
• Installation
• Usage
• Architecture
• Opcode Reference
• Testing
• Contributing
• License

• Rust (1.65+)
• Tokio (for asynchronous runtime)
• Clang (for native function compilation, optional)

Clone the repository and build the project using Cargo:

git clone https://github.com/user/raft-vm.git
cd raft-vm
cargo build --release

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

Example .raft file:

actor Main {
    let x = 5;
    let y = 10;
    send self (x + y);
}

• 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.

raft-vm
 ├── Cargo.toml                 # Project dependencies and build settings
 ├── README.md                  # This document
 └── src
      ├── compiler.rs           # Source to bytecode
      ├── lib.rs                # Library
      ├── main.rs               # CLI entry point
      ├── runtime.rs            # bytecode interpreter
      └── vm
           ├── backend.rs       # Backend logic
           ├── execution.rs     # Execution context (IP, stack, call frames)
           ├── heap.rs          # Heap and memory management
           ├── mod.rs           # VM module coordinator
           ├── opcodes.rs       # Opcode definitions and execution logic
           ├── value.rs         # Value type and arithmetic operations
           └── vm.rs            # Core VM struct and execution loop

Raft uses a custom bytecode instruction set that mirrors fundamental operations:

• Arithmetic: Add, Sub, Mul, Div, Mod, Neg, Exp
• Stack: PushConst, Pop, Dup, Swap, Peek
• Control Flow: Jump, JumpIfFalse, Call, Return
• Actor Management: SpawnActor, SendMessage, ReceiveMessage
• Supervision: SpawnSupervisor, SetStrategy, RestartChild