wasman

README

WASMan (WebAssembly Manager)

Another wasm interpreter engine for gophers.

Usage

Executable

Install

go install github.com/c0mm4nd/wasman/cmd/wasman

$ wasman -h
Usage of ./wasman:
  -extern-files string
        external modules files
  -func string
        main func (default "main")
  -main string
        main module (default "module.wasm")
  -max-toll uint
        the maximum toll in simple toll station

Example: numeric.wasm

$ wasman -main numeric.wasm -func fib 20 # calc the fibonacci number
{
  type: i32
  result: 6765
  toll: 315822
}

If we limit the max toll, it will panic when overflow.

$ wasman -main numeric.wasm -max-toll 300000 -func fib 20
panic: toll overflow

goroutine 1 [running]:
main.main()
        /home/ubuntu/Desktop/wasman/cmd/wasman/main.go:85 +0x87d

Go Embedding

Example

Look for examples?

They are in examples folder

TODOs

• add more complex examples

Documentation

Index

• Variables
• type AdvancedFunc
• type Instance
  • func NewInstance(module *Module, externModules map[string]*Module) (*Instance, error)
• type Linker
  • func NewLinker(config config.LinkerConfig) *Linker
  • func NewLinkerWithModuleMap(config config.LinkerConfig, in map[string]*Module) *Linker
  • func (l *Linker) Define(modName string, mod *Module)
  • func (l *Linker) DefineAdvancedFunc(modName, funcName string, funcGenerator AdvancedFunc) error
  • func (l *Linker) DefineFunc(modName, funcName string, f interface{}) error
  • func (l *Linker) DefineGlobal(modName, globalName string, global interface{}) error
  • func (l *Linker) DefineMemory(modName, memName string, mem []byte) error
  • func (l *Linker) DefineTable(modName, tableName string, table []*uint32) error
  • func (l *Linker) Instantiate(mainModule *Module) (*Instance, error)
• type Module
  • func NewModule(config config.ModuleConfig, r io.Reader) (*Module, error)

Variables

var (
	ErrInvalidSign = errors.New("invalid signature")
)

errors on linking modules

Types

type AdvancedFunc

type AdvancedFunc func(ins *Instance) interface{}

AdvancedFunc is a advanced host func comparing to normal go host func Dev will be able to handle the pre/post-call process of the func and manipulate the Instance's fields like memory

e.g. when we wanna add toll after calling the host func f

func ExampleFuncGenerator_addToll() {
	var linker = wasman.NewLinker()
	var f = func() {fmt.Println("wasm")}

	var af = wasman.AdvancedFunc(func(ins *wasman.Instance) interface{} {
		return func() {
			f()
			ins.AddGas(11)
		}
	})
	linker.DefineAdvancedFunc("env", "add_gas", af)
}

e.g. when we wanna manipulate memory

func ExampleFuncGenerator_addToll() {
	var linker = wasman.NewLinker()

	var af = wasman.AdvancedFunc(func(ins *wasman.Instance) interface{} {
		return func(ptr uint32, length uint32) {
			msg := ins.Memory[int(ptr), int(ptr+uint32)]
			fmt.Println(b)
		}
	})

	linker.DefineAdvancedFunc("env", "print_msg", af)
}

type Instance

type Instance = wasm.Instance

Instance is same to wasm.Instance

func NewInstance

func NewInstance(module *Module, externModules map[string]*Module) (*Instance, error)

NewInstance is a wrapper to the wasm.NewInstance

type Linker

type Linker struct {
	config.LinkerConfig

	Modules map[string]*Module // the built-in modules which acts as externs when instantiating coming main module
}

Linker is a helper to instantiate new modules

func NewLinker

func NewLinker(config config.LinkerConfig) *Linker

NewLinker creates a new Linker

func NewLinkerWithModuleMap

func NewLinkerWithModuleMap(config config.LinkerConfig, in map[string]*Module) *Linker

NewLinkerWithModuleMap creates a new Linker with the built-in modules

func (*Linker) Define

func (l *Linker) Define(modName string, mod *Module)

Define put the module on its namespace

func (*Linker) DefineAdvancedFunc

func (l *Linker) DefineAdvancedFunc(modName, funcName string, funcGenerator AdvancedFunc) error

DefineAdvancedFunc will define a AdvancedFunc on linker

func (*Linker) DefineFunc

func (l *Linker) DefineFunc(modName, funcName string, f interface{}) error

DefineFunc puts a simple go style func into Linker's modules. This f should be a simply func which doesnt handle ins's fields.

func (*Linker) DefineGlobal

func (l *Linker) DefineGlobal(modName, globalName string, global interface{}) error

DefineGlobal will defined an external global for the main module

func (*Linker) DefineMemory

func (l *Linker) DefineMemory(modName, memName string, mem []byte) error

DefineMemory will defined an external memory for the main module

func (*Linker) DefineTable

func (l *Linker) DefineTable(modName, tableName string, table []*uint32) error

DefineTable will defined an external table for the main module

func (*Linker) Instantiate

func (l *Linker) Instantiate(mainModule *Module) (*Instance, error)

Instantiate will instantiate a Module into an runnable Instance

type Module

type Module = wasm.Module

Module is same to wasm.Module

func NewModule

func NewModule(config config.ModuleConfig, r io.Reader) (*Module, error)

NewModule is a wrapper to the wasm.NewModule