Stack and values

Modules l3i::stack, l3i::value, l3i::call, l3i::convert and l3i::options. Stack and values explains the three tiers in prose; this page lists every item.

The borrowed tier pins nothing: a ValueView names one stack slot and is valid exactly as long as the raw Lua index it names, which Rust proves through the frame model. Stack has no pop; only frames pop. Temporaries are pushed through a Frame, and the view returned borrows that frame. with_frame closures are higher-ranked, so a view cannot be returned out of the frame that made it. A stack or a frame has at most one open child frame: opening a sibling panics at the opening line, pushing into a scope while its child is open is refused, and popping or releasing needs &mut, so no live view can survive a pop.

Scope#

Somewhere values can be pushed: the call-level Stack, a Frame, or a bound function’s Call. Helpers that create values are generic over it so a result can be pushed at the call level while a temporary goes through a frame. Sealed; implemented by Stack, Frame and Call.

Stack#

The exclusive handle to one Lua thread’s stack. 'vm is the lifetime for which the caller guarantees the lua_State stays alive: inside a native callback the callback’s frame, host side the borrow of the owning Runtime. Not Clone. Two kinds exist and only one of each may be alive per thread: the root stack leased from Runtime::stack or Thread::with_stack, and a native-call stack created for a bound function while Lua is calling into Rust.

Pushing through a Stack while a frame opened from it is alive is a debug assertion.

Frame#

A temporary region of the stack. Everything pushed through it is popped when it drops (only downwards: an earlier-dropped sibling may have lowered the top). Views produced by a frame borrow the frame; popping needs &mut. Nested frames are opened from a frame with frame, one at a time.

use l3i::Runtime;
use l3i::value::Value;

fn main() -> l3i::Result<()> {
    let runtime = Runtime::new()?;
    let stack = runtime.stack();
    let table = stack.with_frame(|frame| {
        let table = frame.push_table(0, 1)?;
        frame.push_number(42.0);
        table.raw_set(frame, "answer")?;
        Value::store(table.value())
    })?;
    assert_eq!(stack.top(), 0, "the frame restored the height");
    assert!(table.is_table());
    Ok(())
}

Type#

Luau’s value types, including the Luau-only ones, with the LUA_T* discriminants. None is LUA_TNONE, a slot that does not exist. Clone, Copy, Debug, Eq.

Luau’s own name, as lua_typename reports it: no value, nil, boolean, userdata (for both userdata kinds), number, integer, vector, string, table, function, thread, buffer.

ValueView#

A borrowed view of one stack slot. 'v is the scope that keeps the slot alive: the frame that pushed it, or the stack for slots below every frame. Copying a view copies the index, not the value. A view left behind by an out-of-order frame drop reads as Type::None instead of aliasing whatever Luau puts there next. Clone, Copy, Debug.

TableView#

A borrowed view of a table on the stack. Lookups push their result and return a view bound to the frame you pass; the frame decides when it is popped. Stores consume the value on top of that frame. Clone, Copy, Debug.

A view whose slot no longer exists, or a frame on another thread, is Error::Logic.

Value#

Module l3i::value: the owned tier. A Value owns a registry pin (lua_ref) but never the VM. Each carries a weak handle to its VM’s lifetime token, so a value that outlives its Runtime becomes invalid instead of touching a closed VM.

A registry-pinned Lua value tied to one VM. Clone creates an independent pin; Default is invalid(); equality is raw equality within one VM (two invalid values are equal, values from different VMs never are); Debug prints the type and reference id or Value(invalid). Dropping releases the pin, a no-op once the VM has closed.

An invalid value, or a value pushed to another VM, is Error::Logic (Lua reference belongs to a different VM).

Table and Function#

A pinned value known to be a table. Clone, Debug, PartialEq, Default; also FromView (pins the slot; any other type is a type error), Push, CallResults, and a bound-function parameter and return type.

A pinned value known to be a function. Clone, Debug, PartialEq, Default; also FromView, Push, CallResults, and a parameter and return type.

Calling#

Module l3i::call. Every call goes through lua_pcall, so a callee error never unwinds into Rust: it comes back as Error::Runtime, with the stack restored by the frame. The invocation API is non-yielding: a callee that yields through it is Lua function yielded through a non-yielding invocation. Two wordings are kept from the C++ binder: a borrowed-view call reports Lua error at stack index N: <message>, a pinned-function call Lua error: <message>.

Arguments for a call: () and tuples of one to eight Push values.

Results of a call, read from the frame slots first..first + COUNT; Lua pads with nil or truncates. Implemented for (), bool, every Rust integer, f32, f64, String, Vec<u8>, Integer, Vector3, Value, Table, Function, Option<T> where Option<T>: FromView, and tuples of two to six results. Borrowing types (&str, views) are excluded on purpose: the result slots are popped when the call frame closes.

A borrowed view of a function slot, from ValueView::as_function. Clone, Copy, Debug.

use l3i::Runtime;
use l3i::value::Value;

fn main() -> l3i::Result<()> {
    let runtime = Runtime::new()?;
    let multi = runtime.load_function("return function() return 1, 'two' end")?;
    let stack = runtime.stack();
    assert_eq!(multi.invoke::<i32, _>(&stack, ())?, 1);
    assert_eq!(multi.invoke::<(i32, String, Option<i32>), _>(&stack, ())?, (1, "two".to_owned(), None));
    let results: Vec<Value> = multi.invoke_multi(&stack, ())?;
    assert_eq!(results.len(), 2);
    let boom = runtime.load_function("return function() error('boom') end")?;
    let error = boom.invoke::<(), _>(&stack, ()).unwrap_err().to_string();
    assert!(error.starts_with("Lua error: ") && error.ends_with("boom"));
    assert_eq!(stack.top(), 0);
    Ok(())
}

