experimental

package
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 28, 2023 License: Apache-2.0 Imports: 3 Imported by: 0

Documentation

Overview

Package experimental includes features we aren't yet sure about. These are enabled with context.Context keys.

Note: All features here may be changed or deleted at any time, so use with caution!

Example (CloseNotifier)

This shows how to implement a custom cleanup task on close. 

package main

import (
	"context"

	"github.com/AR1011/wazero/experimental"
)

var ctx context.Context

// This shows how to implement a custom cleanup task on close.
func main() {
	closeCh := make(chan struct{})
	ctx = experimental.WithCloseNotifier(
		ctx,
		experimental.CloseNotifyFunc(func(context.Context, uint32) { close(closeCh) }),
	)

	// ... create module, do some work. Sometime later in another goroutine:

	select {
	case <-closeCh:
		// do some cleanup
	default:
		// do some more work with the module
	}
}

Output:
Example (CustomListenerFactory)

This shows how to make a listener that counts go function calls. 

package main

import (
	"context"
	"fmt"
	"log"
	"sort"

	_ "embed"
	"github.com/AR1011/wazero"
	"github.com/AR1011/wazero/api"
	"github.com/AR1011/wazero/experimental"
	"github.com/AR1011/wazero/imports/wasi_snapshot_preview1"
)

// listenerWasm was generated by the following:
//
//	cd testdata; wat2wasm --debug-names listener.wat
//
//go:embed logging/testdata/listener.wasm
var listenerWasm []byte

// uniqGoFuncs implements both FunctionListenerFactory and FunctionListener
type uniqGoFuncs map[string]struct{}

// callees returns the go functions called.
func (u uniqGoFuncs) callees() []string {
	ret := make([]string, 0, len(u))
	for k := range u {
		ret = append(ret, k)
	}

	sort.Strings(ret)
	return ret
}

// NewFunctionListener implements FunctionListenerFactory.NewFunctionListener
func (u uniqGoFuncs) NewFunctionListener(def api.FunctionDefinition) experimental.FunctionListener {
	if def.GoFunction() == nil {
		return nil
	}
	return u
}

// Before implements FunctionListener.Before
func (u uniqGoFuncs) Before(ctx context.Context, _ api.Module, def api.FunctionDefinition, _ []uint64, _ experimental.StackIterator) {
	u[def.DebugName()] = struct{}{}
}

// After implements FunctionListener.After
func (u uniqGoFuncs) After(context.Context, api.Module, api.FunctionDefinition, []uint64) {}

// Abort implements FunctionListener.Abort
func (u uniqGoFuncs) Abort(context.Context, api.Module, api.FunctionDefinition, error) {}

func main() {
	u := uniqGoFuncs{}

	// Set context to one that has an experimental listener
	ctx := context.WithValue(context.Background(), experimental.FunctionListenerFactoryKey{}, u)

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

	wasi_snapshot_preview1.MustInstantiate(ctx, r)

	mod, err := r.Instantiate(ctx, listenerWasm)
	if err != nil {
		log.Panicln(err)
	}

	for i := 0; i < 5; i++ {
		if _, err = mod.ExportedFunction("rand").Call(ctx, 4); err != nil {
			log.Panicln(err)
		}
	}

	// A Go function was called multiple times, but we should only see it once.
	for _, f := range u.callees() {
		fmt.Println(f)
	}

}

Output:

wasi_snapshot_preview1.fd_write
wasi_snapshot_preview1.random_get
Example (StackIterator) 
package main

import (
	"fmt"

	_ "embed"
	"github.com/AR1011/wazero/api"
	"github.com/AR1011/wazero/experimental"
	"github.com/AR1011/wazero/internal/wasm"
)

func main() {
	it := &fakeStackIterator{}

	for it.Next() {
		fn := it.Function()
		pc := it.ProgramCounter()
		fmt.Println("function:", fn.Definition().DebugName())
		fmt.Println("\tprogram counter:", pc)
		fmt.Println("\tsource offset:", fn.SourceOffsetForPC(pc))
	}

}

type fakeStackIterator struct {
	iteration    int
	def          api.FunctionDefinition
	args         []uint64
	pc           uint64
	sourceOffset uint64
}

func (s *fakeStackIterator) Next() bool {
	switch s.iteration {
	case 0:
		s.def = &mockFunctionDefinition{debugName: "fn0"}
		s.args = []uint64{1, 2, 3}
		s.pc = 5890831
		s.sourceOffset = 1234
	case 1:
		s.def = &mockFunctionDefinition{debugName: "fn1"}
		s.args = []uint64{}
		s.pc = 5899822
		s.sourceOffset = 7286
	case 2:
		s.def = &mockFunctionDefinition{debugName: "fn2"}
		s.args = []uint64{4}
		s.pc = 6820312
		s.sourceOffset = 935891
	case 3:
		return false
	}
	s.iteration++
	return true
}

func (s *fakeStackIterator) Function() experimental.InternalFunction {
	return internalFunction{
		definition:   s.def,
		sourceOffset: s.sourceOffset,
	}
}

