README
¶
wypes
Go library to define type-safe host functions in wazero and other WebAssembly runtimes.
Features:
- 🛡 Type safe
- 🐎 Fast
- 🔨 Works with any WebAssmebly runtime, like wazero or wasman
- 🧠 Handles for you memory operations
- 👉 Manages external references
- 🧼 Simple and clean API
- 🐜 Can be compiled with TinyGo
- 😎 No reflect, no unsafe, only generics and dedication.
📦 Installation
go get github.com/orsinium-labs/wypes
🔧 Usage
Define a function using provided types:
func addI32(a wypes.Int32, b wypes.Int32) wypes.Int32 {
return a + b
}
Define a mapping of module and function names to function definitions:
modules := wypes.Modules{
"env": {
"add_i32": wypes.H2(addI32),
},
}
Link the modules to the runtime. We provide a convenience method to do this for wazero:
err := modules.DefineWazero(r, nil)
That's it! Now the wasm module can call the env.add_i32 function.
🛹 Tricks
The library provides lots of useful types that you can use in your functions. Make sure to check the docs. A few highlights:
- Context provides access to the context.Context passed into the guest function call in wazero.
- Store provides access to all the state: memory, stack, references.
- Duration and Time to pass time.Duration and time.Time (as UNIX timestamp).
- HostRef can hold a reference to the Refs store of host objects.
- Void is used as the return type for functions that return no value.
See documentation for more.
Documentation
¶
Index ¶
- Variables
- type Addr
- type Bool
- type Byte
- type Bytes
- type Complex128
- type Complex64
- type Context
- type Duration
- type Float32
- type Float64
- type HostFunc
- func H0[Z Lower](fn func() Z) HostFunc
- func H1[A Lift[A], Z Lower](fn func(A) Z) HostFunc
- func H2[A Lift[A], B Lift[B], Z Lower](fn func(A, B) Z) HostFunc
- func H3[A Lift[A], B Lift[B], C Lift[C], Z Lower](fn func(A, B, C) Z) HostFunc
- func H4[A Lift[A], B Lift[B], C Lift[C], D Lift[D], Z Lower](fn func(A, B, C, D) Z) HostFunc
- func H5[A Lift[A], B Lift[B], C Lift[C], D Lift[D], E Lift[E], Z Lower](fn func(A, B, C, D, E) Z) HostFunc
- func H6[A Lift[A], B Lift[B], C Lift[C], D Lift[D], E Lift[E], F Lift[F], Z Lower](fn func(A, B, C, D, E, F) Z) HostFunc
- func H7[A Lift[A], B Lift[B], C Lift[C], D Lift[D], E Lift[E], F Lift[F], G Lift[G], ...](fn func(A, B, C, D, E, F, G) Z) HostFunc
- func H8[A Lift[A], B Lift[B], C Lift[C], D Lift[D], E Lift[E], F Lift[F], G Lift[G], ...](fn func(A, B, C, D, E, F, G, H) Z) HostFunc
- type HostRef
- type Int
- type Int16
- type Int32
- type Int64
- type Int8
- type Lift
- type LiftLower
- type Lower
- type MapRefs
- type Memory
- type Module
- type Modules
- type Pair
- type Raw
- type Refs
- type Rune
- type SliceMemory
- type SliceStack
- type Stack
- type Store
- type String
- type Time
- type UInt
- type UInt16
- type UInt32
- type UInt64
- type UInt8
- type UIntPtr
- type Value
- type ValueType
- type Void
Constants ¶
This section is empty.
Variables ¶
var ( ErrRefNotFound = errors.New("HostRef with the given ID is not found in Refs") ErrMemRead = errors.New("Memory.Read is out of bounds") ErrMemWrite = errors.New("Memory.Write is out of bounds") ErrRefCast = errors.New("Reference returned by Refs.Get is not of the type expected by HostRef") )
Functions ¶
This section is empty.
Types ¶
type Bool ¶
type Bool bool
Bool wraps [bool].
func (Bool) ValueTypes ¶
ValueTypes implements Value interface.
type Bytes ¶
Bytes wraps a slice of bytes.
The bytes are passed through the linear memory. Since the memory is controlled and allocated by the guest module, you have to provide the Offset to be able to Lower the value into the memory. The offset should be obtained from the guest module, either as an explicit function argument or by calling its allocator.
func (Bytes) ValueTypes ¶
ValueTypes implements Value interface.
type Complex128 ¶
type Complex128 complex128
Complex128 wraps [complex128].
func (Complex128) Unwrap ¶
func (v Complex128) Unwrap() complex128
Unwrap returns the wrapped value.
func (Complex128) ValueTypes ¶
func (Complex128) ValueTypes() []ValueType
ValueTypes implements Value interface.
type Complex64 ¶
type Complex64 complex64
Complex64 wraps [complex64].
func (Complex64) ValueTypes ¶
ValueTypes implements Value interface.
type Context ¶
type Context struct {
// contains filtered or unexported fields
}
Context wraps context.Context.
func (Context) ValueTypes ¶
ValueTypes implements Value interface.
type Duration ¶
Duration wraps time.Duration.
func (Duration) ValueTypes ¶
ValueTypes implements Value interface.
type Float32 ¶
type Float32 float32
Float32 wraps [float32].
func (Float32) ValueTypes ¶
ValueTypes implements Value interface.
type Float64 ¶
type Float64 float64
Float64 wraps [float64].
func (Float64) ValueTypes ¶
ValueTypes implements Value interface.
type HostFunc ¶
HostFunc is a wrapped host-defined function.
It is constructed with functions from H0 to H8 where the number is how many arguments it accepts. If you need more, use Pair.
There is always exactly one result. If you need to return nothing, use Void. If you want to return 2 or more values, use Pair, but make sure that the guest and the runtime support multi-value returns.
func H5 ¶
func H5[A Lift[A], B Lift[B], C Lift[C], D Lift[D], E Lift[E], Z Lower]( fn func(A, B, C, D, E) Z, ) HostFunc
H5 defines a HostFunc that accepts 5 high-level arguments.
func H6 ¶
func H6[A Lift[A], B Lift[B], C Lift[C], D Lift[D], E Lift[E], F Lift[F], Z Lower]( fn func(A, B, C, D, E, F) Z, ) HostFunc
H6 defines a HostFunc that accepts 6 high-level arguments.
func H7 ¶
func H7[A Lift[A], B Lift[B], C Lift[C], D Lift[D], E Lift[E], F Lift[F], G Lift[G], Z Lower]( fn func(A, B, C, D, E, F, G) Z, ) HostFunc
H7 defines a HostFunc that accepts 7 high-level arguments.
func H8 ¶
func H8[A Lift[A], B Lift[B], C Lift[C], D Lift[D], E Lift[E], F Lift[F], G Lift[G], H Lift[H], Z Lower]( fn func(A, B, C, D, E, F, G, H) Z, ) HostFunc
H8 defines a HostFunc that accepts 8 high-level arguments.
If you need more than 8 arguments, think again. If you still do, use Pair.
func (*HostFunc) NumResults ¶
func (*HostFunc) ParamValueTypes ¶
func (*HostFunc) ResultValueTypes ¶
type HostRef ¶
type HostRef[T any] struct { Raw T // contains filtered or unexported fields }
HostRef is a reference to a Go object stored on the host side in Refs.
References created this way are never collected by GC because there is no way to know if the wasm module still needs it. So it is important to explicitly clean references by calling HostRef.Drop.
A common usage pattern is to create a reference in one host-defined function, return it into the wasm module, and then clean it up in another host-defined function caled from wasm when the guest doesn't need the value anymore. In this scenario, the latter function accepts HostRef as an argument and calls its HostRef.Drop method. After that, the reference is removed from Refs in the Store and will be eventually collected by GC.
func (HostRef[T]) Drop ¶ added in v0.1.3
func (v HostRef[T]) Drop()
Drop remove the reference from Refs in Store.
Can be called only on lifted references (passed as an argument into a host-defined function).
func (HostRef[T]) ValueTypes ¶
ValueTypes implements Value interface.
type Int16 ¶
type Int16 int16
Int16 wraps [int16], a signed 16-bit integer.
func (Int16) ValueTypes ¶
ValueTypes implements Value interface.
type Int32 ¶
type Int32 int32
Int32 wraps [int32], a signed 32-bit integer.
func (Int32) ValueTypes ¶
ValueTypes implements Value interface.
type Int64 ¶
type Int64 int64
Int64 wraps [int64], a signed 64-bit integer.
func (Int64) ValueTypes ¶
ValueTypes implements Value interface.
type Int8 ¶
type Int8 int8
Int8 wraps [int8], a signed 8-bit integer.
func (Int8) ValueTypes ¶
ValueTypes implements Value interface.
type MapRefs ¶
MapRefs is a simple Refs implementation powered by a map.
Must be constructed with NewMapRefs.
func NewMapRefs ¶
func NewMapRefs() MapRefs
type Memory ¶
type Memory interface {
// Read is used to [Lift] values of memory-backed types, like [Bytes] and [String].
Read(offset Addr, count uint32) ([]byte, bool)
// Read is used to [Lower] values of memory-backed types, like [Bytes] and [String].
Write(offset Addr, v []byte) bool
}
Memory provides access to the linear memory of the wasm runtime.
The interface is compatible with wazero memory.
type Module ¶
Module is a collection of host-defined functions in a module with the same name.
It maps function names to function definitions.
type Modules ¶
Modules is a collection of host-defined modules.
It maps module names to the module definitions.
type Pair ¶
Pair wraps two values of arbitrary types.
You can combine multiple pairs to pass more than 2 values at once. All values are passed through the stack, not memory.
func (Pair[L, R]) ValueTypes ¶
ValueTypes implements Value interface.
type Refs ¶
type Refs interface {
Get(idx uint32, def any) (any, bool)
Set(idx uint32, val any)
Put(val any) uint32
Drop(idx uint32)
}
Refs holds references to Go values that you want to reference from wasm using HostRef.
type SliceMemory ¶ added in v0.1.2
type SliceMemory []byte
Wraps a slice of bytes to be used as Memory.
func NewSliceMemory ¶ added in v0.1.2
func NewSliceMemory(size int) *SliceMemory
Create new memory instance that internally stores data in a slice.
func (*SliceMemory) Len ¶ added in v0.1.2
func (s *SliceMemory) Len() int
type SliceStack ¶
type SliceStack []uint64
SliceStack adapts a slice of raw values into a Stack.
func NewSliceStack ¶
func NewSliceStack(cap int) *SliceStack
func (*SliceStack) Len ¶
func (s *SliceStack) Len() int
func (*SliceStack) Pop ¶
func (s *SliceStack) Pop() uint64
func (*SliceStack) Push ¶
func (s *SliceStack) Push(v uint64)
type Store ¶
type Store struct {
// Stack is where [Lift] takes the values from and [Lower] puts values to.
Stack Stack
// Memory is used by [Lift] and [Lower] of memory-based types,
// like [Bytes] and [String].
Memory Memory
// Refs is used by [HostRef] to pass through the gues module references
// to complex objects in the host environment that cannot be lowered into wasm.
Refs Refs
// Context can be retrieved by the [Context] type.
Context context.Context
// Error holds the latest error that happened during [Lift] or [Lower].
Error error
}
Store provides access for host-defined functions to the runtime data.
Store itself implements Lift and so can be used as a host-defined function argument.
func (Store) ValueTypes ¶
ValueTypes implements Value interface.
type String ¶
String wraps [string].
The string is passed through the linear memory. Since the memory is controlled and allocated by the guest module, you have to provide the Offset to be able to Lower the value into the memory. The offset should be obtained from the guest module, either as an explicit function argument or by calling its allocator.
func (String) ValueTypes ¶
ValueTypes implements Value interface.
type UInt ¶
type UInt uint
UInt wraps uint, 32-bit unsigned integer.
func (UInt) ValueTypes ¶
ValueTypes implements Value interface.
type UInt16 ¶
type UInt16 uint16
UInt16 wraps uint16, 16-bit unsigned integer.
func (UInt16) ValueTypes ¶
ValueTypes implements Value interface.
type UInt32 ¶
type UInt32 uint32
UInt32 wraps uint32, 32-bit unsigned integer.
func (UInt32) ValueTypes ¶
ValueTypes implements Value interface.
type UInt64 ¶
type UInt64 uint64
UInt64 wraps uint64, 64-bit unsigned integer.
func (UInt64) ValueTypes ¶
ValueTypes implements Value interface.
type UInt8 ¶
type UInt8 uint8
UInt8 wraps uint8, 8-bit unsigned integer.
func (UInt8) ValueTypes ¶
ValueTypes implements Value interface.
type UIntPtr ¶
type UIntPtr uintptr
UIntPtr wraps uintptr, pointer-sized unsigned integer.
func (UIntPtr) ValueTypes ¶
ValueTypes implements Value interface.
type Value ¶
type Value interface {
ValueTypes() []ValueType
}
Value is an interface implemented by all the types in wypes.
type ValueType ¶
type ValueType = byte
const ( // ValueTypeI32 is a 32-bit integer. ValueTypeI32 ValueType = 0x7f // ValueTypeI64 is a 64-bit integer. ValueTypeI64 ValueType = 0x7e // ValueTypeF32 is a 32-bit floating point number. ValueTypeF32 ValueType = 0x7d // ValueTypeF64 is a 64-bit floating point number. ValueTypeF64 ValueType = 0x7c // ValueTypeExternref is an externref type. // // Not supported by many guests including TinyGo, so we don't use it. // https://github.com/tinygo-org/tinygo/issues/2702 ValueTypeExternref ValueType = 0x6f )
Source Files