vm

package
v1.2.0-pre Latest Latest
Warning

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

 Go to latest Published: Jun 6, 2024 License: BSD-3-Clause Imports: 8 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// See https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/#memory-instances%E2%91%A0
	MemoryPageSize = uint32(65536)
	// See https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/#grow-mem
	MemoryLimitPages = uint32(65536)
)
View Source 
const (
	// ExternTypeFuncName is the name of the WebAssembly 1.0 (20191205) Text Format field for ExternTypeFunc.
	ExternTypeFuncName = "func"
	// ExternTypeTableName is the name of the WebAssembly 1.0 (20191205) Text Format field for ExternTypeTable.
	ExternTypeTableName = "table"
	// ExternTypeMemoryName is the name of the WebAssembly 1.0 (20191205) Text Format field for ExternTypeMemory.
	ExternTypeMemoryName = "memory"
	// ExternTypeGlobalName is the name of the WebAssembly 1.0 (20191205) Text Format field for ExternTypeGlobal.
	ExternTypeGlobalName = "global"
)

The below are exported to consolidate parsing behavior for external types.

Variables

View Source 
var (
	I32Type = reflect.TypeOf((*int32)(nil)).Elem()
	I64Type = reflect.TypeOf((*int64)(nil)).Elem()
	F32Type = reflect.TypeOf((*float32)(nil)).Elem()
	F64Type = reflect.TypeOf((*float64)(nil)).Elem()

	ContextType = reflect.TypeOf((*context.Context)(nil)).Elem()
	ModuleType  = reflect.TypeOf((*Module)(nil)).Elem()
)
View Source 
var (
	GetTimeout = 60 * time.Second

	//TODO: Lookup should handle timeout (tns fetch may need to take context)
	LookupTimeout = 10 * time.Second
)

Functions

func DecodeExternref 

func DecodeExternref(input uint64) uintptr

DecodeExternref decodes the input as a ValueTypeExternref.

func DecodeF32 

func DecodeF32(input uint64) float32

DecodeF32 decodes the input as a ValueTypeF32.

func DecodeF64 

func DecodeF64(input uint64) float64

DecodeF64 decodes the input as a ValueTypeF64.

func EncodeExternref 

func EncodeExternref(input uintptr) uint64

EncodeExternref encodes the input as a ValueTypeExternref.

func EncodeF32 

func EncodeF32(input float32) uint64

EncodeF32 encodes the input as a ValueTypeF32.

func EncodeF64 

func EncodeF64(input float64) uint64

EncodeF64 encodes the input as a ValueTypeF64.

func EncodeI32 

func EncodeI32(input int32) uint64

EncodeI32 encodes the input as a ValueTypeI32.

func EncodeI64 

func EncodeI64(input int64) uint64

EncodeI64 encodes the input as a ValueTypeI64.

func ExternTypeName 

func ExternTypeName(et ExternType) string

ExternTypeName returns the name of the WebAssembly 1.0 (20191205) Text Format field of the given type.

func ValueTypeName 

func ValueTypeName(t ValueType) string

ValueTypeName returns the type name of the given ValueType as a string. These type names match the names used in the WebAssembly text format.

func ValueTypeToReflectType 

func ValueTypeToReflectType(v ValueType) reflect.Type

Types

type Backend 

type Backend interface {
	// Returns the URI scheme the backend supports.
	Scheme() string
	// Get attempts to retrieve the WASM asset.
	Get(multAddr ma.Multiaddr) (io.ReadCloser, error)
	// Close will close the Backend.
	Close() error
}

type Config 

type Config struct {
	MemoryLimitPages uint32 // should default to MemoryLimitPages
	Output           OutputType
}

Config sets configuration of the VM service

type Context 

type Context interface {
	// Context returns the go context of the function instance
	Context() context.Context

	// Project returns the Taubyte project id
	Project() string

	// Application returns the application, if none returns an empty string
	Application() string

	// Resource returns the id of the resource being used.
	Resource() string

	// Branch returns the branch name used by this resource execution pipeline.
	Branch() string

	// Commit returns the commit id used by this resource execution pipeline.
	Commit() string

	// Clone clones the VM.Context with a new go context
	Clone(context.Context) Context
}

type ExternType 

type ExternType = byte

ExternType classifies imports and exports with their respective types.

See https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/#external-types%E2%91%A0 

const (
	ExternTypeFunc   ExternType = 0x00
	ExternTypeTable  ExternType = 0x01
	ExternTypeMemory ExternType = 0x02
	ExternTypeGlobal ExternType = 0x03
)

type Factory 

type Factory interface {
	// Load will initialize the Factory
	Load(hm HostModule) error

	// Close will close and cleanup the Factory
	Close() error

	// Name returns the name of the Factory
	Name() string
}

type Function 

