wazero

Files

Crypt Keeper be33572289 Adds HostFunctionBuilder to enable high performance host functions (#828 )

This PR follows @hafeidejiangyou advice to not only enable end users to
avoid reflection when calling host functions, but also use that approach
ourselves internally. The performance results are staggering and will be
noticable in high performance applications.

Before
```
BenchmarkHostCall/Call
BenchmarkHostCall/Call-16            	 1000000	      1050 ns/op
Benchmark_EnvironGet/environGet
Benchmark_EnvironGet/environGet-16         	  525492	      2224 ns/op
```

Now
```
BenchmarkHostCall/Call
BenchmarkHostCall/Call-16            	14807203	        83.22 ns/op
Benchmark_EnvironGet/environGet
Benchmark_EnvironGet/environGet-16         	  951690	      1054 ns/op
```

To accomplish this, this PR consolidates code around host function
definition and enables a fast path for functions where the user takes
responsibility for defining its WebAssembly mappings. Existing users
will need to change their code a bit, as signatures have changed.

For example, we are now more strict that all host functions require a
context parameter zero. Also, we've replaced
`HostModuleBuilder.ExportFunction` and `ExportFunctions` with a new type
`HostFunctionBuilder` that consolidates the responsibility and the
documentation.

```diff
 ctx := context.Background()
-hello := func() {
+hello := func(context.Context) {
         fmt.Fprintln(stdout, "hello!")
 }
-_, err := r.NewHostModuleBuilder("env").ExportFunction("hello", hello).Instantiate(ctx, r)
+_, err := r.NewHostModuleBuilder("env").
+        NewFunctionBuilder().WithFunc(hello).Export("hello").
+        Instantiate(ctx, r)
```

Power users can now use `HostFunctionBuilder` to define functions that
won't use reflection. There are two choices of interfaces to use
depending on if that function needs access to the calling module or not:
`api.GoFunction` and `api.GoModuleFunction`. Here's an example defining
one.

```go
builder.WithGoFunction(api.GoFunc(func(ctx context.Context, params []uint64) []uint64 {
	x, y := uint32(params[0]), uint32(params[1])
	sum := x + y
	return []uint64{sum}
}, []api.ValueType{api.ValueTypeI32, api.ValueTypeI32}, []api.ValueType{api.ValueTypeI32})
```
As you'll notice and as documented, this approach is more verbose and
not for everyone. If you aren't making a low-level library, you are
likely able to afford the 1us penalty for the convenience of reflection.
However, we are happy to enable this option for foundational libraries
and those with high performance requirements (like ourselves)!

Fixes #825

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

2022-10-28 07:51:08 -07:00

testdata

Updates all 3rd party dependencies (#802 )

2022-09-07 11:02:26 +08:00

greet_test.go

Adds Zig example (#741 )

2022-08-11 16:31:06 +08:00

greet.go

Adds HostFunctionBuilder to enable high performance host functions (#828 )

2022-10-28 07:51:08 -07:00

README.md

Stops using "ex." to abbreviate "for example" (#827 )

2022-10-24 11:51:48 +09:00

README.md

Zig allocation example

This example shows how to pass strings in and out of a Wasm function defined in Zig, built with zig build.

$ go run greet.go wazero
wasm >> Hello, wazero!
go >> Hello, wazero!

greet.zig does a few things of interest:

Uses @ptrToInt to change a Zig pointer to a numeric type
Uses [*]u8 as an argument to take a pointer and slices it to build back a string

The Zig code exports "malloc" and "free", which we use for that purpose.

Notes

This example uses @panic() rather than unreachable to handle errors since unreachable emits a call to panic only in Debug and ReleaseSafe mode. In ReleaseFast and ReleaseSmall mode, it would lead into undefined behavior.

If building wasm with a pre-release version of Zig 0.10.0, use -fstage1 to avoid bugs in the new compiler.