lua_state.hpp File Reference

Pool of independent Lua interpreters. More...

#include <atomic>
#include <cstdint>
#include <functional>
#include <memory>
#include <mutex>
#include <optional>
#include <string>
#include <string_view>
#include <toast/export.hpp>
#include <toast/log.hpp>
#include <toast/thread_pool.hpp>
#include <unordered_map>
#include <vector>

Include dependency graph for lua_state.hpp:

Go to the source code of this file.

Classes
class	scripting::LuaState
class	scripting::LuaState::Lock
	Ownership of one interpreter for as long as the object lives. More...
class	scripting::LuaState::NonBlockingScope
	While one exists on a thread, lock() on that thread never waits. More...

Macros
#define	TOAST_LUA_ASSERT_OWNED(state)

Detailed Description

Pool of independent Lua interpreters.

Author

Xein

Date

10 Jul 2026

A Lua interpreter is not thread safe, so every interpreter has exactly one owner thread at a time and only the owner may touch its stack, its registry or any reference that lives inside it

The rules that keep this deadlock free:

• a thread waits for an interpreter only while it owns no other interpreter
• a thread that owns one and finds another one busy gets an empty Lock and must hand the work to ScriptDispatch instead of waiting
• a worker of a tick wave never waits for an interpreter at all, see NonBlockingScope: the scheduler gives every interpreter to one job of the wave, so a busy one means something outside the wave has it
• nothing that runs while an interpreter is owned may wait for another thread (futures, joins)
• Lua values are released through retire(), never from a destructor that may run on a thread that does not own the interpreter

Macro Definition Documentation

TOAST_LUA_ASSERT_OWNED

#define TOAST_LUA_ASSERT_OWNED

(

state

)

Value:

((void)(state))

Check that the calling thread owns the interpreter state belongs to. Debug builds assert it, and the builds that define TOAST_LUA_OWNERSHIP_CHECKS (RelWithDebInfo) abort with a message, since a violation is a corrupted heap waiting to happen and the abort points at where it started