moonseed 0.2.0

Deterministic, checkpointable Lua 5.4 runtime in safe Rust
Documentation
# Moonseed vs mlua vs piccolo

Choose Moonseed for deterministic execution and portable checkpoints of running
Lua. Choose mlua for an existing Lua implementation and its module ecosystem.
Choose piccolo for an experimental Rust VM with control over execution and GC
lifetimes.

The comparison uses the current public docs for **mlua 0.12.2** and
**piccolo 0.3.3**, checked 2026-10-26. "No" means the crate documents no such API.

| Feature | Moonseed 0.1.2 | mlua 0.12.2 | piccolo 0.3.3 |
|---|---|---|---|
| Lua versions | 5.4 source semantics; PUC 5.4.9 suite: 14/33 files pass | Select 5.1–5.5, LuaJIT or Luau | Core Lua subset; no complete version-conformance claim |
| Implementation | Safe Rust; forbids unsafe code | Rust bindings to C/C++ runtimes | Rust VM with isolated unsafe internals |
| Sandbox | Explicit libraries and IO capabilities; logical heap quotas | Select libraries, memory limit; Luau-specific sandbox | Core libraries without IO; tracked allocations; host controls policy |
| Fuel | Slice quantum and total execution limit | Instruction hooks for Lua; interrupts for Luau | `Fuel` passed to `Executor::step` |
| Snapshots | Versioned execution checkpoints, fresh-runtime restore | No whole-VM checkpoint API documented | No whole-VM checkpoint API documented |
| Async | Explicit wait requests and completions | Rust futures with `async` feature | Stackless `Sequence` continuations, not Rust futures |
| Wasm | `wasm32-unknown-unknown` | Emscripten target without JIT | Pure Rust; wasm32 not documented upstream |
| C modules | No | Available with unsafe runtime construction and compatible backend | No C module loader documented |
| Speed class | Interpreter; retained counts below | `lua54` runs PUC Lua, which uses about 2.5795× fewer host instructions than Moonseed in the retained corpus; no binding-overhead ratio claimed | Interpreter; retained counts below |
| Threading | `Runtime` is neither `Send` nor `Sync`; create one per worker | `send` feature makes `Lua` `Send + Sync` | `Lua` is neither `Send` nor `Sync` |
| Ecosystem | Rust embedding API; no C modules | Serde integration, derive macros and Lua module mode | Core Rust embedding API |

Moonseed is pre-1.0; mlua embeds established Lua implementations; piccolo is
experimental and documents frequent API breakage.