func (s *fakeStackIterator) ProgramCounter() experimental.ProgramCounter {
	return experimental.ProgramCounter(s.pc)
}

type internalFunction struct {
	definition   api.FunctionDefinition
	sourceOffset uint64
}

func (f internalFunction) Definition() api.FunctionDefinition {
	return f.definition
}

func (f internalFunction) SourceOffsetForPC(pc experimental.ProgramCounter) uint64 {
	return f.sourceOffset
}

type mockFunctionDefinition struct {
	debugName string
	*wasm.FunctionDefinition
}

func (f *mockFunctionDefinition) DebugName() string {
	return f.debugName
}

func (f *mockFunctionDefinition) ParamTypes() []wasm.ValueType {
	return []wasm.ValueType{}
}

func (f *mockFunctionDefinition) ResultTypes() []wasm.ValueType {
	return []wasm.ValueType{}
}

Output:

function: fn0
	program counter: 5890831
	source offset: 1234
function: fn1
	program counter: 5899822
	source offset: 7286
function: fn2
	program counter: 6820312
	source offset: 935891

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func BenchmarkFunctionListener 

func BenchmarkFunctionListener(n int, module api.Module, stack []StackFrame, listener FunctionListener)

BenchmarkFunctionListener implements a benchmark for function listeners.

The benchmark calls Before and After methods repeatedly using the provided module an stack frames to invoke the methods.

The stack frame is a representation of the call stack that the Before method will be invoked with. The top of the stack is stored at index zero. The stack must contain at least one frame or the benchmark will fail.

func WithCloseNotifier 

func WithCloseNotifier(ctx context.Context, notifier CloseNotifier) context.Context

WithCloseNotifier registers the given CloseNotifier into the given context.Context.

Types

type CloseNotifier 

type CloseNotifier interface {
	// CloseNotify is a notification that occurs *before* an api.Module is
	// closed. `exitCode` is zero on success or in the case there was no exit
	// code.
	//
	// Notes:
	//   - This does not return an error because the module will be closed
	//     unconditionally.
	//   - Do not panic from this function as it doing so could cause resource
	//     leaks.
	//   - While this is only called once per module, if configured for
	//     multiple modules, it will be called for each, e.g. on runtime close.
	CloseNotify(ctx context.Context, exitCode uint32)
}

CloseNotifier is a notification hook, invoked when a module is closed.

Note: This is experimental progress towards #1197, and likely to change. Do not expose this in shared libraries as it can cause version locks.

type CloseNotifyFunc 

type CloseNotifyFunc func(ctx context.Context, exitCode uint32)

CloseNotifyFunc is a convenience for defining inlining a CloseNotifier.

func (CloseNotifyFunc) CloseNotify 

func (f CloseNotifyFunc) CloseNotify(ctx context.Context, exitCode uint32)

CloseNotify implements CloseNotifier.CloseNotify.

type FunctionListener 

type FunctionListener interface {
	// Before is invoked before a function is called.
	//
	// There is always one corresponding call to After or Abort for each call to
	// Before. This guarantee allows the listener to maintain an internal stack
	// to perform correlations between the entry and exit of functions.
	//
	// # Params
	//
	//   - ctx: the context of the caller function which must be the same
	//	   instance or parent of the result.
	//   - mod: the calling module.
	//   - def: the function definition.
	//   - params:  api.ValueType encoded parameters.
	//   - stackIterator: iterator on the call stack. At least one entry is
	//     guaranteed (the called function), whose Args() will be equal to
	//     params. The iterator will be reused between calls to Before.
	//
	// Note: api.Memory is meant for inspection, not modification.
	// mod can be cast to InternalModule to read non-exported globals.
	Before(ctx context.Context, mod api.Module, def api.FunctionDefinition, params []uint64, stackIterator StackIterator)

	// After is invoked after a function is called.
	//
	// # Params
	//
	//   - ctx: the context of the caller function.
	//   - mod: the calling module.
	//   - def: the function definition.
	//   - results: api.ValueType encoded results.
	//
	// # Notes
	//
	//   - api.Memory is meant for inspection, not modification.
	//   - This is not called when a host function panics, or a guest function traps.
	//      See Abort for more details.
	After(ctx context.Context, mod api.Module, def api.FunctionDefinition, results []uint64)

	// Abort is invoked when a function does not return due to a trap or panic.
	//
	// # Params
	//
	//   - ctx: the context of the caller function.
	//   - mod: the calling module.
	//   - def: the function definition.
	//   - err: the error value representing the reason why the function aborted.
	//
	// # Notes
	//
	//   - api.Memory is meant for inspection, not modification.
	Abort(ctx context.Context, mod api.Module, def api.FunctionDefinition, err error)
}

FunctionListener can be registered for any function via FunctionListenerFactory to be notified when the function is called.

type FunctionListenerFactory 

type FunctionListenerFactory interface {
	// NewFunctionListener returns a FunctionListener for a defined function.
	// If nil is returned, no listener will be notified.
	NewFunctionListener(api.FunctionDefinition) FunctionListener
}

