GopherLua 完全指南在 Go 中嵌入 Lua 5.1 虚拟机与编译器的实战手册【免费下载链接】tempoGrafana Tempo is a high volume, minimal dependency distributed tracing backend.项目地址: https://gitcode.com/GitHub_Trending/tempo1/tempoGopherLua 是一个用纯 Go 编写的 Lua 5.1并支持 Lua 5.2 的goto语句虚拟机与编译器其目标与 Lua 官方一致做一门具备可扩展语义的脚本语言。本文以本仓库 vendor 目录下所携带的 README.rst 为骨架结合源码与依赖声明展开系统讲解其设计思想、数据模型、内存调优、双向调用、协程、Channel 与并发模式等全部核心能力读完你即可在自己的 Go 程序中安全、高效地嵌入 Lua 脚本。GopherLua 在 Grafana Tempo 仓库中作为 vendor 依赖随项目一起分发见 go.mod 中github.com/yuin/gopher-lua v1.1.1 // indirect的间接依赖声明这意味着任何构建 Tempo 的环境都会同时编译该库。本文所述 API 与实现细节均可在仓库 vendor/github.com/yuin/gopher-lua 目录下的源码中得到验证。设计原则面向易用性而非极致性能GopherLua 的设计遵循两条核心原则可扩展语义的脚本语言与 Lua 的目标一致允许宿主程序通过 Go API 轻松嵌入脚本能力。用户友好的 Go API原版 Lua C 实现采用基于栈的 API这种设计能带来性能提升减少内存分配以及具体类型与 interface 之间的转换。但 GopherLua 的 API不是基于栈的——它在易用性与性能之间明确选择了前者。栈仅用于传递参数和接收返回值。性能定位与安装GopherLua 官方对其性能的定位是不算快但也不算太慢not fast but not too slow在微基准测试中其性能与 Python3 基本相当或略好。需要注意这是上游项目自身的陈述具体表现应以实际基准为准。安装方式与普通 Go 依赖一致go get github.com/yuin/gopher-luaGopherLua 支持 Go 1.9 及以上版本。本仓库 vendor 中携带的版本为 v1.1.1见 go.mod可直接查看源码验证 API。快速开始运行脚本引入包并在虚拟机中执行脚本是最基本的用法import ( github.com/yuin/gopher-lua )执行字符串形式的脚本L : lua.NewState() defer L.Close() if err : L.DoString(print(hello)); err ! nil { panic(err) }执行文件形式的脚本L : lua.NewState() defer L.Close() if err : L.DoFile(hello.lua); err ! nil { panic(err) }DoFile的内部流程是加载 Lua 脚本 → 编译为字节码 → 在 LState 中运行字节码下文共享字节码一节会利用这一机制。Lua 语言本身的语法语义可参照 Lua 5.1 参考手册GopherLua 的 Go API 在绝大多数情况下与 Lua API 一一对应唯一的区别是 GopherLua 使用对象LValue而非 Lua 栈索引来操作。数据模型一切皆 LValueGopherLua 程序中所有数据都是LValue。它是在 value.go 中定义的 interface 类型包含两个方法String() stringType() LValueType实现LValue接口的对象如下表所示类型名Go 类型Type() 返回值常量LNilType(常量)LTNilLNilLBool(常量)LTBoolLTrue、LFalseLNumberfloat64LTNumber-LStringstringLTString-LFunctionstruct 指针LTFunction-LUserDatastruct 指针LTUserData-LStatestruct 指针LTThread-LTablestruct 指针LTTable-LChannelchan LValueLTChannel-类型测试的两种方式可以用 Go 的类型断言方式也可以用Type()返回值来判断lv : L.Get(-1) // 获取栈顶的值 if str, ok : lv.(lua.LString); ok { // lv 是 LString fmt.Println(string(str)) } if lv.Type() ! lua.LTString { panic(string required.) }lv : L.Get(-1) // 获取栈顶的值 if tbl, ok : lv.(*lua.LTable); ok { // lv 是 LTable fmt.Println(L.ObjLen(tbl)) }注意LBool、LNumber、LString不是指针类型。nil 与 false 的判断陷阱测试LNilType和LBool时必须使用预定义的常量lv : L.Get(-1) // 获取栈顶的值 if lv lua.LTrue { // 正确 } if bl, ok : lv.(lua.LBool); ok bool(bl) { // 错误 }在 Lua 语义中nil和false都会使条件为假。GopherLua 为此提供了两个辅助函数其实现见 value.golv : L.Get(-1) // 获取栈顶的值 if lua.LVIsFalse(lv) { // lv 是 nil 或 false } if lua.LVAsBool(lv) { // lv 既不是 nil 也不是 false }struct 对象的方法与限制基于 Go struct 的对象LFunction、LUserData、LTable带有一些公开的方法和字段可用于性能优化和调试但存在两个限制Metatable 不生效没有错误处理。调优Callstack 与 Registry 大小一个LState的callstack调用栈大小控制着 Lua 函数在脚本内的最大调用深度Go 函数调用不计入。Registry寄存器为函数调用包括 Lua 函数和 Go 函数以及表达式中的临时变量提供栈式存储其存储需求会随调用栈使用量和代码复杂度增长。Registry 和 Callstack 都可以设置为固定大小或自动伸缩。当进程中实例化大量LState时认真调优这两个选项非常值得。RegistryRegistry 支持在每个LState上分别配置初始大小、最大大小和增长步长。它可以根据需要增长但增长后不会自动缩小L : lua.NewState(lua.Options{ RegistrySize: 1024 * 20, // registry 的初始大小 RegistryMaxSize: 1024 * 80, // registry 可增长到的最大大小。若为 0默认值则不会自动增长 RegistryGrowStep: 32, // 每次空间不足时增长的步长。默认值为 32 }) defer L.Close()Registry 对给定脚本来说太小最终会导致 panic太大则浪费内存当实例化大量LState时可能相当可观。自动增长的 Registry 只会在扩容瞬间带来一点性能开销其余时间不影响性能。CallstackCallstack 有两种模式固定大小性能最高内存开销固定。自动伸缩按需分配和释放 callstack 页保证任意时刻占用最小内存代价是每次分配新的 callframe 页时有一点性能开销。默认情况下LState按每页 8 帧的方式分配和释放 callstack 帧因此分配开销不会发生在每次函数调用上。对大多数使用场景而言自动伸缩 callstack 的性能影响很可能可以忽略。L : lua.NewState(lua.Options{ CallStackSize: 120, // 该 LState 的最大 callstack 大小 MinimizeStackMemory: true, // 默认值为 false。设为 true 时callstack 会按需自动增长和收缩上限为 CallStackSize不设置则 callstack 固定为 CallStackSize }) defer L.Close()选项默认值上面的示例是按 LState 逐一定制。当选项未指定时也可以直接修改包级默认变量lua.RegistrySize、lua.RegistryGrowStep和lua.CallStackSize来调整默认值。仓库 vendor 中的 config.go 给出了这些默认值的真实定义var RegistrySize 256 * 20 // 5120 var RegistryGrowStep 32 var CallStackSize 256此外由*LState#NewThread()创建的子 LState 会继承父 LState 的 callstack 与 registry 大小。其他 NewState 选项Options.SkipOpenLibs bool默认 false默认情况下GopherLua 在创建新 LState 时会打开所有内置库。设为true可跳过该行为之后通过各OpenXXX(L *LState) int函数按需只打开所需的库用法见下文打开内建模块子集。Options.IncludeGoStackTrace bool默认 false默认情况下发生 panic 时 GopherLua 不显示 Go 栈回溯。设为true可获得 Go 栈回溯信息。API 详解Go 与 Lua 双向互操作从 Lua 调用 GoCalling Go from Lua任何注册到 GopherLua 的函数都是lua.LGFunction其类型定义在 value.gotype LGFunction func(*LState) int一个典型示例——注册double函数参数从栈上取结果推回栈返回值为结果数量func Double(L *lua.LState) int { lv : L.ToInt(1) /* 获取参数 */ L.Push(lua.LNumber(lv * 2)) /* 推入结果 */ return 1 /* 结果数量 */ } func main() { L : lua.NewState() defer L.Close() L.SetGlobal(double, L.NewFunction(Double)) /* 原版 lua_setglobal 使用栈…… */ }在 Lua 侧调用print(double(20)) -- 40协程Coroutinesco, _ : L.NewThread() /* 创建新线程 */ fn : L.GetGlobal(coro).(*lua.LFunction) /* 从 Lua 获取函数 */ for { st, err, values : L.Resume(co, fn) if st lua.ResumeError { fmt.Println(yield break(error)) fmt.Println(err.Error()) break } for i, lv : range values { fmt.Printf(%v : %v\n, i, lv) } if st lua.ResumeOK { fmt.Println(yield break(ok)) break } }打开内建模块子集默认打开全部内建库可能带来不必要的权限暴露例如文件访问、系统调用。以下示例演示如何只打开一个子集——比如用于规避带文件访问或系统调用能力的模块func main() { L : lua.NewState(lua.Options{SkipOpenLibs: true}) defer L.Close() for _, pair : range []struct { n string f lua.LGFunction }{ {lua.LoadLibName, lua.OpenPackage}, // 必须是第一个 {lua.BaseLibName, lua.OpenBase}, {lua.TabLibName, lua.OpenTable}, } { if err : L.CallByParam(lua.P{ Fn: L.NewFunction(pair.f), NRet: 0, Protect: true, }, lua.LString(pair.n)); err ! nil { panic(err) } } if err : L.DoFile(main.lua); err ! nil { panic(err) } }注意lua.LoadLibName/lua.OpenPackage必须是第一个打开的库。用 Go 创建模块mymodule.gopackage mymodule import ( github.com/yuin/gopher-lua ) func Loader(L *lua.LState) int { // 将导出函数注册到表 mod : L.SetFuncs(L.NewTable(), exports) // 注册其他内容 L.SetField(mod, name, lua.LString(value)) // 返回模块 L.Push(mod) return 1 } var exports map[string]lua.LGFunction{ myfunc: myfunc, } func myfunc(L *lua.LState) int { return 0 }mymain.gopackage main import ( ./mymodule github.com/yuin/gopher-lua ) func main() { L : lua.NewState() defer L.Close() L.PreloadModule(mymodule, mymodule.Loader) if err : L.DoFile(main.lua); err ! nil { panic(err) } }main.lualocal m require(mymodule) m.myfunc() print(m.name)从 Go 调用 LuaCalling Lua from GoL : lua.NewState() defer L.Close() if err : L.DoFile(double.lua); err ! nil { panic(err) } if err : L.CallByParam(lua.P{ Fn: L.GetGlobal(double), NRet: 1, Protect: true, }, lua.LNumber(10)); err ! nil { panic(err) } ret : L.Get(-1) // 返回值 L.Pop(1) // 移除接收到的值如果Protect为falseGopherLua 将直接 panic 而不是返回error值。用户自定义类型User-Defined Types通过LUserData可以用 Go 定义新类型并扩展 GopherLua。完整示例type Person struct { Name string } const luaPersonTypeName person // 将 person 类型注册到给定的 L。 func registerPersonType(L *lua.LState) { mt : L.NewTypeMetatable(luaPersonTypeName) L.SetGlobal(person, mt) // 静态属性 L.SetField(mt, new, L.NewFunction(newPerson)) // 方法 L.SetField(mt, __index, L.SetFuncs(L.NewTable(), personMethods)) } // 构造函数 func newPerson(L *lua.LState) int { person : Person{L.CheckString(1)} ud : L.NewUserData() ud.Value person L.SetMetatable(ud, L.GetTypeMetatable(luaPersonTypeName)) L.Push(ud) return 1 } // 检查第一个 Lua 参数是否为携带 *Person 的 *LUserData并返回该 *Person。 func checkPerson(L *lua.LState) *Person { ud : L.CheckUserData(1) if v, ok : ud.Value.(*Person); ok { return v } L.ArgError(1, person expected) return nil } var personMethods map[string]lua.LGFunction{ name: personGetSetName, } // Person#Name 的 getter 与 setter func personGetSetName(L *lua.LState) int { p : checkPerson(L) if L.GetTop() 2 { p.Name L.CheckString(2) return 0 } L.Push(lua.LString(p.Name)) return 1 } func main() { L : lua.NewState() defer L.Close() registerPersonType(L) if err : L.DoString( p person.new(Steeve) print(p:name()) -- Steeve p:name(Alice) print(p:name()) -- Alice ); err ! nil { panic(err) } }终止运行中的 LStateGopherLua 支持 Go 的 context 模式。通过L.SetContext(ctx)将 context 绑定到 LState即可在超时或取消时终止脚本执行L : lua.NewState() defer L.Close() ctx, cancel : context.WithTimeout(context.Background(), 1*time.Second) defer cancel() // 将 context 设置到 LState L.SetContext(ctx) err : L.DoString( local clock os.clock function sleep(n) -- seconds local t0 clock() while clock() - t0 n do end end sleep(3) ) // err.Error() 包含 context deadline exceeded与协程配合时取消父 context 会级联取消子 contextL : lua.NewState() defer L.Close() ctx, cancel : context.WithCancel(context.Background()) L.SetContext(ctx) defer cancel() L.DoString( function coro() local i 0 while true do coroutine.yield(i) i i1 end return i end ) co, cocancel : L.NewThread() defer cocancel() fn : L.GetGlobal(coro).(*LFunction) _, err, values : L.Resume(co, fn) // err 为 nil cancel() // 取消父 context _, err, values L.Resume(co, fn) // err 非 nil子 context 已被取消注意使用 context 会带来性能下降。上游 README 给出的对比数据为启用 context 的 fib.lua 基准运行约 7.5 秒而未启用 context 的版本约 5.3 秒。因此对性能敏感、且不需要超时控制的脚本应权衡是否启用 context。共享 Lua 字节码当多个LState需要运行同一个脚本时可以先编译一次字节码并在它们之间共享从而节省内存。由于字节码是只读的、Lua 脚本无法修改它因此共享是安全的// CompileLua 从磁盘读取 lua 文件并编译。 func CompileLua(filePath string) (*lua.FunctionProto, error) { file, err : os.Open(filePath) defer file.Close() if err ! nil { return nil, err } reader : bufio.NewReader(file) chunk, err : parse.Parse(reader, filePath) if err ! nil { return nil, err } proto, err : lua.Compile(chunk, filePath) if err ! nil { return nil, err } return proto, nil } // DoCompiledFile 接收 CompileLua 返回的 FunctionProto 并在 LState 中运行。 // 等价于对原源文件在该 LState 上调用 DoFile。 func DoCompiledFile(L *lua.LState, proto *lua.FunctionProto) error { lfunc : L.NewFunctionFromProto(proto) L.Push(lfunc) return L.PCall(0, lua.MultRet, nil) } // 示例在多个 VM 间共享编译后的字节码。 func Example() { codeToShare : CompileLua(mylua.lua) a : lua.NewState() b : lua.NewState() c : lua.NewState() DoCompiledFile(a, codeToShare) DoCompiledFile(b, codeToShare) DoCompiledFile(c, codeToShare) }Goroutines 与 Channel 并发模型LState不是 goroutine 安全的。官方推荐模式是每个 goroutine 使用一个独立的 LStategoroutine 之间通过 channel 通信。Channel 在 GopherLua 中以channel对象表示channel表提供执行 channel 操作的函数。注意由于内部含非 goroutine 安全对象以下对象不能通过 channel 发送包括从 Go API 发送线程state函数functionuserdata带 metatable 的表生产者-消费者完整示例func receiver(ch, quit chan lua.LValue) { L : lua.NewState() defer L.Close() L.SetGlobal(ch, lua.LChannel(ch)) L.SetGlobal(quit, lua.LChannel(quit)) if err : L.DoString( local exit false while not exit do channel.select( {|-, ch, function(ok, v) if not ok then print(channel closed) exit true else print(received:, v) end end}, {|-, quit, function(ok, v) print(quit) exit true end} ) end ); err ! nil { panic(err) } } func sender(ch, quit chan lua.LValue) { L : lua.NewState() defer L.Close() L.SetGlobal(ch, lua.LChannel(ch)) L.SetGlobal(quit, lua.LChannel(quit)) if err : L.DoString( ch:send(1) ch:send(2) ); err ! nil { panic(err) } ch - lua.LString(3) quit - lua.LTrue } func main() { ch : make(chan lua.LValue) quit : make(chan lua.LValue) go receiver(ch, quit) go sender(ch, quit) time.Sleep(3 * time.Second) }Go APIToChannel、CheckChannel、OptChannel可直接在 Go 侧使用。Lua APIchannel.make([buf:int]) - ch:channel创建缓冲区大小为buf的新 channel。默认buf为 0。channel.select(case:table [, case:table, case:table ...]) - {index:int, recv:any, ok}与 Go 的select语句相同。返回所选 case 的索引若该 case 是接收操作还返回收到的值与一个表示 channel 是否已关闭的布尔值。case是一个 table结构如下接收{|-, ch:channel [, handler:func(ok, data:any)]}发送{-|, ch:channel, data:any [, handler:func(data:any)]}默认{default [, handler:func()]}channel.select示例无 handler 版本local idx, recv, ok channel.select( {|-, ch1}, {|-, ch2} ) if not ok then print(closed) elseif idx 1 then -- 从 ch1 收到 print(recv) elseif idx 2 then -- 从 ch2 收到 print(recv) endchannel.select示例带 handler 版本channel.select( {|-, ch1, function(ok, data) print(ok, data) end}, {-|, ch2, value, function(data) print(data) end}, {default, function() print(default action) end} )其余方法channel:send(data:any)向 channel 发送数据。channel:receive() - ok:bool, data:any从 channel 接收数据。channel:close()关闭 channel。LState 池模式为配合每 goroutine 一个 LState的并发模型官方推荐用类似sync.Pool的机制创建线程级 LStatetype lStatePool struct { m sync.Mutex saved []*lua.LState } func (pl *lStatePool) Get() *lua.LState { pl.m.Lock() defer pl.m.Unlock() n : len(pl.saved) if n 0 { return pl.New() } x : pl.saved[n-1] pl.saved pl.saved[0 : n-1] return x } func (pl *lStatePool) New() *lua.LState { L : lua.NewState() // 在这里初始化 L。 // 加载脚本、设置全局变量、共享 channel 等…… return L } func (pl *lStatePool) Put(L *lua.LState) { pl.m.Lock() defer pl.m.Unlock() pl.saved append(pl.saved, L) } func (pl *lStatePool) Shutdown() { for _, L : range pl.saved { L.Close() } } // 全局 LState 池 var luaPool lStatePool{ saved: make([]*lua.LState, 0, 4), }使用方式func MyWorker() { L : luaPool.Get() defer luaPool.Put(L) /* 你的代码 */ } func main() { defer luaPool.Shutdown() go MyWorker() go MyWorker() /* 等等…… */ }与标准 Lua 的差异Goroutines 扩展GopherLua 支持 channel 操作有独立的channel类型channel表提供相应操作函数。不支持的函数string.dumpos.setlocalelua_Debug.namewhatpackage.loadlibdebug hooks其他杂项差异collectgarbage不接受任何参数且运行的是整个 Go 程序的垃圾回收器。file:setvbuf不支持行缓冲。不支持夏令时Daylight saving time。GopherLua 提供设置环境变量的函数os.setenv(name, value)。支持 Lua 5.2 的goto与::label::语句此时goto是关键字不能用作变量名。独立解释器 gluaLua 自带名为lua的解释器GopherLua 对应的独立解释器叫gluago get github.com/yuin/gopher-lua/cmd/gluaglua的选项与标准lua解释器一致可用作命令行快速验证脚本或作为宿主内嵌的交互/批处理入口。周边库生态GopherLua 社区围绕其 VM 提供了丰富的扩展库覆盖数据映射、正则、HTTP、JSON/YAML、文件系统、加密、SQL、外设访问等场景常见的有gopher-luar简化与 gopher-lua 之间的数据传递。gluamapper将 Lua table 映射到 Go struct。gluaregopher-lua 的正则表达式支持。gluahttpgopher-lua 的 HTTP 请求模块。gopher-jsongopher-lua 的 JSON 编解码器。gluayamlgopher-lua 的 YAML 解析器。glua-lfs部分实现 luafilesystem 模块。gluaurlURL 解析/构造模块。gluahttpscrape简单的 HTML 抓取模块。gluaxmlpathxmlpath 模块。gmoonscriptMoonscript 编译器。gluacrypto原生 Go 实现的 crypto 库。gluasql原生 Go 实现的 SQL 客户端。gluaperiphery外设访问库GPIO、SPI、I2C、MMIO、Linux 串口。glua-asyncasync/await 实现。gopherlua-debugger调试器。gluamahonia编码转换器。在 Tempo 仓库中的存在形式从本仓库的结构看GopherLua 在 Grafana Tempo 中仅作为间接依赖随 vendor 目录分发用于支撑其他间接依赖的编译go.mod 中github.com/yuin/gopher-lua v1.1.1 // indirect。仓库的源码目录中并未发现直接import github.com/yuin/gopher-lua的业务代码也没有.lua脚本文件。因此对于想要深入理解该库本身的读者vendor/github.com/yuin/gopher-lua 目录是一个现成的、与官方版本一致的源码研读对象——本文提到的LValue、LGFunctionvalue.go、Options默认值config.go等核心定义均可直接在该目录中对照阅读。许可证与作者GopherLua 以 MIT 许可证发布作者为 Yusuke Inuzuka。其许可证文本见 vendor/github.com/yuin/gopher-lua/LICENSE。【免费下载链接】tempoGrafana Tempo is a high volume, minimal dependency distributed tracing backend.项目地址: https://gitcode.com/GitHub_Trending/tempo1/tempo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考