Direct access and the VM

Modules l3i::direct (with plan, registry, field), l3i::native, l3i::vector_writer, l3i::memory, l3i::thread and l3i::debug. Direct access and The rest of the VM are the guides.

Direct access#

Module l3i::direct. Luau can call a native callback straight from GETTABLEKS, SETTABLEKS and NAMECALL for a tagged userdata when the key is an interned string with an atom, skipping the metatable walk and the Lua call frame. Three pieces make that work: an AtomCatalogue installed as lua_Callbacks.useratom; a DirectPlan or Registry resolving (tag, kind, atom) to a slot with Luau’s per-instruction 16-bit cache validated before use; and per-tag direct callbacks, run inside a C frame whose function slot is the stored metamethod. The binder installs wrapper metamethods that keep the original as upvalue 1, so both the direct path and the ordinary metamethod path run the same typed handler and can fall back to the original.

A Luau string atom: a small stable id assigned when the string is interned; -1 for strings outside the catalogue.

Which metamethod a direct callback stands in for. repr(u8), Clone, Copy, Debug, Eq.

AtomCatalogue#

Interned member names eligible for direct dispatch, owned by one VM. Names and atoms are host data; the binder requires them to be unique and non-negative. Two runtimes in one process may carry different catalogues. Clone, Debug.

Installs catalogue as this VM’s useratom callback and verifies every spelling resolves. OpenMW installs the callback before luaL_openlibs: call this on a runtime built with standard_libraries(false), then open them, or pass the catalogue to RuntimeBuilder::atom_catalogue. A VM takes exactly one catalogue; a second, or a foreign useratom, is a logic error.

The atom of the string at view, resolving it now if Luau has not yet.

On Runtime: fn atom_catalogue(&self) -> Option<Rc<AtomCatalogue>> and fn atom_of(&self, name: &str) -> Option<Atom>.

DirectAccess#

Outcome of a direct __index or __newindex handler: the handler produced the result (exactly one pushed value for index, none for newindex), or the original metamethod answers. Clone, Copy, Debug, Eq.

Direct member access for a tagged userdata type. Handlers run inside Luau’s direct-access C frame: for index the stack is [ud, key], for newindex [ud, key, value], for namecall [ud, args...] with lua_namecallatom valid. slot is Luau’s per-instruction 16-bit cache, shared between every userdata type and starting at 0; validate it with a plan or registry before trusting it. Errors are raised into Luau; panics abort. Every method defaults to the fallback.

Which of the three metamethods a type dispatches directly, with the constants ALL, INDEX and NAMECALL. Clone, Copy, Debug, Default, Eq.

On MetatableBuilder: installs the direct-dispatch wrappers over the metamethods already present, keeping each original as the wrapper’s upvalue 1. Call after every method, property and metamethod registration for T, and register the VM callbacks with register afterwards. A missing original metamethod, or a metatable whose __type is not T::NAME, is a logic error.

Registers T’s direct callbacks with the VM (lua_registeruserdatadirectaccess) for the metamethods in which. T must be tagged in this runtime with a read-only metatable whose corresponding metamethods are the wrappers direct_dispatch installed; anything else is a logic error, because a fallback would otherwise re-enter the callback.

The callbacks themselves are public for hosts that register by hand: index_callback::<T>, newindex_callback::<T> (lua_UserdataDirectAccess), namecall_callback::<T> (lua_UserdataDirectNamecall), and the metamethod wrappers index_wrapper::<T>, newindex_wrapper::<T>, namecall_wrapper::<T>. All are unsafe extern "C-unwind" and must only be reached through Luau for userdata of T’s tag.

DirectPlan#

Module l3i::direct::plan: the normal path. A plan is the (tag, kind, atom) -> slot table built at run time from what this VM actually assigned, so handlers keep working when the same type is tag 8 in one VM and tag 17 in another. The cache-hit path compares the cached entry’s TypeId, so it never needs a tag lookup.

One resolved dispatch entry. Clone, Debug, Eq.

The dense table. Debug.

The plan installed on scope’s VM, if any: one shared-block read and an Rc clone.

use l3i::direct::plan::DirectPlanBuilder;
use l3i::direct::{self, AccessKind, DirectMetamethods};

// After `tagged::register::<Planned>` installed `direct_dispatch` wrappers on the metatable:
direct::register::<Planned>(&runtime, DirectMetamethods { index: true, newindex: true, namecall: false })?;
DirectPlanBuilder::new(&runtime)
    .slot::<Planned>(AccessKind::Index, "value", PLANNED_VALUE_GET)?
    .slot::<Planned>(AccessKind::NewIndex, "value", PLANNED_VALUE_SET)?
    .finish()?;

Registry#

Module l3i::direct::registry: the compile-time alternative for hosts whose tags and atoms are constants. An atom catalogue plus slot descriptors, folded into a dense table in a const fn. Slot values are contiguous and fixed by catalogue order, never by registration order, so they can be treated as protocol identifiers.

