WebAssembly is a portable binary format. That means the same file can run anywhere.

To uphold this bold statement, each language, platform and system must be able to run WebAssembly — as fast and safely as possible.

Wasmer is a WebAssembly runtime written in Rust. It goes without saying that the runtime can be used in any Rust application. We have also successfully embedded the runtime in other languages:

We are super happy to announce github.com/wasmerio/go-ext-wasm/wasmer , a Go library to run WebAssembly binaries, fast.

Calling a WebAssembly function from Go

First, let’s install wasmer in your go environment (with cgo support).

export CGO_ENABLED=1; export CC=gcc; go install github.com/wasmerio/go-ext-wasm/wasmer

Let’s jump immediately into some examples. github.com/wasmerio/go-ext-wasm/wasmer is a regular Go library. The installation is automated with import "github.com/wasmerio/go-ext-wasm/wasmer" .

Let’s get our hands dirty. We will write a program that compiles to WebAssembly easily, using Rust for instance:

simple.rs, a small Rust program that compiles to WebAssembly.

After compilation to WebAssembly, we get a file like this one, named simple.wasm .

The following Go program executes the sum function by passing 5 and 37 as arguments:

simple.go, a small Go program that executes the WebAssembly file (result of the compilation of the Rust program).

Great! We have successfully executed a WebAssembly file inside Go.

Note: Go values passed to the WebAssembly exported function are automatically cast to WebAssembly values. Types are inferred and casting is done automatically. Thus, a WebAssembly function acts as any regular Go function.

WebAssembly calling Go funtions

A WebAssembly module exports some functions, so that they can be called from the outside world. This is the entry point to execute WebAssembly.

Nonetheless, a WebAssembly module can also have imported functions. Let’s consider the following Rust program:

import.rs, the sum function implementation is in another language. Download the WebAssembly file here

The exported function add1 calls the sum function. Its implementation is absent, only its signature is defined. This is an “extern function”, and for WebAssembly, this is an imported function, because its implementation must be imported.

Let’s implement the sum function in Go! To do so, need to use cgo:

The sum function signature is defined in C (see the comment above import "C" ), The sum implementation is defined in Go. Notice the //export which is the way cgo uses to map Go code to C code, NewImports is an API used to create WebAssembly imports. In this code "sum" is the WebAssembly imported function name, sum is the Go function pointer, and C.sum is the cgo function pointer, Finally, NewInstanceWithImports is the constructor to use to instantiate the WebAssembly module with imports. That’s it.

Let’s see the complete program:

import.go, the sum implementation is written in Go.

Reading the memory

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

memory.rs, a small Rust function that returns a pointer to a string.

The return_hello function returns a pointer to a string. The string terminates by a null byte, à la C. Let’s jump on the Go side:

memory.go, a Go program that reads a string based on a pointer returned by WebAssembly.

The return_hello function returns a pointer as an i32 value. We get its value by calling ToI32 . Then, we fetch the memory data with instance.Memory.Data() .

This function returns a slice over the WebAssembly instance memory. It can be used as any regular Go slice.

Fortunately for us, we already know the length of the string we want to read, so memory[pointer : pointer+13] is enough to read the bytes, that are then cast to a string. Et voilà !

You can read the Greet Example to see a more advanced usage of the memory API.

Benchmarks

So far, github.com/wasmerio/go-ext-wasm/wasmer has a nice API, but …is it fast?

Contrary to PHP or Ruby, there are already existing runtimes in the Go world to execute WebAssembly. The main candidates are:

Life, from Perlin Network, a WebAssembly interpreter

Wagon, from Go Interpreter, a WebAssembly interpreter and toolkit.

In our blog post about the PHP extension, we have used the n-body algorithm to benchmark the performance. Life provides more benchmarks: the Fibonacci algorithm (the recursive version), the Pollard’s rho algorithm, and the Snappy Compress operation. The latter works successfully with github.com/wasmerio/go-ext-wasm/wasmer but not with Life or Wagon. We have removed it from the benchmark suites. Benchmark sources are online.

We use Life 20190521143330–57f3819c2df0, and Wagon 0.4.0, i.e. the latest versions to date.

The benchmark numbers represent the average result for 10 runs each. The computer that ran these benchmarks is a MacBook Pro 15" from 2016, 2.9Ghz Core i7 with 16Gb of memory.

Results are grouped by benchmark algorithm on the X axis. The Y axis represents the time used to run the algorithm, expressed in milliseconds. The lower, the better.