FunctionListenerFactory returns FunctionListeners to be notified when a function is called.

func MultiFunctionListenerFactory 

func MultiFunctionListenerFactory(factories ...FunctionListenerFactory) FunctionListenerFactory

MultiFunctionListenerFactory constructs a FunctionListenerFactory which combines the listeners created by each of the factories passed as arguments.

This function is useful when multiple listeners need to be hooked to a module because the propagation mechanism based on installing a listener factory in the context.Context used when instantiating modules allows for a single listener to be installed.

The stack iterator passed to the Before method is reset so that each listener can iterate the call stack independently without impacting the ability of other listeners to do so.

type FunctionListenerFactoryFunc 

type FunctionListenerFactoryFunc func(api.FunctionDefinition) FunctionListener

FunctionListenerFactoryFunc is a function type implementing the FunctionListenerFactory interface, making it possible to use regular functions and methods as factory of function listeners.

func (FunctionListenerFactoryFunc) NewFunctionListener 

func (f FunctionListenerFactoryFunc) NewFunctionListener(def api.FunctionDefinition) FunctionListener

NewFunctionListener satisfies the FunctionListenerFactory interface, calls f.

type FunctionListenerFactoryKey 

type FunctionListenerFactoryKey struct{}

FunctionListenerFactoryKey is a context.Context Value key. Its associated value should be a FunctionListenerFactory.

See https://github.com/AR1011/wazero/issues/451

type FunctionListenerFunc 

type FunctionListenerFunc func(context.Context, api.Module, api.FunctionDefinition, []uint64, StackIterator)

FunctionListenerFunc is a function type implementing the FunctionListener interface, making it possible to use regular functions and methods as listeners of function invocation.

The FunctionListener interface declares two methods (Before and After), but this type invokes its value only when Before is called. It is best suites for cases where the host does not need to perform correlation between the start and end of the function call.

func (FunctionListenerFunc) Abort 

func (f FunctionListenerFunc) Abort(context.Context, api.Module, api.FunctionDefinition, error)

Abort is declared to satisfy the FunctionListener interface, but it does nothing.

func (FunctionListenerFunc) After 

func (f FunctionListenerFunc) After(context.Context, api.Module, api.FunctionDefinition, []uint64)

After is declared to satisfy the FunctionListener interface, but it does nothing.

func (FunctionListenerFunc) Before 

func (f FunctionListenerFunc) Before(ctx context.Context, mod api.Module, def api.FunctionDefinition, params []uint64, stackIterator StackIterator)

Before satisfies the FunctionListener interface, calls f.

type InternalFunction 

type InternalFunction interface {
	// Definition provides introspection into the function's names and
	// signature.
	Definition() api.FunctionDefinition

	// SourceOffsetForPC resolves a program counter into its corresponding
	// offset in the Code section of the module this function belongs to.
	// The source offset is meant to help map the function calls to their
	// location in the original source files. Returns 0 if the offset cannot
	// be calculated.
	SourceOffsetForPC(pc ProgramCounter) uint64
}

InternalFunction exposes some information about a function instance.

type InternalModule 

type InternalModule interface {
	api.Module

	// NumGlobal returns the count of all globals in the module.
	NumGlobal() int

	// Global provides a read-only view for a given global index.
	//
	// The methods panics if i is out of bounds.
	Global(i int) api.Global
}

InternalModule is an api.Module that exposes additional information.

type ProgramCounter 

type ProgramCounter uint64

ProgramCounter is an opaque value representing a specific execution point in a module. It is meant to be used with Function.SourceOffsetForPC and StackIterator.

type StackFrame 

type StackFrame struct {
	Function     api.Function
	Params       []uint64
	Results      []uint64
	PC           uint64
	SourceOffset uint64
}

StackFrame represents a frame on the call stack.

type StackIterator 

type StackIterator interface {
	// Next moves the iterator to the next function in the stack. Returns
	// false if it reached the bottom of the stack.
	Next() bool
	// Function describes the function called by the current frame.
	Function() InternalFunction
	// ProgramCounter returns the program counter associated with the
	// function call.
	ProgramCounter() ProgramCounter
}

StackIterator allows iterating on each function of the call stack, starting from the top. At least one call to Next() is required to start the iteration.

Note: The iterator provides a view of the call stack at the time of iteration. As a result, parameter values may be different than the ones their function was called with.

func NewStackIterator 

func NewStackIterator(stack ...StackFrame) StackIterator

NewStackIterator constructs a stack iterator from a list of stack frames. The top most frame is the last one.

Source Files

View all Source files

Directories

Path Synopsis
Package gojs allows you to run wasm binaries compiled by Go when `GOOS=js GOARCH=wasm`.
 Package gojs allows you to run wasm binaries compiled by Go when `GOOS=js GOARCH=wasm`.
example
example/cat
Package sysfs includes a low-level filesystem interface and utilities needed for WebAssembly host functions (ABI) such as WASI and runtime.GOOS=js.
 Package sysfs includes a low-level filesystem interface and utilities needed for WebAssembly host functions (ABI) such as WASI and runtime.GOOS=js.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.