Documentation ¶
Overview ¶
Package wasmer is a Go library to run WebAssembly binaries.
Index ¶
- Constants
- func GetLastError() (string, error)
- func ReadBytes(filename string) ([]byte, error)
- func Trap(instanceContext *InstanceContext, errorMessage string) bool
- func Validate(bytes []byte) bool
- type ExportDescriptor
- type ExportedFunctionError
- type Import
- type ImportDescriptor
- type ImportExportKind
- type ImportFunction
- type ImportMemory
- type ImportObject
- func NewDefaultWasiImportObject() *ImportObject
- func NewDefaultWasiImportObjectForVersion(version WasiVersion) *ImportObject
- func NewImportObject() *ImportObject
- func NewWasiImportObject(arguments []string, environmentVariables []string, preopenedDirs []string, ...) *ImportObject
- func NewWasiImportObjectForVersion(version WasiVersion, arguments []string, environmentVariables []string, ...) *ImportObject
- type ImportObjectError
- type ImportedFunctionError
- type Imports
- func (imports *Imports) Append(importName string, implementation interface{}, cgoPointer unsafe.Pointer) (*Imports, error)
- func (imports *Imports) AppendFunction(importName string, implementation interface{}, cgoPointer unsafe.Pointer) (*Imports, error)
- func (imports *Imports) AppendMemory(importName string, memory *Memory) (*Imports, error)
- func (imports *Imports) Close()
- func (imports *Imports) Namespace(namespace string) *Imports
- type Instance
- type InstanceContext
- type InstanceError
- type MapDirEntry
- type Memory
- type MemoryError
- type Module
- func (module *Module) Close()
- func (module *Module) Instantiate() (Instance, error)
- func (module *Module) InstantiateWithImportObject(importObject *ImportObject) (Instance, error)
- func (module *Module) InstantiateWithImports(imports *Imports) (Instance, error)
- func (module *Module) Serialize() ([]byte, error)
- type ModuleError
- type Value
- type ValueType
- type WasiVersion
Constants ¶
const ( // ImportExportKindFunction represents an import/export descriptor of kind function. ImportExportKindFunction = ImportExportKind(cWasmFunction) // ImportExportKindGlobal represents an import/export descriptor of kind global. ImportExportKindGlobal = ImportExportKind(cWasmGlobal) // ImportExportKindMemory represents an import/export descriptor of kind memory. ImportExportKindMemory = ImportExportKind(cWasmMemory) // ImportExportKindTable represents an import/export descriptor of kind table. ImportExportKindTable = ImportExportKind(cWasmTable) )
const ( // Unknown represents an unknown WASI version. Unknown = WasiVersion(cVersionUnknown) // Latest represents the latest WASI version. Latest = WasiVersion(cVersionSnapshot0) // Snapshot0 represents the `wasi_unstable` WASI version. Snapshot0 = WasiVersion(cVersionSnapshot0) // Snapshot1 represents the `wasi_snapshot1_preview` WASI version. Snapshot1 = WasiVersion(cVersionSnapshot1) )
Variables ¶
This section is empty.
Functions ¶
func GetLastError ¶
GetLastError returns the last error message if any, otherwise returns an error.
func ReadBytes ¶
ReadBytes reads a `.wasm` file and returns its content as an array of bytes.
func Trap ¶
func Trap(instanceContext *InstanceContext, errorMessage string) bool
@by taifu Trap stop executing the current instance
Types ¶
type ExportDescriptor ¶
type ExportDescriptor struct { // The export name. Name string // The export kind/type. Kind ImportExportKind }
ExportDescriptor represents an export descriptor of a WebAssembly module. It is different of an export of a WebAssembly instance. An export descriptor only has a name and a kind/type.
type ExportedFunctionError ¶
type ExportedFunctionError struct {
// contains filtered or unexported fields
}
ExportedFunctionError represents any kind of errors related to a WebAssembly exported function. It is returned by `Instance` functions only.
func NewExportedFunctionError ¶
func NewExportedFunctionError(functionName string, message string) *ExportedFunctionError
NewExportedFunctionError constructs a new `ExportedFunctionError`, where `functionName` is the name of the exported function, and `message` is the error message. If the error message contains `%s`, then this parameter will be replaced by `functionName`.
func (*ExportedFunctionError) Error ¶
func (error *ExportedFunctionError) Error() string
ExportedFunctionError is an actual error. The `Error` function returns the error message.
type Import ¶
type Import interface{}
Import represents a WebAssembly instance imported function or memory. Imagine it is an union of `ImportFunction` and `ImportMemory`.
type ImportDescriptor ¶
type ImportDescriptor struct { // The import name. Name string // The import namespace. Namespace string // The import kind/type. Kind ImportExportKind }
ImportDescriptor represents an import descriptor of a WebAssembly module. It is different of an import of a WebAssembly instance. An import descriptor only has a name, a namespace, and a kind/type.
type ImportExportKind ¶
type ImportExportKind int
ImportExportKind represents an import/export descriptor kind/type.
type ImportFunction ¶
type ImportFunction struct {
// contains filtered or unexported fields
}
ImportFunction represents a WebAssembly instance imported function.
type ImportMemory ¶
type ImportMemory struct {
// contains filtered or unexported fields
}
ImportMemory represents a WebAssembly instance imported memory.
type ImportObject ¶
type ImportObject struct {
// contains filtered or unexported fields
}
ImportObject owns a set of imports. It can be combined with a `Module` to create an `Instance`.
func NewDefaultWasiImportObject ¶
func NewDefaultWasiImportObject() *ImportObject
NewDefaultWasiImportObject constructs a new `ImportObject` with WASI host imports.
To specify WASI program arguments, environment variables, preopened directories, and more, see `NewWasiImportObject`
func NewDefaultWasiImportObjectForVersion ¶
func NewDefaultWasiImportObjectForVersion(version WasiVersion) *ImportObject
NewDefaultWasiImportObjectForVersion is similar to `NewDefaultWasiImportObject` but it specifies the WASI version.
func NewImportObject ¶
func NewImportObject() *ImportObject
NewImportObject creates an empty `ImportObject`.
func NewWasiImportObject ¶
func NewWasiImportObject( arguments []string, environmentVariables []string, preopenedDirs []string, mappedDirs []MapDirEntry, ) *ImportObject
NewWasiImportObject creates an `ImportObject` with the default WASI imports. Specify arguments (the first is the program name), environment variables ("envvar=value"), preopened directories (host file paths), and mapped directories (host file paths with an alias, see `MapDirEntry`)
func NewWasiImportObjectForVersion ¶
func NewWasiImportObjectForVersion( version WasiVersion, arguments []string, environmentVariables []string, preopenedDirs []string, mappedDirs []MapDirEntry, ) *ImportObject
NewWasiImportObjectForVersion is similar to `NewWasiImportObject` but it specifies the WASI version.
func (*ImportObject) Close ¶
func (importObject *ImportObject) Close()
Close frees the `ImportObject`
func (*ImportObject) Extend ¶
func (importObject *ImportObject) Extend(imports Imports) error
Extend adds the given imports to the existing import object
func (*ImportObject) Imports ¶
func (importObject *ImportObject) Imports() (*Imports, error)
Imports returns `*Imports` for a given `ImportObject`
type ImportObjectError ¶
type ImportObjectError struct {
// contains filtered or unexported fields
}
ImportObjectError represents errors related to `ImportObject`s.
func NewImportObjectError ¶
func NewImportObjectError(message string) *ImportObjectError
NewImportObjectError constructs a new `ImportObjectError`
func (*ImportObjectError) Error ¶
func (error *ImportObjectError) Error() string
ImportObjectError is an actual error. The `Error` function returns the error message.
type ImportedFunctionError ¶
type ImportedFunctionError struct {
// contains filtered or unexported fields
}
ImportedFunctionError represents any kind of errors related to a WebAssembly imported function. It is returned by `Import` or `Imports` functions only.
func NewImportedFunctionError ¶
func NewImportedFunctionError(functionName string, message string) *ImportedFunctionError
NewImportedFunctionError constructs a new `ImportedFunctionError`, where `functionName` is the name of the imported function, and `message` is the error message. If the error message contains `%s`, then this parameter will be replaced by `functionName`.
func (*ImportedFunctionError) Error ¶
func (error *ImportedFunctionError) Error() string
ImportedFunctionError is an actual error. The `Error` function returns the error message.
type Imports ¶
type Imports struct {
// contains filtered or unexported fields
}
Imports represents a set of imported functions for a WebAssembly instance.
func (*Imports) Append ¶
func (imports *Imports) Append(importName string, implementation interface{}, cgoPointer unsafe.Pointer) (*Imports, error)
Append adds a new imported function to the current set. Deprecated, please use AppendFunction instead.
func (*Imports) AppendFunction ¶
func (imports *Imports) AppendFunction(importName string, implementation interface{}, cgoPointer unsafe.Pointer) (*Imports, error)
AppendFunction adds a new imported function to the current set.
func (*Imports) AppendMemory ¶
AppendMemory adds a new imported memory to the current set.
type Instance ¶
type Instance struct { // All functions exported by the WebAssembly instance, indexed // by their name as a string. An exported function is a // regular variadic Go closure. Arguments are untyped. Since // WebAssembly only supports: `i32`, `i64`, `f32` and `f64` // types, the accepted Go types are: `int8`, `uint8`, `int16`, // `uint16`, `int32`, `uint32`, `int64`, `int`, `uint`, `float32` // and `float64`. In addition to those types, the `Value` type // (from this project) is accepted. The conversion from a Go // value to a WebAssembly value is done automatically except for // the `Value` type (where type is coerced, that's the intent // here). The WebAssembly type is automatically inferred. Note // that the returned value is of kind `Value`, and not a // standard Go type. Exports map[string]func(...interface{}) (Value, error) // The exported memory of a WebAssembly instance. Memory *Memory // contains filtered or unexported fields }
Instance represents a WebAssembly instance.
func NewInstance ¶
NewInstance constructs a new `Instance` with no imports.
func NewInstanceWithImports ¶
NewInstanceWithImports constructs a new `Instance` with imports.
func (*Instance) HasMemory ¶
HasMemory checks whether the instance has at least one exported memory.
func (*Instance) SetContextData ¶
func (instance *Instance) SetContextData(data interface{})
SetContextData assigns a _data that can be used by all imported functions. Each imported function receives as its first argument an instance context (see `InstanceContext`). An instance context can hold any kind of _data, including _data that contain Go references such as slices, maps, or structs with reference types or pointers. It is important to understand that _data is global to the instance, and thus is shared by all imported functions.
func (*Instance) SetGasLimit ¶
SetGasLimit set gas limit
type InstanceContext ¶
type InstanceContext struct {
// contains filtered or unexported fields
}
InstanceContext represents a way to access instance API from within an imported context.
func GetWasmerInstanceContext ¶
func GetWasmerInstanceContext(instance *Instance) *InstanceContext
GetWasmerInstanceContext get instance context
func IntoInstanceContext ¶
func IntoInstanceContext(instanceContext unsafe.Pointer) InstanceContext
IntoInstanceContext casts the first `context unsafe.Pointer` argument of an imported function into an `InstanceContext`.
func (*InstanceContext) Data ¶
func (instanceContext *InstanceContext) Data() interface{}
Data returns the instance context _data as an `interface{}`. It's up to the user to assert the proper type.
func (*InstanceContext) Memory ¶
func (instanceContext *InstanceContext) Memory() *Memory
Memory returns the current instance memory.
type InstanceError ¶
type InstanceError struct {
// contains filtered or unexported fields
}
InstanceError represents any kind of errors related to a WebAssembly instance. It is returned by `Instance` functions only.
func NewInstanceError ¶
func NewInstanceError(message string) *InstanceError
NewInstanceError constructs a new `InstanceError`.
func (*InstanceError) Error ¶
func (error *InstanceError) Error() string
`InstanceError` is an actual error. The `Error` function returns the error message.
type MapDirEntry ¶
type MapDirEntry struct {
// contains filtered or unexported fields
}
MapDirEntry is an entry that can be passed to `NewWasiImportObject`. Preopens a file for the WASI module but renames it to the given name
type Memory ¶
type Memory struct {
// contains filtered or unexported fields
}
Memory represents a WebAssembly memory. To read and write _data, please see the `Data` function. The memory can be owned or borrowed. It is only possible to create an owned memory from the user-land.
func NewMemory ¶
NewMemory instantiates a new owned WebAssembly memory, bound for imported memory.
func (*Memory) Close ¶
func (memory *Memory) Close()
Close closes/frees memory allocated at the NewMemory at time.
func (*Memory) Data ¶
Data returns a slice of bytes over the WebAssembly memory.
func (*Memory) Grow ¶
Grow the memory by a number of pages (65kb each).
func (*Memory) IsOwned ¶
IsOwned checks whether the memory is owned, or borrowed.
type MemoryError ¶
type MemoryError struct {
// contains filtered or unexported fields
}
MemoryError represents any kind of errors related to a WebAssembly memory. It is returned by `Memory` functions only.
func NewMemoryError ¶
func NewMemoryError(message string) *MemoryError
NewMemoryError constructs a new `MemoryError`.
func (*MemoryError) Error ¶
func (error *MemoryError) Error() string
`MemoryError` is an actual error. The `Error` function returns the error message.
type Module ¶
type Module struct { Exports []ExportDescriptor Imports []ImportDescriptor // contains filtered or unexported fields }
Module represents a WebAssembly module.
func Compile ¶
Compile compiles a WebAssembly module from bytes.
func DeserializeModule ¶
DeserializeModule deserializes a sequence of bytes into a module. Ideally, those bytes must come from `Module.Serialize`.
func (*Module) Instantiate ¶
Instantiate creates a new instance of the WebAssembly module.
func (*Module) InstantiateWithImportObject ¶
func (module *Module) InstantiateWithImportObject(importObject *ImportObject) (Instance, error)
InstantiateWithImportObject creates a new instance of a WebAssembly module with an `ImportObject`
func (*Module) InstantiateWithImports ¶
InstantiateWithImports creates a new instance with imports of the WebAssembly module.
type ModuleError ¶
type ModuleError struct {
// contains filtered or unexported fields
}
ModuleError represents any kind of errors related to a WebAssembly module.
func NewModuleError ¶
func NewModuleError(message string) *ModuleError
NewModuleError constructs a new `ModuleError`.
func (*ModuleError) Error ¶
func (error *ModuleError) Error() string
`ModuleError` is an actual error. The `Error` function returns the error message.
type Value ¶
type Value struct {
// contains filtered or unexported fields
}
Value represents a WebAssembly value of a particular type.
func (Value) GetType ¶
GetType gets the type of the WebAssembly value.
func (Value) String ¶
String formats the WebAssembly value as a Go string.
func (Value) ToF32 ¶
ToF32 reads the WebAssembly value bits as a `float32`. The WebAssembly value type is ignored.
func (Value) ToF64 ¶
ToF64 reads the WebAssembly value bits as a `float64`. The WebAssembly value type is ignored.
func (Value) ToI32 ¶
ToI32 reads the WebAssembly value bits as an `int32`. The WebAssembly value type is ignored.
func (Value) ToI64 ¶
ToI64 reads the WebAssembly value bits as an `int64`. The WebAssembly value type is ignored.
type ValueType ¶
type ValueType int
ValueType represents the `Value` type.
const ( // TypeI32 represents the WebAssembly `i32` type. TypeI32 ValueType = iota // TypeI64 represents the WebAssembly `i64` type. TypeI64 // TypeF32 represents the WebAssembly `f32` type. TypeF32 // TypeF64 represents the WebAssembly `f64` type. TypeF64 // TypeVoid represents nothing. // WebAssembly doesn't have “void” type, but it is introduced // here to represent the returned value of a WebAssembly exported // function that returns nothing. TypeVoid )
type WasiVersion ¶
type WasiVersion uint
WasiVersion represents the WASI version.
func WasiGetVersion ¶
func WasiGetVersion(module Module) WasiVersion
WasiGetVersion returns the WASI version of a module if any, other `Unknown` is returned.