type Function interface {
	// Definition is metadata about this function from its defining module.
	Definition() FunctionDefinition

	// Call invokes the function with parameters encoded according to ParamTypes. Up to one result is returned.
	Call(ctx context.Context, params ...uint64) ([]uint64, error)
}

Function is a WebAssembly function exported from an instantiated module.

type FunctionDefinition 

type FunctionDefinition interface {
	// Name is the module-defined name of the function, which is not necessarily
	// the same as its export name.
	Name() string

	// ParamTypes are the possibly empty sequence of value types accepted by a
	// function with this signature.
	ParamTypes() []ValueType

	// ResultTypes are the results of the function.
	ResultTypes() []ValueType
}

FunctionDefinition is a WebAssembly function exported in a module.

type FunctionInstance 

type FunctionInstance interface {
	FunctionInstanceCommon
	Call(ctx context.Context, args ...interface{}) Return
	RawCall(ctx context.Context, args ...uint64) ([]uint64, error)
}

type FunctionInstanceCommon 

type FunctionInstanceCommon interface {
	// Cancel will cancel the context of the FunctionInstance
	Cancel() error
}

type Global 

type Global interface {
	// Type describes the numeric type of the global.
	Type() ValueType

	// Get returns the last known value of this global. When the context is nil, it defaults to context.Background.
	Get() uint64
}

Global is a WebAssembly 1.0 (20191205) global exported from an instantiated module.

type HostFunction 

type HostFunction interface{}

HostFunction is the function handler of a HostModuleFunctionDefinition

type HostModule 

type HostModule interface {
	// Functions adds the function definitions to the HostModule
	Functions(...*HostModuleFunctionDefinition) error

	// Memory adds the memory definitions to the HostModule
	Memories(...*HostModuleMemoryDefinition) error

	// Globals adds the global definitions to the HostModule
	Globals(...*HostModuleGlobalDefinition) error

	// Compile will compile the defined HostModule, and return a ModuleInstance
	Compile() (ModuleInstance, error)
}

type HostModuleDefinitions 

type HostModuleDefinitions struct {
	Functions []*HostModuleFunctionDefinition
	Memories  []*HostModuleMemoryDefinition
	Globals   []*HostModuleGlobalDefinition
}

type HostModuleFunctionDefinition 

type HostModuleFunctionDefinition struct {
	Name    string
	Handler HostFunction
}

HostModuleFunctionDefinition is the definition of a Function within a HostModule

type HostModuleGlobalDefinition 

type HostModuleGlobalDefinition struct {
	Name  string
	Value interface{}
}

HostModuleGlobalDefinition is Global Value stored within the HostModule

type HostModuleMemoryDefinition 

type HostModuleMemoryDefinition struct {
	Name  string
	Pages struct {
		Min   uint64
		Max   uint64
		Maxed bool
	}
}

HostModuleMemoryDefinition is the memory definition of the Host Module.

type Instance 

type Instance interface {
	// Context returns the context of the function Instance
	Context() Context

	// Close will close the Instance
	Close() error

	// Runtime returns a new Function Instance Runtime
	Runtime(*HostModuleDefinitions) (Runtime, error)

	// Filesystem returns the filesystem used by the given Instance.
	Filesystem() afero.Fs

	// Stdout returns the Reader interface of stdout
	Stdout() io.Reader

	// Stderr returns the Reader interface of stderr
	Stderr() io.Reader
}

type Loader 

type Loader interface {
	// Load resolves the module, then loads the module using a Backend
	Load(ctx Context, module string) (io.ReadCloser, error)
}

type Memory 

type Memory interface {
	Size() uint32

	// Grow increases memory by the delta in pages (65536 bytes per page).
	Grow(deltaPages uint32) (previousPages uint32, ok bool)

	// ReadByte reads a single byte from the underlying buffer at the offset or returns false if out of range.
	ReadByte(offset uint32) (byte, bool)

	// ReadUint16Le reads a uint16 in little-endian encoding from the underlying buffer at the offset in or returns
	// false if out of range.
	ReadUint16Le(offset uint32) (uint16, bool)

	// ReadUint32Le reads a uint32 in little-endian encoding from the underlying buffer at the offset in or returns
	// false if out of range.
	ReadUint32Le(offset uint32) (uint32, bool)

	// ReadFloat32Le reads a float32 from 32 IEEE 754 little-endian encoded bits in the underlying buffer at the offset
	// or returns false if out of range.
	ReadFloat32Le(offset uint32) (float32, bool)

	// ReadUint64Le reads a uint64 in little-endian encoding from the underlying buffer at the offset or returns false
	// if out of range.
	ReadUint64Le(offset uint32) (uint64, bool)

	// ReadFloat64Le reads a float64 from 64 IEEE 754 little-endian encoded bits in the underlying buffer at the offset
	// or returns false if out of range.
	ReadFloat64Le(offset uint32) (float64, bool)

	// Read reads byteCount bytes from the underlying buffer at the offset or
	// returns false if out of range.
	Read(offset, byteCount uint32) ([]byte, bool)

	// WriteByte writes a single byte to the underlying buffer at the offset in or returns false if out of range.
	WriteByte(offset uint32, v byte) bool

	// WriteUint16Le writes the value in little-endian encoding to the underlying buffer at the offset in or returns
	// false if out of range.
	WriteUint16Le(offset uint32, v uint16) bool

	// WriteUint32Le writes the value in little-endian encoding to the underlying buffer at the offset in or returns
	// false if out of range.
	WriteUint32Le(offset, v uint32) bool

	// WriteFloat32Le writes the value in 32 IEEE 754 little-endian encoded bits to the underlying buffer at the offset
	// or returns false if out of range.
	WriteFloat32Le(offset uint32, v float32) bool

	// WriteUint64Le writes the value in little-endian encoding to the underlying buffer at the offset in or returns
	// false if out of range.
	WriteUint64Le(offset uint32, v uint64) bool

	// WriteFloat64Le writes the value in 64 IEEE 754 little-endian encoded bits to the underlying buffer at the offset
	// or returns false if out of range.
	WriteFloat64Le(offset uint32, v float64) bool

	// Write writes the slice to the underlying buffer at the offset or returns false if out of range.
	Write(offset uint32, v []byte) bool
}

