github.com/bananabytelabs/wazero@v0.0.0-20240105073314-54b22a776da8/internal/wasm/engine.go (about)

     1  package wasm
     2  
     3  import (
     4  	"context"
     5  
     6  	"github.com/bananabytelabs/wazero/api"
     7  	"github.com/bananabytelabs/wazero/experimental"
     8  )
     9  
    10  // Engine is a Store-scoped mechanism to compile functions declared or imported by a module.
    11  // This is a top-level type implemented by an interpreter or compiler.
    12  type Engine interface {
    13  	// Close closes this engine, and releases all the compiled cache.
    14  	Close() (err error)
    15  
    16  	// CompileModule implements the same method as documented on wasm.Engine.
    17  	CompileModule(ctx context.Context, module *Module, listeners []experimental.FunctionListener, ensureTermination bool) error
    18  
    19  	// CompiledModuleCount is exported for testing, to track the size of the compilation cache.
    20  	CompiledModuleCount() uint32
    21  
    22  	// DeleteCompiledModule releases compilation caches for the given module (source).
    23  	// Note: it is safe to call this function for a module from which module instances are instantiated even when these
    24  	// module instances have outstanding calls.
    25  	DeleteCompiledModule(module *Module)
    26  
    27  	// NewModuleEngine compiles down the function instances in a module, and returns ModuleEngine for the module.
    28  	//
    29  	// * module is the source module from which moduleFunctions are instantiated. This is used for caching.
    30  	// * instance is the *ModuleInstance which is created from `module`.
    31  	//
    32  	// Note: Input parameters must be pre-validated with wasm.Module Validate, to ensure no fields are invalid
    33  	// due to reasons such as out-of-bounds.
    34  	NewModuleEngine(module *Module, instance *ModuleInstance) (ModuleEngine, error)
    35  }
    36  
    37  // ModuleEngine implements function calls for a given module.
    38  type ModuleEngine interface {
    39  	// DoneInstantiation is called at the end of the instantiation of the module.
    40  	DoneInstantiation()
    41  
    42  	// NewFunction returns an api.Function for the given function pointed by the given Index.
    43  	NewFunction(index Index) api.Function
    44  
    45  	// ResolveImportedFunction is used to add imported functions needed to make this ModuleEngine fully functional.
    46  	// 	- `index` is the function Index of this imported function.
    47  	// 	- `indexInImportedModule` is the function Index of the imported function in the imported module.
    48  	//	- `importedModuleEngine` is the ModuleEngine for the imported ModuleInstance.
    49  	ResolveImportedFunction(index, indexInImportedModule Index, importedModuleEngine ModuleEngine)
    50  
    51  	// ResolveImportedMemory is called when this module imports a memory from another module.
    52  	ResolveImportedMemory(importedModuleEngine ModuleEngine)
    53  
    54  	// LookupFunction returns the FunctionModule and the Index of the function in the returned ModuleInstance at the given offset in the table.
    55  	LookupFunction(t *TableInstance, typeId FunctionTypeID, tableOffset Index) (*ModuleInstance, Index)
    56  
    57  	// GetGlobalValue returns the value of the global variable at the given Index.
    58  	// Only called when OwnsGlobals() returns true, and must not be called for imported globals
    59  	GetGlobalValue(idx Index) (lo, hi uint64)
    60  
    61  	// OwnsGlobals returns true if this ModuleEngine owns the global variables. If true, wasm.GlobalInstance's Val,ValHi should
    62  	// not be accessed directly.
    63  	OwnsGlobals() bool
    64  
    65  	// FunctionInstanceReference returns Reference for the given Index for a FunctionInstance. The returned values are used by
    66  	// the initialization via ElementSegment.
    67  	FunctionInstanceReference(funcIndex Index) Reference
    68  }