github.com/taubyte/vm-wasm-utils@v1.0.2/engine.go (about)

     1  package wasm
     2  
     3  import (
     4  	"context"
     5  	"errors"
     6  )
     7  
     8  // Engine is a Store-scoped mechanism to compile functions declared or imported by a module.
     9  // This is a top-level type implemented by an interpreter or compiler.
    10  type Engine interface {
    11  	// CompileModule implements the same method as documented on wasm.Engine.
    12  	CompileModule(ctx context.Context, module *Module) error
    13  
    14  	// CompiledModuleCount is exported for testing, to track the size of the compilation cache.
    15  	CompiledModuleCount() uint32
    16  
    17  	// DeleteCompiledModule releases compilation caches for the given module (source).
    18  	// Note: it is safe to call this function for a module from which module instances are instantiated even when these
    19  	// module instances have outstanding calls.
    20  	DeleteCompiledModule(module *Module)
    21  
    22  	// NewModuleEngine compiles down the function instances in a module, and returns ModuleEngine for the module.
    23  	//
    24  	// * name is the name the module was instantiated with used for error handling.
    25  	// * module is the source module from which moduleFunctions are instantiated. This is used for caching.
    26  	// * importedFunctions: functions this module imports, already compiled in this engine.
    27  	// * moduleFunctions: functions declared in this module that must be compiled.
    28  	// * tables: possibly shared tables used by this module. When nil tableInit will be nil.
    29  	// * tableInit: a mapping of Table's index to a mapping of TableInstance.Table index to the function index it should point to.
    30  	//
    31  	// Note: Input parameters must be pre-validated with wasm.Module Validate, to ensure no fields are invalid
    32  	// due to reasons such as out-of-bounds.
    33  	NewModuleEngine(
    34  		name string,
    35  		module *Module,
    36  		importedFunctions, moduleFunctions []*FunctionInstance,
    37  		tables []*TableInstance,
    38  		tableInits []TableInitEntry,
    39  	) (ModuleEngine, error)
    40  }
    41  
    42  // ModuleEngine implements function calls for a given module.
    43  type ModuleEngine interface {
    44  	// Name returns the name of the module this engine was compiled for.
    45  	Name() string
    46  
    47  	// Call invokes a function instance f with given parameters.
    48  	Call(ctx context.Context, m *CallContext, f *FunctionInstance, params ...uint64) (results []uint64, err error)
    49  
    50  	// CreateFuncElementInstance creates an ElementInstance whose references are engine-specific function pointers
    51  	// corresponding to the given `indexes`.
    52  	CreateFuncElementInstance(indexes []*Index) *ElementInstance
    53  
    54  	// InitializeFuncrefGlobals initializes the globals of Funcref type as the opaque pointer values of engine specific compiled functions.
    55  	InitializeFuncrefGlobals(globals []*GlobalInstance)
    56  }
    57  
    58  // TableInitEntry is normalized element segment used for initializing tables by engines.
    59  type TableInitEntry struct {
    60  	TableIndex Index
    61  	// Offset is the offset in the table from which the table is initialized by engine.
    62  	Offset Index
    63  	// FunctionIndexes contains nullable function indexes.
    64  	FunctionIndexes []*Index
    65  }
    66  
    67  // ErrElementOffsetOutOfBounds is the error raised when the active element offset exceeds the table length.
    68  // Before FeatureReferenceTypes, this was checked statically before instantiation, after the proposal,
    69  // this must be raised as runtime error (as in assert_trap in spectest), not even an instantiation error.
    70  //
    71  // See https://github.com/WebAssembly/spec/blob/d39195773112a22b245ffbe864bab6d1182ccb06/test/core/linking.wast#L264-L274
    72  var ErrElementOffsetOutOfBounds = errors.New("element offset ouf of bounds")