Memory allows restricted access to a module's memory. Notably, this does not allow growing.

type MemorySizer 

type MemorySizer func(minPages uint32, maxPages *uint32) (min, capacity, max uint32)

MemorySizer applies during compilation after a module has been decoded from wasm, but before it is instantiated.

type Module 

type Module interface {
	// Name is the name this module was instantiated with. Exported functions can be imported with this name.
	Name() string

	// Memory returns a memory defined in this module or nil if there are none wasn't.
	Memory() Memory

	// ExportedFunction returns a function exported from this module or nil if it wasn't.
	ExportedFunction(name string) Function

	// ExportedMemory returns a memory exported from this module or nil if it wasn't.
	ExportedMemory(name string) Memory

	// ExportedGlobal a global exported from this module or nil if it wasn't.
	ExportedGlobal(name string) Global

	// CloseWithExitCode releases resources allocated for this Module. Use a non-zero exitCode parameter to indicate a
	// failure to ExportedFunction callers. When the context is nil, it defaults to context.Background.
	CloseWithExitCode(exitCode uint32) error

	// Close closes the resource. When the context is nil, it defaults to context.Background.
	Close(context.Context) error
}

Module return functions exported in a module, post-instantiation.

type ModuleInstance 

type ModuleInstance interface {
	// Function returns a FunctionInstance of given name from the ModuleInstance
	Functions() []FunctionDefinition
	Function(name string) (FunctionInstance, error)
	Memory() Memory
}

type MutableGlobal 

type MutableGlobal interface {
	Global

	// Set updates the value of this global. When the context is nil, it defaults to context.Background.
	Set(v uint64)
}

MutableGlobal is a Global whose value can be updated at runtime (variable).

type OutputType 

type OutputType uint32
const (
	Pipe OutputType = iota
	Buffer
)

type Plugin 

type Plugin interface {
	// New creates a new PluginInstance
	New(Instance) (PluginInstance, error)

	// Name returns the name of the Plugin
	Name() string

	Close() error
}

TODO: New takes options for factories

type PluginInstance 

type PluginInstance interface {
	// Load will load all Factories to the HostModule, and return the ModuleInstance
	Load(HostModule) (ModuleInstance, error)

	// Close will close the PluginInstance
	Close() error
}

type Resolver 

type Resolver interface {
	// Lookup resolves a module name and returns the uri
	Lookup(ctx Context, module string) (ma.Multiaddr, error)
}

type Return 

type Return interface {
	// Returns an error
	Error() error

	// Rets will returns the raw uint64 values of the call return
	Rets() []uint64

	// Reflect assigns the return values to the given args
	Reflect(args ...interface{}) error
}

type Runtime 

type Runtime interface {
	Module(name string) (ModuleInstance, error)
	Expose(name string) (HostModule, error)
	Attach(plugin Plugin) (PluginInstance, ModuleInstance, error)
	Stdout() io.Reader
	Stderr() io.Reader
	// TODO: Add Runtime Stat
	Close() error
}

type Service 

type Service interface {
	New(context Context, config Config) (Instance, error)
	Source() Source
	Close() error
}

type Source 

type Source interface {
	// Module Loads the given module name, and returns the SourceModule
	Module(ctx Context, name string) (SourceModule, error)
}

type SourceModule 

type SourceModule []byte

type ValueType 

type ValueType = byte

ValueType describes a numeric type used in Web Assembly 1.0 (20191205). 

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 a externref type.
	ValueTypeExternref ValueType = 0x6f
)

Source Files

View all Source files

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.