Conversion#

Module l3i::convert. Conversion is explicit supported-type dispatch: a type either implements FromView and Push with one checked conversion, or it does not convert. No probing, no string-to-number coercion, no silent fallback.

A Rust type readable from one stack slot. EXPECTED is the name diagnostics use. from_view converts or returns the type or range error. from_raw_arg is from_view for an argument slot the binder reads directly through Luau’s 16-byte value layout; scalar types override it, the default converts through the API. matches is used only for overload resolution and optional argument disambiguation.

A Rust type pushable as one Lua value. push_only pushes without producing a view; the hot return path uses it so a scalar result costs one lua_push* and nothing else. &T pushes as T.

Out-of-range wording: Lua stack index N: integer <value> is out of range for i32, number <value> is out of range for u8, number <value> is not an exact usize.

Integer, Exact and Bits64#

An explicit Luau 64-bit integer. Plain Rust integers push as Lua numbers; wrap them in Integer to push the integer runtime type. Reads accept only an integer slot. Clone, Copy, Debug, Default, Eq, Hash.

An integer parameter that never rounds: a Luau integer in range, or a number with a zero fractional part in range (640.4 is refused where a plain i32 would read 640). For indices, offsets, counts, sizes and ids. Input only; it has no push form. Implemented for every Rust integer type. Clone, Copy, Debug, Default, Eq, Hash.

A 64-bit pattern carried in a Luau integer: opaque ids and hashes, all 64 bits, no numeric meaning. Numerically it may look negative to a script. Reads accept an integer only; a number never becomes one. Clone, Copy, Debug, Default, Eq, Hash.

Vector3#

A native Luau vector; the VM is built 3-wide. repr(C), Clone, Copy, Debug, Default, PartialEq, From<[f32; 3]> and into [f32; 3].

BufferView and BytesView#

A borrowed view of a Luau buffer: raw bytes owned by Luau, mutable from scripts and from the host. Safe access goes through bounds-checked copies, never a Rust slice: a script can pass one buffer to two parameters, so two views of the same storage are ordinary. Bounds failures use the buffer library’s own wording, buffer access out of bounds. Clone, Copy, Debug.

Immutable bytes from either a Lua string or a Luau buffer, without normalising: an API that accepts “some bytes” reads through this and never copies to decide. EXPECTED is string or buffer. Clone, Copy, Debug.

Creates a zero-filled buffer of len bytes on scope.

use l3i::Runtime;
use l3i::convert::{BufferView, BytesView};

fn main() -> l3i::Result<()> {
    let runtime = Runtime::new()?;
    let total = runtime.bind_function("dreamweave.tests.total", |bytes: BytesView| {
        bytes.to_vec().iter().map(|&x| i64::from(x)).sum::<i64>()
    })?;
    runtime.set_global("total", &total)?;
    runtime.exec("assert(total('\\1\\2\\3') == 6) local b = buffer.create(4) buffer.writeu8(b, 3, 5) assert(total(b) == 5)")?;
    let fill = runtime.bind_function("dreamweave.tests.fill", |buffer: BufferView, value: i64| {
        buffer.fill(0, buffer.len(), value as u8)?;
        let range = buffer.range(1, 2)?;
        Ok::<i64, l3i::Error>(i64::from(range.read_u8(0)?) + i64::from(range.read_u8(1)?))
    })?;
    runtime.set_global("fill", &fill)?;
    runtime.exec("local b = buffer.create(4) assert(fill(b, 7) == 14)")?;
    Ok(())
}

RawValue#

One Luau stack slot as laid out by this build: an 8-byte value union, a 32-bit extra word and the 32-bit type tag. The binder reads argument slots through this mirror instead of Luau’s index resolution; csrc/extra.cpp pins every offset at compile time and every runtime proves the mirror against the API once at creation. repr(C), 16 bytes.

Options#

Module l3i::options: strict camelCase option tables. Every key must be known, required keys are reported precisely, errors carry field paths, and nothing defaults permissively: a misspelt option is an error, not a silently ignored default.

One option table being read. Options::read opens a frame, checks that the value is a table with string keys, hands the reader to body, and then fails if any key was never asked for.

Inside a table body an error comes back prefixed with the reader’s context and key (archive:extract.inputs: ...) unless it already starts with that path; a slot conversion’s Lua stack index N: prefix is dropped, since a field error names the field.

A type built from an option table; read is provided and runs Options::read with from_options.

use l3i::options::{FromOptions, Options};
use l3i::Result;

#[derive(Debug, PartialEq)]
struct Extract {
    path: String,
    force: bool,
    limit: Option<i64>,
    nested: Option<i64>,
}

impl FromOptions for Extract {
    fn from_options(o: &mut Options<'_, '_>) -> Result<Self> {
        Ok(Extract {
            path: o.required("path")?,
            force: o.or("force", false)?,
            limit: o.optional("limit")?,
            nested: o.nested("nested", |inner| inner.required::<i64>("depth"))?,
        })
    }
}

With Extract::read(call, view, "archive:extract") a script passing { path = 'a', frce = true } gets archive:extract: unknown option 'frce'; known options are force, limit, nested, path, and { path = 'a', nested = { } } gets archive:extract.nested: missing required option 'depth'.