▽

Package gojs

func Instantiate ¶

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

Instantiate detects and instantiates host functions for wasm compiled with `GOOS=js GOARCH=wasm`. `guest` must be a result of `r.CompileModule`.

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 `goModule`, use FunctionExporter.

func MustInstantiate ¶

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

MustInstantiate calls Instantiate or panics on error.

This is a simpler function for those who know host functions are not already instantiated, and don't need to unload them separate from the runtime.

func Run ¶

func Run(ctx context.Context, r wazero.Runtime, compiled wazero.CompiledModule, moduleConfig Config) error

Run instantiates a new module and calls "run" with the given config.

Parameters

• ctx: context to use when instantiating the module and calling "run".
• r: runtime to instantiate both the host and guest (compiled) module in.
• compiled: guest binary compiled with `GOOS=js GOARCH=wasm`
• config: the Config to use including wazero.ModuleConfig or extensions of it.

Example

After compiling your Wasm binary with wazero.Runtime's `CompileModule`, run it like below:

// Instantiate host functions needed by gojs
gojs.MustInstantiate(ctx, r)

// Assign any configuration relevant for your compiled wasm.
config := gojs.NewConfig(wazero.NewConfig())

// Run your wasm, notably handing any ExitError
err = gojs.Run(ctx, r, compiled, config)
if exitErr, ok := err.(*sys.ExitError); ok && exitErr.ExitCode() != 0 {
	log.Panicln(err)
} else if !ok {
	log.Panicln(err)
}

Notes

• Wasm generated by `GOOS=js GOARCH=wasm` is very slow to compile: Use wazero.RuntimeConfig with wazero.CompilationCache when re-running the same binary.
• The guest module is closed after being run.

type Config ¶

Config extends wazero.ModuleConfig with GOOS=js specific extensions. Use NewConfig to create an instance.

type Config interface {
    // WithOSWorkdir sets the initial working directory used to Run Wasm to
    // the value of os.Getwd instead of the default of root "/".
    //
    // Here's an example that overrides this to the current directory:
    //
    //	err = gojs.Run(ctx, r, compiled, gojs.NewConfig(moduleConfig).
    //			WithOSWorkdir())
    //
    // Note: To use this feature requires mounting the real root directory via
    // wazero.FSConfig `WithDirMount`. On windows, this root must be the same drive
    // as the value of os.Getwd. For example, it would be an error to mount `C:\`
    // as the guest path "", while the current directory is inside `D:\`.
    WithOSWorkdir() Config
}

func NewConfig ¶

func NewConfig(moduleConfig wazero.ModuleConfig) Config

NewConfig returns a Config that can be used for configuring module instantiation.

type FunctionExporter ¶

FunctionExporter builds host functions for wasm compiled with `GOOS=js GOARCH=wasm`.

type FunctionExporter interface {
    // ExportFunctions builds functions to an existing host module builder.
    //
    // This should be named "go" or "gojs", depending on the version of Go the
    // guest was compiled with. The module name changed from "go" to "gojs" in
    // Go 1.21.
    ExportFunctions(wazero.HostModuleBuilder)
}

func NewFunctionExporter ¶

func NewFunctionExporter() FunctionExporter

NewFunctionExporter returns a FunctionExporter object.

Subdirectories