Documentation
¶
Overview ¶
Package wasi_snapshot_preview1 contains Go-defined functions to access system calls, such as opening a file, similar to Go's x/sys package. These are accessible from WebAssembly-defined functions via importing ModuleName. All WASI functions return a single Errno result: ErrnoSuccess on success.
e.g. Call Instantiate before instantiating any wasm binary that imports "wasi_snapshot_preview1", Otherwise, it will error due to missing imports.
ctx := context.Background() r := wazero.NewRuntime(ctx) defer r.Close(ctx) // This closes everything this Runtime created. wasi_snapshot_preview1.MustInstantiate(ctx, r) mod, _ := r.Instantiate(ctx, wasm)
See https://github.com/WebAssembly/WASI
Example ¶
This is an example of how to use WebAssembly System Interface (WASI) with its simplest function: "proc_exit".
See https://github.com/AR1011/wazero/tree/main/examples/wasi for another example.
package main
import (
"context"
_ "embed"
"fmt"
"os"
"github.com/AR1011/wazero"
"github.com/AR1011/wazero/imports/wasi_snapshot_preview1"
"github.com/AR1011/wazero/sys"
)
// exitOnStartWasm was generated by the following:
//
// cd testdata; wat2wasm --debug-names exit_on_start.wat
//
//go:embed testdata/exit_on_start.wasm
var exitOnStartWasm []byte
// This is an example of how to use WebAssembly System Interface (WASI) with its simplest function: "proc_exit".
//
// See https://github.com/AR1011/wazero/tree/main/examples/wasi for another example.
func main() {
// Choose the context to use for function calls.
ctx := context.Background()
// Create a new WebAssembly Runtime.
r := wazero.NewRuntime(ctx)
defer r.Close(ctx)
// Instantiate WASI, which implements system I/O such as console output.
wasi_snapshot_preview1.MustInstantiate(ctx, r)
// InstantiateModule runs the "_start" function which is like a "main" function.
mod, err := r.InstantiateWithConfig(ctx, exitOnStartWasm,
// Override default configuration (which discards stdout).
wazero.NewModuleConfig().WithStdout(os.Stdout).WithName("wasi-demo"))
if mod != nil {
defer r.Close(ctx)
}
// Note: Most compilers do not exit the module after running "_start", unless
// there was an error. This allows you to call exported functions.
if exitErr, ok := err.(*sys.ExitError); ok {
fmt.Printf("exit_code: %d\n", exitErr.ExitCode())
}
}
Output: exit_code: 2
Index ¶
Examples ¶
Constants ¶
const ModuleName = wasip1.InternalModuleName
ModuleName is the module name WASI functions are exported into.
See https://github.com/WebAssembly/WASI/blob/snapshot-01/phases/snapshot/docs.md
Variables ¶
This section is empty.
Functions ¶
func Instantiate ¶
Instantiate instantiates the ModuleName module into the runtime.
Notes ¶
- Failure cases are documented on wazero.Runtime InstantiateModule.
- Closing the wazero.Runtime has the same effect as closing the result.
Types ¶
type Builder ¶
type Builder interface {
// Compile compiles the ModuleName module. Call this before Instantiate.
//
// Note: This has the same effect as the same function on wazero.HostModuleBuilder.
Compile(context.Context) (wazero.CompiledModule, error)
// Instantiate instantiates the ModuleName module and returns a function to close it.
//
// Note: This has the same effect as the same function on wazero.HostModuleBuilder.
Instantiate(context.Context) (api.Closer, error)
}
Builder configures the ModuleName module for later use via Compile or Instantiate.
Notes ¶
- This is an interface for decoupling, not third-party implementations. All implementations are in wazero.
type FunctionExporter ¶
type FunctionExporter interface {
ExportFunctions(wazero.HostModuleBuilder)
}
FunctionExporter exports functions into a wazero.HostModuleBuilder.
Notes ¶
- This is an interface for decoupling, not third-party implementations. All implementations are in wazero.
func NewFunctionExporter ¶
func NewFunctionExporter() FunctionExporter
NewFunctionExporter returns a new FunctionExporter. This is used for the following two use cases:
- Overriding a builtin function with an alternate implementation.
- Exporting functions to the module "wasi_unstable" for legacy code.
Example of overriding default behavior ¶
// Export the default WASI functions.
wasiBuilder := r.NewHostModuleBuilder(ModuleName)
wasi_snapshot_preview1.NewFunctionExporter().ExportFunctions(wasiBuilder)
// Subsequent calls to NewFunctionBuilder override built-in exports.
wasiBuilder.NewFunctionBuilder().
WithFunc(func(ctx context.Context, mod api.Module, exitCode uint32) {
// your custom logic
}).Export("proc_exit")
Example of using the old module name for WASI ¶
// Instantiate the current WASI functions under the wasi_unstable
// instead of wasi_snapshot_preview1.
wasiBuilder := r.NewHostModuleBuilder("wasi_unstable")
wasi_snapshot_preview1.NewFunctionExporter().ExportFunctions(wasiBuilder)
_, err := wasiBuilder.Instantiate(testCtx, r)
Source Files
Directories