...
▽

Package wasi_snapshot_preview1

import "github.com/tetratelabs/wazero/imports/wasi_snapshot_preview1"
Overview
Index
Examples
Subdirectories

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.

Code:

package wasi_snapshot_preview1_test

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 Example() {
    // 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
}

Constants

ModuleName is the module name WASI functions are exported into.

See https://github.com/WebAssembly/WASI/blob/snapshot-01/phases/snapshot/docs.md 

const ModuleName = wasip1.InternalModuleName

func Instantiate 

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

Instantiate instantiates the ModuleName module into the runtime.

Notes

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.

type Builder

Builder configures the ModuleName module for later use via Compile or Instantiate.

Notes

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)
}

func NewBuilder 

func NewBuilder(r wazero.Runtime) Builder

NewBuilder returns a new Builder.

type FunctionExporter

FunctionExporter exports functions into a wazero.HostModuleBuilder.

Notes

type FunctionExporter interface {
    ExportFunctions(wazero.HostModuleBuilder)
}

func NewFunctionExporter 

func NewFunctionExporter() FunctionExporter

NewFunctionExporter returns a new FunctionExporter. This is used for the following two use cases:

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)

Subdirectories

Name Synopsis
..
example