Module state 

Global State — port of lstate.c (445 lines, 25 functions) + lstate.h (merged).

Manages per-thread (LuaState) and process-wide (GlobalState) Lua state: creation, initialization, teardown, and coroutine lifecycle helpers.

The lstate.h header is merged into this module per PORTING.md §1.

C source files

• reference/lua-5.4.7/src/lstate.c (445 lines, 25 functions)
• reference/lua-5.4.7/src/lstate.h (408 lines; struct + macro definitions merged)

Structs

CallInfo

Saved state for a Lua or C call frame.

CallInfoExtra

Payload of CallInfo.u2.

CallInfoIdx

Index into the call-info stack.

DynLibId

Opaque handle to a dynamically loaded library, allocated by a DynLibLoadHook backend and stored in package._CLIBS.

ExternalRootKey

Stable key for a value pinned in ExternalRootSet.

ExternalRootSet

Values held alive by external Rust handles.

GcHandle

A short-lived handle returned by state.gc() for GC operations.

GcRef

A GC-managed pointer to a Lua collectable object. Newtype over lua_gc::Gc<T> so callers preserve gc.0-shape access while the backend swaps under them.

GlobalState

Process-wide state shared by all Lua threads.

LuaClosureC

LuaClosureLua

LuaProto

LuaState

Per-thread Lua execution state.

LuaString

LuaTable

A Lua table: hybrid array + hash map.

LuaUserData

OsExecuteResult

Result returned by OsExecuteHook, carrying the three values that C-Lua’s luaL_execresult pushes: (boolean|nil, "exit"|"signal", int).

StackIdx

Index into the Lua value stack. Never a pointer or borrow. Stack reallocates; only indices are stable across mutations.

StackIdxConv

Internal: a thin wrapper used so stubbed methods can accept either StackIdx or u32 (Phase A code mixes both). Phase B will normalise.

StackValue

One slot on the Lua value stack. Wraps a LuaValue and an optional to-be-closed delta (for the tbclist mechanism).

ThreadRegistryEntry

One row of GlobalState::threads. Pairs the per-thread LuaState with the canonical GcRef<LuaThread> so every push_thread for the same id shares pointer-identity. Phase E-1 adds this; Phase E-2 extends it with interior-mutability bookkeeping when resume/yield need to mutate the child thread while the parent holds a borrow.

UpVal

A closure upvalue. Open upvalues point at a slot on a thread’s stack (referred to by index, since the stack reallocates). Closed upvalues own the value.

Enums

CallInfoFrame

Payload of CallInfo.u.

DynamicSymbol

Resolved dynamic-library symbol.

F2Imod

Float-to-integer rounding mode (matches C-Lua’s F2Imod).

GcKind

Garbage collector operating mode.

LuaCallable

LuaClosure

LuaError

The Lua error type. Carries a LuaValue payload because Lua errors can be any value (typically a string).

LuaStatus

Thread / call status codes.

LuaValue

The dynamically-typed Lua value. Replaces C’s TValue.

OsExecuteReason

Reason a shell command terminated, returned by OsExecuteHook.

UpValState

Discriminator state for an upvalue: either still pointing at a thread’s stack slot, or owning the value after close.

Traits

Collectable

Marker trait for GC-managed objects.

LuaClosureExt

LuaClosure accessor — nupvalues() reports the upvalue count uniformly.

LuaLClosureRefExt

LuaProtoExt

LuaProto source bytes accessor.

LuaStringRefExt

LuaTableRefExt

GcRef<LuaTable> / GcRef<LuaUserData> field-access helpers. These methods are needed by api.rs and tagmethods.rs but the lua-types placeholders don’t yet expose them. TODO(phase-b): replace with real accessor methods on the canonical types in lua-types.

LuaTypeExt

Extension methods on lua_types::LuaType.

LuaUserDataRefExt

LuaValueExt

Extension methods on LuaValue. TODO(phase-b): move these to lua_types::value (or wherever the canonical impl lives) once the type helpers stabilise.

StackIdxExt

StackIdx checked-arithmetic helpers. Returns the raw u32 because Phase A callers use the result in arithmetic comparisons against other u32 quantities (stack-distance offsets).

TmIndex

Discriminant-to-index conversion for the two parallel TagMethod enums.

Functions

close

Close the Lua state and free all resources.

close_thread

Close a coroutine thread from the perspective of another thread.

inc_c_stack

Increment the C-call depth counter, checking for overflow.

new_state

Create a new independent Lua state. Returns None only on OOM.

new_thread

Create a new coroutine thread sharing the same GlobalState as the caller.

reset_thread

Reset a thread to its base state, closing all to-be-closed variables.

reset_thread_api

Deprecated wrapper for close_thread(L, NULL).

set_c_stack_limit

Deprecated no-op that returns LUAI_MAXCCALLS.

stack_idx_to_i32

Phase-A code casts StackIdx as i32; provide a From so it compiles. TODO(phase-b): expressions like state.top_idx().0 as i32 should become state.top_idx().raw() as i32. The non-primitive-cast error is silenced here by promoting the StackIdx through a free-function conversion.

Type Aliases

CpuClockHook

Function-pointer signature for retrieving program CPU time in seconds.

DynLibLoadHook

Function-pointer signature for loading a dynamic library, installed on GlobalState::dynlib_load_hook by the embedder.

DynLibSymbolHook

Function-pointer signature for resolving a symbol in a previously loaded dynamic library, installed on GlobalState::dynlib_symbol_hook.

DynLibUnloadHook

Function-pointer signature for unloading a dynamic library, installed on GlobalState::dynlib_unload_hook.

EntropyHook

Function-pointer signature for host entropy used by default PRNG seeds and table-sort pivot randomisation. Hosts without entropy may leave it unset; the stdlib then uses deterministic fallback values instead of touching OS stubs.

EnvHook

Function-pointer signature for reading a host environment variable.

FileLoaderHook

Function-pointer signature for reading a file’s full contents into memory, installed on GlobalState::file_loader_hook by the embedder.

FileOpenHook

Function-pointer signature for opening a file handle, installed on GlobalState::file_open_hook by the embedder.

FileRemoveHook

Function-pointer signature for removing a file, installed on GlobalState::file_remove_hook by the embedder.

FileRenameHook

Function-pointer signature for renaming a file, installed on GlobalState::file_rename_hook by the embedder.

InputHook

Function-pointer signature for reading bytes from a host-provided input stream, installed on GlobalState::stdin_hook by the embedder.

LuaCFnPtr

Opaque registry index into GlobalState.c_functions, where the real lua_CFunction (fn(&mut LuaState) -> Result<usize, LuaError>) is stored. Lua-types can’t reference LuaState without a circular dep, so we keep the closure variant type-erased here and resolve through the registry at call time.

LuaCFunction

A Lua-callable function pointer. C: lua_CFunction.

LuaKFunction

Continuation function for yieldable C calls. C: lua_KFunction.

LuaRustFunction

OsExecuteHook

Function-pointer signature for executing a shell command, installed on GlobalState::os_execute_hook by the embedder.

OutputHook

Function-pointer signature for writing bytes to a host-provided output stream, installed on GlobalState::stdout_hook or GlobalState::stderr_hook by the embedder.

ParserHook

Function-pointer signature for the text-source parser, installed on GlobalState::parser_hook by the embedder.

PopenHook

Function-pointer signature for spawning a child process with a connected pipe, installed on GlobalState::popen_hook by the embedder.

TempNameHook

Function-pointer signature for generating a host temporary filename.

UnixTimeHook

Function-pointer signature for retrieving the current Unix time in seconds.