Slot 0 is Unknown, the value Luau starts every instruction cache with.

One dispatch entry. Clone, Copy, Debug, Eq.

ATOMS catalogued names, SLOTS descriptors, and the dense lookup table. Debug.

Direct fields#

Module l3i::direct::field: lua_registeruserdatadirectfieldget. A registered getter runs from GETTABLEKS with no Lua frame, receiving only the userdata payload and a result slot. It must not touch the Lua API and must not fail. Only the value kinds Luau provides setters for can be produced; there is no string setter, so a text field is a getter.

A value a direct field getter can produce. Also Push and Return, so the same getter serves as the canonical property. Clone, Copy, Debug, PartialEq.

A direct field getter for T: a unit type, so the getter is a plain function pointer with no context.

Registers H as the direct getter for field on T, which must be a registered tagged type with a read-only metatable. Luau offers no query, replacement or removal for direct fields, so registering a field twice is a logic error here.

use l3i::direct::field::{DirectField, FieldValue};

struct ValueField;

impl DirectField<Counter> for ValueField {
    fn get(counter: &Counter) -> FieldValue {
        FieldValue::Integer(counter.value.get())
    }
}

native#

Module l3i::native: the entry point for hand-written lua_CFunctions that use the binder’s stack layer.

Runs body as the entire implementation of a lua_CFunction, with a Stack over the calling thread. Errors become Lua errors after every Rust value has dropped; panics abort. state must be the lua_State* Luau passed to the enclosing C function, and the caller that function’s frame. The raw C API has the rules for such functions.

use std::ffi::c_int;
use l3i::ffi;
use l3i::stack::Scope;

unsafe extern "C-unwind" fn good_method_body(state: *mut ffi::lua_State) -> c_int {
    unsafe {
        l3i::native::enter(state, |stack| {
            let discriminator = stack.at(ffi::lua_upvalueindex(1)).read::<i32>()?;
            let argument = stack.at(2).read::<i32>()?;
            stack.push(&(argument * discriminator))?;
            Ok(1)
        })
    }
}

The vector buffer writer#

Module l3i::vector_writer: the interpreter half of OpenMW’s native vector buffer writer. Luau’s vector metatable ships an __index but no __namecall; installing one lets a script write a vector into a buffer in a single call with exactly the semantics of three buffer.writef32 calls. Any other method name resolves through the original __index, kept as upvalue 1. The code generation half, native_code::vector_buffer::VectorBufferWriter, lowers the call to three native f32 stores.

On Runtime: installs vector:writef32x3(buffer, offset) on the vector metatable. Fails when the metatable already has a __namecall. Uses this VM’s atom for writef32x3 when its catalogue has one, else compares the method name.

Memory#

Module l3i::memory: collector controls beyond the watchdog, allocation rate, dumps, the buffer cage, embedder GC integration, light userdata, raw tag operations, coroutine finalizers and fast-flag introspection.

lua_gc commands. Sizes are in kilobytes where Luau’s are: Count is the heap size in KB, CountRemainder the remainder in bytes, Step(n) one incremental step of n KB (0 for a basic step) returning 1 when a cycle ended, SetGoal the target heap growth percentage before a new cycle. The defaults, a 200 percent goal, multiplier 200 and 1 KB steps, are Luau’s. Clone, Copy, Debug, Eq.

On Runtime:

use l3i::Runtime;
use l3i::memory::GcControl;

fn main() -> l3i::Result<()> {
    let runtime = Runtime::new()?;
    runtime.exec("keep = {} for i = 1, 1000 do keep[i] = { i } end")?;
    assert_eq!(runtime.gc(GcControl::IsRunning), 1);
    let previous_goal = runtime.gc(GcControl::SetGoal(150));
    assert_eq!(runtime.gc(GcControl::SetGoal(previous_goal)), 150);
    while runtime.gc(GcControl::Step(1)) != 1 {}
    assert!(runtime.allocation_rate() >= -1);
    Ok(())
}

A caged allocator for Luau buffers (lua_setmemorycage): every buffer allocation goes through it. The lua_Alloc contract: new_size == 0 frees ptr and returns null; ptr null with new_size > 0 allocates; otherwise reallocates. Installed through RuntimeBuilder::buffer_cage before any buffer exists.

The embedder side of cross-heap marking (lua_setembeddergc): each cycle Luau first asks the embedder to reset its bookkeeping, then, once it has marked userdata through UserdataMark callbacks, asks it to mark every weak reference reachable from marked native objects. No Lua API may be used from these methods.

A mark callback for T (lua_setuserdatamark), called when the collector marks a T reachable; T must be tagged in this runtime. No Lua API may be used in mark.

An embedder-managed weak reference (lua_weakref). Released explicitly; a leaked one costs a registry slot until the VM closes. Debug.

