Runtime

Modules l3i::runtime, l3i::runtime::profiler, l3i::sandbox, l3i::source, l3i::flags, l3i::error, l3i::diagnostics and l3i::debug_name. Runtime, Error and Result are re-exported from the root. Start here shows a runtime in use and Runtime options covers the watchdog, memory categories and the profiler in prose.

RuntimeBuilder#

Host choices made before the VM exists. Made by Runtime::builder(); defaults: debug root dreamweave, pointer encoding seeded, standard libraries opened, no limits, profiler off, initialization category 0, no atom catalogue, no buffer cage, no native code.

Errors from build: the flag policy names a flag this Luau build lacks (Error::Logic), coroutine finalizers are asked for after a runtime was built without them (Error::Logic), the state cannot be allocated (Error::Runtime), the atom catalogue does not resolve, or the value layout mirror disagrees with the API.

Runtime#

Owns one Luau VM. Dropping it closes the VM after dropping every runtime-owned state value and ending the lifetime token that pinned Values check, so a value that outlives its runtime becomes invalid instead of touching a closed VM. Not Clone, not Send.

Creating#

A VM with the default configuration; the builder; or a VM built from a finalised extension plan: every extension installed in dependency order, direct dispatch, modules and compiler metadata published together.

Running code#

Compile and run source on the main thread with this runtime’s compile options: discarding results; reading what the chunk returns (runtime.eval::<f64>("return 1 + 1"), a tuple for several results, () for none); or running a chunk that returns one function and pinning it. Each leases the root stack, so do not hold Runtime::stack across them. A compile error or a Lua error is Error::Runtime with Luau’s message.

Compiles source and pushes the chunk function onto frame, which may be on any thread of this VM; the second form sets the chunk’s environment to env so its globals resolve through that table. A frame from another VM or a chunk name containing NUL is a logic error.

use l3i::Runtime;

fn main() -> l3i::Result<()> {
    let runtime = Runtime::new()?;
    runtime.exec("assert(typeof(42i) == 'integer')")?;
    let sum: f64 = runtime.eval("return 1 + 1")?;
    assert_eq!(sum, 2.0);
    let double = runtime.load_function("return function(n) return n * 2 end")?;
    assert_eq!(double.invoke::<i32, _>(&runtime.stack(), (21,))?, 42);
    Ok(())
}

Globals, functions and modules#

Binds callable as a Lua function named debug_name under this runtime’s debug roots and returns it pinned. The shapes a callable may take are on Binding and userdata.

Stores any pushable value as the global name (fails when the globals table is read-only), or pins the global name (nil pins as a valid nil).

A package table at path; a LuauModule registered and frozen; a check that name is a valid debug name under the roots. See module on Binding and userdata.

The configured roots; luaL_openlibs (call once); luaL_sandbox, which makes the globals and the standard library tables read-only and the globals table a safe environment, for hosts that do not use Sandbox.

Compile options and the plan#

The options exec, eval and load_function use. A runtime made from a plan derives them from the plan and refuses to replace them (Error::Logic).

The plan this runtime came from; the .d.luau for that plan including installed module members; and, for a hand-assembled runtime only, registering T as the owner of its packed kind. Registering the same type twice is a no-op; another type on the same kind number, or any registration on a planned runtime, is a logic error.

Host state#

Runtime-owned state by type, one value per type per namespace, dropped before the VM closes. The host’s namespace is insert_state/host_state; extensions store theirs through InstallContext::insert_state and state_of reads the state extension owner stored.

Limits, categories and the profiler#

The watchdog limits; a change takes effect for the next call scope.

Opens a call scope for context; scopes must nest strictly. See CallScope below.

INITIALIZATION_CONTEXT in the configured initialization category, the context sandbox and template setup runs under.

Bytes allocated across all categories, or in one; and the main thread’s active category, which allocations are attributed to.

Accumulated call statistics (profiler only); selecting one context to sample every 32nd safepoint while it is the innermost active call (changing the selection clears the samples, and nothing costs anything while nothing is sampled); and a copy of the samples so far.

The host’s frame counter for statistics, which profiler::FrameStats::catch_up folds against.

source:line of the innermost Lua code running on the main thread; empty when none is.

The collector#

A full collection (Rust destructors of unreachable userdata run inside); one incremental step of steps kilobytes (0 is one basic step), true when a cycle finished; the same with its wall time. Runtime::gc(GcControl) and the rest of the collector controls are on Direct access and the VM.

The stack#

