Repository: tetratelabs/wazero
Pull request #351 (2022-03-09 04:18:16)

Renames Runtime.DecodeModule to CompileModule
The best way to reduce performance impact of instantiating a module
multiple times is lowering it to wazero's IR or even generating
assembly. This renames `DecodeModule` to `CompileModule` to allow that
sort of side-effect to be obvious even if it isn't currently
implemented.



Patch:
diff --git a/builder.go b/builder.go
index 1836f90a..726b049e 100644
--- a/builder.go
+++ b/builder.go
@@ -114,7 +114,7 @@ func (b *moduleBuilder) Build() (*Module, error) {
 	}
 }
 
-// InstantiateModule implements ModuleBuilder.InstantiateModule
+// Instantiate implements ModuleBuilder.Instantiate
 func (b *moduleBuilder) Instantiate() (wasm.Module, error) {
 	if module, err := b.Build(); err != nil {
 		return nil, err
diff --git a/wasi.go b/wasi.go
index f312f9e9..b818f657 100644
--- a/wasi.go
+++ b/wasi.go
@@ -88,9 +88,9 @@ func WASISnapshotPreview1WithConfig(c *WASIConfig) *Module {
 //	wasi, _ := r.NewHostModule(wazero.WASISnapshotPreview1())
 //	module, _ := StartWASICommandFromSource(r, source)
 //
-// Note: This is a convenience utility that chains Runtime.DecodeModule with StartWASICommand.
+// Note: This is a convenience utility that chains Runtime.CompileModule with StartWASICommand.
 func StartWASICommandFromSource(r Runtime, source []byte) (wasm.Module, error) {
-	if decoded, err := r.DecodeModule(source); err != nil {
+	if decoded, err := r.CompileModule(source); err != nil {
 		return nil, err
 	} else {
 		return StartWASICommand(r, decoded)
@@ -104,7 +104,7 @@ func StartWASICommandFromSource(r Runtime, source []byte) (wasm.Module, error) {
 // Ex.
 //	r := wazero.NewRuntime()
 //	wasi, _ := r.NewHostModule(wazero.WASISnapshotPreview1())
-//	decoded, _ := r.DecodeModule(source)
+//	decoded, _ := r.CompileModule(source)
 //	module, _ := StartWASICommand(r, decoded)
 //
 // Prerequisites of the "Current Unstable ABI" from wasi.ModuleSnapshotPreview1:
diff --git a/wasm.go b/wasm.go
index 92903302..20e0854c 100644
--- a/wasm.go
+++ b/wasm.go
@@ -14,7 +14,7 @@ import (
 //
 // Ex.
 //	r := wazero.NewRuntime()
-//	decoded, _ := r.DecodeModule(source)
+//	decoded, _ := r.CompileModule(source)
 //	module, _ := r.InstantiateModule(decoded)
 //
 // See https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/
@@ -32,11 +32,12 @@ type Runtime interface {
 	// Module returns exports from an instantiated module or nil if there aren't any.
 	Module(moduleName string) wasm.Module
 
-	// DecodeModule decodes the WebAssembly 1.0 (20191205) text or binary source or errs if invalid.
+	// CompileModule decodes the WebAssembly 1.0 (20191205) text or binary source or errs if invalid.
+	// Any pre-compilation done after decoding the source is dependent on the RuntimeConfig.
 	//
-	// Note: the name defaults to what was decoded from the custom name section.
+	// Note: The resulting module name defaults to what was decoded from the custom name section.
 	// See https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/#name-section%E2%91%A0
-	DecodeModule(source []byte) (*Module, error)
+	CompileModule(source []byte) (*Module, error)
 
 	// InstantiateModuleFromSource instantiates a module from the WebAssembly 1.0 (20191205) text or binary source or
 	// errs if invalid.
@@ -44,15 +45,15 @@ type Runtime interface {
 	// Ex.
 	//	module, _ := wazero.NewRuntime().InstantiateModuleFromSource(source)
 	//
-	// Note: This is a convenience utility that chains DecodeModule with InstantiateModule. To instantiate the same source
-	// multiple times, use DecodeModule as InstantiateModule avoids redundant decoding and/or compilation.
+	// Note: This is a convenience utility that chains CompileModule with InstantiateModule. To instantiate the same
+	// source multiple times, use CompileModule as InstantiateModule avoids redundant decoding and/or compilation.
 	InstantiateModuleFromSource(source []byte) (wasm.Module, error)
 
 	// InstantiateModule instantiates the module namespace or errs if the configuration was invalid.
 	//
 	// Ex.
 	//	r := wazero.NewRuntime()
-	//	decoded, _ := r.DecodeModule(source)
+	//	decoded, _ := r.CompileModule(source)
 	//	module, _ := r.InstantiateModule(decoded)
 	//
 	// Note: The last value of RuntimeConfig.WithContext is used for any WebAssembly 1.0 (20191205) Start ExportedFunction.
@@ -84,8 +85,8 @@ func (r *runtime) Module(moduleName string) wasm.Module {
 	return r.store.Module(moduleName)
 }
 
-// DecodeModule implements Runtime.DecodeModule
-func (r *runtime) DecodeModule(source []byte) (*Module, error) {
+// CompileModule implements Runtime.CompileModule
+func (r *runtime) CompileModule(source []byte) (*Module, error) {
 	if source == nil {
 		return nil, errors.New("source == nil")
 	}
@@ -121,7 +122,7 @@ func (r *runtime) DecodeModule(source []byte) (*Module, error) {
 
 // InstantiateModuleFromSource implements Runtime.InstantiateModuleFromSource
 func (r *runtime) InstantiateModuleFromSource(source []byte) (wasm.Module, error) {
-	if decoded, err := r.DecodeModule(source); err != nil {
+	if decoded, err := r.CompileModule(source); err != nil {
 		return nil, err
 	} else {
 		return r.InstantiateModule(decoded)


Test patch:
diff --git a/wasi_test.go b/wasi_test.go
index 9b8096c1..7125d19d 100644
--- a/wasi_test.go
+++ b/wasi_test.go
@@ -27,7 +27,7 @@ func TestStartWASICommand_UsesStoreContext(t *testing.T) {
 	_, err = r.InstantiateModule(WASISnapshotPreview1())
 	require.NoError(t, err)
 
-	decoded, err := r.DecodeModule([]byte(`(module $wasi_test.go
+	decoded, err := r.CompileModule([]byte(`(module $wasi_test.go
 	(import "" "start" (func $start))
 	(memory 1)
 	(export "_start" (func $start))
diff --git a/wasm_test.go b/wasm_test.go
index 638410c5..afac2088 100644
--- a/wasm_test.go
+++ b/wasm_test.go
@@ -52,7 +52,7 @@ func TestRuntime_DecodeModule(t *testing.T) {
 		tc := tt
 
 		t.Run(tc.name, func(t *testing.T) {
-			decoded, err := r.DecodeModule(tc.source)
+			decoded, err := r.CompileModule(tc.source)
 			require.NoError(t, err)
 			require.Equal(t, tc.expectedName, decoded.name)
 		})
@@ -86,7 +86,7 @@ func TestRuntime_DecodeModule_Errors(t *testing.T) {
 		tc := tt
 
 		t.Run(tc.name, func(t *testing.T) {
-			_, err := r.DecodeModule(tc.source)
+			_, err := r.CompileModule(tc.source)
 			require.EqualError(t, err, tc.expectedErr)
 		})
 	}
@@ -96,7 +96,7 @@ func TestRuntime_DecodeModule_Errors(t *testing.T) {
 // names. This pattern is used in wapc-go.
 func TestDecodedModule_WithName(t *testing.T) {
 	r := NewRuntime()
-	base, err := r.DecodeModule([]byte(`(module $0 (memory 1))`))
+	base, err := r.CompileModule([]byte(`(module $0 (memory 1))`))
 	require.NoError(t, err)
 
 	require.Equal(t, "0", base.name)
@@ -138,7 +138,7 @@ func TestModule_Memory(t *testing.T) {
 
 		r := NewRuntime()
 		t.Run(tc.name, func(t *testing.T) {
-			decoded, err := r.DecodeModule([]byte(tc.wat))
+			decoded, err := r.CompileModule([]byte(tc.wat))
 			require.NoError(t, err)
 
 			// Instantiate the module and get the export of the above hostFn
@@ -276,7 +276,7 @@ func TestFunction_Context(t *testing.T) {
 			source := requireImportAndExportFunction(t, r, hostFn, functionName)
 
 			// Instantiate the module and get the export of the above hostFn
-			decoded, err := r.DecodeModule(source)
+			decoded, err := r.CompileModule(source)
 			require.NoError(t, err)
 
 			module, err := r.InstantiateModule(decoded)
@@ -306,7 +306,7 @@ func TestRuntime_NewModule_UsesStoreContext(t *testing.T) {
 	_, err := r.NewModuleBuilder("").ExportFunction("start", start).Instantiate()
 	require.NoError(t, err)
 
-	decoded, err := r.DecodeModule([]byte(`(module $runtime_test.go
+	decoded, err := r.CompileModule([]byte(`(module $runtime_test.go
 	(import "" "start" (func $start))
 	(start $start)
 )`))