1package wasm
 2
 3import (
 4	"context"
 5
 6	"github.com/tetratelabs/wazero/api"
 7	"github.com/tetratelabs/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.
12type 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.
38type 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	// 	- `descFunc` is the type Index in Module.TypeSection of this imported function. It corresponds to Import.DescFunc.
48	// 	- `indexInImportedModule` is the function Index of the imported function in the imported module.
49	//	- `importedModuleEngine` is the ModuleEngine for the imported ModuleInstance.
50	ResolveImportedFunction(index, descFunc, indexInImportedModule Index, importedModuleEngine ModuleEngine)
51
52	// ResolveImportedMemory is called when this module imports a memory from another module.
53	ResolveImportedMemory(importedModuleEngine ModuleEngine)
54
55	// LookupFunction returns the FunctionModule and the Index of the function in the returned ModuleInstance at the given offset in the table.
56	LookupFunction(t *TableInstance, typeId FunctionTypeID, tableOffset Index) (*ModuleInstance, Index)
57
58	// GetGlobalValue returns the value of the global variable at the given Index.
59	// Only called when OwnsGlobals() returns true, and must not be called for imported globals
60	GetGlobalValue(idx Index) (lo, hi uint64)
61
62	// SetGlobalValue sets the value of the global variable at the given Index.
63	// Only called when OwnsGlobals() returns true, and must not be called for imported globals
64	SetGlobalValue(idx Index, lo, hi uint64)
65
66	// OwnsGlobals returns true if this ModuleEngine owns the global variables. If true, wasm.GlobalInstance's Val,ValHi should
67	// not be accessed directly.
68	OwnsGlobals() bool
69
70	// FunctionInstanceReference returns Reference for the given Index for a FunctionInstance. The returned values are used by
71	// the initialization via ElementSegment.
72	FunctionInstanceReference(funcIndex Index) Reference
73
74	// MemoryGrown notifies the engine that the memory has grown.
75	MemoryGrown()
76}