Documentation
¶
Overview ¶
Package wasm 在进程内运行插件的 WebAssembly 后端(wazero,纯 Go、无 CGO)。
一个插件就是一个 wasip1 reactor 模块。宿主与插件之间只有一条调用约定(ABI), 往返的消息一律是 JSON:
插件导出 lumo_alloc(size) -> ptr 宿主往插件内存里写请求前先让插件分配 插件导出 lumo_call(ptr, len) -> ptr<<32|len 处理一次请求,返回结果所在的位置 宿主导出 lumo.host_call(ptr, len) -> len 插件发起宿主调用,宿主暂存结果、只回长度 宿主导出 lumo.host_result(ptr) 插件分配好缓冲区后把暂存的结果取走
宿主调用拆成两步,是为了不在宿主函数里反过来调插件的导出函数:Go 编出来的 wasm 不保证能重入,两步交接则全程只有一个方向的调用。
插件拿不到文件系统、网络、环境变量与命令行参数;时钟与随机数照常提供(Go 运行时离不开)。 标准输出与标准错误接到宿主日志上。每次调用都有时限,超时即中断并丢弃该实例。
Index ¶
Constants ¶
View Source
const ( // MemoryLimitPages 是每个实例的线性内存上限(64 KiB 一页,共 32 MiB)。 MemoryLimitPages = 512 // MaxInstances 是每个插件同时存在的实例数上限。实例是单线程的,并发请求靠多实例分担。 MaxInstances = 4 // DescribeTimeout 是 describe 调用的时限。 DescribeTimeout = 2 * time.Second )
View Source
const ABIVersion = 1
ABIVersion 是调用约定的版本。插件在 describe 里报出自己编译时的版本,对不上就不加载。
View Source
const HostModule = "lumo"
HostModule 是宿主函数所在的导入模块名。
Variables ¶
View Source
var ErrBusy = errors.New("插件正忙,这次没排上")
ErrBusy 表示时限内等不到空闲实例:插件没坏,只是忙不过来。
View Source
var ErrClosed = errors.New("插件已停止运行")
ErrClosed 表示插件已卸下。
View Source
var ErrTimeout = errors.New("插件调用超时")
ErrTimeout 表示调用超时被中断。
Functions ¶
Types ¶
type Description ¶
type Description struct {
ABI int `json:"abi"`
SDK string `json:"sdk"`
// Handlers 按类别列出插件登记了哪些处理函数,宿主据此核对清单里的声明。
Handlers map[string][]string `json:"handlers"`
}
Description 是插件在 describe 里报出的自我描述。
type Engine ¶
type Engine struct {
// contains filtered or unexported fields
}
Engine 持有一个 wazero 运行时,所有插件共用。
type GuestError ¶
type GuestError struct{ Message string }
GuestError 是插件的处理函数自己返回的错误。插件没有崩,只是这次没做成。
func (*GuestError) Error ¶
func (e *GuestError) Error() string
type Options ¶
type Options struct {
// CacheDir 是编译缓存目录;留空则不落盘,每次启动都重新编译。
CacheDir string
// Host 处理插件发起的宿主调用。
Host HostFunc
Logger *slog.Logger
}
Options 是 Engine 的构造参数。
type Plugin ¶
type Plugin struct {
// contains filtered or unexported fields
}
Plugin 是一个编译好的插件,持有它的实例池。
func (*Plugin) Call ¶
func (p *Plugin) Call(ctx context.Context, req Request, timeout time.Duration) (json.RawMessage, error)
Call 向插件发一次请求,返回它的结果。
Click to show internal directories.
Click to hide internal directories.