Atomic Operations in WebAssembly

Although a full treatment of every WebAssembly instruction would be out of place in this book, it’s worth pointing out the instructions specific to atomic operations on shared memory, since they’re key to multithreaded WebAssembly code, whether compiled from another language, or hand-written in WAT.

WebAssembly instructions often start with the type. In the case of atomic operations, the type is always i32 or i64, corresponding to 32-bit and 64-bit integers respectively. All atomic operations have .atomic. next in the instruction name. After that, you’ll find the specific instruction name.

Let’s go over some of the atomic operation instructions. We won’t go over exact syntax, but this should give you an idea of the kinds of operations available at the instruction level:

[i32|i64].atomic.[load|load8_u|load16_u|load32_u]

The load family of instructions is equivalent to Atomics.load() in JavaScript. Using one of the suffixed instructions allows you to load smaller numbers of bits, extending the result with zeros.

[i32|i64].atomic.[store|store8|store16|store32]

The store family of instructions is equivalent to Atomics.store() in JavaScript. Using one of the suffixed instructions wraps the input value to that number of bits, and stores those at the index.

[i32|i64].atomic.[rmw|rmw8|rmw16|rmw32].[add|sub|and|or|xor|xchg|cmpxchg][|_u]

The rmw family of instructions all perform read-modify-write operations, equivalent to add(), sub(), and(), or(), xor(), exchange(), and compareExchnage() from the Atomics object in JavaScript, respectively. The operations are suffixed with a _u when they zero-extend, and rmw can have a suffix corresponding to the number of bits to be read.

The next two operations have a slightly different naming convention:

memory.atomic.[wait32|wait64]

These are equivalent to Atomics.wait() in JavaScript, suffixed according to the number of bits they operate on.

memory.atomic.notify

This is equivalent to Atomics.notify() in JavaScript.

These instructions are enough to perform the same atomic operations in WebAssembly as we can in JavaScript, but there’s an additional operation not available in JavaScript:

atomic.fence

This instruction takes no arguments and doesn’t return anything. It’s intended to be used by higher level languages that have ways of guaranteeing ordering of non-atomic accesses to shared memory.

All of these operations are used with the given WebAssembly module’s linear memory, which is the sandbox in which it gets to read and write values. When WebAssembly modules are initialized from JavaScript, they can be initialized with a linear memory provided provided as an option. This can be backed by a SharedArrayBuffer to enable usage across threads.

Although it’s certainly possible to use these instructions in WebAssembly, they suffer from the same drawback that the rest of WebAssembly does: it’s incredibly tedious and painstaking to write. Luckily, we can compile higher-level languages down to WebAssembly.

Other WebAssembly Compilers

Emscripten isn’t the only way to compile code to WebAssembly. Indeed, WebAssembly was designed primarily as a compile target, rather than as a general-purpose language in its own right. There are myriad tools for compiling well-known languages to WebAssembly, and there are even some languages built with WebAssembly as the main target in mind, rather than machine code. Some are listed here, but it’s by no means exhaustive. You’ll notice a lot of “at time of writing” here, because this space is relatively new and the best ways of creating multithreaded WebAssembly code are still being developed! At least, at time of writing.

Clang/Clang++

The LLVM C-family compilers can target WebAssembly with the -target wasm32-unknown-unkown or -target wasm64-unknown-unkown options respectively. This is actually what Emscripten is now based on, in which POSIX threads and atomic operations work as expected. At time of writing, this is some of the best support for multithreaded WebAssembly. While clang and clang++ support WebAssembly output, the recommended approach is to use Emscripten, to get the full suite of platform support in browsers and Node.js.

Rustc

The Rust programming language compiler rustc supports WebAssembly output. The Rust website is a great starting point on how to use rustc in this way. To make use of threads, you can use the wasm-bindgen-rayon crate, which provides a parallelism API implemented using WebWorkers. At time of writing, Rust’s standard library thread support won’t work.

AssemblyScript

The AssemblyScript compiler takes a subset of TypeScript as input, generates WebAssembly output. While it does not support spawning threads, it does support atomic operations and using SharedArrayBuffers, so as long as you handle the threads themselves on the JavaScript side via web workers or worker_threads, you can make full use of multithreaded programming in AssemblyScript. We’ll cover it in more depth in “AssemblyScript”.

There are, of course, many more options, with new ones arriving all the time. It’s worth having a look around the web to see if your compiled language of choice can target WebAssembly, and whether or not it supports atomic operations in WebAssembly.

Happycoin in AssemblyScript

Much like previous versions of our Happycoin example, this approach multiplexes the crunching of numbers over several threads and sends the results back. It’s a glimpse of how multithreaded AssemblyScript can work. In a real-world application, you’d want to take advantage of shared memory and atomic operations but to keep things simple, we’ll stick with just fanning the work out to the threads.

Let’s begin by creating a directory called ch7-happycoin-as and switch to that directory. We’ll initialize a new project and add some necessary dependencies as follows:

$ npm init -y
$ npm install assemblyscript
$ npm install @asssemblyscript/loader

The assemblyscript package includes the AssemblyScript compiler, and the assemblyscript/loader package give us handy tools for interacting with the built module.

In the scripts object in the newly-created package.json, we’ll add "build" and "start" properties to simplify the compilation and running of the program:

