Involved Source Filescheckpoint.goclose.go 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!features.goimportresolver.golistener.gomemory.go
Package-Level Type Names (total 17)
/* sort by: | */
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. 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.CloseNotifyFunc
func WithCloseNotifier(ctx context.Context, notifier CloseNotifier) context.Context
CloseNotifyFunc is a convenience for defining inlining a CloseNotifier. CloseNotify implements CloseNotifier.CloseNotify.
CloseNotifyFunc : CloseNotifier
FunctionListener can be registered for any function via
FunctionListenerFactory to be notified when the function is called. 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. 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. 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.FunctionListenerFunc
func FunctionListenerFactory.NewFunctionListener(api.FunctionDefinition) FunctionListener
func FunctionListenerFactoryFunc.NewFunctionListener(def api.FunctionDefinition) FunctionListener
func BenchmarkFunctionListener(n int, module api.Module, stack []StackFrame, listener FunctionListener)
func github.com/tetratelabs/wazero/internal/wasm.Engine.CompileModule(ctx context.Context, module *wasm.Module, listeners []FunctionListener, ensureTermination bool) error
func github.com/tetratelabs/wazero/internal/wasm.(*Module).AssignModuleID(wasm []byte, listeners []FunctionListener, withEnsureTermination bool)
FunctionListenerFactoryFunc is a function type implementing the
FunctionListenerFactory interface, making it possible to use regular
functions and methods as factory of function listeners. NewFunctionListener satisfies the FunctionListenerFactory interface, calls f.
FunctionListenerFactoryFunc : FunctionListenerFactory
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. Abort is declared to satisfy the FunctionListener interface, but it does
nothing. After is declared to satisfy the FunctionListener interface, but it does
nothing. Before satisfies the FunctionListener interface, calls f.
FunctionListenerFunc : FunctionListener
ImportResolver is an experimental func type that, if set,
will be used as the first step in resolving imports.
See issue 2294.
If the import name is not found, it should return nil.
func WithImportResolver(ctx context.Context, resolver ImportResolver) context.Context
InternalFunction exposes some information about a function instance. Definition provides introspection into the function's names and
signature. 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.
func StackIterator.Function() InternalFunction
InternalModule is an api.Module that exposes additional
information. Close closes the resource.
Note: The context parameter is used for value lookup, such as for
logging. A canceled or otherwise done context will not prevent Close
from succeeding. CloseWithExitCode releases resources allocated for this Module. Use a non-zero exitCode parameter to indicate a
failure to ExportedFunction callers.
The error returned here, if present, is about resource de-allocation (such as I/O errors). Only the last error is
returned, so a non-nil return means at least one error happened. Regardless of error, this Module will
be removed, making its name available again.
Calling this inside a host function is safe, and may cause ExportedFunction callers to receive a sys.ExitError
with the exitCode. ExportedFunction returns a function exported from this module or nil if it wasn't.
# Notes
- The default wazero.ModuleConfig attempts to invoke `_start`, which
in rare cases can close the module. When in doubt, check IsClosed prior
to invoking a function export after instantiation.
- The semantics of host functions assumes the existence of an "importing module" because, for example, the host function needs access to
the memory of the importing module. Therefore, direct use of ExportedFunction is forbidden for host modules.
Practically speaking, it is usually meaningless to directly call a host function from Go code as it is already somewhere in Go code. ExportedFunctionDefinitions returns all the exported function
definitions in this module, keyed on export name. ExportedGlobal a global exported from this module or nil if it wasn't. ExportedMemory returns a memory exported from this module or nil if it wasn't.
WASI modules require exporting a Memory named "memory". This means that a module successfully initialized
as a WASI Command or Reactor will never return nil for this name.
See https://github.com/WebAssembly/WASI/blob/snapshot-01/design/application-abi.md#current-unstable-abi ExportedMemoryDefinitions returns all the exported memory definitions
in this module, keyed on export name.
Note: As of WebAssembly Core Specification 2.0, there can be at most one
memory. Global provides a read-only view for a given global index.
The methods panics if i is out of bounds. IsClosed returns true if the module is closed, so no longer usable.
This can happen for the following reasons:
- Closer was called directly.
- A guest function called Closer indirectly, such as `_start` calling
`proc_exit`, which internally closed the module.
- wazero.RuntimeConfig `WithCloseOnContextDone` was enabled and a
context completion closed the module.
Where any of the above are possible, check this value before calling an
ExportedFunction, even if you didn't formerly receive a sys.ExitError.
sys.ExitError is only returned on non-zero code, something that closes
the module successfully will not result it one. Memory returns a memory defined in this module or nil if there are none wasn't. Name is the name this module was instantiated with. Exported functions can be imported with this name. NumGlobal returns the count of all globals in the module.( InternalModule) String() string
*github.com/tetratelabs/wazero/internal/wasm.ModuleInstance
InternalModule : github.com/tetratelabs/wazero.CompilationCache
InternalModule : github.com/tetratelabs/wazero/api.Closer
InternalModule : github.com/tetratelabs/wazero/api.Module
InternalModule : github.com/tetratelabs/wazero/internal/internalapi.WazeroOnly
InternalModule : github.com/polarsignals/frostdb/query/logicalplan.Named
InternalModule : expvar.Var
InternalModule : fmt.Stringer
LinearMemory is an expandable []byte that backs a Wasm linear memory. Free the backing memory buffer. Reallocates the linear memory to size bytes in length.
Notes:
- To back a shared memory, Reallocate can't change the address of the
backing []byte (only its length/capacity may change).
- Reallocate may return nil if fails to grow the LinearMemory. This
condition may or may not be handled gracefully by the Wasm module.
func MemoryAllocator.Allocate(cap, max uint64) LinearMemory
func MemoryAllocatorFunc.Allocate(cap, max uint64) LinearMemory
func github.com/ncruces/go-sqlite3/internal/alloc.NewMemory(cap, max uint64) LinearMemory
MemoryAllocator is a memory allocation hook,
invoked to create a LinearMemory. Allocate should create a new LinearMemory with the given specification:
cap is the suggested initial capacity for the backing []byte,
and max the maximum length that will ever be requested.
Notes:
- To back a shared memory, the address of the backing []byte cannot
change. This is checked at runtime. Implementations should document
if the returned LinearMemory meets this requirement.MemoryAllocatorFunc
func WithMemoryAllocator(ctx context.Context, allocator MemoryAllocator) context.Context
func github.com/tetratelabs/wazero/internal/wasm.NewMemoryInstance(memSec *wasm.Memory, allocator MemoryAllocator, moduleEngine wasm.ModuleEngine) *wasm.MemoryInstance
MemoryAllocatorFunc is a convenience for defining inlining a MemoryAllocator. Allocate implements MemoryAllocator.Allocate.
MemoryAllocatorFunc : MemoryAllocator
ProgramCounter is an opaque value representing a specific execution point in
a module. It is meant to be used with Function.SourceOffsetForPC and
StackIterator.
func StackIterator.ProgramCounter() ProgramCounter
func InternalFunction.SourceOffsetForPC(pc ProgramCounter) uint64
Snapshot holds the execution state at the time of a Snapshotter.Snapshot call. Restore sets the Wasm execution state to the capture. Because a host function
calling this is resetting the pointer to the executation stack, the host function
will not be able to return values in the normal way. ret is a slice of values the
host function intends to return from the restored function.
func Snapshotter.Snapshot() Snapshot
Snapshotter allows host functions to snapshot the WebAssembly execution environment. Snapshot captures the current execution state.
func GetSnapshotter(ctx context.Context) Snapshotter
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. Function describes the function called by the current frame. Next moves the iterator to the next function in the stack. Returns
false if it reached the bottom of the stack. ProgramCounter returns the program counter associated with the
function call.
StackIterator : github.com/apache/arrow-go/v18/arrow/compute/exec.ArrayIter[bool]
func NewStackIterator(stack ...StackFrame) StackIterator
func FunctionListener.Before(ctx context.Context, mod api.Module, def api.FunctionDefinition, params []uint64, stackIterator StackIterator)
func FunctionListenerFunc.Before(ctx context.Context, mod api.Module, def api.FunctionDefinition, params []uint64, stackIterator StackIterator)
Package-Level Functions (total 9)
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.
GetSnapshotter gets the Snapshotter from a host function.
It is only present if WithSnapshotter was called with the function invocation context.
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.
NewStackIterator constructs a stack iterator from a list of stack frames.
The top most frame is the last one.
WithCloseNotifier registers the given CloseNotifier into the given
context.Context.
WithFunctionListenerFactory registers a FunctionListenerFactory
with the context.
WithImportResolver returns a new context with the given ImportResolver.
WithMemoryAllocator registers the given MemoryAllocator into the given
context.Context. The context must be passed when initializing a module.
WithSnapshotter enables snapshots.
Passing the returned context to a exported function invocation enables snapshots,
and allows host functions to retrieve the Snapshotter using GetSnapshotter.
Package-Level Constants (only one)
CoreFeaturesThreads enables threads instructions ("threads").
# Notes
- The instruction list is too long to enumerate in godoc.
See https://github.com/WebAssembly/threads/blob/main/proposals/threads/Overview.md
- Atomic operations are guest-only until api.Memory or otherwise expose them to host functions.
- On systems without mmap available, the memory will pre-allocate to the maximum size. Many
binaries will use a theroetical maximum like 4GB, so if using such a binary on a system
without mmap, consider editing the binary to reduce the max size setting of memory.
The pages are generated with Goldsv0.8.2. (GOOS=linux GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @zigo_101 (reachable from the left QR code) to get the latest news of Golds.
