README
¶
Wazero Engine · WebAssembly 脚本引擎
基于 wazero 的零 CGO WebAssembly 运行时引擎
概述
Wazero 引擎使用 tetratelabs/wazero 库，为 Go 应用提供 WebAssembly (WASM) 模块的加载与执行能力。WASM 是二进制格式，因此 LoadString / ExecuteString 的 code 参数是原始 WASM 字节。
引擎特性
| 特性 | 说明 |
|---|---|
| 底层库 | github.com/tetratelabs/wazero v1.9.0 |
| 格式 | WASM 1.0 二进制 |
| 宿主函数 | 通过 host 导入模块暴露宿主函数，WASM 模块可 import "host" |
| 函数调用 | CallFunction 使用 uint64 参数调用导出的 WASM 函数 |
| 线程安全 | 双锁模式（RWMutex + execMutex） |
| 热更新 | 支持 StartWatch / StopWatch |
| 类型常量 | scriptEngine.WazeroType |
安装
go get github.com/tx7do/go-scripts/wazero
快速开始
package main
import (
"context"
"fmt"
"log"
"os"
scriptEngine "github.com/tx7do/go-scripts"
_ "github.com/tx7do/go-scripts/wazero" // 注册 Wazero 引擎
)
func main() {
eng, err := scriptEngine.NewScriptEngine(scriptEngine.WazeroType)
if err != nil {
log.Fatal(err)
}
defer eng.Close()
ctx := context.Background()
eng.Init(ctx)
// 加载 WASM 模块（原始字节）
wasmBytes, _ := os.ReadFile("add.wasm")
_ = eng.LoadString(ctx, "add.wasm", string(wasmBytes))
// 实例化并运行（调用 _start）
eng.Execute(ctx)
// 调用导出的 WASM 函数
result, _ := eng.CallFunction(ctx, "add", uint64(3), uint64(4))
fmt.Println(result) // 7
}
API 参考
| 方法 | 说明 |
|---|---|
Init(ctx) |
创建 wazero 运行时 |
Close() |
关闭运行时及所有已编译模块 |
LoadString(ctx, name, code) |
编译 WASM 字节码并加入队列 |
Execute(ctx) |
实例化最后一个模块并调用 _start |
ExecuteString(ctx, name, code) |
编译并立即实例化 WASM 字节码 |
RegisterFunction(name, fn) |
注册宿主函数到 host 导入模块 |
CallFunction(ctx, name, args...) |
调用导出的 WASM 函数（参数为 uint64） |
RegisterModule(name, module) |
注册命名宿主模块 |
GetGlobal(name) |
读取 WASM 导出的全局变量（返回 uint64） |
StartWatch(ctx, key) |
启动 WASM 模块热更新监听 |
StopWatch(key) |
停止热更新监听 |
注意：
RegisterFunction注册的宿主函数参数必须兼容 WASM 调用约定（context.Context、api.Module或数值类型uint32/uint64/int32/int64/float32/float64）。
测试
cd wazero && go test -v ./...
相关文档
License
Documentation
¶
Overview ¶
Package wazero provides a script engine implementation using the wazero WebAssembly runtime (https://github.com/wazero/wazero). It allows executing WebAssembly (WASM) modules as scripts at runtime.
WebAssembly is a binary format, so the "code" passed to LoadString / ExecuteString / loaded from Source is raw WASM bytes (Go strings can hold arbitrary bytes, so the []byte ↔ string conversion is lossless).
Construction:
eng, _ := wazero.New(ctx) eng.Init(ctx) eng.LoadString(ctx, "add.wasm", string(wasmBytes)) result, _ := eng.Execute(ctx)
After Execute, use CallFunction to invoke exported WASM functions:
result, _ := eng.CallFunction(ctx, "add", uint64(3), uint64(4))
The engine supports hot-reload via StartWatch/StopWatch when the bound Source implements the Watcher interface.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrWazeroEngineNotInitialized is returned when an operation is invoked // before Init or after Close. ErrWazeroEngineNotInitialized = errors.New("wazero engine not initialized") // ErrWazeroEngineAlreadyInitialized is returned when Init is called on an // already-initialized engine. ErrWazeroEngineAlreadyInitialized = errors.New("wazero engine already initialized") // ErrWazeroRuntimeNotInitialized is returned when the underlying wazero // runtime is nil. ErrWazeroRuntimeNotInitialized = errors.New("wazero runtime not initialized") // ErrWazeroCompileFailed is returned when compiling WASM bytes fails. ErrWazeroCompileFailed = errors.New("wazero compile failed") // ErrWazeroInstantiateFailed is returned when instantiating a WASM module fails. ErrWazeroInstantiateFailed = errors.New("wazero instantiate failed") // ErrWazeroNoModuleLoaded is returned when Execute is called but no module // has been compiled yet. ErrWazeroNoModuleLoaded = errors.New("wazero no module loaded") // ErrWazeroFunctionNotFound is returned when CallFunction cannot find the // named exported function in the instantiated module. ErrWazeroFunctionNotFound = errors.New("wazero function not found") // ErrWazeroNotInstantiated is returned when CallFunction / GetGlobal is // called before any module has been instantiated via Execute. ErrWazeroNotInstantiated = errors.New("wazero module not instantiated") )
Sentinel errors returned by the Wazero engine.
Functions ¶
This section is empty.
Types ¶
This section is empty.
Source Files