assemblyscript

Documentation

Overview

Package assemblyscript contains Go-defined special functions imported by AssemblyScript under the module name "env".

Special Functions

AssemblyScript code import the below special functions when not using WASI. Note: Sometimes only "abort" is imported.

• "abort" - exits with 255 with an abort message written to wazero.ModuleConfig WithStderr.
• "trace" - no output unless.
• "seed" - uses wazero.ModuleConfig WithRandSource as the source of seed values.

See https://www.assemblyscript.org/concepts.html#special-imports

Relationship to WASI

AssemblyScript supports compiling JavaScript functions that use I/O, such as `console.log("hello")`. However, WASI is not built-in to AssemblyScript. Use the `wasi-shim` to compile if you get import errors.

See https://github.com/AssemblyScript/wasi-shim#usage and wasi_snapshot_preview1.Instantiate for more.

Example (FunctionExporter)

This shows how to instantiate AssemblyScript's special imports when you also need other functions in the "env" module.

package main

import (
	"context"

	_ "embed"
	"github.com/tetratelabs/wazero"
	"github.com/tetratelabs/wazero/imports/assemblyscript"
)

func main() {
	ctx := context.Background()

	r := wazero.NewRuntime(ctx)
	defer r.Close(ctx) // This closes everything this Runtime created.

	// First construct your own module builder for "env"
	envBuilder := r.NewHostModuleBuilder("env").
		NewFunctionBuilder().
		WithFunc(func() uint32 { return 1 }).
		Export("get_int")

	// Now, add AssemblyScript special function imports into it.
	assemblyscript.NewFunctionExporter().
		WithAbortMessageDisabled().
		ExportFunctions(envBuilder)

}

Example (Instantiate)

This shows how to instantiate AssemblyScript's special imports.

package main

import (
	"context"

	_ "embed"
	"github.com/tetratelabs/wazero"
	"github.com/tetratelabs/wazero/imports/assemblyscript"
)

func main() {
	ctx := context.Background()

	r := wazero.NewRuntime(ctx)
	defer r.Close(ctx) // This closes everything this Runtime created.

	// This adds the "env" module to the runtime, with AssemblyScript's special
	// function imports.
	assemblyscript.MustInstantiate(ctx, r)

}

Index

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

Examples

• Package (FunctionExporter)
• Package (Instantiate)

Functions

func Instantiate

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

Instantiate instantiates the "env" module used by AssemblyScript into the runtime.

Notes

• Failure cases are documented on wazero.Runtime InstantiateModule.
• Closing the wazero.Runtime has the same effect as closing the result.
• To add more functions to the "env" module, use FunctionExporter.

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 "env" is not already instantiated, and don't need to unload it.

Types

type FunctionExporter

type FunctionExporter interface {
	// WithAbortMessageDisabled configures the AssemblyScript abort function to
	// discard any message.
	WithAbortMessageDisabled() FunctionExporter

	// WithTraceToStdout configures the AssemblyScript trace function to output
	// messages to Stdout, as configured by wazero.ModuleConfig WithStdout.
	WithTraceToStdout() FunctionExporter

	// WithTraceToStderr configures the AssemblyScript trace function to output
	// messages to Stderr, as configured by wazero.ModuleConfig WithStderr.
	//
	// Because of the potential volume of trace messages, it is often more
	// appropriate to use WithTraceToStdout instead.
	WithTraceToStderr() FunctionExporter

	// ExportFunctions builds functions to export with a wazero.HostModuleBuilder
	// named "env".
	ExportFunctions(wazero.HostModuleBuilder)
}

FunctionExporter configures the functions in the "env" module used by AssemblyScript.

func NewFunctionExporter

func NewFunctionExporter() FunctionExporter

NewFunctionExporter returns a FunctionExporter object with trace disabled.