Skip to content
🐹🕸️ Go library to run WebAssembly binaries.
Branch: master
Clone or download
bors and Hywan Merge #42
42: feat(instance,module) Improve error messages r=Hywan a=Hywan

Fix #41.

These patches improve error messages when instantiating a module with `Module.Instantiate` or with `NewInstance`.

The error message that is returned by `Module.Instantiate` isn't very helpful, but it's going to change with wasmerio/wasmer#493. Let's wait the next release of the runtime!

Co-authored-by: Ivan Enderlin <ivan.enderlin@hoa-project.net>
Latest commit 722faa9 Jun 12, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci test(circleci) Install Go on macOS. Jun 3, 2019
.github/ISSUE_TEMPLATE feat(github) Add Github templates. May 28, 2019
benchmarks test(benchmarks) Update `wasmer` to the latest `wasmer` version. May 29, 2019
go-wasmer feat(go-wasmer) New package to get CLI support. Jun 3, 2019
src feat(extension) First baby step. May 3, 2019
wasmer test(module) Test enhanced errors when compiling a module. Jun 12, 2019
.gitignore chore(runtime) Distribute the runtime dylib (tentative). May 27, 2019
Cargo.lock fix(runtime) Update Wasmer to 0.4.2. May 22, 2019
Cargo.toml chore(release) Bump version. May 29, 2019
LICENSE doc(license) Add a `LICENSE` file. May 21, 2019
README.md doc(readme) Improve the Benchmarks Section. Jun 7, 2019
bors.toml test(circleci) Build and test on macOS. May 29, 2019
go.mod feat(go-wasmer) New package to get CLI support. Jun 3, 2019
go.sum feat(go-wasmer) New package to get CLI support. Jun 3, 2019
justfile

README.md

Wasmer logo

Join the Wasmer Community Read our API documentation Go Report Card License

Wasmer is a Go library for executing WebAssembly binaries.

Install

To install the library, follow the classical:

$ go get github.com/wasmerio/go-ext-wasm/wasmer

To install the go-wasmer CLI, follow the classical:

$ go install github.com/wasmerio/go-ext-wasm/go-wasmer

go install will work on many macOS and Linux distributions. It will not work on Windows yet, we are working on it.

Documentation

The documentation can be read online on godoc.org. It contains function descriptions, short examples, long examples etc. Everything one need to start using Wasmer with Go!

Also, there is this article written for the announcement that introduces the project: Announcing the fastest WebAssembly runtime for Go: wasmer.

Examples

Basic example: Exported function

There is a toy program in wasmer/test/testdata/examples/simple.rs, written in Rust (or any other language that compiles to WebAssembly):

#[no_mangle]
pub extern fn sum(x: i32, y: i32) -> i32 {
    x + y
}

After compilation to WebAssembly, the wasmer/test/testdata/examples/simple.wasm binary file is generated. (Download it).

Then, we can execute it in Go:

package main

import (
	"fmt"
	wasm "github.com/wasmerio/go-ext-wasm/wasmer"
)

func main() {
	// Reads the WebAssembly module as bytes.
	bytes, _ := wasm.ReadBytes("simple.wasm")
	
	// Instantiates the WebAssembly module.
	instance, _ := wasm.NewInstance(bytes)
	defer instance.Close()

	// Gets the `sum` exported function from the WebAssembly instance.
	sum := instance.Exports["sum"]

	// Calls that exported function with Go standard values. The WebAssembly
	// types are inferred and values are casted automatically.
	result, _ := sum(5, 37)

	fmt.Println(result) // 42!
}

Imported function

A WebAssembly module can export functions, this is how to run a WebAssembly function, like we did in the previous example with instance.Exports["sum"](1, 2). Nonetheless, a WebAssembly module can depend on “extern functions”, then called imported functions. For instance, let's consider the basic following Rust program:

extern {
    fn sum(x: i32, y: i32) -> i32;
}

#[no_mangle]
pub extern fn add1(x: i32, y: i32) -> i32 {
    unsafe { sum(x, y) + 1 }
}

