Expand description
Bytecode compiler and stack VM for the Nybl programming language.
nybl-vm implements the same language, host interface, values, limits, and
diagnostics as the tree-walker in nybl-lang,
while compiling source to reusable bytecode. It is the usual choice for
scripts that run hot loops or are executed repeatedly at runtime.
§One-shot execution
run parses, compiles, validates, and executes one isolated program:
use nybl::{NyblError, NyblHost, NyblLimits, Value};
struct Host;
impl NyblHost for Host {
fn call(
&mut self,
_: &str,
_: &[Value],
_: u32,
) -> Option<Result<Value, NyblError>> {
None
}
fn on_print(&mut self, message: &str) {
assert_eq!(message, "42");
}
}
let mut host = Host;
nybl_vm::run(
"print(6 * 7)",
&mut host,
&NyblLimits::standard(),
).unwrap();§Compile once, execute with fresh state
Use compile and execute when the bytecode should be reused but each
run should start with fresh globals:
let statements = nybl::parse("let answer = 6 * 7").unwrap();
let chunk = nybl_vm::compile(&statements).unwrap();
nybl_vm::validate_chunk(&chunk).unwrap();
let mut host = Host;
nybl_vm::execute(
chunk,
&mut host,
&NyblLimits::standard(),
).unwrap();validate_chunk rejects malformed control flow, operands, pool indices,
and nested chunks before execution. disassemble provides a readable
representation for tooling and diagnostics.
§Persistent programs
NyblInstance loads and compiles once, then retains globals, modules,
functions, types, methods, callbacks, and random-number state across host
calls. Root-level pub fn declarations define the callable ABI.
let mut host = Host;
let mut instance = nybl_vm::NyblInstance::load(
"let count = 0\npub fn next() { count += 1; return count }",
&mut host,
&NyblLimits::standard(),
).unwrap();
assert_eq!(
instance.call("next", &[], &mut host).unwrap().inspect(),
"1",
);§Reference parameters
The VM implements Nybl’s explicit ref parameters with the same
transactional copy-in/copy-out semantics as the tree-walker and AOT
engine. Mutable plain-variable targets commit together after a normal
return and roll back together on runtime or resource errors. Parameter
modes remain attached to first-class callable values.
Rust NyblInstance::call and NyblInstance::call_value arguments are
value-only and reject ref-bearing callables before execution. See the
reference-parameters
guide for the
complete target, forwarding, evaluation-order, and method rules.
User-defined ref self receivers use the same transactional commit and
rollback path as explicit reference arguments; ordinary self is
read-only.
§Features
std(default) retains Rust standard-library host behavior and forwards tonybl-lang/std.nybl-std(default) forwards tonybl-lang/nybl-stdso hosts can resolve the bundledstd.*modules.no_stdforwards tonybl-lang/no_std; combine it withdefault-features = falsefor bare-metal orwasm32-unknown-unknownbuilds. If Cargo unifiesstdandno_std,stdwins.
See the embedding guide and stateful instance guide for lifecycle, limits, callback affinity, and engine-selection details.
Re-exports§
pub use chunk::Chunk;pub use chunk::CodeOffset;pub use chunk::ConstIdx;pub use chunk::Constant;pub use chunk::EnumConstructShape;pub use chunk::EnumDef;pub use chunk::EnumIdx;pub use chunk::EnumVariantDef;pub use chunk::EnumVariantShape;pub use chunk::FnDef;pub use chunk::FnIdx;pub use chunk::Instr;pub use chunk::InterpIdx;pub use chunk::InterpPart;pub use chunk::InterpRecipe;pub use chunk::LoopStateKind;pub use chunk::NameIdx;pub use chunk::StructDef;pub use chunk::StructIdx;pub use compiler::compile;pub use disasm::disassemble;pub use validate::validate_chunk;pub use vm::CompiledScript;pub use vm::NyblInstance;pub use vm::PreparedEntry;pub use vm::Vm;pub use vm::execute;pub use vm::run;
Modules§
- chunk
- Bytecode chunk layout: instructions, constants, and nested function bodies. See the crate root for the textual description of the instruction set.
- compiler
- AST → bytecode compilation. See
cratedocs for the instruction set overview. - disasm
- Human-readable rendering of a
Chunkfor debugging and tests. - validate
- Structural validation for public, hand-built bytecode chunks.
- vm
- Bytecode VM execution.