mirascript-vm
mirascript-vm is the native, single-threaded Rust runtime for MiraScript. Source
is compiled and validated independently from execution: a MiraScript contains
only the decoded program and owned constant table, while a Runtime owns globals,
the standard library, execution state, and every dynamically allocated value.
Quick start
use ;
let script = compile?;
let mut runtime = new;
let foo = runtime.insert_record?;
runtime.insert_global?;
assert_eq!;
# Ok::
One script can run in multiple runtimes, and one runtime can run any number of
scripts. Each run resets frames, registers, the call stack, timeout accounting,
and its execution generation. Globals, standard-library values, the arena, and
materialized string constants remain until the runtime is dropped. Re-entering
Runtime::run from a native callback returns RuntimeErrorKind::ReentrantRun.
Values and arena ownership
MiraValue is an 8-byte, copyable NaN-box. Nil, booleans, numbers, and truly
static strings are inline; dynamic strings, arrays, records, functions, and
modules use 48-bit typed handles into the owning runtime's append-only arena.
Checked lookups reject foreign, out-of-range, and wrongly typed handles.
The compiled constant table never contains runtime handles. A string constant is
allocated only when its bytecode instruction executes and is cached by
(ScriptId, constant_index) in that runtime. Unexecuted branches allocate
nothing, clones of one script share the cache identity, and different runtimes
materialize their own copies.
Use Runtime::insert for an owned MiraManageable, or the category-specific
insert_string, insert_array, insert_record, insert_function, and
insert_module methods when a typed MiraHandle<T> is needed. The matching
checked get_* and get_*_mut methods let the host inspect or mutate live values.
Host records, arrays, functions, and modules
All compound behavior is dispatched through dyn MiraArray, dyn MiraRecord,
dyn MiraFunction, and dyn MiraModule. Script and host implementations use the
same traits; MiraManageable carries an owned value until Runtime::insert
places it in the correct arena.
#[derive(MiraRecord)] supports all structs and #[derive(MiraArray)] supports
tuple and unit structs. Both preserve #[mira(rename = "...")],
#[mira(skip)], generics, dependency aliases, and #[mira(crate = ...)].
Nested derived records and arrays are projection views: they retain a typed parent
handle and read the field from the runtime on every access instead of cloning it.
use ;
let mut runtime = new;
let user = runtime.insert_record?;
runtime.insert_global?;
let script = compile?;
assert_eq!;
runtime.get_record_mut?.position.x = 10.0;
assert_eq!;
# Ok::
Use #[mira] to expose native functions and inline modules. The original Rust
function is unchanged; the macro adds an upper-case companion constant that can
be inserted into a runtime. Inside a Mira module, function diagnostic names are
qualified while export keys remain local.
use ;
assert_eq!;
let mut runtime = new;
runtime.insert_global?;
assert_eq!;
assert_eq!;
# Ok::
const = NAME overrides the Rust companion constant, rename = "full.name"
overrides the MiraFunction or MiraModule diagnostic name, and use = "key"
overrides the direct parent module's export key. Consecutive #[mira] modules
build dotted default names; an unmarked module starts a new naming root.
MiraExtern is currently only a public, sealed marker. It has no constructor or
derive macro, and downstream crates cannot implement it.
Execution options and providers
Runtime::with_options configures the timeout, checkpoint interval, maximum call
depth, maximum bounded array length, and a RuntimeProviders implementation for
random numbers, time, and debug output.
use Rc;
use ;
;
let mut runtime = with_options;
assert_eq!;
# Ok::
Timeout checks are cooperative. Loop backedges and function calls reach checkpoints; a blocking native callback cannot be preempted.
Lifetimes and errors
Strings, arrays, and records returned from a run remain valid in that runtime.
Script closures and modules retain their shared decoded program and execution
generation but cannot escape as results; cached callables from an older run return
RuntimeErrorKind::ExecutionEnded. The runtime has no garbage collector: all arena
values are released together when it is dropped.
MiraError separates compiler diagnostics, invalid bytecode, structured runtime
failures, conversion failures with field/index paths, and arbitrary host errors.
Runtime errors retain bytecode offsets and call-stack context.
Development
cargo fmt --all -- --check
cargo check --workspace --all-targets
cargo test --workspace
cargo doc --workspace --no-deps
git diff --check