wasi_snapshot_preview1

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/tetratelabs/wazero/tree/main/examples/wasi for another example.

package main

import (
	"context"
	_ "embed"
	"fmt"
	"os"

	"github.com/tetratelabs/wazero"
	"github.com/tetratelabs/wazero/imports/wasi_snapshot_preview1"
	"github.com/tetratelabs/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/tetratelabs/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

• Constants
• func Instantiate(ctx context.Context, r wazero.Runtime) (api.Closer, error)
• func MustInstantiate(ctx context.Context, r wazero.Runtime)
• type Builder
  • func NewBuilder(r wazero.Runtime) Builder
• type FunctionExporter
  • func NewFunctionExporter() FunctionExporter

Examples

• Package

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

Functions

func Instantiate

func Instantiate(ctx context.Context, r wazero.Runtime) (api.Closer, error)

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.

func MustInstantiate

func MustInstantiate(ctx context.Context, r wazero.Runtime)

MustInstantiate calls Instantiate or panics on error.

This is a simpler function for those who know the module ModuleName is not already instantiated, and don't need to unload it.

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.

func NewBuilder

func NewBuilder(r wazero.Runtime) Builder

NewBuilder returns a new Builder.

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)