"build": "asc happycoin.ts --binaryFile happycoin.wasm --exportRuntime",
"start": "node --no-warnings --experimental-wasi-unstable-preview1 happycoin.mjs"

The additional --exportRuntime parameter gives us some high-level tools for interacting with values from AssemblyScript. We’ll get into that a bit later.

When invoking Node.js in the "start" script, we pass the experimental WASI flag. This enables the WASI interface, giving WebAssembly access to system-level functionality that would otherwise be inaccessible. We’ll use this from AssemblyScript to generate random numbers. Because it’s experimental at time of writing, we’ll add the --no-warnings flag² to suppress the warning we get for using WASI. The experimental status also means the flag may change in the future, so always be sure to consult the Node.js documentation for the version of Node.js you’re running.

Now, let’s write some AssemblyScript! Example 7-5 contains an AssemblyScript version of the Happycoin algorithm. Go ahead and add it to a file called happycoin.ts.

import 'wasi'; 

const randArr64 = new Uint64Array(1);
const randArr8 = Uint8Array.wrap(randArr64.buffer, 0, 8); 
function random64(): u64 {
  crypto.getRandomValues(randArr8); 
  return randArr64[0];
}

function sumDigitsSquared(num: u64): u64 {
  let total: u64 = 0;
  while (num > 0) {
    const numModBase = num % 10;
    total += numModBase ** 2;
    num = num / 10;
  }
  return total;
}

function isHappy(num: u64): boolean {
  while (num != 1 && num != 4) {
    num = sumDigitsSquared(num);
  }
  return num === 1;
}

function isHappycoin(num: u64): boolean {
  return isHappy(num) && num % 10000 === 0;
}

export function getHappycoins(num: u32): Array<u64> {
  const result = new Array<u64>();
  for (let i: u32 = 1; i < num; i++) {
    const randomNum = random64();
    if (isHappycoin(randomNum)) {
      result.push(randomNum);
    }
  }
  return result;
}

If you’re familiar with TypeScript, this file looks very close to just being a TypeScript port of “Happycoin: Revisited”. You’d be correct! This is one of the major advantages of AssemblyScript. We’re not writing in a brand-new language, and yet we’re writing code that maps very closely to WebAssembly. Note that the return value of the exported function is of type Array<u64>. Exported functions in WebAssembly can’t return arrays of any kind, but they can return an index into the module’s memory (a pointer, really), which is exactly what’s happening here. We could deal with this manually, but as we’ll see, the AssemblyScript loader makes it much easier.

Of course, since AssemblyScript doesn’t provide a way of spawning threads on its own, we’ll need to do that from JavaScript. For this example, we’ll use ECMAScript modules to take advantage of top-level await, so go ahead and put the contents of Example 7-6 into a file called happycoin.mjs.

import { WASI } from 'wasi'; 
import fs from 'fs/promises';
import loader from '@assemblyscript/loader';
import { Worker, isMainThread, parentPort } from 'worker_threads';

const THREAD_COUNT = 4;

if (isMainThread) {
  let inFlight = THREAD_COUNT;
  let count = 0;
  for (let i = 0; i < THREAD_COUNT; i++) {
    const worker = new Worker(new URL(import.meta.url)); 
    worker.on('message', msg => {
      count += msg.length;
      process.stdout.write(msg.join(' ') + ' ');
      if (--inFlight === 0) {
        process.stdout.write('
count ' + count + '
');
      }
    });
  }
} else {
  const wasi = new WASI();
  const importObject = { wasi_snapshot_preview1: wasi.wasiImport };
  const wasmFile = await fs.readFile('./happycoin.wasm');
  const happycoinModule = await loader.instantiate(wasmFile, importObject);
  wasi.start(happycoinModule);

  const happycoinsWasmArray =
    happycoinModule.exports.getHappycoins(10_000_000/THREAD_COUNT);
  const happycoins = happycoinModule.exports.__getArray(happycoinsWasmArray);
  parentPort.postMessage(happycoins);
}

Adapted from “Happycoin: Revisited”, we’re again checking whether we’re in the main thread or not, and spawning four worker threads from the main thread. In the main thread, we’re expecting only one message on the default MessagePort, containing an array of found Happycoins. We simply log those, and a count of all of them once all the worker threads have sent the message.

On the else side, in the worker threads, we initialize a WASI instance to pass to the WebAssembly module, and then instantiate the module using @assemblyscript/loader, giving us what we need to handle the array return value we get from the getHappycoins function. We call the getHappycoins() method exported by the module, which gives us a pointer to an array in the WebAssembly linear memory. The __getArray function, provided by the loader, converts that pointer into a JavaScript Array, which we can then use as normal. We pass that to the main thread for output.

To run this example, run the following two commands. The first will compile the AssemblyScript to WebAssembly, and the second will run it via the JavaScript we just put together:

$ npm run build
$ npm start

The output will look roughly the same as with previous Happycoin examples. Here is the output from one local run:

7641056713284760000
... 134 entries redacted for brevity ...
10495060512882410000
count 136

As with all of these solutions, it’s important to evaluate the tradeoffs made with proper benchmarks. As an exercise, try timing this example against the other Happycoin implementations in this book. Is it faster or slower? Can you figure out why? What improvements can be made?