Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
LuauEngine.h
Go to the documentation of this file.
1// SPDX-FileCopyrightText: 2026 fuddlesworth
2// SPDX-License-Identifier: LGPL-2.1-or-later
3
4#pragma once
5
6#include "phosphorscripting_export.h"
7
8#include <QByteArray>
9#include <QString>
10#include <QVariant>
11#include <QVariantList>
12
13#include <atomic>
14#include <cstddef>
15#include <memory>
16
17struct lua_State;
18
20
21class LuauWatchdog;
22
39class PHOSPHORSCRIPTING_EXPORT LuauEngine
40{
41public:
42 enum class CallStatus {
43 Ok,
44 TimedOut,
45 Error,
46 };
47
49 {
51 QVariant result;
52 QString message;
53 };
54
59 static constexpr std::size_t DefaultMemoryCapBytes = 64ull * 1024 * 1024;
60
65 explicit LuauEngine(std::shared_ptr<LuauWatchdog> watchdog = nullptr,
68
69 LuauEngine(const LuauEngine&) = delete;
70 LuauEngine& operator=(const LuauEngine&) = delete;
71
74 bool init(QString* error = nullptr);
75
78 bool runPrelude(const QString& chunkName, const QByteArray& source, QString* error = nullptr);
79
82 void sandbox();
83
86 int loadModule(const QString& chunkName, const QByteArray& source, QString* error = nullptr);
87
89 void releaseModule(int handle);
90
93 QVariant moduleField(int moduleHandle, const QString& key) const;
94
96 bool hasFunction(int moduleHandle, const QString& name) const;
97
102 CallOutcome callModule(int moduleHandle, const QString& function, const QVariantList& args, int timeoutMs);
103
104 bool isValid() const noexcept
105 {
106 return m_L != nullptr;
107 }
108
110 std::size_t memoryUsedBytes() const noexcept
111 {
112 return m_memory.used;
113 }
114
116 std::size_t peakMemoryBytes() const noexcept
117 {
118 return m_memory.peak;
119 }
120
122 std::size_t memoryCapBytes() const noexcept
123 {
124 return m_memory.cap;
125 }
126
127private:
128 static void interruptCallback(lua_State* L, int gc);
129
134 static void* allocate(void* ud, void* ptr, std::size_t osize, std::size_t nsize);
135
142 struct MemoryBudget
143 {
144 std::size_t used = 0;
145 std::size_t peak = 0;
146 std::size_t cap = 0;
147 bool enforce = false;
148 };
149
153 CallStatus guardedPcall(int nargs, int nresults, int timeoutMs, QString* message);
154
155 lua_State* m_L = nullptr;
156 std::shared_ptr<LuauWatchdog> m_watchdog;
157 std::shared_ptr<std::atomic<bool>> m_interrupt;
158 MemoryBudget m_memory;
159 bool m_sandboxed = false;
160 // VM-thread-only: written by guardedPcall before arming the watchdog and
161 // read after disarming; the interrupt callback that consumes them also runs
162 // on the VM thread (the watchdog thread only flips the atomic m_interrupt).
163 bool m_timedOut = false;
164 int m_lastTimeoutMs = 0;
165};
166
167} // namespace PhosphorScripting
std::size_t peakMemoryBytes() const noexcept
High-water mark of memoryUsedBytes over the engine's lifetime.
Definition LuauEngine.h:116
bool init(QString *error=nullptr)
Create the VM, open the (restricted) standard libraries, and wire the interrupt callback.
LuauEngine(const LuauEngine &)=delete
static constexpr std::size_t DefaultMemoryCapBytes
Default per-engine heap ceiling for untrusted script execution.
Definition LuauEngine.h:59
bool hasFunction(int moduleHandle, const QString &name) const
Whether the module exposes a callable field named name.
std::size_t memoryCapBytes() const noexcept
The configured heap ceiling (0 = unlimited).
Definition LuauEngine.h:122
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,...
bool isValid() const noexcept
Definition LuauEngine.h:104
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.
bool runPrelude(const QString &chunkName, const QByteArray &source, QString *error=nullptr)
Compile + run a chunk that installs host globals.
CallOutcome callModule(int moduleHandle, const QString &function, const QVariantList &args, int timeoutMs)
Call module[function](args...) under the watchdog, returning a single result.
CallStatus
Definition LuauEngine.h:42
@ Error
Definition LuauEngine.h:45
std::size_t memoryUsedBytes() const noexcept
Live heap bytes currently allocated by the VM (host accounting).
Definition LuauEngine.h:110
void releaseModule(int handle)
Release a module handle from loadModule.
void sandbox()
Freeze the global table and standard libraries.
LuauEngine & operator=(const LuauEngine &)=delete
QVariant moduleField(int moduleHandle, const QString &key) const
Read a (non-function) field from a loaded module as a QVariant.
One supervisor thread that interrupts runaway scripts across many engines.
Definition LuauWatchdog.h:38
Definition LuauEngine.h:19
QVariant result
Set when status == Ok (nil → invalid QVariant).
Definition LuauEngine.h:51
QString message
Set when status != Ok.
Definition LuauEngine.h:52
CallStatus status
Definition LuauEngine.h:50