scripting::LuaState Class Reference

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

Public Member Functions
auto	lock (size_t index) noexcept -> Lock
	Acquires the interpreter at index for the calling thread.
auto	tryLock (size_t index) noexcept -> Lock
	Non-blocking variant of lock().
auto	assign (uint64_t group, std::optional< size_t > forced=std::nullopt) -> size_t
	Picks the interpreter for a new script runtime.
void	unassign (uint64_t group, size_t index) noexcept
	Gives back what assign() handed out.
auto	loads () const -> std::vector< uint32_t >
	How many runtimes every interpreter hosts, for diagnostics and tests.
auto	poolSize () const noexcept -> size_t
auto	mainState (size_t index) const noexcept -> lua_State *
	The main thread of an interpreter; only the owner may touch it.
void	retire (size_t index, std::move_only_function< void()> destroyer) noexcept
	Runs destroyer while the interpreter index is owned.
auto	contentionCount () const noexcept -> uint64_t
	How many times a thread that owned an interpreter found another one busy; non zero means work was queued.
auto	waitCount () const noexcept -> uint64_t
	How many times a thread had to wait for an interpreter that another thread owned.
auto	runString (std::string_view lua_code) noexcept -> bool
	Runs a chunk on state 0; intended for debug/console use.
auto	runStringOn (size_t index, std::string_view lua_code, std::string *error=nullptr) noexcept -> bool
	Runs a chunk on the given interpreter.
void	refreshTypeMarkers () noexcept
	Re-registers the Node/Asset type-marker globals on every state.

Static Public Member Functions
static auto	create () noexcept -> std::unique_ptr< LuaState >
static auto	get () noexcept -> LuaState &
static auto	exists () noexcept -> bool
static auto	indexOf (lua_State *state) noexcept -> std::optional< size_t >
static auto	ownedByCurrentThread (size_t index) noexcept -> bool
	True when the calling thread currently owns the interpreter.
static auto	ownedByCurrentThread (lua_State *state) noexcept -> bool
static auto	ownsAnyState () noexcept -> bool
	True when the calling thread owns any interpreter.
static auto	lastOwnedIndex () noexcept -> std::optional< size_t >
	The interpreter this thread acquired last, if it owns any.
static auto	newGroup () noexcept -> uint64_t
	Allocates the number of a new script group, never zero.
static void	retireOrLeak (size_t index, std::move_only_function< void()> destroyer) noexcept
	Like retire(), but once the pool is gone the destroyer is leaked instead of run, the interpreters no longer exist.

Static Public Attributes
static constexpr uint32_t	k_group_chunk = 8
	How many runtimes of one script group share an interpreter before the next ones go to another.

Member Function Documentation

assign()

auto scripting::LuaState::assign ( uint64_t group, std::optional< size_t > forced = std::nullopt ) -> size_t

nodiscard

Picks the interpreter for a new script runtime.

The runtimes of one script group (the nodes of a prefab instance) are kept together, so the calls between their scripts are plain calls that nothing else can be running at the same time. No interpreter hosts more than k_group_chunk of one group though: a group with hundreds of scripts is spread over several, or those scripts could only ever tick one after the other. Runtimes without a group, and every new chunk of a group, go to the least loaded interpreter that has room for them

Parameters

forced

Place the runtime there instead, for a thread that owns that interpreter and cannot wait for another

Note

Every call has to be paired with unassign() once the runtime is gone

Here is the caller graph for this function:

lock()

auto scripting::LuaState::lock ( size_t index ) -> Lock

nodiscardnoexcept

Acquires the interpreter at index for the calling thread.

Waits for the interpreter only when the calling thread owns no other one. A thread that already owns an interpreter never waits for a second one

Here is the caller graph for this function:

retire()

void scripting::LuaState::retire ( size_t index, std::move_only_function< void()> destroyer )

noexcept

Runs destroyer while the interpreter index is owned.

Used to release anything that holds a reference inside the interpreter

---

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

• engine/src/toast/scripting/lua_state.hpp
• engine/src/toast/scripting/lua_state.cpp