In this case, the add1 function is a WebAssembly exported function, whilst the sum function is a WebAssembly imported function (the WebAssembly instance needs to import it to complete the program). Good news: We can write the implementation of the sum function directly in Go!

First, we need to declare the sum function signature in C inside a Go comment (with the help of cgo):

package main

// #include <stdlib.h>
//
// extern int32_t sum(void *context, int32_t x, int32_t y);
import "C"

Second, we declare the sum function implementation in Go. Notice the //export which is the way cgo uses to map Go code to C code.

//export sum
func sum(context unsafe.Pointer, x int32, y int32) int32 {
	return x + y
}

Third, we use NewImports to create the WebAssembly imports. In this code:

  • "sum" is the imported function name,
  • sum is the Go function pointer, and
  • C.sum is the cgo function pointer.
imports, _ := wasm.NewImports().Append("sum", sum, C.sum)

Finally, we use NewInstanceWithImports to inject the imports:

bytes, _ := wasm.ReadBytes("imported_function.wasm")
instance, _ := wasm.NewInstanceWithImports(bytes, imports)
defer instance.Close()

// Gets and calls the `add1` exported function from the WebAssembly instance.
results, _ := instance.Exports["add1"](1, 2)

fmt.Println(result)
//   add1(1, 2)
// = sum(1 + 2) + 1
// = 1 + 2 + 1
// = 4
// QED

Read the memory

A WebAssembly instance has a linear memory. Let's see how to read it. Consider the following Rust program:

#[no_mangle]
pub extern fn return_hello() -> *const u8 {
    b"Hello, World!\0".as_ptr()
}

The return_hello function returns a pointer to a string. This string is stored in the WebAssembly memory. Let's read it.

bytes, _ := wasm.ReadBytes("memory.wasm")
instance, _ := wasm.NewInstance(bytes)
defer instance.Close()

// Calls the `return_hello` exported function.
// This function returns a pointer to a string.
result, _ := instance.Exports["return_hello"]()

// Gets the pointer value as an integer.
pointer := result.ToI32()

// Reads the memory.
memory := instance.Memory.Data()

fmt.Println(string(memory[pointer : pointer+13])) // Hello, World!

In this example, we already know the string length, and we use a slice to read a portion of the memory directly. Notice that the string terminates by a null byte, which means we could iterate over the memory starting from pointer until a null byte is met; that's a similar approach.

For a more complete example, see the Greet Example.

Development

The Go library is written in Go and Rust.

To build both parts, run the following commands:

$ just rust
$ just go

To build the Go part, run:

(Yes, you need just).

Testing

Once the library is build, run the following command:

$ just test

Benchmarks

We compared Wasmer to Wagon and Life. The benchmarks are in benchmarks/. The computer that ran these benchmarks is a MacBook Pro 15" from 2016, 2.9Ghz Core i7 with 16Gb of memory. Here are the results in a table (the lower the ratio is, the better):

Benchmark Runtime Time (ms) Ratio
N-Body Wasmer 42.078
Wagon 1841.950 44×
Life 1976.215 47×
Fibonacci (recursive) Wasmer 28.559
Wagon 3238.050 113×
Life 3029.209 106×
Pollard rho 128 Wasmer 37.478
Wagon 2165.563 58×
Life 2407.752 64×

While both Life and Wagon provide on average the same speed, Wasmer is on average 72 times faster.

Put on a graph, it looks like this (reminder: the lower, the better):

Benchmark results

What is WebAssembly?

Quoting the WebAssembly site:

WebAssembly (abbreviated Wasm) is a binary instruction format for a stack-based virtual machine. Wasm is designed as a portable target for compilation of high-level languages like C/C++/Rust, enabling deployment on the web for client and server applications.

About speed:

WebAssembly aims to execute at native speed by taking advantage of common hardware capabilities available on a wide range of platforms.

About safety:

WebAssembly describes a memory-safe, sandboxed execution environment […].

License

The entire project is under the MIT License. Please read the LICENSE file.

You can’t perform that action at this time.