wa-lang.org/wazero@v1.0.2/internal/wasm/engine.go (about)

     1  package wasm
     2  
     3  import (
     4  	"context"
     5  
     6  	"wa-lang.org/wazero/experimental"
     7  )
     8  
     9  // Engine is a Store-scoped mechanism to compile functions declared or imported by a module.
    10  // This is a top-level type implemented by an interpreter or compiler.
    11  type Engine interface {
    12  	// CompileModule implements the same method as documented on wasm.Engine.
    13  	CompileModule(ctx context.Context, module *Module, listeners []experimental.FunctionListener) error
    14  
    15  	// CompiledModuleCount is exported for testing, to track the size of the compilation cache.
    16  	CompiledModuleCount() uint32
    17  
    18  	// DeleteCompiledModule releases compilation caches for the given module (source).
    19  	// Note: it is safe to call this function for a module from which module instances are instantiated even when these
    20  	// module instances have outstanding calls.
    21  	DeleteCompiledModule(module *Module)
    22  
    23  	// NewModuleEngine compiles down the function instances in a module, and returns ModuleEngine for the module.
    24  	//
    25  	// * name is the name the module was instantiated with used for error handling.
    26  	// * module is the source module from which moduleFunctions are instantiated. This is used for caching.
    27  	// * importedFunctions: functions this module imports, already compiled in this engine.
    28  	// * moduleFunctions: functions declared in this module that must be compiled.
    29  	//
    30  	// Note: Input parameters must be pre-validated with wasm.Module Validate, to ensure no fields are invalid
    31  	// due to reasons such as out-of-bounds.
    32  	NewModuleEngine(name string, module *Module, importedFunctions, moduleFunctions []*FunctionInstance) (ModuleEngine, error)
    33  }
    34  
    35  // ModuleEngine implements function calls for a given module.
    36  type ModuleEngine interface {
    37  	// Name returns the name of the module this engine was compiled for.
    38  	Name() string
    39  
    40  	// NewCallEngine returns a CallEngine for the given FunctionInstance.
    41  	NewCallEngine(callCtx *CallContext, f *FunctionInstance) (CallEngine, error)
    42  
    43  	// LookupFunction returns the index of the function in the function table.
    44  	LookupFunction(t *TableInstance, typeId FunctionTypeID, tableOffset Index) (Index, error)
    45  
    46  	// CreateFuncElementInstance creates an ElementInstance whose references are engine-specific function pointers
    47  	// corresponding to the given `indexes`.
    48  	CreateFuncElementInstance(indexes []*Index) *ElementInstance
    49  
    50  	// InitializeFuncrefGlobals initializes the globals of Funcref type as the opaque pointer values of engine specific compiled functions.
    51  	InitializeFuncrefGlobals(globals []*GlobalInstance)
    52  
    53  	// FunctionInstanceReference returns Reference for the given Index for a FunctionInstance. The returned values are used by
    54  	// the initialization via ElementSegment.
    55  	FunctionInstanceReference(funcIndex Index) Reference
    56  }
    57  
    58  // CallEngine implements function calls for a FunctionInstance. It manages its own call frame stack and value stack,
    59  // internally, and shouldn't be used concurrently.
    60  type CallEngine interface {
    61  	// Call invokes a function instance f with given parameters.
    62  	Call(ctx context.Context, m *CallContext, params []uint64) (results []uint64, err error)
    63  }