ludus::runtime::behavior::LuauProvider¶

Class

Owner-thread interpreter provider with an implementation-only VM and fallible allocation.

Note

Owner-thread only, no concurrent access. Does not cross the GameApi ABI or own world state.

Declared in modules/runtime/behavior/include/ludus/runtime/behavior/behavior.h

#include <ludus/runtime/behavior/behavior.h>

class ludus::runtime::behavior::LuauProvider final

Methods¶

LuauProvider¶

ludus::runtime::behavior::LuauProvider::LuauProvider() noexcept=default

Constructs an unloaded provider without allocating.

Declared in modules/runtime/behavior/include/ludus/runtime/behavior/behavior.h

~LuauProvider¶

ludus::runtime::behavior::LuauProvider::~LuauProvider() noexcept

Retires the VM. Destruction inside its callback is a contract violation.

Declared in modules/runtime/behavior/include/ludus/runtime/behavior/behavior.h

LuauProvider¶

ludus::runtime::behavior::LuauProvider::LuauProvider(const LuauProvider &)=delete

Providers cannot share or copy VM ownership.

Declared in modules/runtime/behavior/include/ludus/runtime/behavior/behavior.h

operator=¶

LuauProvider & ludus::runtime::behavior::LuauProvider::operator=(const LuauProvider &)=delete

Providers cannot assign VM ownership.

Related types: LuauProvider

Declared in modules/runtime/behavior/include/ludus/runtime/behavior/behavior.h

Load¶

Status ludus::runtime::behavior::LuauProvider::Load(const Contract &contract, std::span< const uint8 > trusted_package, usize heap_limit=usize{8} *1024 *1024, uint32 safepoints=100000) noexcept

Stages a fresh VM and retains the active package if preparation fails.

Parameter	Description
`contract`	Borrowed immutable generated descriptor and strings; must outlive the active VM.
`trusted_package`	Only accepted paired-cooker bytes, admitted by the owner; never hostile bytecode.
`heap_limit`	Per-VM peak allocator byte limit, including temporary realloc storage; nonzero.

Note

Reload can hold old/new VMs simultaneously; fixed provider metadata is outside this limit.

Parameter	Description
`safepoints`	Cooperative invocation/initialization bound; nonzero, not an instruction count.

Note

Contract and immutable package storage must outlive the active VM. No acquisition/download occurs. A partial invocation returns Paused; complete or Close it before replacing this package.

Related types: uint8 · usize · uint32 · Status · Contract

Declared in modules/runtime/behavior/include/ludus/runtime/behavior/behavior.h

Invoke¶

Status ludus::runtime::behavior::LuauProvider::Invoke(const Invocation &input, Services services, Outcome &output, Diagnostic &diagnostic) noexcept

Runs one non-yielding handler; validates all copied inputs/state and preserves output on failure.

Note

A runtime fault retires this VM; explicit Load is required to resume play. Services are borrowed only for the call.

Related types: Status · Diagnostic · Invocation · Outcome · Services

Declared in modules/runtime/behavior/include/ludus/runtime/behavior/behavior.h

BeginDebug¶

Status ludus::runtime::behavior::LuauProvider::BeginDebug(const Invocation &input, Services services, Outcome &output, Diagnostic &diagnostic) noexcept

Begins an explicitly debug-enabled invocation, retaining copied inputs and staged state until completion.

Note

Services::User must outlive any pause. The owning game must stop simulation until completion or Close. Output is preserved while paused or on failure; debugger storage is fallibly allocated outside hot paths.

Related types: Status · Diagnostic · Invocation · Outcome · Services

Declared in modules/runtime/behavior/include/ludus/runtime/behavior/behavior.h

ResumeDebug¶

Status ludus::runtime::behavior::LuauProvider::ResumeDebug(uint64 expected_stop, DebugMode mode, Outcome &output, Diagnostic &diagnostic) noexcept

Resumes exactly the inspected pause. Stale/zero stops fail without entering the VM or changing output.

Related types: uint64 · DebugMode · Status · Diagnostic · Outcome

Declared in modules/runtime/behavior/include/ludus/runtime/behavior/behavior.h

Breakpoint¶

int32 ludus::runtime::behavior::LuauProvider::Breakpoint(uint64 asset, int32 compiled_line, bool enabled=true) noexcept

Configures an asset breakpoint at a compiled line; returns the actual executable line, or -1 on rejection.

Related types: uint64 · int32

Declared in modules/runtime/behavior/include/ludus/runtime/behavior/behavior.h

Inspect¶

bool ludus::runtime::behavior::LuauProvider::Inspect(DebugSnapshot &output) const noexcept

Copies safe stack/local values; preserves output on reentrancy or when no package is loaded.

Related types: DebugSnapshot

Declared in modules/runtime/behavior/include/ludus/runtime/behavior/behavior.h

Close¶

Status ludus::runtime::behavior::LuauProvider::Close() noexcept

Retires the VM and any partial debugger transaction. A nested call returns Reentrant and leaves ownership intact.

Related types: Status

Declared in modules/runtime/behavior/include/ludus/runtime/behavior/behavior.h

LiveBytes¶

usize ludus::runtime::behavior::LuauProvider::LiveBytes() const noexcept

Returns physical VM allocation bytes, including headers/retained capacity (zero when unloaded); excludes fixed owner metadata.

Related types: usize

Declared in modules/runtime/behavior/include/ludus/runtime/behavior/behavior.h