Documentation

Overview

Package wasmer is a complete and mature WebAssembly runtime for Go based on Wasmer (https://github.com/wasmerio/wasmer).

Features

• Easy to use: The wasmer API mimics the standard WebAssembly API,

• Fast: wasmer executes the WebAssembly modules as fast as possible, close to native speed,

• Safe: All calls to WebAssembly will be fast, but more importantly, complete safe and sandboxed.

Quick Introduction

The wasmer Go package brings the required API to execute WebAssembly modules. In a nutshell, wasmer compiles the WebAssembly module into compiled code, and then executes it. wasmer is designed to work in various environments and platforms: From nano single-board computers to large and powerful servers, including more exotic ones. To address those requirements, Wasmer provides 2 engines and 3 compilers.

Succinctly, an engine is responsible to drive the compilation and the execution of a WebAssembly module. By extension, a headless engine can only execute a WebAssembly module, i.e. a module that has previously been compiled, or compiled, serialized and deserialized. By default, the wasmer package comes with 2 headless engines:

• JIT, the compiled machine code lives in memory,

• Native, the compiled machine code lives in a shared object file (.so, .dylib, or .dll), and is natively executed.

The wasmer Go packages comes with 3 compilers:

• Singlepass: Super fast compilation times, slower execution times. Not prone to JIT-bombs. Ideal for blockchains.

• Cranelift: Fast compilation times, fast execution times. Ideal for development.

• LLVM: Slow compilation times, very fast execution times (close to native). Ideal for production.

WebAssembly C API standard

Wasmer —the runtime— is written in Rust; C and C++ bindings exist. This Go package relies on the so-called wasm_c_api, https://github.com/WebAssembly/wasm-c-api, which is the new standard C API, implemented inside Wasmer as the Wasmer C API, https://wasmerio.github.io/wasmer/crates/wasmer_c_api/. This standard is characterized as a living standard. The API is not yet stable, even though it shows maturity overtime. However, the Wasmer C API provides some extensions, like the wasi_* or wasmer_* types and functions, which aren't yet defined by the standard. The Go package commits to keep a semantic versioning over the API, regardless what happens with the C API.

Examples

The very basic example is the following

// Let's assume we don't have WebAssembly bytes at hand. We
// will write WebAssembly manually.
wasmBytes := []byte(`
	(module
	  (type (func (param i32 i32) (result i32)))
	  (func (type 0)
	    local.get 0
	    local.get 1
	    i32.add)
	  (export "sum" (func 0)))
`)

// Create an Engine
engine := wasmer.NewEngine()

// Create a Store
store := wasmer.NewStore(engine)

// Let's compile the module.
module, err := wasmer.NewModule(store, wasmBytes)

if err != nil {
	fmt.Println("Failed to compile module:", err)
}

// Create an empty import object.
importObject := wasmer.NewImportObject()

// Let's instantiate the WebAssembly module.
instance, err := wasmer.NewInstance(module, importObject)

if err != nil {
	panic(fmt.Sprintln("Failed to instantiate the module:", err))
}

// Now let's execute the `sum` function.
sum, err := instance.Exports.GetFunction("sum")

if err != nil {
	panic(fmt.Sprintln("Failed to get the `add_one` function:", err))
}

result, err := sum(1, 2)

if err != nil {
	panic(fmt.Sprintln("Failed to call the `add_one` function:", err))
}

fmt.Println("Results of `sum`:", result)

// Output:
// Results of `sum`: 3

That's it. Now explore the API! Some pointers for the adventurers:

• The basic elements are Module and Instance,

• Exports of an instance are represented by the Exports type,

• Maybe your module needs to import Function, Memory, Global or Table? Well, there is the ImportObject for that!

Index

Constants

View Source
const (
	// Represents the Cranelift compiler.
	CRANELIFT = CompilerKind(C.CRANELIFT)

	// Represents the LLVM compiler.
	LLVM = CompilerKind(C.LLVM)

	// Represents the Singlepass compiler.
	SINGLEPASS = CompilerKind(C.SINGLEPASS)
)
View Source
const (
	// Represents the JIT engine.
	JIT = EngineKind(C.JIT)

	// Represents the Native engine.
	NATIVE = EngineKind(C.NATIVE)
)
View Source
const (
	// Represents an extern of kind function.
	FUNCTION = ExternKind(C.WASM_EXTERN_FUNC)

	// Represents an extern of kind global.
	GLOBAL = ExternKind(C.WASM_EXTERN_GLOBAL)

	// Represents an extern of kind table.
	TABLE = ExternKind(C.WASM_EXTERN_TABLE)

	// Represents an extern of kind memory.
	MEMORY = ExternKind(C.WASM_EXTERN_MEMORY)
)
View Source
const (
	// Represents a global that is immutable.
	IMMUTABLE = GlobalMutability(C.WASM_CONST)

	// Represents a global that is mutable.
	MUTABLE = GlobalMutability(C.WASM_VAR)
)
View Source
const (
	// A 32-bit integer. In WebAssembly, integers are
	// sign-agnostic, i.E. this can either be signed or unsigned.
	I32 = ValueKind(C.WASM_I32)

	// A 64-bit integer. In WebAssembly, integers are
	// sign-agnostic, i.E. this can either be signed or unsigned.
	I64 = ValueKind(C.WASM_I64)

	// A 32-bit float.
	F32 = ValueKind(C.WASM_F32)

	// A 64-bit float.
	F64 = ValueKind(C.WASM_F64)

	// An externref value which can hold opaque data to the
	// WebAssembly instance itself.
	AnyRef = ValueKind(C.WASM_ANYREF)

	// A first-class reference to a WebAssembly function.
	FuncRef = ValueKind(C.WASM_FUNCREF)
)
View Source
const (
	// Latest version. It's a “floating” version, i.e. it's an
	// alias to the latest version. Using this version is a way to
	// ensure that modules will run only if they come with the
	// latest WASI version (in case of security issues for
	// instance), by just updating the runtime.
	WASI_VERSION_LATEST = WasiVersion(C.LATEST)

	// Represents the wasi_unstable version.
	WASI_VERSION_SNAPSHOT0 = WasiVersion(C.SNAPSHOT0)

	// Represents the wasi_snapshot_preview1 version.
	WASI_VERSION_SNAPSHOT1 = WasiVersion(C.SNAPSHOT1)

	// Represents an invalid version.
	WASI_VERSION_INVALID = WasiVersion(C.INVALID_VERSION)
)
View Source
const WasmMaxPages = uint(0x10000)

Represents the maximum number of pages.

View Source
const WasmMinPages = uint(0x100)

Represents the minimum number of pages.

View Source
const WasmPageSize = uint(0x10000)

Represents a memory page size.

Variables

This section is empty.

Functions

func IsCompilerAvailable

func IsCompilerAvailable(compiler CompilerKind) bool

IsCompilerAvailable checks that the given compiler is available in this current version of `wasmer-go`.

IsCompilerAvailable(CRANELIFT)

func IsEngineAvailable

func IsEngineAvailable(engine EngineKind) bool

IsEngineAvailable checks that the given engine is available in this current version of `wasmer-go`.

IsEngineAvailable(JIT)

func LimitMaxUnbound

func LimitMaxUnbound() uint32

LimitMaxUnbound returns the value used to represent an unbound limit, i.e. when a limit only has a min but not a max. See Limit.

func ValidateModule

func ValidateModule(store *Store, bytes []byte) error

ValidateModule validates a new Module against the given Store.

It takes two arguments, the Store and the WebAssembly module as a byte array. The function returns an error describing why the bytes are invalid, otherwise it returns nil.

wasmBytes := []byte(`...`)
engine := wasmer.NewEngine()
store := wasmer.NewStore(engine)
err := wasmer.ValidateModule(store, wasmBytes)

isValid := err != nil

func Wat2Wasm

func Wat2Wasm(wat string) ([]byte, error)

Wat2Wasm parses a string as either WAT code or a binary Wasm module.

See https://webassembly.github.io/spec/core/text/index.html.

Note: This is not part of the standard Wasm C API. It is Wasmer specific.

wat := "(module)"
wasm, _ := Wat2Wasm(wat)
engine := wasmer.NewEngine()
store := wasmer.NewStore(engine)
module, _ := wasmer.NewModule(store, wasmBytes)

Types

type CompilerKind

type CompilerKind C.wasmer_compiler_t

CompilerKind represents the possible compiler types.

func (CompilerKind) String

func (self CompilerKind) String() string

Strings returns the CompilerKind as a string.

CRANELIFT.String() // "cranelift"
LLVM.String() // "llvm"

type Config

type Config struct {
	// contains filtered or unexported fields
}

Config holds the compiler and the Engine used by the Store.

func NewConfig

func NewConfig() *Config

NewConfig instantiates and returns a new Config.

config := NewConfig()

func (*Config) UseCraneliftCompiler

func (self *Config) UseCraneliftCompiler() *Config

UseCraneliftCompiler sets the compiler to Cranelift in the configuration.

config := NewConfig()
config.UseCraneliftCompiler()

This method might fail if the Cranelift compiler isn't available. Check `IsCompilerAvailable` to learn more.

func (*Config) UseJITEngine

func (self *Config) UseJITEngine() *Config

UseJITEngine sets the engine to JIT in the configuration.

config := NewConfig()
config.UseJITEngine()

This method might fail if the JIT engine isn't available. Check `IsEngineAvailable` to learn more.

func (*Config) UseLLVMCompiler

func (self *Config) UseLLVMCompiler() *Config

UseLLVMCompiler sets the compiler to LLVM in the configuration.

config := NewConfig()
config.UseLLVMCompiler()

This method might fail if the LLVM compiler isn't available. Check `IsCompilerAvailable` to learn more.

func (*Config) UseNativeEngine

func (self *Config) UseNativeEngine() *Config

UseNativeEngine sets the engine to Native in the configuration.

config := NewConfig()
config.UseNativeEngine()

This method might fail if the Native engine isn't available. Check `IsEngineAvailable` to learn more.

func (*Config) UseSinglepassCompiler

func (self *Config) UseSinglepassCompiler() *Config

UseSinglepassCompiler sets the compiler to Singlepass in the configuration.

config := NewConfig()
config.UseSinglepassCompiler()

This method might fail if the Singlepass compiler isn't available. Check `IsCompilerAvailable` to learn more.

func (*Config) UseTarget

func (self *Config) UseTarget(target *Target) *Config

Use a specific target for doing cross-compilation.

triple, _ := NewTriple("aarch64-unknown-linux-gnu")
cpuFeatures := NewCpuFeatures()
target := NewTarget(triple, cpuFeatures)

config := NewConfig()
config.UseTarget(target)

type CpuFeatures

type CpuFeatures struct {
	// contains filtered or unexported fields
}

CpuFeatures holds a set of CPU features. They are identified by their stringified names. The reference is the GCC options:

https://gcc.gnu.org/onlinedocs/gcc/x86-Options.html,

https://gcc.gnu.org/onlinedocs/gcc/ARM-Options.html,

https://gcc.gnu.org/onlinedocs/gcc/AArch64-Options.html.

At the time of writing this documentation (it might be outdated in the future), the supported featurse are the following:

• sse2,

• sse3,

• ssse3,

• sse4.1,

• sse4.2,

• popcnt,

• avx,

• bmi,

• bmi2,

• avx2,

• avx512dq,

• avx512vl,

• lzcnt.

func NewCpuFeatures

func NewCpuFeatures() *CpuFeatures

NewCpuFeatures creates a new CpuFeatures, which is a set of CPU features.

func (*CpuFeatures) Add

func (self *CpuFeatures) Add(feature string) error

Add adds a new CPU feature to the existing set.

type Engine

type Engine struct {
	// contains filtered or unexported fields
}

Engine is used by the Store to drive the compilation and the execution of a WebAssembly module.

func NewEngine

func NewEngine() *Engine

NewEngine instantiates and returns a new Engine with the default configuration.

engine := NewEngine()

func NewEngineWithConfig

func NewEngineWithConfig(config *Config) *Engine

NewEngineWithConfig instantiates and returns a new Engine with the given configuration.

config := NewConfig()
engine := NewEngineWithConfig(config)

func NewJITEngine

func NewJITEngine() *Engine

NewJITEngine instantiates and returns a new JIT engine.

engine := NewJITEngine()

func NewNativeEngine

func NewNativeEngine() *Engine

NewNativeEngine instantiates and returns a new Native engine.

engine := NewNativeEngine()

type EngineKind

type EngineKind C.wasmer_engine_t

EngineKind represents the possible engine types.

func (EngineKind) String

func (self EngineKind) String() string

Strings returns the EngineKind as a string.

JIT.String() // "jit"
NATIVE.String() // "native"

type Error

type Error struct {
	// contains filtered or unexported fields
}

Error represents a Wasmer runtime error.

func (*Error) Error

func (error *Error) Error() string

Error returns the Error's message.

type ExportType

type ExportType struct {
	// contains filtered or unexported fields
}

ExportType is a descriptor for an exported WebAssembly value.

func NewExportType

func NewExportType(name string, ty IntoExternType) *ExportType

NewExportType instantiates a new ExportType with a name and an extern type.

Note: An extern type is anything implementing IntoExternType: FunctionType, GlobalType, MemoryType, TableType.

valueType := NewValueType(I32)
globalType := NewGlobalType(valueType, CONST)
exportType := NewExportType("a_global", globalType)

func (*ExportType) Name

func (self *ExportType) Name() string

Name returns the name of the export type.

exportType := NewExportType("a_global", globalType)
exportType.Name() // "global"

func (*ExportType) Type

func (self *ExportType) Type() *ExternType

Type returns the type of the export type.

exportType := NewExportType("a_global", globalType)
exportType.Type() // ExternType

type Exports

type Exports struct {
	// contains filtered or unexported fields
}

Exports is a special kind of map that allows easily unwrapping the types of instances.

func (*Exports) Get

func (self *Exports) Get(name string) (*Extern, error)

Get retrieves and returns an Extern by its name.

Note: If the name does not refer to an existing export, Get will return an Error.

instance, _ := NewInstance(module, NewImportObject())
extern, error := instance.Exports.Get("an_export")

func (*Exports) GetFunction

func (self *Exports) GetFunction(name string) (NativeFunction, error)

GetFunction retrieves a exported function by its name and returns it as a native Go function.

The difference with GetRawFunction is that Function.Native has been called on the exported function.

Note: If the name does not refer to an existing export, GetFunction will return an Error.

Note: If the export is not a function, GetFunction will return nil as its result.

instance, _ := NewInstance(module, NewImportObject())
exportedFunc, error := instance.Exports.GetFunction("an_exported_function")

if error != nil && exportedFunc != nil {
    exportedFunc()
}

func (*Exports) GetGlobal

func (self *Exports) GetGlobal(name string) (*Global, error)

GetGlobal retrieves and returns a exported Global by its name.

Note: If the name does not refer to an existing export, GetGlobal will return an Error.

Note: If the export is not a global, GetGlobal will return nil as a result.

instance, _ := NewInstance(module, NewImportObject())
exportedGlobal, error := instance.Exports.GetGlobal("an_exported_global")

func (*Exports) GetMemory

func (self *Exports) GetMemory(name string) (*Memory, error)

GetMemory retrieves and returns a exported Memory by its name.

Note: If the name does not refer to an existing export, GetMemory will return an Error.

Note: If the export is not a memory, GetMemory will return nil as a result.

instance, _ := NewInstance(module, NewImportObject())
exportedMemory, error := instance.Exports.GetMemory("an_exported_memory")

func (*Exports) GetRawFunction

func (self *Exports) GetRawFunction(name string) (*Function, error)

GetRawFunction retrieves and returns an exported Function by its name.

Note: If the name does not refer to an existing export, GetRawFunction will return an Error.

Note: If the export is not a function, GetRawFunction will return nil as its result.

instance, _ := NewInstance(module, NewImportObject())
exportedFunc, error := instance.Exports.GetRawFunction("an_exported_function")

if error != nil && exportedFunc != nil {
    exportedFunc.Call()
}

func (*Exports) GetTable

func (self *Exports) GetTable(name string) (*Table, error)

GetTable retrieves and returns a exported Table by its name.

Note: If the name does not refer to an existing export, GetTable will return an Error.

Note: If the export is not a table, GetTable will return nil as a result.

instance, _ := NewInstance(module, NewImportObject())
exportedTable, error := instance.Exports.GetTable("an_exported_table")

func (*Exports) GetWasiStartFunction

func (self *Exports) GetWasiStartFunction() (NativeFunction, error)

GetWasiStartFunction is similar to GetFunction("_start"). It saves you the cost of knowing the name of the WASI start function.

type Extern

type Extern struct {
	// contains filtered or unexported fields
}

Extern is the runtime representation of an entity that can be imported or exported.

func (*Extern) IntoExtern

func (self *Extern) IntoExtern() *Extern

func (*Extern) IntoFunction

func (self *Extern) IntoFunction() *Function

IntoFunction converts the Extern into a Function.

Note:️ If the Extern is not a Function, IntoFunction will return nil as its result.

function, _ := instance.Exports.GetFunction("exported_function")
extern = function.IntoExtern()
_ := extern.IntoFunction()

func (*Extern) IntoGlobal

func (self *Extern) IntoGlobal() *Global

IntoGlobal converts the Extern into a Global.

Note:️ If the Extern is not a Global, IntoGlobal will return nil as its result.

global, _ := instance.Exports.GetGlobal("exported_global")
extern = global.IntoExtern()
_ := extern.IntoGlobal()

func (*Extern) IntoMemory

func (self *Extern) IntoMemory() *Memory

IntoMemory converts the Extern into a Memory.

Note:️ If the Extern is not a Memory, IntoMemory will return nil as its result.

memory, _ := instance.Exports.GetMemory("exported_memory")
extern = memory.IntoExtern()
_ := extern.IntoMemory()

func (*Extern) IntoTable

func (self *Extern) IntoTable() *Table

IntoTable converts the Extern into a Table.

Note:️ If the Extern is not a Table, IntoTable will return nil as its result.

table, _ := instance.Exports.GetTable("exported_table")
extern = table.IntoExtern()
_ := extern.IntoTable()

func (*Extern) Kind

func (self *Extern) Kind() ExternKind

Kind returns the Extern's ExternKind.

global, _ := instance.Exports.GetGlobal("exported_global")
_ = global.IntoExtern().Kind()

func (*Extern) Type

func (self *Extern) Type() *ExternType

Type returns the Extern's ExternType.

global, _ := instance.Exports.GetGlobal("exported_global")
_ = global.IntoExtern().Type()

type ExternKind

type ExternKind C.wasm_externkind_t

Represents the kind of an Extern.

func (ExternKind) String

func (self ExternKind) String() string

String returns the ExternKind as a string.

FUNCTION.String() // "func"
GLOBAL.String()   // "global"
TABLE.String()    // "table"
MEMORY.String()   // "memory"

type ExternType

type ExternType struct {
	// contains filtered or unexported fields
}

ExternType classifies imports and external values with their respective types.

See also

Specification: https://webassembly.github.io/spec/core/syntax/types.html#external-types

func (*ExternType) IntoFunctionType

func (self *ExternType) IntoFunctionType() *FunctionType

IntoFunctionType converts the ExternType into a FunctionType.

Note:️ If the ExternType is not a FunctionType, IntoFunctionType will return nil as its result.

function, _ := instance.Exports.GetFunction("exported_function")
externType = function.IntoExtern().Type()
_ := externType.IntoFunctionType()

func (*ExternType) IntoGlobalType

func (self *ExternType) IntoGlobalType() *GlobalType

IntoGlobalType converts the ExternType into a GlobalType.

Note:️ If the ExternType is not a GlobalType, IntoGlobalType will return nil as its result.

global, _ := instance.Exports.GetGlobal("exported_global")
externType = global.IntoExtern().Type()
_ := externType.IntoGlobalType()

func (*ExternType) IntoMemoryType

func (self *ExternType) IntoMemoryType() *MemoryType

IntoMemoryType converts the ExternType into a MemoryType.

Note:️ If the ExternType is not a MemoryType, IntoMemoryType will return nil as its result.

memory, _ := instance.Exports.GetMemory("exported_memory")
externType = memory.IntoExtern().Type()
_ := externType.IntoMemoryType()

func (*ExternType) IntoTableType

func (self *ExternType) IntoTableType() *TableType

IntoTableType converts the ExternType into a TableType.

Note:️ If the ExternType is not a TableType, IntoTableType will return nil as its result.

table, _ := instance.Exports.GetTable("exported_table")
externType = table.IntoExtern().Type()
_ := externType.IntoTableType()

func (*ExternType) Kind

func (self *ExternType) Kind() ExternKind

Kind returns the ExternType's ExternKind

global, _ := instance.Exports.GetGlobal("exported_global")
extern = global.IntoExtern()
_ = extern.Kind()

type Frame

type Frame struct {
	// contains filtered or unexported fields
}

Frame represents a frame of a WebAssembly stack trace.

func (*Frame) FunctionIndex

func (self *Frame) FunctionIndex() uint32

FunctionIndex returns the function index in the original WebAssembly module that this frame corresponds to.

func (*Frame) FunctionOffset

func (self *Frame) FunctionOffset() uint

FunctionOffset returns the byte offset from the beginning of the function in the original WebAssembly file to the instruction this frame points to.

func (*Frame) Instance

func (self *Frame) Instance()

func (*Frame) ModuleOffset

func (self *Frame) ModuleOffset() uint

ModuleOffset returns the byte offset from the beginning of the original WebAssembly file to the instruction this frame points to.

type Function

type Function struct {
	// contains filtered or unexported fields
}

Function is a WebAssembly function instance.

func NewFunction

func NewFunction(store *Store, ty *FunctionType, function func([]Value) ([]Value, error)) *Function

NewFunction instantiates a new Function in the given Store.

It takes three arguments, the Store, the FunctionType and the definition for the Function.

The function definition must be a native Go function with a Value array as its single argument. The function must return a Value array or an error.

Note:️ Even if the function does not take any argument (or use any argument) it must receive a Value array as its single argument. At runtime, this array will be empty. The same applies to the result.

hostFunction := wasmer.NewFunction(
	store,
	wasmer.NewFunctionType(
		wasmer.NewValueTypes(), // zero argument
		wasmer.NewValueTypes(wasmer.I32), // one i32 result
	),
	func(args []wasmer.Value) ([]wasmer.Value, error) {
		return []wasmer.Value{wasmer.NewI32(42)}, nil
	},
)

func NewFunctionWithEnvironment

func NewFunctionWithEnvironment(store *Store, ty *FunctionType, userEnvironment interface{}, functionWithEnv func(interface{}, []Value) ([]Value, error)) *Function

NewFunctionWithEnvironment is similar to NewFunction except that the user-defined host function (in Go) accepts an additional first parameter which is an environment. This environment can be anything. It is typed as interface{}.

type MyEnvironment struct {
	foo int32
}

environment := &MyEnvironment {
	foo: 42,
}

hostFunction := wasmer.NewFunction(
	store,
	wasmer.NewFunctionType(
		wasmer.NewValueTypes(), // zero argument
		wasmer.NewValueTypes(wasmer.I32), // one i32 result
	),
	environment,
	func(environment interface{}, args []wasmer.Value) ([]wasmer.Value, error) {
		_ := environment.(*MyEnvironment)

		return []wasmer.Value{wasmer.NewI32(42)}, nil
	},
)

func (*Function) Call

func (self *Function) Call(parameters ...interface{}) (interface{}, error)

Call will call the Function and return its results as native Go values.

function, _ := instance.Exports.GetFunction("exported_function")
_ = function.Call(1, 2, 3)

func (*Function) IntoExtern

func (self *Function) IntoExtern() *Extern

IntoExtern converts the Function into an Extern.

function, _ := instance.Exports.GetFunction("exported_function")
extern := function.IntoExtern()

func (*Function) Native

func (self *Function) Native() NativeFunction

Native will turn the Function into a native Go function that can be then called.

function, _ := instance.Exports.GetFunction("exported_function")
nativeFunction = function.Native()
_ = nativeFunction(1, 2, 3)

func (*Function) ParameterArity

func (self *Function) ParameterArity() uint

ParameterArity returns the number of arguments the Function expects as per its definition.

function, _ := instance.Exports.GetFunction("exported_function")
arity := function.ParameterArity()

func (*Function) ResultArity

func (self *Function) ResultArity() uint

ParameterArity returns the number of results the Function will return.

function, _ := instance.Exports.GetFunction("exported_function")
arity := function.ResultArity()

func (*Function) Type

func (self *Function) Type() *FunctionType

Type returns the Function's FunctionType.

function, _ := instance.Exports.GetFunction("exported_function")
ty := function.Type()

type FunctionType

type FunctionType struct {
	// contains filtered or unexported fields
}

FunctionType classifies the signature of functions, mapping a vector of parameters to a vector of results. They are also used to classify the inputs and outputs of instructions.

See also

Specification: https://webassembly.github.io/spec/core/syntax/types.html#function-types

func NewFunctionType

func NewFunctionType(params []*ValueType, results []*ValueType) *FunctionType

NewFunctionType instantiates a new FunctionType from two ValueType arrays: the parameters and the results.

params := wasmer.NewValueTypes()
results := wasmer.NewValueTypes(wasmer.I32)
functionType := wasmer.NewFunctionType(params, results)

func (*FunctionType) IntoExternType

func (self *FunctionType) IntoExternType() *ExternType

IntoExternType converts the FunctionType into an ExternType.

function, _ := instance.Exports.GetFunction("exported_function")
functionType := function.Type()
externType = functionType.IntoExternType()

func (*FunctionType) Params

func (self *FunctionType) Params() []*ValueType

Params returns the parameters definitions from the FunctionType as a ValueType array

params := wasmer.NewValueTypes()
results := wasmer.NewValueTypes(wasmer.I32)
functionType := wasmer.NewFunctionType(params, results)
paramsValueTypes = functionType.Params()

func (*FunctionType) Results

func (self *FunctionType) Results() []*ValueType

Results returns the results definitions from the FunctionType as a ValueType array

params := wasmer.NewValueTypes()
results := wasmer.NewValueTypes(wasmer.I32)
functionType := wasmer.NewFunctionType(params, results)
resultsValueTypes = functionType.Results()

type Global

type Global struct {
	// contains filtered or unexported fields
}

Global stores a single value of the given GlobalType.

See also

https://webassembly.github.io/spec/core/syntax/modules.html#globals

func NewGlobal

func NewGlobal(store *Store, ty *GlobalType, value Value) *Global

NewGlobal instantiates a new Global in the given Store.

It takes three arguments, the Store, the GlobalType and the Value for the Global.

valueType := NewValueType(I32)
globalType := NewGlobalType(valueType, CONST)
global := NewGlobal(store, globalType, NewValue(42, I32))

func (*Global) Get

func (self *Global) Get() (interface{}, error)

Get returns the Global's value as a native Go value.

global, _ := instance.Exports.GetGlobal("exported_global")
value, _ := global.Get()

func (*Global) IntoExtern

func (self *Global) IntoExtern() *Extern

IntoExtern converts the Global into an Extern.

global, _ := instance.Exports.GetGlobal("exported_global")
extern := global.IntoExtern()

func (*Global) Set

func (self *Global) Set(value interface{}, kind ValueKind) error

Set sets the Global's value.

It takes two arguments, the Global's value as a native Go value and the value's ValueKind.

global, _ := instance.Exports.GetGlobal("exported_global")
_ = global.Set(1, I32)

func (*Global) Type

func (self *Global) Type() *GlobalType

Type returns the Global's GlobalType.

global, _ := instance.Exports.GetGlobal("exported_global")
ty := global.Type()

type GlobalMutability

type GlobalMutability C.wasm_mutability_t

func (GlobalMutability) String

func (self GlobalMutability) String() string

String returns the GlobalMutability as a string.

IMMUTABLE.String() // "const"
MUTABLE.String()   // "var"

type GlobalType

type GlobalType struct {
	// contains filtered or unexported fields
}

GlobalType classifies global variables, which hold a value and can either be mutable or immutable.

See also

Specification: https://webassembly.github.io/spec/core/syntax/types.html#global-types

func NewGlobalType

func NewGlobalType(valueType *ValueType, mutability GlobalMutability) *GlobalType

NewGlobalType instantiates a new GlobalType from a ValueType and a GlobalMutability

valueType := NewValueType(I32)
globalType := NewGlobalType(valueType, IMMUTABLE)

func (*GlobalType) IntoExternType

func (self *GlobalType) IntoExternType() *ExternType

IntoExternType converts the GlobalType into an ExternType.

valueType := NewValueType(I32)
globalType := NewGlobalType(valueType, IMMUTABLE)
externType = globalType.IntoExternType()

func (*GlobalType) Mutability

func (self *GlobalType) Mutability() GlobalMutability

Mutability returns the GlobalType's GlobalMutability

valueType := NewValueType(I32)
globalType := NewGlobalType(valueType, IMMUTABLE)
globalType.Mutability().String() // "const"

func (*GlobalType) ValueType

func (self *GlobalType) ValueType() *ValueType

ValueType returns the GlobalType's ValueType

valueType := NewValueType(I32)
globalType := NewGlobalType(valueType, IMMUTABLE)
globalType.ValueType().Kind().String() // "i32"

type ImportObject

type ImportObject struct {
	// contains filtered or unexported fields
}

ImportObject contains all of the import data used when instantiating a WebAssembly module.

func NewImportObject

func NewImportObject() *ImportObject

NewImportObject instantiates a new empty ImportObject.

imports := NewImportObject()

func (*ImportObject) ContainsNamespace

func (self *ImportObject) ContainsNamespace(name string) bool

ContainsNamespace returns true if the ImportObject contains the given namespace (or module name)

imports := NewImportObject()
_ = imports.ContainsNamespace("env") // false

func (*ImportObject) Register

func (self *ImportObject) Register(namespaceName string, namespace map[string]IntoExtern)

Register registers a namespace (or module name) in the ImportObject.

It takes two arguments: the namespace name and a map with imports names as key and externs as values.

Note:️ An extern is anything implementing IntoExtern: Function, Global, Memory, Table.

 imports := NewImportObject()
 importObject.Register(
 	"env",
 	map[string]wasmer.IntoExtern{
 		"host_function": hostFunction,
 		"host_global": hostGlobal,
 	},
)

Note:️ The namespace (or module name) may be empty:

imports := NewImportObject()
importObject.Register(
	"",
	map[string]wasmer.IntoExtern{
 		"host_function": hostFunction,
		"host_global": hostGlobal,
	},
)

type ImportType

type ImportType struct {
	// contains filtered or unexported fields
}

ImportType is a descriptor for an imported value into a WebAssembly module.

func NewImportType

func NewImportType(module string, name string, ty IntoExternType) *ImportType

NewImportType instantiates a new ImportType with a module name (or namespace), a name and an extern type.

Note:️ An extern type is anything implementing IntoExternType: FunctionType, GlobalType, MemoryType, TableType.

valueType := NewValueType(I32)
globalType := NewGlobalType(valueType, CONST)
importType := NewImportType("ns", "host_global", globalType)

func (*ImportType) Module

func (self *ImportType) Module() string

Module returns the ImportType's module name (or namespace).

valueType := NewValueType(I32)
globalType := NewGlobalType(valueType, CONST)
importType := NewImportType("ns", "host_global", globalType)
_ = importType.Module()

func (*ImportType) Name

func (self *ImportType) Name() string

Name returns the ImportType's name.

valueType := NewValueType(I32)
globalType := NewGlobalType(valueType, CONST)
importType := NewImportType("ns", "host_global", globalType)
_ = importType.Name()

func (*ImportType) Type

func (self *ImportType) Type() *ExternType

Type returns the ImportType's type as an ExternType.

valueType := NewValueType(I32)
globalType := NewGlobalType(valueType, CONST)
importType := NewImportType("ns", "host_global", globalType)
_ = importType.Type()

type Instance

type Instance struct {
	Exports *Exports
	// contains filtered or unexported fields
}

func NewInstance

func NewInstance(module *Module, imports *ImportObject) (*Instance, error)

NewInstance instantiates a new Instance.

It takes two arguments, the Module and an ImportObject.

Note:️ Instantiating a module may return TrapError if the module's start function traps.

wasmBytes := []byte(`...`)
engine := wasmer.NewEngine()
store := wasmer.NewStore(engine)
module, err := wasmer.NewModule(store, wasmBytes)
importObject := wasmer.NewImportObject()
instance, err := wasmer.NewInstance(module, importObject)

type IntoExtern

type IntoExtern interface {
	IntoExtern() *Extern
}

IntoExtern is an interface implemented by entity that can be imported of exported.

type IntoExternType

type IntoExternType interface {
	IntoExternType() *ExternType
}

type Limits

type Limits struct {
	// contains filtered or unexported fields
}

Limits classify the size range of resizeable storage associated with memory types and table types.

See also

Specification: https://webassembly.github.io/spec/core/syntax/types.html#limits

func NewLimits

func NewLimits(minimum uint32, maximum uint32) (*Limits, error)

NewLimits instantiates a new Limits which describes the Memory used. The minimum and maximum parameters are "number of memory pages".

️Note: Each page is 64 KiB in size.

Note: You cannot Memory.Grow the Memory beyond the maximum defined here.

func (*Limits) Maximum

func (self *Limits) Maximum() uint32

Maximum returns the maximum size of the Memory allocated in "number of pages".

Each page is 64 KiB in size.

Note: You cannot Memory.Grow beyond this defined maximum size.

func (*Limits) Minimum

func (self *Limits) Minimum() uint32

Minimum returns the minimum size of the Memory allocated in "number of pages".

Note:️ Each page is 64 KiB in size.

type Memory

type Memory struct {
	// contains filtered or unexported fields
}

Memory is a vector of raw uninterpreted bytes.

See also

Specification: https://webassembly.github.io/spec/core/syntax/modules.html#memories

func NewMemory

func NewMemory(store *Store, ty *MemoryType) *Memory

NewMemory instantiates a new Memory in the given Store.

It takes two arguments, the Store and the MemoryType for the Memory.

memory := wasmer.NewMemory(
    store,
    wasmer.NewMemoryType(wasmer.NewLimits(1, 4)),
)

func (*Memory) Data

func (self *Memory) Data() []byte

Data returns the Memory's contents as an byte array.

memory, _ := instance.Exports.GetMemory("exported_memory")
data := memory.Data()

func (*Memory) DataSize

func (self *Memory) DataSize() uint

Size returns the Memory's size as a number of bytes.

memory, _ := instance.Exports.GetMemory("exported_memory")
size := memory.DataSize()

func (*Memory) Grow

func (self *Memory) Grow(delta Pages) bool

Grow grows the Memory's size by a given number of Pages (the delta).

memory, _ := instance.Exports.GetMemory("exported_memory")
grown := memory.Grow(2)

func (*Memory) IntoExtern

func (self *Memory) IntoExtern() *Extern

IntoExtern converts the Memory into an Extern.

memory, _ := instance.Exports.GetMemory("exported_memory")
extern := memory.IntoExtern()

func (*Memory) Size

func (self *Memory) Size() Pages

Size returns the Memory's size as Pages.

memory, _ := instance.Exports.GetMemory("exported_memory")
size := memory.Size()

func (*Memory) Type

func (self *Memory) Type() *MemoryType

Type returns the Memory's MemoryType.

memory, _ := instance.Exports.GetMemory("exported_memory")
ty := memory.Type()

type MemoryType

type MemoryType struct {
	// contains filtered or unexported fields
}

MemoryType classifies linear memories and their size range.

See also

Specification: https://webassembly.github.io/spec/core/syntax/types.html#memory-types

func NewMemoryType

func NewMemoryType(limits *Limits) *MemoryType

NewMemoryType instantiates a new MemoryType given some Limits.

limits := NewLimits(1, 4)
memoryType := NewMemoryType(limits)

func (*MemoryType) IntoExternType

func (self *MemoryType) IntoExternType() *ExternType

IntoExternType converts the MemoryType into an ExternType.

limits := NewLimits(1, 4)
memoryType := NewMemoryType(limits)
externType = memoryType.IntoExternType()

func (*MemoryType) Limits

func (self *MemoryType) Limits() *Limits

Limits returns the MemoryType's Limits.

limits := NewLimits(1, 4)
memoryType := NewMemoryType(limits)
_ = memoryType.Limits()

type Module

type Module struct {
	// contains filtered or unexported fields
}

Module contains stateless WebAssembly code that has already been compiled and can be instantiated multiple times.

WebAssembly programs are organized into modules, which are the unit of deployment, loading, and compilation. A module collects definitions for types, functions, tables, memories, and globals. In addition, it can declare imports and exports and provide initialization logic in the form of data and element segments or a start function.

See also

Specification: https://webassembly.github.io/spec/core/syntax/modules.html#modules

func DeserializeModule

func DeserializeModule(store *Store, bytes []byte) (*Module, error)

DeserializeModule deserializes an byte array to a Module.

wasmBytes := []byte(`...`)
engine := wasmer.NewEngine()
store := wasmer.NewStore(engine)
module, _ := wasmer.NewModule(store, wasmBytes)
bytes := module.Serialize()
//...
deserializedModule := wasmer.DeserializeModule(store, bytes)

func NewModule

func NewModule(store *Store, bytes []byte) (*Module, error)

NewModule instantiates a new Module with the given Store.

It takes two arguments, the Store and the Wasm module as a byte array of WAT code.

wasmBytes := []byte(`...`)
engine := wasmer.NewEngine()
store := wasmer.NewStore(engine)
module, err := wasmer.NewModule(store, wasmBytes)

func (*Module) Exports

func (self *Module) Exports() []*ExportType

Exports returns the Module's exports as an ExportType array.

wasmBytes := []byte(`...`)
engine := wasmer.NewEngine()
store := wasmer.NewStore(engine)
module, _ := wasmer.NewModule(store, wasmBytes)
exports := module.Exports()

func (*Module) Imports

func (self *Module) Imports() []*ImportType

Imports returns the Module's imports as an ImportType array.

wasmBytes := []byte(`...`)
engine := wasmer.NewEngine()
store := wasmer.NewStore(engine)
module, _ := wasmer.NewModule(store, wasmBytes)
imports := module.Imports()

func (*Module) Name

func (self *Module) Name() string

Name returns the Module's name.

Note:️ This is not part of the standard Wasm C API. It is Wasmer specific.

wasmBytes := []byte(`(module $moduleName)`)
engine := wasmer.NewEngine()
store := wasmer.NewStore(engine)
module, _ := wasmer.NewModule(store, wasmBytes)
name := module.Name()

func (*Module) Serialize

func (self *Module) Serialize() ([]byte, error)

Serialize serializes the module and returns the Wasm code as an byte array.

wasmBytes := []byte(`...`)
engine := wasmer.NewEngine()
store := wasmer.NewStore(engine)
module, _ := wasmer.NewModule(store, wasmBytes)
bytes := module.Serialize()

type NativeFunction

type NativeFunction = func(...interface{}) (interface{}, error)

NativeFunction is a type alias representing a host function that can be called as any Go function.

type Pages

type Pages C.wasm_memory_pages_t

Units of WebAssembly pages (as specified to be 65,536 bytes).

func (*Pages) ToBytes

func (self *Pages) ToBytes() uint

ToBytes converts a Pages to a native Go uint which is the Pages' size in bytes.

memory, _ := instance.Exports.GetMemory("exported_memory")
size := memory.Size().ToBytes()

func (*Pages) ToUint32

func (self *Pages) ToUint32() uint32

ToUint32 converts a Pages to a native Go uint32 which is the Pages' size.

memory, _ := instance.Exports.GetMemory("exported_memory")
size := memory.Size().ToUint32()

type Store

type Store struct {
	Engine *Engine
	// contains filtered or unexported fields
}

Store represents all global state that can be manipulated by WebAssembly programs. It consists of the runtime representation of all instances of functions, tables, memories, and globals that have been allocated during the life time of the abstract machine.

The Store holds the Engine (that is — amongst many things — used to compile the Wasm bytes into a valid module artifact).

See also

Specification: https://webassembly.github.io/spec/core/exec/runtime.html#store

func NewStore

func NewStore(engine *Engine) *Store

NewStore instantiates a new Store with an Engine.

engine := NewEngine()
store := NewStore(engine)

type Table

type Table struct {
	// contains filtered or unexported fields
}

A table instance is the runtime representation of a table. It holds a vector of function elements and an optional maximum size, if one was specified in the table type at the table’s definition site.

See also

Specification: https://webassembly.github.io/spec/core/exec/runtime.html#table-instances

func (*Table) IntoExtern

func (self *Table) IntoExtern() *Extern

IntoExtern converts the Table into an Extern.

table, _ := instance.Exports.GetTable("exported_table")
extern := table.IntoExtern()

func (*Table) Size

func (self *Table) Size() TableSize

Size returns the Table's size.

table, _ := instance.Exports.GetTable("exported_table")
size := table.Size()

type TableSize

type TableSize C.wasm_table_size_t

TableSize represents the size of a table.

func (*TableSize) ToUint32

func (self *TableSize) ToUint32() uint32

ToUint32 converts a TableSize to a native Go uint32.

table, _ := instance.Exports.GetTable("exported_table")
size := table.Size().ToUint32()

type TableType

type TableType struct {
	// contains filtered or unexported fields
}

TableType classifies tables over elements of element types within a size range.

See also

Specification: https://webassembly.github.io/spec/core/syntax/types.html#table-types

func NewTableType

func NewTableType(valueType *ValueType, limits *Limits) *TableType

NewTableType instantiates a new TableType given a ValueType and some Limits.

valueType := NewValueType(I32)
limits := NewLimits(1, 4)
tableType := NewTableType(valueType, limits)
_ = tableType.IntoExternType()

func (*TableType) IntoExternType

func (self *TableType) IntoExternType() *ExternType

IntoExternType converts the TableType into an ExternType.

valueType := NewValueType(I32)
limits := NewLimits(1, 4)
tableType := NewTableType(valueType, limits)
_ = tableType.IntoExternType()

func (*TableType) Limits

func (self *TableType) Limits() *Limits

Limits returns the TableType's Limits.

valueType := NewValueType(I32)
limits := NewLimits(1, 4)
tableType := NewTableType(valueType, limits)
_ = tableType.Limits()

func (*TableType) ValueType

func (self *TableType) ValueType() *ValueType

ValueType returns the TableType's ValueType.

valueType := NewValueType(I32)
limits := NewLimits(1, 4)
tableType := NewTableType(valueType, limits)
_ = tableType.ValueType()

type Target

type Target struct {
	// contains filtered or unexported fields
}

Target represents a triple + CPU features pairs.

func NewTarget

func NewTarget(triple *Triple, cpuFeatures *CpuFeatures) *Target

NewTarget creates a new target.

triple, err := NewTriple("aarch64-unknown-linux-gnu")
cpuFeatures := NewCpuFeatures()
target := NewTarget(triple, cpuFeatures)

type Trace

type Trace struct {
	// contains filtered or unexported fields
}

Trace represents a WebAssembly trap.

type Trap

type Trap struct {
	// contains filtered or unexported fields
}

Trap stores trace message with backtrace when an error happened.

func NewTrap

func NewTrap(store *Store, message string) *Trap

Creates a new trap with a message.

engine := wasmer.NewEngine()
store := wasmer.NewStore(engine)
trap := NewTrap(store, "oops")

func (*Trap) Message

func (self *Trap) Message() string

Message returns the message attached to the current Trap.

func (*Trap) Origin

func (self *Trap) Origin() *Frame

Origin returns the top frame of WebAssembly stack responsible for this trap.

frame := trap.Origin()

func (*Trap) Trace

func (self *Trap) Trace() *Trace

Trace returns the trace of WebAssembly frames for this trap.

type TrapError

type TrapError struct {
	// contains filtered or unexported fields
}

TrapError represents a trap produced during Wasm execution.

See also

Specification: https://webassembly.github.io/spec/core/intro/overview.html#trap

func (*TrapError) Error

func (self *TrapError) Error() string

Error returns the TrapError's message.

func (*TrapError) Origin

func (self *TrapError) Origin() *Frame

Origin returns the TrapError's origin as a Frame.

func (*TrapError) Trace

func (self *TrapError) Trace() []*Frame

Trace returns the TrapError's trace as a Frame array.

type Triple

type Triple struct {
	// contains filtered or unexported fields
}

Triple; historically such things had three fields, though they have added additional fields over time.

func NewTriple

func NewTriple(triple string) (*Triple, error)

NewTriple creates a new triple, otherwise it returns an error specifying why the provided triple isn't valid.

triple, err := NewTriple("aarch64-unknown-linux-gnu")

func NewTripleFromHost

func NewTripleFromHost() *Triple

NewTripleFromHost creates a new triple from the current host.

type Value

type Value struct {
	// contains filtered or unexported fields
}

Value; WebAssembly computations manipulate values of basic value types:

• Integer (32 or 64 bit width),

• Floating-point (32 or 64 bit width),

• Vectors (128 bits, with 32 or 64 bit lanes).

See Also

Specification: https://webassembly.github.io/spec/core/exec/runtime.html#values

func NewF32

func NewF32(value interface{}) Value

NewF32 instantiates a new F32 Value with the given value.

Note: If a Wasm value cannot be created from the given value, NewF32 will panic.

value := NewF32(4.2)

func NewF64

func NewF64(value interface{}) Value

NewF64 instantiates a new F64 Value with the given value.

Note: If a Wasm value cannot be created from the given value, NewF64 will panic.

value := NewF64(4.2)

func NewI32

func NewI32(value interface{}) Value

NewI32 instantiates a new I32 Value with the given value.

Note: If a Wasm value cannot be created from the given value, NewI32 will panic.

value := NewI32(42)

func NewI64

func NewI64(value interface{}) Value

NewI64 instantiates a new I64 Value with the given value.

Note: If a Wasm value cannot be created from the given value, NewI64 will panic.

value := NewI64(42)

func NewValue

func NewValue(value interface{}, kind ValueKind) Value

NewValue instantiates a new Value with the given value and ValueKind.

Note: If a Wasm value cannot be created from the given value,

value := NewValue(42, I32)

func (*Value) F32

func (self *Value) F32() float32

F32 returns the Value's value as a native Go float32.

Note: It panics if the value is not of type F32.

value := NewF32(4.2)
_ = value.F32()

func (*Value) F64

func (self *Value) F64() float64

F64 returns the Value's value as a native Go float64.

Note: It panics if the value is not of type F64.

value := NewF64(4.2)
_ = value.F64()

func (*Value) I32

func (self *Value) I32() int32

I32 returns the Value's value as a native Go int32.

Note: It panics if the value is not of type I32.

value := NewI32(42)
_ = value.I32()

func (*Value) I64

func (self *Value) I64() int64

I64 returns the Value's value as a native Go int64.

Note: It panics if the value is not of type I64.

value := NewI64(42)
_ = value.I64()

func (*Value) Kind

func (self *Value) Kind() ValueKind

Kind returns the Value's ValueKind.

value := NewF64(4.2)
_ = value.Kind()

func (*Value) Unwrap

func (self *Value) Unwrap() interface{}

Unwrap returns the Value's value as a native Go value.

value := NewF64(4.2)
_ = value.Unwrap()

type ValueKind

type ValueKind C.wasm_valkind_t

ValueKind represents the kind of a value.

func (ValueKind) IsNumber

func (self ValueKind) IsNumber() bool

IsNumber returns true if the ValueKind is a number type.

I32.IsNumber()     // true
I64.IsNumber()     // true
F32.IsNumber()     // true
F64.IsNumber()     // true
AnyRef.IsNumber()  // false
FuncRef.IsNumber() // false

func (ValueKind) IsReference

func (self ValueKind) IsReference() bool

IsReference returns true if the ValueKind is a reference.

I32.IsReference()     // false
I64.IsReference()     // false
F32.IsReference()     // false
F64.IsReference()     // false
AnyRef.IsReference()  // true
FuncRef.IsReference() // true

func (ValueKind) String

func (self ValueKind) String() string

String returns the ValueKind as a string.

I32.String()     // "i32"
I64.String()     // "i64"
F32.String()     // "f32"
F64.String()     // "f64"
AnyRef.String()  // "anyref"
FuncRef.String() // "funcref"

type ValueType

type ValueType struct {
	// contains filtered or unexported fields
}

ValueType classifies the individual values that WebAssembly code can compute with and the values that a variable accepts.

func NewValueType

func NewValueType(kind ValueKind) *ValueType

NewValueType instantiates a new ValueType given a ValueKind.

valueType := NewValueType(I32)

func NewValueTypes

func NewValueTypes(kinds ...ValueKind) []*ValueType

NewValueTypes instantiates a new ValueType array from a list of ValueKind. Not that the list may be empty.

valueTypes := NewValueTypes(I32, I64, F32)

Note:️ NewValueTypes is specifically designed to help you declare function types, e.g. with NewFunctionType:

functionType := NewFunctionType(
	NewValueTypes(), // arguments
	NewValueTypes(I32), // results
)

func (*ValueType) Kind

func (self *ValueType) Kind() ValueKind

Kind returns the ValueType's ValueKind

valueType := NewValueType(I32)
_ = valueType.Kind()

type WasiEnvironment

type WasiEnvironment struct {
	// contains filtered or unexported fields
}

WasiEnvironment represents the environment provided to the WASI imports (see NewFunctionWithEnvironment which is designed for user-defined host function; that's the same idea here but applied to WASI functions and other imports).

func (*WasiEnvironment) GenerateImportObject

func (self *WasiEnvironment) GenerateImportObject(store *Store, module *Module) (*ImportObject, error)

GenerateImportObject generates an import object, that can be extended and passed to NewInstance.

wasiEnv, _ := NewWasiStateBuilder("test-program").
	Argument("--foo").
	Environment("ABC", "DEF").
	Environment("X", "ZY").
	MapDirectory("the_host_current_directory", ".").
	Finalize()

importObject, _ := wasiEnv.GenerateImportObject(store, module)
instance, _ := NewInstance(module, importObject)
start, _ := instance.Exports.GetWasiStartFunction()

start()

func (*WasiEnvironment) ReadStderr

func (self *WasiEnvironment) ReadStderr() []byte

ReadStderr reads the WASI module stderr if captured with WasiStateBuilder.CaptureStderr. See ReadStdout to see an example.

func (*WasiEnvironment) ReadStdout

func (self *WasiEnvironment) ReadStdout() []byte

ReadStdout reads the WASI module stdout if captured with WasiStateBuilder.CaptureStdout

wasiEnv, _ := NewWasiStateBuilder("test-program").
	Argument("--foo").
	Environment("ABC", "DEF").
	Environment("X", "ZY").
	MapDirectory("the_host_current_directory", ".").
	CaptureStdout().
	Finalize()

importObject, _ := wasiEnv.GenerateImportObject(store, module)
instance, _ := NewInstance(module, importObject)
start, _ := instance.Exports.GetWasiStartFunction()

start()

stdout := string(wasiEnv.ReadStdout())

type WasiStateBuilder

type WasiStateBuilder struct {
	// contains filtered or unexported fields
}

WasiStateBuilder is a convenient API for configuring WASI.

func NewWasiStateBuilder

func NewWasiStateBuilder(programName string) *WasiStateBuilder

NewWasiStateBuilder creates a new WASI state builder, starting by configuring the WASI program name.

wasiStateBuilder := NewWasiStateBuilder("test-program")

func (*WasiStateBuilder) Argument

func (self *WasiStateBuilder) Argument(argument string) *WasiStateBuilder

Argument configures a new argument to the WASI module.

wasiStateBuilder := NewWasiStateBuilder("test-program").
	Argument("--foo")

func (*WasiStateBuilder) CaptureStderr

func (self *WasiStateBuilder) CaptureStderr() *WasiStateBuilder

CaptureStderr configures the WASI module to capture its stderr.

func (*WasiStateBuilder) CaptureStdout

func (self *WasiStateBuilder) CaptureStdout() *WasiStateBuilder

CaptureStdout configures the WASI module to capture its stdout.

wasiStateBuilder := NewWasiStateBuilder("test-program").
	Argument("--foo").
	Environment("KEY", "VALUE").
	MapDirectory("the_host_current_directory", ".")
	CaptureStdout()

func (*WasiStateBuilder) Environment

func (self *WasiStateBuilder) Environment(key string, value string) *WasiStateBuilder

Environment configures a new environment variable for the WASI module.

wasiStateBuilder := NewWasiStateBuilder("test-program").
	Argument("--foo").
	Environment("KEY", "VALUE")

func (*WasiStateBuilder) Finalize

func (self *WasiStateBuilder) Finalize() (*WasiEnvironment, error)

Finalize tells the state builder to produce a WasiEnvironment. It consumes the current WasiStateBuilder.

It can return an error if the state builder contains invalid configuration.

wasiEnvironment, err := NewWasiStateBuilder("test-program").
	Argument("--foo").
	Environment("KEY", "VALUE").
	MapDirectory("the_host_current_directory", ".")
	CaptureStdout().
  Finalize()

func (*WasiStateBuilder) InheritStderr

func (self *WasiStateBuilder) InheritStderr() *WasiStateBuilder

InheritStderr configures the WASI module to inherit the stderr from the host.

func (*WasiStateBuilder) InheritStdin

func (self *WasiStateBuilder) InheritStdin() *WasiStateBuilder

InheritStdin configures the WASI module to inherit the stdin from the host.

func (*WasiStateBuilder) InheritStdout

func (self *WasiStateBuilder) InheritStdout() *WasiStateBuilder

InheritStdout configures the WASI module to inherit the stdout from the host.

func (*WasiStateBuilder) MapDirectory

func (self *WasiStateBuilder) MapDirectory(alias string, directory string) *WasiStateBuilder

MapDirectory configures a new directory to pre-open with a different name exposed to the WASI module.

wasiStateBuilder := NewWasiStateBuilder("test-program").
	Argument("--foo").
	Environment("KEY", "VALUE").
	MapDirectory("the_host_current_directory", ".")

func (*WasiStateBuilder) PreopenDirectory

func (self *WasiStateBuilder) PreopenDirectory(preopenDirectory string) *WasiStateBuilder

PreopenDirectory configures a new directory to pre-open.

This opens the given directory at the virtual root /, and allows the WASI module to read and write to the given directory.

wasiStateBuilder := NewWasiStateBuilder("test-program").
	Argument("--foo").
	Environment("KEY", "VALUE").
	PreopenDirectory("bar")

type WasiVersion

type WasiVersion C.wasi_version_t

WasiVersion represents the possible WASI versions.

func GetWasiVersion

func GetWasiVersion(module *Module) WasiVersion

GetWasiVersion returns the WASI version of the given Module if any, WASI_VERSION_INVALID otherwise.

wasiVersion := GetWasiVersion(module)

func (WasiVersion) String

func (self WasiVersion) String() string

String returns the WasiVersion as a string.

WASI_VERSION_SNAPSHOT0.String() //  "wasi_unstable"
WASI_VERSION_SNAPSHOT1.String() // "wasi_snapshot_preview1"

Directories

Path Synopsis
packaged
include
See https://github.com/golang/go/issues/26366.
See https://github.com/golang/go/issues/26366.
lib
See https://github.com/golang/go/issues/26366.
See https://github.com/golang/go/issues/26366.
lib/darwin-amd64
See https://github.com/golang/go/issues/26366.
See https://github.com/golang/go/issues/26366.
lib/linux-aarch64
See https://github.com/golang/go/issues/26366.
See https://github.com/golang/go/issues/26366.
lib/linux-amd64
See https://github.com/golang/go/issues/26366.
See https://github.com/golang/go/issues/26366.