The main thread’s root stack at host level, valid while the runtime is. Panics if a root stack from this runtime is alive and not suspended inside a Lua call. Inside a bound function use the Call scope instead.

Also on Runtime#

Methods other modules add to Runtime are documented with their module: sandbox (below); new_thread, set_hooks, clear_hooks, gc, allocation_rate, clock, encode_pointer, memory_dump, gc_dump, set_light_userdata_name, light_userdata_name, weak_ref, set_embedder_gc, clear_embedder_gc, atom_catalogue, atom_of, install_vector_buffer_writer on Direct access and the VM; open_library, sandbox_luau, register_library, find_table, set_jit_inliner, install_require, require_function, proxy_require_function, register_require_module, registered_require_modules, clear_require_cache_entry, clear_require_cache on Binding and userdata; native_code on Native code and analysis.

PointerEncodingKey#

Four 64-bit words for lua_setpointerencodekey. Clone, Copy, Debug, Eq.

Whether the key reproduces Luau’s default identity map (lua_setpointerencodekey clears a’s low bit and sets b’s); a fresh key from OS entropy, redrawn while it would be the identity.

INITIALIZATION_CONTEXT#

The context id call scopes use for sandbox and template setup.

caller_location#

source:line of the innermost Lua code running on scope’s thread; from inside a bound function, the script line that called it. Empty when no Lua code is running there.

CallKind, CallContext and CallScope#

What kind of call a scope wraps. Clone, Copy, Debug, Eq.

Who is running, for accounting: a host-defined context id and the memory category allocations are attributed to. Clone, Copy, Debug, Eq.

An active script call. Opening one pushes an active-call context so the interrupt and allocation callbacks know a script is running, switches the memory category when the profiler is on, and arms the watchdog deadline (the outermost or earliest one wins); dropping it records self time (elapsed minus nested), allocation activity, and restores the previous category and deadline. A scope is a no-op when neither the profiler nor a limit needs it.

use l3i::Runtime;
use l3i::runtime::{CallContext, CallKind, MemoryCategory};

fn main() -> l3i::Result<()> {
    let runtime = Runtime::builder().profiler(true).build()?;
    let script = runtime.load_function("return function() local s = 0 for i = 1, 1000 do s = s + i end end")?;
    {
        let _scope = runtime.call_scope(CallContext { id: 7, category: MemoryCategory(2) }, CallKind::ScriptCall);
        script.invoke::<(), _>(&runtime.stack(), ())?;
    }
    assert_eq!(runtime.call_stats().timed_calls, 1);
    Ok(())
}

MemoryCategory and Limits#

A Luau memory category (0..256). Ids and their meanings are host data; OpenMW uses 0 for shared, 1 global, 2 menu, 3 player. Clone, Copy, Debug, Default, Eq, Hash.

Watchdog limits; zero disables a limit. Clone, Copy, Debug, Default, Eq.

CallStats, Samples and SampledLocation#

Accumulated profiler statistics: total measured self time of script calls, self time and allocation activity (bytes grown) per host context id, timed calls, and the overhead samples taken every 64th call. Clone, Debug, Default, PartialEq.

Where a sampled context spends its time: innermost Lua frames by source:line, and every Lua function on the sampled stacks by source:linedefined (counted once per sample however deep it recurses). count is the samples that found at least one Lua frame. Both Clone, Debug, Default, Eq.

Profiler statistics#

Module l3i::runtime::profiler: the averaging and peak-decay rules OpenMW’s script statistics use, as pure data with no VM involved. Report text and UI stay in the host.

A rolling average seeded by its first sample. Clone, Copy, Debug, Default, PartialEq.

Wall time of a phase and the script time within it, averaged together so both cover the same frames. fn record(&mut self, total_ms: f64, scripts_ms: f64) folds one frame. Clone, Copy, Debug, Default, PartialEq.

Per-context statistics kept across frames: this frame’s accumulators plus the averages and peak they fold into. Clone, Copy, Debug, Default, PartialEq.

Sandbox#

Module l3i::sandbox. Modules and sandboxes explains the model: a frozen base environment copying every string-keyed global except _G, getfenv, setfenv, newproxy, getmetatable, print and require, with tables as read-only views; a writable instance environment per script whose frozen metatable indexes the base env; and templates compiled once on a loader thread and cloned per script.

Clone, Debug, Default.

On Runtime: prepares a sandbox on this VM, installing the prelude and the chosen compatibility shims into the real globals. Call once, after every module the base env should expose is registered. log receives each print line, already tab-joined and prefixed with the instance name. Needs at least one debug root.

