Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
PhosphorScripting::LuauEngine Class Reference

An embedded, sandboxed Luau virtual machine with a QVariant API. More...

#include <PhosphorScripting/LuauEngine.h>

Classes

struct  CallOutcome

Public Types

enum class  CallStatus { Ok , TimedOut , Error }

Public Member Functions

 LuauEngine (std::shared_ptr< LuauWatchdog > watchdog=nullptr, std::size_t memoryCapBytes=DefaultMemoryCapBytes)
 watchdog may be shared across engines; nullptr disables the timeout safety net (useful for short, trusted scripts in tests).
 ~LuauEngine ()
 LuauEngine (const LuauEngine &)=delete
LuauEngine & operator= (const LuauEngine &)=delete
bool init (QString *error=nullptr)
 Create the VM, open the (restricted) standard libraries, and wire the interrupt callback.
bool runPrelude (const QString &chunkName, const QByteArray &source, QString *error=nullptr)
 Compile + run a chunk that installs host globals.
void sandbox ()
 Freeze the global table and standard libraries.
int loadModule (const QString &chunkName, const QByteArray &source, QString *error=nullptr)
 Compile + load a module chunk and run it; the chunk is expected to return a table.
void releaseModule (int handle)
 Release a module handle from loadModule.
QVariant moduleField (int moduleHandle, const QString &key) const
 Read a (non-function) field from a loaded module as a QVariant.
bool hasFunction (int moduleHandle, const QString &name) const
 Whether the module exposes a callable field named name.
CallOutcome callModule (int moduleHandle, const QString &function, const QVariantList &args, int timeoutMs)
 Call module[function](args...) under the watchdog, returning a single result.
bool isValid () const noexcept
std::size_t memoryUsedBytes () const noexcept
 Live heap bytes currently allocated by the VM (host accounting).
std::size_t peakMemoryBytes () const noexcept
 High-water mark of memoryUsedBytes over the engine's lifetime.
std::size_t memoryCapBytes () const noexcept
 The configured heap ceiling (0 = unlimited).

Static Public Attributes

static constexpr std::size_t DefaultMemoryCapBytes = 64ull * 1024 * 1024
 Default per-engine heap ceiling for untrusted script execution.

Detailed Description

An embedded, sandboxed Luau virtual machine with a QVariant API.

Lifecycle: construct → init → runPrelude (zero or more, to install host globals such as a pluau standard library) → sandbox (freeze globals

The lua_State is private: the public surface is entirely QVariant-based so no Luau symbols cross the library boundary. Domain bindings marshal their params into nested QVariantMap/QVariantList and read results back the same way.

Not thread-safe — like the underlying VM, all calls must occur on the owning thread. Runaway scripts are bounded by the shared LuauWatchdog.

Member Enumeration Documentation

◆ CallStatus

Enumerator
Ok 
TimedOut 
Error 

Constructor & Destructor Documentation

◆ LuauEngine() [1/2]

PhosphorScripting::LuauEngine::LuauEngine ( std::shared_ptr< LuauWatchdog > watchdog = nullptr,
std::size_t memoryCapBytes = DefaultMemoryCapBytes )
explicit

watchdog may be shared across engines; nullptr disables the timeout safety net (useful for short, trusted scripts in tests).

memoryCapBytes caps heap allocated once the engine is sandboxed (0 = unlimited); the watchdog bounds CPU time, this bounds memory. See sandbox.

◆ ~LuauEngine()

PhosphorScripting::LuauEngine::~LuauEngine ( )

◆ LuauEngine() [2/2]

PhosphorScripting::LuauEngine::LuauEngine ( const LuauEngine & )
delete

Member Function Documentation

◆ callModule()

CallOutcome PhosphorScripting::LuauEngine::callModule ( int moduleHandle,
const QString & function,
const QVariantList & args,
int timeoutMs )

Call module[function](args...) under the watchdog, returning a single result.

timeoutMs <= 0 means no timeout. A result too large to convert (see Marshal::MaxNodes and Marshal::MaxBytes) is reported as CallStatus::Error, not as a nil.

◆ hasFunction()

bool PhosphorScripting::LuauEngine::hasFunction ( int moduleHandle,
const QString & name ) const

Whether the module exposes a callable field named name.

◆ init()

bool PhosphorScripting::LuauEngine::init ( QString * error = nullptr)

Create the VM, open the (restricted) standard libraries, and wire the interrupt callback.

Returns false (and sets error) on failure.

◆ isValid()

bool PhosphorScripting::LuauEngine::isValid ( ) const
inlinenoexcept

◆ loadModule()

int PhosphorScripting::LuauEngine::loadModule ( const QString & chunkName,
const QByteArray & source,
QString * error = nullptr )

Compile + load a module chunk and run it; the chunk is expected to return a table.

Returns a handle (>= 0) to that table, or -1 on error.

◆ memoryCapBytes()

std::size_t PhosphorScripting::LuauEngine::memoryCapBytes ( ) const
inlinenoexcept

The configured heap ceiling (0 = unlimited).

◆ memoryUsedBytes()

std::size_t PhosphorScripting::LuauEngine::memoryUsedBytes ( ) const
inlinenoexcept

Live heap bytes currently allocated by the VM (host accounting).

◆ moduleField()

QVariant PhosphorScripting::LuauEngine::moduleField ( int moduleHandle,
const QString & key ) const

Read a (non-function) field from a loaded module as a QVariant.

Returns an invalid QVariant if the handle/key is absent.

◆ operator=()

LuauEngine & PhosphorScripting::LuauEngine::operator= ( const LuauEngine & )
delete

◆ peakMemoryBytes()

std::size_t PhosphorScripting::LuauEngine::peakMemoryBytes ( ) const
inlinenoexcept

High-water mark of memoryUsedBytes over the engine's lifetime.

◆ releaseModule()

void PhosphorScripting::LuauEngine::releaseModule ( int handle)

Release a module handle from loadModule.

◆ runPrelude()

bool PhosphorScripting::LuauEngine::runPrelude ( const QString & chunkName,
const QByteArray & source,
QString * error = nullptr )

Compile + run a chunk that installs host globals.

Must be called BEFORE sandbox while the global table is still writable.

◆ sandbox()

void PhosphorScripting::LuauEngine::sandbox ( )

Freeze the global table and standard libraries.

Call once, after all preludes and before loading untrusted modules.

Member Data Documentation

◆ DefaultMemoryCapBytes

std::size_t PhosphorScripting::LuauEngine::DefaultMemoryCapBytes = 64ull * 1024 * 1024
staticconstexpr

Default per-engine heap ceiling for untrusted script execution.

Generous headroom over a tiling algorithm's real working set (which is well under 1 MiB beyond the ~1–2 MiB VM + stdlib baseline), while still bounding a runaway allocation long before it can exhaust the host.


The documentation for this class was generated from the following file: