Adds MustInstantiate to host imports (#814)

Signed-off-by: Adrian Cole <adrian@tetrate.io>

builder.go

@@ -137,6 +137,7 @@ type HostModuleBuilder interface {
 	Compile(context.Context) (CompiledModule, error)
 
 	// Instantiate is a convenience that calls Compile, then Namespace.InstantiateModule.
+	// This can fail for reasons documented on Namespace.InstantiateModule.
 	//
 	// Ex.
 	//

example_test.go

@@ -35,9 +35,7 @@ func Example() {
 
 	// Instantiate WASI, which implements host functions needed for TinyGo to
 	// implement `panic`.
-	if _, err := wasi_snapshot_preview1.Instantiate(ctx, r); err != nil {
+	wasi_snapshot_preview1.MustInstantiate(ctx, r)
-		log.Panicln(err)
-	}
 
 	// Instantiate the guest Wasm into the same runtime. It exports the `add`
 	// function, implemented in WebAssembly.

examples/allocation/tinygo/greet.go

@@ -40,9 +40,7 @@ func main() {
 
 	// Note: testdata/greet.go doesn't use WASI, but TinyGo needs it to
 	// implement functions such as panic.
-	if _, err = wasi_snapshot_preview1.Instantiate(ctx, r); err != nil {
+	wasi_snapshot_preview1.MustInstantiate(ctx, r)
-		log.Panicln(err)
-	}
 
 	// Instantiate a WebAssembly module that imports the "log" function defined
 	// in "env" and exports "memory" and functions we'll use in this example.

examples/basic/add.go

@@ -34,9 +34,7 @@ func main() {
 
 	// Instantiate WASI, which implements host functions needed for TinyGo to
 	// implement `panic`.
-	if _, err := wasi_snapshot_preview1.Instantiate(ctx, r); err != nil {
+	wasi_snapshot_preview1.MustInstantiate(ctx, r)
-		log.Panicln(err)
-	}
 
 	// Instantiate the guest Wasm into the same runtime. It exports the `add`
 	// function, implemented in WebAssembly.

experimental/fs_example_test.go

@@ -27,9 +27,7 @@ func Example_withFS() {
 	r := wazero.NewRuntime(ctx)
 	defer r.Close(ctx) // This closes everything this Runtime created.
 
-	if _, err := wasi_snapshot_preview1.Instantiate(ctx, r); err != nil {
+	wasi_snapshot_preview1.MustInstantiate(ctx, r)
-		log.Panicln(err)
-	}
 
 	// Instantiate a module exporting a WASI function that uses the filesystem.
 	mod, err := r.InstantiateModuleFromBinary(ctx, fsWasm)

experimental/listener_example_test.go

@@ -61,9 +61,7 @@ func Example_customListenerFactory() {
 	r := wazero.NewRuntimeWithConfig(ctx, wazero.NewRuntimeConfigInterpreter())
 	defer r.Close(ctx) // This closes everything this Runtime created.
 
-	if _, err := wasi_snapshot_preview1.Instantiate(ctx, r); err != nil {
+	wasi_snapshot_preview1.MustInstantiate(ctx, r)
-		log.Panicln(err)
-	}
 
 	// Compile the WebAssembly module using the default configuration.
 	code, err := r.CompileModule(ctx, listenerWasm, wazero.NewCompileConfig())

experimental/logging/log_listener_example_test.go

@@ -27,9 +27,7 @@ func Example_newLoggingListenerFactory() {
 	r := wazero.NewRuntimeWithConfig(ctx, wazero.NewRuntimeConfigInterpreter())
 	defer r.Close(ctx) // This closes everything this Runtime created.
 
-	if _, err := wasi_snapshot_preview1.Instantiate(ctx, r); err != nil {
+	wasi_snapshot_preview1.MustInstantiate(ctx, r)
-		log.Panicln(err)
-	}
 
 	// Compile the WebAssembly module using the default configuration.
 	code, err := r.CompileModule(ctx, listenerWasm, wazero.NewCompileConfig())

imports/assemblyscript/assemblyscript.go

@@ -45,11 +45,22 @@ const (
 	functionSeed  = "seed"
 )
 
+// MustInstantiate calls Instantiate or panics on error.
+//
+// This is a simpler function for those who know the module "env" is not
+// already instantiated, and don't need to unload it.
+func MustInstantiate(ctx context.Context, r wazero.Runtime) {
+	if _, err := Instantiate(ctx, r); err != nil {
+		panic(err)
+	}
+}
+
 // Instantiate instantiates the "env" module used by AssemblyScript into the
 // runtime default namespace.
 //
 // # Notes
 //
+//   - Failure cases are documented on wazero.Namespace InstantiateModule.
 //   - Closing the wazero.Runtime has the same effect as closing the result.
 //   - To add more functions to the "env" module, use FunctionExporter.
 //   - To instantiate into another wazero.Namespace, use FunctionExporter.

imports/assemblyscript/assemblyscript_example_test.go

@@ -3,7 +3,6 @@ package assemblyscript_test
 import (
 	"context"
 	_ "embed"
-	"log"
 
 	"github.com/tetratelabs/wazero"
 	"github.com/tetratelabs/wazero/imports/assemblyscript"
@@ -18,9 +17,7 @@ func Example_instantiate() {
 
 	// This adds the "env" module to the runtime, with AssemblyScript's special
 	// function imports.
-	if _, err := assemblyscript.Instantiate(ctx, r); err != nil {
+	assemblyscript.MustInstantiate(ctx, r)
-		log.Panicln(err)
-	}
 
 	// Output:
 }

imports/emscripten/emscripten.go

@@ -20,11 +20,22 @@ import (
 	"github.com/tetratelabs/wazero/internal/wasm"
 )
 
+// MustInstantiate calls Instantiate or panics on error.
+//
+// This is a simpler function for those who know the module "env" is not
+// already instantiated, and don't need to unload it.
+func MustInstantiate(ctx context.Context, r wazero.Runtime) {
+	if _, err := Instantiate(ctx, r); err != nil {
+		panic(err)
+	}
+}
+
 // Instantiate instantiates the "env" module used by Emscripten into the
 // runtime default namespace.
 //
 // # Notes
 //
+//   - Failure cases are documented on wazero.Namespace InstantiateModule.
 //   - Closing the wazero.Runtime has the same effect as closing the result.
 //   - To add more functions to the "env" module, use FunctionExporter.
 //   - To instantiate into another wazero.Namespace, use FunctionExporter.

imports/emscripten/emscripten_example_test.go

@@ -3,7 +3,6 @@ package emscripten_test
 import (
 	"context"
 	_ "embed"
-	"log"
 
 	"github.com/tetratelabs/wazero"
 	"github.com/tetratelabs/wazero/imports/emscripten"
@@ -18,14 +17,10 @@ func Example_instantiate() {
 	defer r.Close(ctx) // This closes everything this Runtime created.
 
 	// Add WASI which is typically required when using Emscripten.
-	if _, err := wasi_snapshot_preview1.Instantiate(ctx, r); err != nil {
+	wasi_snapshot_preview1.MustInstantiate(ctx, r)
-		log.Panicln(err)
-	}
 
 	// Now, add the "env" module to the runtime, Emscripten default imports.
-	if _, err := emscripten.Instantiate(ctx, r); err != nil {
+	emscripten.MustInstantiate(ctx, r)
-		log.Panicln(err)
-	}
 
 	// Output:
 }
@@ -39,9 +34,7 @@ func Example_functionExporter() {
 	defer r.Close(ctx) // This closes everything this Runtime created.
 
 	// Add WASI which is typically required when using Emscripten.
-	if _, err := wasi_snapshot_preview1.Instantiate(ctx, r); err != nil {
+	wasi_snapshot_preview1.MustInstantiate(ctx, r)
-		log.Panicln(err)
-	}
 
 	// Next, construct your own module builder for "env" with any functions
 	// you need.

imports/emscripten/emscripten_test.go

@@ -32,10 +32,9 @@ func TestGrow(t *testing.T) {
 	r := wazero.NewRuntimeWithConfig(ctx, wazero.NewRuntimeConfigInterpreter())
 	defer r.Close(ctx)
 
-	_, err := wasi_snapshot_preview1.Instantiate(ctx, r)
+	wasi_snapshot_preview1.MustInstantiate(ctx, r)
-	require.NoError(t, err)
 
-	_, err = Instantiate(ctx, r)
+	_, err := Instantiate(ctx, r)
 	require.NoError(t, err)
 
 	// Emscripten exits main with zero by default

imports/wasi_snapshot_preview1/example/cat.go

@@ -57,9 +57,7 @@ func main() {
 		WithStdout(os.Stdout).WithStderr(os.Stderr).WithFS(rooted)
 
 	// Instantiate WASI, which implements system I/O such as console output.
-	if _, err = wasi_snapshot_preview1.Instantiate(ctx, r); err != nil {
+	wasi_snapshot_preview1.MustInstantiate(ctx, r)
-		log.Panicln(err)
-	}
 
 	// Choose the binary we want to test. Most compilers that implement WASI
 	// are portable enough to use binaries interchangeably.

imports/wasi_snapshot_preview1/wasi.go

@@ -10,7 +10,7 @@
 //	r := wazero.NewRuntime(ctx)
 //	defer r.Close(ctx) // This closes everything this Runtime created.
 //
-//	_, _ = Instantiate(ctx, r)
+//	wasi_snapshot_preview1.MustInstantiate(ctx, r)
 //	mod, _ := r.InstantiateModuleFromBinary(ctx, wasm)
 //
 // See https://github.com/WebAssembly/WASI
@@ -30,11 +30,22 @@ import (
 const ModuleName = "wasi_snapshot_preview1"
 const i32, i64 = wasm.ValueTypeI32, wasm.ValueTypeI64
 
+// MustInstantiate calls Instantiate or panics on error.
+//
+// This is a simpler function for those who know the module ModuleName is not
+// already instantiated, and don't need to unload it.
+func MustInstantiate(ctx context.Context, r wazero.Runtime) {
+	if _, err := Instantiate(ctx, r); err != nil {
+		panic(err)
+	}
+}
+
 // Instantiate instantiates the ModuleName module into the runtime default
-// namespace.
+// namespace..
 //
 // # Notes
 //
+//   - Failure cases are documented on wazero.Namespace InstantiateModule.
 //   - Closing the wazero.Runtime has the same effect as closing the result.
 //   - To instantiate into another wazero.Namespace, use NewBuilder instead.
 func Instantiate(ctx context.Context, r wazero.Runtime) (api.Closer, error) {

internal/integration_test/bench/bench_test.go

@@ -224,9 +224,6 @@ func createRuntime(b *testing.B, config wazero.RuntimeConfig) wazero.Runtime {
 
 	// Note: host_func.go doesn't directly use WASI, but TinyGo needs to be initialized as a WASI Command.
 	// Add WASI to satisfy import tests
-	_, err = wasi_snapshot_preview1.Instantiate(testCtx, r)
+	wasi_snapshot_preview1.MustInstantiate(testCtx, r)
-	if err != nil {
-		b.Fatal(err)
-	}
 	return r
 }

internal/integration_test/bench/codec_test.go

@@ -96,16 +96,14 @@ func TestExampleUpToDate(t *testing.T) {
 
 	t.Run("Executable", func(t *testing.T) {
 		r := wazero.NewRuntimeWithConfig(testCtx, wazero.NewRuntimeConfig())
+		defer r.Close(testCtx)
 
 		// Add WASI to satisfy import tests
-		wm, err := wasi_snapshot_preview1.Instantiate(testCtx, r)
+		wasi_snapshot_preview1.MustInstantiate(testCtx, r)
-		require.NoError(t, err)
-		defer wm.Close(testCtx)
 
 		// Decode and instantiate the module
 		module, err := r.InstantiateModuleFromBinary(testCtx, exampleWasm)
 		require.NoError(t, err)
-		defer module.Close(testCtx)
 
 		// Call the swap function as a smoke test
 		results, err := module.ExportedFunction("swap").Call(testCtx, 1, 2)

internal/integration_test/fs/fs_test.go

@@ -152,8 +152,7 @@ func TestReader(t *testing.T) {
 	r := wazero.NewRuntime(testCtx)
 	defer r.Close(testCtx)
 
-	_, err := wasi_snapshot_preview1.Instantiate(testCtx, r)
+	wasi_snapshot_preview1.MustInstantiate(testCtx, r)
-	require.NoError(t, err)
 
 	realFs := fstest.MapFS{"animals.txt": &fstest.MapFile{Data: animals}}
 	sys := wazero.NewModuleConfig().WithFS(realFs)