A light userdata: a raw pointer with a tag (lua_pushlightuserdatatagged); tag 0 is the plain light userdata Lua knows. Push (a tag outside 0..LUA_LUTAG_LIMIT is a logic error) and FromView. Clone, Copy, Debug, Eq.

Module l3i::memory::raw, for hosts that manage a tag’s meaning themselves:

Fast flags (process-wide, frozen by the crate’s policy once a runtime exists; for Luau’s Debug* flags only):

On Thread: fn add_finalizer(&self, scope: &impl Scope, callback: ValueView<'_>) -> Result<()> registers a function to run when the coroutine is finalized (it fails unless the process has finalizers, chosen with RuntimeBuilder::coroutine_finalizers, and for the main thread, a fresh thread or a dead coroutine), and fn has_finalizers(&self) -> bool. fn finalizer_function(&self, scope: &impl Scope, close: bool) -> Result<Function> is the pinned function that runs the pending finalizers when called, once. With close false the coroutine must have finished or failed, and its finalizers receive "finished" and its results or "error" and its error; with close true it must be suspended or idle, the call resets it and its finalizers receive "cancelled". It fails when nothing is pending, in the wrong state, and for a coroutine that died of a memory or error-handler error instead of a runtime error.

Threads#

Module l3i::thread: Lua threads driven from the host. The host starts a Thread with a function and arguments, then resumes it with the values the coroutine’s yield receives. Bound functions yield by returning bind::Yield and request a debugger break by returning bind::Break.

What a resume step did: the coroutine yielded these values and can be resumed; its function returned these values and the thread is finished; or it hit a lua_break. Debug.

lua_status: not started or finished normally; yielded; broken; or died with a LUA_ERR* code. Clone, Copy, Debug, Eq.

lua_costatus as seen from another thread; Normal is active but not running (it resumed another coroutine). Clone, Copy, Debug, Eq.

A pinned Lua thread, from Runtime::new_thread(&self) -> Result<Thread>, sharing the VM’s globals and registry.

An error inside the coroutine comes back as Error::Runtime (Lua error: <message>) and leaves the thread in its error status. A function or thread from another VM, or a start on a thread that is not idle, is Error::Logic.

use l3i::Runtime;
use l3i::thread::{Resume, ThreadStatus};

fn main() -> l3i::Result<()> {
    let runtime = Runtime::new()?;
    let generator = runtime.load_function(
        "return function(a) local b = coroutine.yield(a + 1) local c = coroutine.yield(b * 2) return a + b + c end",
    )?;
    let thread = runtime.new_thread()?;
    let stack = runtime.stack();
    let Resume::Yielded(values) = thread.start(&stack, &generator, (1,))? else { panic!("expected a yield") };
    assert_eq!(values.len(), 1);
    assert_eq!(thread.status(), ThreadStatus::Yielded);
    let Resume::Yielded(_) = thread.resume(&stack, (10,))? else { panic!("expected a yield") };
    let Resume::Finished(values) = thread.resume(&stack, (100,))? else { panic!("expected a return") };
    assert_eq!(values.len(), 1);
    Ok(())
}

Debug#

Module l3i::debug: activation records, locals, upvalues, arguments, tracebacks, single stepping, breakpoints, coverage, and the VM callbacks a debugger or host needs.

One activation record (lua_getinfo with "slnua"): what is Lua or C, source the chunk name without its leading = or @, current_line the line being executed or -1. Clone, Debug, Eq.

Where a running function is (lua_getinfo with "sl"): the chunk name without its leading = or @ ([C] for a native function) and the line being executed, -1 when unknown. Luau records lines, not columns, so no binder can give a column. Clone, Debug, Eq.

Hit counts of one function from lua_getcoverage; hits per line, -1 for lines without executable code. Clone, Debug, Eq.

Debug queries over the call stack of a scope’s thread, implemented for every Scope.

What a debugger hook wants the VM to do next. Break stops the thread with LUA_BREAK for the host to resume; only possible on a thread the host drives through Thread, since on the main thread Luau raises attempt to break across metamethod/C-call boundary. Clone, Copy, Debug, Eq.

Host callbacks for the remaining lua_Callbacks slots. Every method has a no-op default; a HookSet selects which slots are installed so the VM pays only for the ones in use. Hooks that receive a Stack run where the Lua API may be used on that thread; the ones that receive raw states may not touch it (Luau’s documented restriction). Hooks must not panic: panics abort.

Which slots to install, with the constants NONE, ALL and DEBUGGER (break, step, interrupt, protected error). user_thread is always delivered, since the runtime owns that callback for its per-thread records. Clone, Copy, Debug, Default, Eq.

On Runtime: fn set_hooks(&self, hooks: impl RuntimeHooks, set: HookSet) installs hooks for the slots in set, replacing any previous hooks and clearing the slots outside set; fn clear_hooks(&self) removes them.