Documentation
¶
Overview ¶
Package api defines the interface for the Lua VM execution engine.
This package merges the responsibilities of C's lvm.c (execution loop) and ldo.c (call/return/error handling) because they are mutually recursive. In Go, this avoids circular imports while matching the C reality.
All shared types (LuaError, Status, CIST_* flags, CallInfo, LuaState) are defined in state/api. This package only defines VM-specific signatures.
Reference: .analysis/05-vm-execution-loop.md, .analysis/04-call-return-error.md
callerror.go — Function name resolution and type error messages. Mirrors: funcnamefromcode, funcnamefromcall, luaG_callerror, luaG_typeerror from ldebug.c
Call, return, error handling, and stack management for the Lua VM.
This is the Go equivalent of C's ldo.c. It handles: - Error handling via panic/recover (Go's equivalent of setjmp/longjmp) - Stack reallocation and growth - Function call preparation and post-call cleanup - Protected calls (pcall) - Parser integration
Reference: lua-master/ldo.c, .analysis/04-call-return-error.md
VM execution loop — the heart of the Lua interpreter.
This is the Go equivalent of C's lvm.c. The core is execute(), a giant switch on opcodes that runs Lua bytecode.
Reference: lua-master/lvm.c, .analysis/05-vm-execution-loop.md
vmhelpers.go — VM helper functions (arithmetic, comparison, coercion, table access).
Index ¶
- func APIGetTable(L *state.LuaState, t, key object.TValue, ra int)
- func APISetTable(L *state.LuaState, t, key, val object.TValue)
- func Call(L *state.LuaState, funcIdx int, nResults int)
- func CallNoYield(L *state.LuaState, funcIdx int, nResults int)
- func CheckStack(L *state.LuaState, n int)
- func CloseTBC(L *state.LuaState, level int)
- func CloseTBCKeepTop(L *state.LuaState, level int)
- func CloseThread(L *state.LuaState, from *state.LuaState) int
- func Concat(L *state.LuaState, total int)
- func DumpProto(p *object.Proto, strip bool) []byte
- func EqualObj(L *state.LuaState, t1, t2 object.TValue) bool
- func ErrorMsg(L *state.LuaState)
- func FinishGet(L *state.LuaState, t, key object.TValue, ra int)
- func FinishSet(L *state.LuaState, t, key, val object.TValue)
- func FuncNameFromCode(L *state.LuaState, p *object.Proto, pc int) (string, string)
- func GetFuncLine(f *object.Proto, pc int) int
- func GetGlobalTable(L *state.LuaState) *table.Table
- func LessEqual(L *state.LuaState, l, r object.TValue) bool
- func LessThan(L *state.LuaState, l, r object.TValue) bool
- func Load(L *state.LuaState, reader lex.LexReader, source string) int
- func MarkTBC(L *state.LuaState, level int)
- func ObjLen(L *state.LuaState, ra int, rb object.TValue)
- func PCall(L *state.LuaState, funcIdx int, nResults int, errFunc int) int
- func Resume(L *state.LuaState, from *state.LuaState, nArgs int) (int, int)
- func RunError(L *state.LuaState, msg string)
- func ShortSrc(source string) string
- func UndumpProto(L *state.LuaState, data []byte, name string) (*closure.LClosure, error)
- func Yield(L *state.LuaState, nResults int)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func APIGetTable ¶
APIGetTable performs result = t[key] with __index metamethod support. Used by the C API's lua_gettable. Writes result to L.Stack[ra].
func APISetTable ¶
APISetTable performs t[key] = val with __newindex metamethod support. Used by the C API's lua_settable.
func Call ¶
Call performs a function call. For Lua functions, calls execute. Mirrors: luaD_call / ccall in ldo.c
func CallNoYield ¶
CallNoYield performs a non-yieldable function call. Mirrors: luaD_callnoyield in ldo.c
func CheckStack ¶
CheckStack ensures at least n free stack slots, growing if needed.
func CloseTBC ¶
CloseTBC is the exported wrapper for closeTBC. Closes all TBC variables from L.TBCList down to (but not including) level. Uses StatusOK semantics: resets L.Top to level+1 before calling __close. Used by the API layer (lua_settop).
func CloseTBCKeepTop ¶
CloseTBCKeepTop closes TBC variables with CLOSEKTOP semantics: does NOT reset L.Top, preserving values above the closed slot. Used by lua_closeslot where return values sit above TBC vars.
func CloseThread ¶
CloseThread closes all TBC variables in a coroutine and resets it. Mirrors: lua_closethread → luaE_resetthread in lstate.c:315
func DumpProto ¶
DumpProto serializes a Proto to Lua 5.5 binary chunk format. If strip is true, debug information is omitted. Mirrors: luaU_dump in ldump.c
func ErrorMsg ¶
ErrorMsg calls the error handler (if set) then throws a runtime error. Mirrors: luaG_errormsg in ldebug.c The error object must already be on the stack at L.Top-1.
func FuncNameFromCode ¶
funcNameFromCode examines the instruction at pc to determine the function name. Returns (kind, name) or ("", "") if unknown. Mirrors: funcnamefromcode in ldebug.c FuncNameFromCode examines the instruction at pc to determine the function name. Returns (kind, name) or ("", "") if unknown. Mirrors: funcnamefromcode in ldebug.c
func GetFuncLine ¶
GetFuncLine returns the source line corresponding to instruction 'pc' in proto 'f'. Returns -1 if no debug info is available. Mirrors: luaG_getfuncline in ldebug.c
func GetGlobalTable ¶
GetGlobalTable returns the global table from the registry.
func Load ¶
Load compiles Lua source and pushes the resulting closure. Returns StatusOK on success, StatusErrSyntax on parse error.
func MarkTBC ¶
MarkTBC is the exported wrapper for markTBC. Used by the API layer (lua_toclose) to mark a stack slot as to-be-closed.
func RunError ¶
RunError raises a runtime error with a string message. Mirrors: luaG_runerror in ldebug.c — adds source:line: prefix for Lua frames.
func ShortSrc ¶
ShortSrc creates a short source name for error messages. Mirrors: luaO_chunkid in lobject.c
func UndumpProto ¶
UndumpProto deserializes a Lua 5.5 binary chunk into a Proto + LClosure. Returns the LClosure ready to execute. Mirrors: luaU_undump in lundump.c
Types ¶
This section is empty.
Source Files