The mlua entries follow its [crate guide](https://docs.rs/crate/mlua/0.12.2)
and [Lua API](https://docs.rs/mlua/0.12.2/mlua/struct.Lua.html), including the
backend-specific limits and unsafe constructor requirements. Piccolo's
[project description](https://docs.rs/crate/piccolo/0.3.3) describes its safety
boundary and experimental status; its [Lua](https://docs.rs/piccolo/0.3.3/piccolo/struct.Lua.html),
[Fuel](https://docs.rs/piccolo/0.3.3/piccolo/struct.Fuel.html) and
[Executor](https://docs.rs/piccolo/0.3.3/piccolo/struct.Executor.html) APIs describe
library selection, accounting and scheduling.

The retained Moonseed corpus uses **2.5795× PUC Lua 5.4.9** instructions over
21 nonempty workloads and **0.5635× Piccolo** over 16. Piccolo lacks five
required library workloads. These are whole-process Callgrind counts on
sources reduced 100×, including startup, compilation, setup, execution and
teardown. Aggregates exclude the empty startup probe; scaling changes nested
work and working sets, so these counts do not estimate full-size elapsed time
or benchmark mlua. See
[method and source identities](https://github.com/Tavrin/moonseed/blob/main/docs/PERFORMANCE.md#release-instruction-counts).

## Three embedding tasks

Each task shows the same operation in all three APIs. Moonseed blocks run as
doctests. The `rust,ignore` blocks illustrate the other APIs from their docs;
they are not tested here. For mlua, select `lua54` and `vendored` features.
These finite examples assume completion; a production scheduler must handle
pauses, waits, errors and resource exhaustion.

### 1. Run a chunk and read an integer

**Moonseed**

```rust
use moonseed::*;
let mut rt = Runtime::builder().build()?;
rt.load_main(&compile(b"return 42")?)?;
assert_eq!(rt.run(1_000, &mut Journal::new()).map_err(moonseed::Error::from)?, StepOutcome::Completed);
let values = rt.result_values()?;
assert_eq!(i64::from_lua_multi(values, &mut rt)?, 42);
# Ok::<(), Box<dyn std::error::Error>>(())
```

**mlua** ([Lua::load](https://docs.rs/mlua/0.12.2/mlua/struct.Lua.html#method.load)
and [Chunk::eval](https://docs.rs/mlua/0.12.2/mlua/struct.Chunk.html#method.eval))

```rust,ignore
let lua = mlua::Lua::new();
let answer: i64 = lua.load("return 42").eval().unwrap();
assert_eq!(answer, 42);
```

**piccolo** ([Closure::load](https://docs.rs/piccolo/0.3.3/piccolo/struct.Closure.html#method.load),
[Executor::start](https://docs.rs/piccolo/0.3.3/piccolo/struct.Executor.html#method.start),
[Lua::execute](https://docs.rs/piccolo/0.3.3/piccolo/struct.Lua.html#method.execute))

```rust,ignore
let mut lua = piccolo::Lua::core();
let executor = lua.try_enter(|ctx| {
    let chunk = piccolo::Closure::load(ctx, Some("example"), &b"return 42"[..])?;
    Ok(ctx.stash(piccolo::Executor::start(ctx, chunk.into(), ())))
}).unwrap();
let answer: i64 = lua.execute(&executor).unwrap();
assert_eq!(answer, 42);
```

### 2. Exchange a table field containing a string

**Moonseed**

```rust
use moonseed::*;
let mut rt = Runtime::builder().build()?;
let record = rt.create_table()?;
record.raw_set(&mut rt, "text", "hello")?;
rt.globals().raw_set(&mut rt, "record", &record)?;
rt.load_main(&compile(b"record.text = record.text .. '!' ")?)?;
assert_eq!(rt.run(1_000, &mut Journal::new()).map_err(moonseed::Error::from)?, StepOutcome::Completed);
assert_eq!(record.raw_get::<_, String>(&mut rt, "text")?, "hello!");
# Ok::<(), Box<dyn std::error::Error>>(())
```

**mlua** ([Table](https://docs.rs/mlua/0.12.2/mlua/struct.Table.html))

```rust,ignore
let lua = mlua::Lua::new();
let record = lua.create_table().unwrap();
record.set("text", "hello").unwrap();
lua.globals().set("record", record.clone()).unwrap();
lua.load("record.text = record.text .. '!'").exec().unwrap();
assert_eq!(record.get::<String>("text").unwrap(), "hello!");
```

**piccolo** ([Table](https://docs.rs/piccolo/0.3.3/piccolo/struct.Table.html))

```rust,ignore
let mut lua = piccolo::Lua::core();
let executor = lua.try_enter(|ctx| {
    let record = piccolo::Table::new(&ctx);
    record.set(ctx, "text", "hello")?;
    ctx.globals().set(ctx, "record", record)?;
    let chunk = piccolo::Closure::load(ctx, None,
        &b"record.text = record.text .. '!'; return record.text"[..])?;
    Ok(ctx.stash(piccolo::Executor::start(ctx, chunk.into(), ())))
}).unwrap();
let text: String = lua.execute(&executor).unwrap();
assert_eq!(text, "hello!");
```

### 3. Register a Rust callback callable from Lua

**Moonseed**

```rust
use moonseed::*;
let mut registry = HostRegistry::new();
registry.typed("app.answer", NativePolicy::VmLocal, |_cx, (): ()| Ok(42i64));
let mut rt = Runtime::builder().registry(registry).build()?;
let answer = rt.make_closure("app.answer", ())?;
rt.globals().raw_set(&mut rt, "answer", answer)?;
rt.load_main(&compile(b"return answer()")?)?;
assert_eq!(rt.run(1_000, &mut Journal::new()).map_err(moonseed::Error::from)?, StepOutcome::Completed);
let values = rt.result_values()?;
assert_eq!(i64::from_lua_multi(values, &mut rt)?, 42);
# Ok::<(), Box<dyn std::error::Error>>(())
```

**mlua** ([Lua::create_function](https://docs.rs/mlua/0.12.2/mlua/struct.Lua.html#method.create_function))

```rust,ignore
let lua = mlua::Lua::new();
let answer = lua.create_function(|_, ()| Ok(42i64)).unwrap();
lua.globals().set("answer", answer).unwrap();
assert_eq!(lua.load("return answer()").eval::<i64>().unwrap(), 42);
```

**piccolo** ([Callback::from_fn](https://docs.rs/piccolo/0.3.3/piccolo/struct.Callback.html#method.from_fn)
and [Stack::replace]https://docs.rs/piccolo/0.3.3/piccolo/struct.Stack.html#method.replace)

```rust,ignore
let mut lua = piccolo::Lua::core();
let executor = lua.try_enter(|ctx| {
    let answer = piccolo::Callback::from_fn(&ctx, |ctx, _, mut stack| {
        stack.replace(ctx, 42i64);
        Ok(piccolo::CallbackReturn::Return)
    });
    ctx.globals().set(ctx, "answer", answer)?;
    let chunk = piccolo::Closure::load(ctx, None, &b"return answer()"[..])?;
    Ok(ctx.stash(piccolo::Executor::start(ctx, chunk.into(), ())))
}).unwrap();
assert_eq!(lua.execute::<i64>(&executor).unwrap(), 42);
```

For bounded scheduling, userdata, errors and restore, continue with
[Using Moonseed](../USING_MOONSEED.md) and the [embedding reference](../EMBEDDING.md).