117. WebAssembly as a target

A VM you didn’t have to write

In Part IV you wrote a bytecode VM for Drip. Your compiler and your VM agreed on a private format: which byte means OP_ADD, how a constant is stored. Nobody else could run your bytecode.

Now imagine a bytecode format that every browser and Node already understand, specified so precisely that independent engines run it the same way. That is WebAssembly, the last back end this track looks at.

Forty-one bytes

Here is a whole WebAssembly program, written by hand. It exports one function, add, that adds two 32-bit integers:

const bytes = new Uint8Array([
  0x00, 0x61, 0x73, 0x6d, // magic
  0x01, 0x00, 0x00, 0x00, // version 1
  0x01, 0x07, 0x01, 0x60, // type
  0x02, 0x7f, 0x7f, 0x01, 0x7f,
  0x03, 0x02, 0x01, 0x00, // function
  0x07, 0x07, 0x01, 0x03, // export
  0x61, 0x64, 0x64, 0x00, 0x00,
  0x0a, 0x09, 0x01, 0x07, // code
  0x00, 0x20, 0x00, 0x20, 0x01,
  0x6a, 0x0b,
]);

Every byte has a job. Step through them:

The format begins with the 4-byte magic number \0asm and version 1, then a list of sections. Each section is a one-byte id, the length of its contents, and the contents. The ids used here are 1 (types), 3 (functions), 7 (exports) and 10 (code), and those sections must appear in that order^[1]. Lengths and other integers are written in LEB128, a variable-length encoding where small numbers take a single byte, which is why each length here is one byte.

The body, 20 00 20 01 6a 0b, is bytecode for a stack machine, like Drip’s. The difference is what happens before it runs. An engine first validates the module, type-checking every function so that, for example, i32.add can never find a string or an empty stack. The specification notes that engines don’t need a real operand stack at all: because validation fixes the stack height at every point, the slots can be treated as registers^[1], and engines compile the module to machine code.

Calling it from JavaScript

JavaScript loads a module through the WebAssembly object, usually asynchronously, so compiling doesn’t freeze the page^[2]:

const { instance } =
  await WebAssembly.instantiate(bytes);
console.log(instance.exports.add(40, 2));
// 42

The runnable example uses the synchronous constructors instead, because the book’s runner stops as soon as your code returns. Look at the last line: i32 arithmetic wraps around at 2³², instead of turning into a bigger number the way JavaScript’s numbers do.

const bytes = new Uint8Array([
  0x00, 0x61, 0x73, 0x6d, // magic
  0x01, 0x00, 0x00, 0x00, // version
  // type: (i32, i32) -> i32
  0x01, 0x07, 0x01, 0x60,
  0x02, 0x7f, 0x7f, 0x01, 0x7f,
  // function: f0 has type 0
  0x03, 0x02, 0x01, 0x00,
  // export: "add" is f0
  0x07, 0x07, 0x01, 0x03,
  0x61, 0x64, 0x64, 0x00, 0x00,
  // code: the body of f0
  0x0a, 0x09, 0x01, 0x07, 0x00,
  0x20, 0x00, // local.get 0
  0x20, 0x01, // local.get 1
  0x6a,       // i32.add
  0x0b,       // end
]);
const mod =
  new WebAssembly.Module(bytes);
const inst =
  new WebAssembly.Instance(mod);
const add = inst.exports.add;
console.log(bytes.length);
console.log(add(2, 3));
console.log(add(2147483647, 1));

One flat memory

The add function only touched its parameters. Real programs need memory, and here WebAssembly is very different from JavaScript. There are no objects, no shapes, no garbage-collected heap in the classic design. There is one long array of bytes, the linear memory, and instructions such as f64.load and f64.store read and write 8 bytes at a numeric address^[1].

That is chapter 17’s picture, “memory is one long array”, made literal. The memory grows in pages of 65,536 bytes. Numbers are stored little-endian, smallest byte first. And an access past the end doesn’t corrupt anything: it traps, which JavaScript sees as a thrown WebAssembly.RuntimeError.

JavaScript sees the same memory as an ArrayBuffer, memory.buffer. Put a Float64Array over it and both sides look at the same bytes. In the next example, the module exports its memory and a get(i) function that runs f64.load at address i * 8. JavaScript writes a column of numbers, and WebAssembly reads them:

