Edoardo Vacchi
2c14bbff3d
Add experimental support for the [Typed Function References](https://github.com/WebAssembly/function-references) proposal. Closes https://github.com/wazero/wazero/issues/2483, follows up to the refactoring in https://github.com/wazero/wazero/pull/2495 and prepares to WasmGC. Typed function references extend WebAssembly's type system with non-nullable reference types and concrete function type indices (`(ref $t)`, `(ref null $t)`), enabling direct calls through typed references (`call_ref`, `return_call_ref`) and null-aware branching (`br_on_null`, `br_on_non_null`, `ref.as_non_null`). Excluding tests and spec suites, the feature amounts to roughly 1,900 lines of code. Feature flag: `experimental.CoreFeaturesTypedFunctionReferences` ## What's the use for this? Sadly, very little. This proposal is a pretty much just a prerequisite for the GC proposal. On the flip side, it completes the exception handling spec (https://github.com/wazero/wazero/pull/2489): 1. two EH spec tests were previously skipped because they required distinguishing nullable from non-nullable references. Those tests now pass. 2. The fuzzer is now enabled for both exception handling and typed function references. It could not be enabled for EH because the fuzzer would generate func refs. So I guess, technically, it has a use :D ## Type System `ValueType` (already `uint64` introduced in https://github.com/wazero/wazero/pull/2495) is now extended with bit flags to encode nullability and concrete type indices: | Bits | Purpose | |-------|---------------------------------| | 0-7 | Base type byte (same as before) | | 8 | Non-nullable flag | | 9 | Concrete ref flag | | 32-63 | Type index (for `(ref $t)`) | This encoding should be fine for WasmGC too and should not require further changes in the near future. Subtyping rules: non-nullable is a subtype of nullable (same kind/index); concrete function refs `(ref $t)` are subtypes of `funcref`. ## New Instructions | Opcode | Hex | Description | |-------------------|--------|----------------------------------------------------------| | `call_ref` | `0x14` | Indirect call through a typed function reference | | `return_call_ref` | `0x15` | Tail-call variant of `call_ref` | | `ref.as_non_null` | `0xd4` | Assert ref is non-null, trap otherwise | | `br_on_null` | `0xd5` | Branch if null, push non-null ref on fall-through | | `br_on_non_null` | `0xd6` | Branch if non-null (carrying the ref), fall-through on null | ## Validation Tricky bits: - Non-nullable local initialization tracking: `local.get` on a non-nullable ref local is rejected unless a `local.set`/`local.tee` has been executed in the same or enclosing block scope. State is saved/restored at block boundaries per the spec (needed an additional field to keep track of init'd values) - `ref.func` now pushes `(ref $t)` (the concrete non-nullable type of the referenced function) onto the validation type stack instead of plain `funcref`, so that passing it to `call_ref` type-checks without an upcast. - Block types, element segments, table types, and const expressions all support concrete ref types. - The type section now validates forward references (standalone types can only reference previously defined types; rec group members can reference each other). ## Interpreter The five new opcodes are compiled to new IR operations and executed in the interpreter loop. `call_ref` / `return_call_ref` load the function instance from the opaque reference pointer, null-check, and dispatch. `br_on_null` / `br_on_non_null` pop the reference, check nullity, and either branch or fall through with the appropriate stack state. ## Compiler (wazevo) Implemented entirely as SSA-level lowering with no backend-specific code: - `call_ref` / `return_call_ref`: load executable and module context pointers from the function instance, null-check via `ExitIfTrueWithCode(ExitCodeNullReference)`, then dispatch as an indirect call. - `br_on_null` / `br_on_non_null`: compare against zero, branch with trampoline blocks for try-table exits and listener support. - `ref.as_non_null`: null-check with trap. ## Binary Decoding - `decodeRefType` helper extracted and shared across `value.go`, `element.go`, `table.go`, and `code.go` for consistent handling of `(ref null ht)` / `(ref ht)` prefixes. - Tables support the `0x40 0x00` prefix for initializer expressions (required for non-nullable table element types). - `DecodeBlockType` handles concrete ref types as block results. ## Cross-Module Linking `call_indirect` uses `FunctionTypeID` for fast runtime type checks. The existing `FunctionType.key()` method builds the key from raw `ValueType` bytes, but with concrete refs `(ref $0)` in module A and `(ref $0)` in module B may refer to structurally identical types at different local indices. `structuralTypeKey` fixes this by replacing local type indices with the already-assigned `FunctionTypeID` of the referenced type, so two modules with the same structural signature share a single `FunctionTypeID`. ## Spec Suite The spec test suite uses `wasm-tools json-from-wast` (same as exception handling). All 22 test files pass. ## Fuzzing The fuzzer (`nodiff`) now enables both `CoreFeaturesExceptionHandling` and `CoreFeaturesTypedFunctionReferences`. Dummy import generation handles `exnref` and concrete ref types. --------- Signed-off-by: Edoardo Vacchi <evacchi@users.noreply.github.com>
wazero: the zero dependency WebAssembly runtime for Go developers
WebAssembly is a way to safely run code compiled in other languages. Runtimes
execute WebAssembly Modules (Wasm), which are most often binaries with a .wasm
extension.
wazero is a WebAssembly Core Specification 1.0 and 2.0 compliant runtime written in Go. It has zero dependencies, and doesn't rely on CGO. This means you can run applications in other languages and still keep cross compilation.
Import wazero and extend your Go application with code written in any language!
Example
The best way to learn wazero is by trying one of our examples. The most basic example extends a Go application with an addition function defined in WebAssembly.
Runtime
There are two runtime configurations supported in wazero: Compiler is default:
By default, ex wazero.NewRuntime(ctx), the Compiler is used if supported. You
can also force the interpreter like so:
r := wazero.NewRuntimeWithConfig(ctx, wazero.NewRuntimeConfigInterpreter())
Interpreter
Interpreter is a naive interpreter-based implementation of Wasm virtual
machine. Its implementation doesn't have any platform (GOARCH, GOOS) specific
code, therefore interpreter can be used for any compilation target available
for Go (such as riscv64).
Compiler
Compiler compiles WebAssembly modules into machine code ahead of time (AOT),
during Runtime.CompileModule. This means your WebAssembly functions execute
natively at runtime. Compiler is faster than Interpreter, often by order of
magnitude (10x) or more. This is done without host-specific dependencies.
Conformance
Both runtimes pass WebAssembly Core 1.0 and 2.0 specification tests on supported platforms:
| Runtime | Usage | amd64 | arm64 | others |
|---|---|---|---|---|
| Interpreter | wazero.NewRuntimeConfigInterpreter() |
✅ | ✅ | ✅ |
| Compiler | wazero.NewRuntimeConfigCompiler() |
✅ | ✅ | ❌ |
Support Policy
The below support policy focuses on compatibility concerns of those embedding wazero into their Go applications.
wazero
wazero's 1.0 release happened in March 2023, and is in use by many projects and production sites.
We offer an API stability promise with semantic versioning. In other words, we promise to not break any exported function signature without incrementing the major version. This does not mean no innovation: New features and behaviors happen with a minor version increment, e.g. 1.0.11 to 1.2.0. We also fix bugs or change internal details with a patch version, e.g. 1.0.0 to 1.0.1.
You can get the latest version of wazero like this.
go get github.com/tetratelabs/wazero@latest
Please give us a star if you end up using wazero!
Go
wazero has no dependencies except Go and x/sys, so the only source of
conflict in your project's use of wazero is the Go version.
wazero follows the same version policy as Go's Release Policy: two versions. wazero will ensure these versions work and bugs are valid if there's an issue with a current Go version.
Platform
wazero has two runtime modes: Interpreter and Compiler. The only supported operating systems are ones we test, but that doesn't necessarily mean other operating system versions won't work.
We currently test Linux (Ubuntu and scratch), MacOS and Windows as packaged by GitHub Actions, as well as nested VMs running on Linux for FreeBSD, NetBSD, OpenBSD, DragonFly BSD, illumos and Solaris.
We also test cross compilation for many GOOS and GOARCH combinations.
- Interpreter
- Linux is tested on amd64, arm64 and riscv64.
- Windows, FreeBSD, NetBSD, OpenBSD, DragonFly BSD, illumos and Solaris are tested only on amd64.
- macOS is tested only on arm64.
- Compiler
- Linux is tested on amd64 and arm64.
- Windows, FreeBSD, NetBSD, DragonFly BSD, illumos and Solaris are tested only on amd64.
- macOS is tested only on arm64.
wazero has no dependencies and doesn't require CGO. This means it can also be embedded in an application that doesn't use an operating system. This is a main differentiator between wazero and alternatives.
We verify zero dependencies by running tests in Docker's scratch image. This approach ensures compatibility with any parent image.
macOS code-signing entitlements
If you're developing for macOS and need to code-sign your application, please read issue #2393.
wazero is a registered trademark of Tetrate.io, Inc. in the United States and/or other countries