fusevm/
lib.rs

1//! fusevm — Language-agnostic bytecode VM with fused superinstructions.
2//!
3//! Any language frontend can compile to fusevm opcodes and get:
4//! - Fused superinstructions for hot loops (`AccumSumLoop`, etc.)
5//! - Extension opcode dispatch for language-specific ops
6//! - Stack-based execution with slot-indexed fast paths
7//! - Three-tier Cranelift JIT:
8//!   - Linear (straight-line, compile on first call)
9//!   - Block (whole-chunk CFG, threshold 10)
10//!   - Tracing (hot loop body, threshold 50, full side-exit machinery)
11//!
12//! ## Tracing JIT capability matrix
13//!
14//! | Capability | Status |
15//! |---|---|
16//! | Loop bodies, int slots, no calls | Phase 1 |
17//! | Cross-call inlining (branchless callees) | Phase 2 |
18//! | Caller-frame `if`/`else` with side-exits | Phase 3 |
19//! | Callee-frame branches, frame materialization on deopt | Phase 4 |
20//! | Value-stack reconstruction on deopt (Int + Float) | Phase 5 + 5b |
21//! | Side-exit deopt counter + auto-blacklist | Phase 6 |
22//! | Persistent metadata export/import (`TraceMetadata`) | Phase 7 |
23//! | Bounded recursion inlining (depth ≤ 4) | Phase 8 |
24//! | Side-trace stitching from hot deopt sites | Phase 9 |
25//!
26//! ## Architecture
27//!
28//! ```text
29//! stryke source ──→ stryke compiler ──┐
30//! awkrs source ──→ awkrs compiler     ├──→ fusevm::Op ──→ VM::run()
31//! zshrs source  ──→ shell compiler  ──┘             ↳ optional tracing JIT
32//! ```
33//!
34//! ## Usage
35//!
36//! ```rust
37//! use fusevm::{Op, ChunkBuilder, VM, VMResult, Value};
38//!
39//! let mut b = ChunkBuilder::new();
40//! b.emit(Op::LoadInt(40), 1);
41//! b.emit(Op::LoadInt(2), 1);
42//! b.emit(Op::Add, 1);
43//!
44//! let mut vm = VM::new(b.build());
45//! match vm.run() {
46//!     VMResult::Ok(val) => println!("result: {}", val.to_str()),
47//!     VMResult::Error(e) => eprintln!("error: {}", e),
48//!     VMResult::Halted => {}
49//! }
50//! ```
51
52pub mod chunk;
53pub mod host;
54pub mod jit;
55pub mod op;
56pub mod shell_builtins;
57pub mod value;
58pub mod vm;
59
60pub use chunk::{Chunk, ChunkBuilder};
61pub use host::{DefaultHost, ShellHost};
62pub use jit::{
63    DeoptFrame, DeoptInfo, JitCompiler, JitExtension, NativeCode, SlotKind, TraceJitConfig,
64    TraceLookup, TraceMetadata,
65};
66pub use op::Op;
67pub use value::Value;
68pub use vm::{Frame, VMResult, VM};
fusevm/lib.rs

fusevm/
lib.rs