const bytes = new Uint8Array([
  0x00, 0x61, 0x73, 0x6d,
  0x01, 0x00, 0x00, 0x00,
  // type: (i32) -> f64
  0x01, 0x06, 0x01,
  0x60, 0x01, 0x7f, 0x01, 0x7c,
  // function: f0 has type 0
  0x03, 0x02, 0x01, 0x00,
  // memory: 1 page to start
  0x05, 0x03, 0x01, 0x00, 0x01,
  // export: "mem" and "get"
  0x07, 0x0d, 0x02,
  0x03, 0x6d, 0x65, 0x6d, 0x02, 0x00,
  0x03, 0x67, 0x65, 0x74, 0x00, 0x00,
  // code: f64.load at i * 8
  0x0a, 0x0c, 0x01, 0x0a, 0x00,
  0x20, 0x00, // local.get 0
  0x41, 0x08, // i32.const 8
  0x6c,       // i32.mul
  0x2b, 0x03, 0x00, // f64.load
  0x0b,       // end
]);
const m = new WebAssembly.Module(bytes);
const { mem, get } =
  new WebAssembly.Instance(m).exports;
console.log(mem.buffer.byteLength);

const xs = new Float64Array(
  mem.buffer, 0, 4);
xs.set([1.5, 2.5, 3.5, 4.5]);
console.log(get(2));
xs[2] = 99;
console.log(get(2));

// 1.5 is 3ff8000000000000 in hex:
// smallest byte first
const b = new Uint8Array(mem.buffer);
console.log(...b.slice(0, 8));

try {
  get(8192); // byte 65536: too far
} catch (e) {
  console.log(e.name, e.message);
}
mem.grow(1);
console.log(xs.length);

Columns in linear memory

Viscosity’s SoA containers already hold their numeric fields in Float64Array columns. In linear memory, those columns become regions of one memory. With capacity cap, field number k can start at byte k * cap * 8, so element i of that field is at:

const addr = k * cap * 8 + i * 8;

A loop over x and vx walks two contiguous runs of bytes, the pattern Part II measured as fast. The WebAssembly SIMD instructions you met in chapter 21, such as f64x2.add, can then handle two lanes per instruction^[4].

So is this what Viscosity does? Not yet, and the honest answer has three parts:

• The TypeScript engine has no WebAssembly back end. Its plugins rewrite source code: JavaScript in, JavaScript out, plus Python.
• WebAssembly runs the compiler, not its output. The Rust port in engine/rust is complete: it emits byte-identical code and reports to the TypeScript engine’s. Its wasm crate wraps the whole compiler and exposes compile(source), returning { code, explain }. Built for the wasm32-unknown-unknown target, it reproduces every parity fixture too, so Viscosity itself can run in a browser as WebAssembly (Track B, chapter 189). What it produces is still JavaScript. The book’s playground uses the TypeScript engine, bundled as JavaScript.
• Emitting loops as WebAssembly is a design, not code. Strings and objects have no place in linear memory, columns would have to move when the memory grows, and every call between JavaScript and WebAssembly crosses a boundary. Whether a hot loop would gain enough to pay for that is a question nobody has measured here.

Your turn

function planMemory(fs, cap) {
  const offsets = {};
  for (let k = 0; k < fs.length; k++) {
    offsets[fs[k]] = k * cap;
  }
  const bytes = fs.length * cap;
  return { offsets, bytes, pages: 0 };
}

function uleb(n) {
  return [n];
}

What you learned

• WebAssembly is a standardized, portable binary format for code: a preamble (\0asm, version 1) and sections with ids, lengths and contents. Bodies are bytecode for a stack machine that engines validate and then compile.
• JavaScript loads modules with WebAssembly.instantiate and calls their exports. i32 arithmetic wraps around.
• Linear memory is one flat, growable array of bytes, in 64 KiB pages, little-endian, and trapping on out-of-bounds access. JavaScript views it through memory.buffer, which grow detaches.
• SoA columns map onto linear memory as one start address per column. Viscosity doesn’t emit WebAssembly. The Rust port compiles the compiler to WebAssembly, which is a different job.