A prepared sandbox for one VM: the base environment and the generators.

Errors: a package, loader, hidden value, template or environment from another VM is Error::Logic; a script error from run is Error::Runtime with Lua error: and the message.

One script’s environment and its loaded packages table.

A compiled script, loaded once, instantiated many times. Debug.

use l3i::Runtime;
use l3i::runtime::{CallContext, MemoryCategory};
use l3i::sandbox::{InstanceSpec, SandboxOptions};

fn main() -> l3i::Result<()> {
    let runtime = Runtime::new()?;
    let sandbox = runtime.sandbox(|line| println!("{line}"), SandboxOptions::default())?;
    let loader = runtime.load_function(
        "return function(name, env) return function(n) if n == 'answer' then return 42 end error('module ' .. n .. ' not found') end end",
    )?;
    let spec = InstanceSpec { name: "scriptA", packages: &[], hidden_data: None, loader: &loader };
    let instance = sandbox.new_instance(&runtime, &spec)?;
    let template = sandbox.load_template(&runtime, "script.lua", "print('hello') return require('answer')")?;
    let results = sandbox.run(&runtime, &template, &instance, CallContext { id: 1, category: MemoryCategory(0) })?;
    assert_eq!(results.len(), 1);
    Ok(())
}

CompileOptions#

Module l3i::source.

Luau compiler policy. An explicit CompileOptions always travels with the source, never Luau’s silent defaults. Clone, Debug, Default.

Compile-time knowledge about a library’s members. Both methods default to None.

A constant the compiler may fold in place of a library member access. Clone, Debug, PartialEq.

Compiles Luau source to bytecode. A compile error is Error::Runtime carrying Luau’s message (without a chunk name) rather than error bytecode. Freezes the flag policy first.

Loading chunks on the thread of any scope, implemented for every Scope. The chunk loads on the scope’s own thread, so Luau resolves its builtin imports against that thread’s globals when they are marked safe, and with jit and a runtime built with native code it is compiled according to the runtime’s mode (always under Eager, when marked --!native under Annotated). The chunk runs in the thread’s globals until the host sets another environment.

Flags#

Module l3i::flags: the process-global Luau feature-flag policy. Flags change the bytecode the compiler emits, so Runtime creation and source::compile both freeze the same policy before anything else.

l3i’s flag policy: the flags in the Ast, Bytecode, Compiler and VM components, which are always linked, including LuauExperimentalIfLocalSyntax and the two that gate APIs the binder exposes (LuauGcTraceUdata, LuauBufferCage); and the CodeGen flags, applied only with the jit feature. Each name carries its reason in the source. The X64 and A64 flags exist only on their own architecture, and LuauCoroutineFinally is raised separately by the builder.

Freezes the policy. Idempotent and thread-safe. A flag name the linked Luau lacks is Error::Logic (Luau 0.742 has no fast flag named ...) rather than a silent no-op.

Whether this process runs with coroutine finalizers, which the first runtime built decides (RuntimeBuilder::coroutine_finalizers). False until a runtime exists.

Error#

Module l3i::error, re-exported from the root.

Display prints the message, or Lua error for LuaErrorOnStack. Clone, Debug, Eq, std::error::Error.

Diagnostics#

Module l3i::diagnostics: error text matching Luau’s own lauxlib wording, so scripts see the messages the C++ binder produced through luaL_typeerror and luaL_argerror.

The message luaL_typeerror(L, narg, expected) would raise for value, with the caller location prefix luaL_error adds: invalid argument #2 to 'name' (number expected, got string), or missing argument #2 to 'name' (number expected) for a nonexistent slot. The first numbers the argument by its raw stack position; the second takes the number explicitly.

__type from the metatable when present, else the basic type name (luaT_objtypename).

A non-executing description for error messages: booleans, numbers and (truncated, escaped) strings by content, everything else as <type>.

UTF-8-safe bounded truncation with a trailing ...; escaping of quotes, backslashes and control bytes with multibyte UTF-8 passed through.

Debug names#

Module l3i::debug_name. A debug name is a dot-separated path of identifiers rooted at one of the host’s configured roots (openmw.util.Vector3.__mul, dreamweave.archive.open). Luau borrows the name pointer for a closure’s whole life, so names are interned in a VM-private registry table for the VM’s life.

True when name is <root>.<ident>(.<ident>)* for one of roots; or Error::Logic naming the roots when it is not.