Vectors (SIMD)

A vector holds sixteen bytes of numbers side by side: sixteen u8s, eight u16s, four i32s or u32s or f32s, or two f64s. The processor can move a whole vector in one instruction, so a loop that loads, stores and shuffles vectors does in one step what would otherwise take four or sixteen. The six types and their functions come from the built-in module nish:simd. The rules are in the reference under nish:simd and its lane operations.

Making a vector

Import the type you need. Its name is also its constructor, which takes one value per lane, lane 0 first. splat… puts one value in every lane:

import { i32x4, splatF64x2, extract } from "nish:simd";

export const main = (): i32 => {
  const v = i32x4(10, 20, 30, 40);
  const half = splatF64x2(0.5);
  console.log(extract(v, 2));
  console.log(extract(half, 1));
  return 0;
};

That prints 30 and 0.5.

Type Lanes Constructor splat… load…
u8x16 sixteen u8 u8x16(a0, …, a15) splatU8x16(x) loadU8x16(xs, i)
u16x8 eight u16 u16x8(a0, …, a7) splatU16x8(x) loadU16x8(xs, i)
i32x4 four i32 i32x4(a, b, c, d) splatI32x4(x) loadI32x4(xs, i)
u32x4 four u32 u32x4(a, b, c, d) splatU32x4(x) loadU32x4(xs, i)
f32x4 four f32 f32x4(a, b, c, d) splatF32x4(x) loadF32x4(xs, i)
f64x2 two f64 f64x2(a, b) splatF64x2(x) loadF64x2(xs, i)

Loading and storing

loadI32x4(xs, i) reads xs[i] to xs[i + 3] into a vector, and store(v, xs, i) writes a vector's lanes back to the same places. The array's elements must be the lane type: an i32x4 comes from an i32[], a u8x16 from a u8[].

The index is checked once for the whole vector, and if any of its lanes would fall outside the array the program stops with the index out of range: … >= len message an xs[i] gives. It names i when i itself is out of range, and otherwise the last lane, i + N - 1, where N is the lane count: loadI32x4(xs, 2) on a five-element array stops with index out of range: 5 >= 5.

A loop guard that already keeps every lane in range removes the check, as it does for xs[i]: under while (i <= n - 4), with n the array's length and i counting up from 0, loadI32x4(xs, i) compiles to the load alone. A guard one lane short, i <= n - 3, proves nothing, so that load keeps its check.

import { loadU8x16, store } from "nish:simd";

export const main = (): i32 => {
  const src: u8[] = [];
  for (let i = 0; i < 32; i++) {
    src.push(toU8(i));
  }
  const dst: u8[] = [];
  for (let i = 0; i < 32; i++) {
    dst.push(0);
  }
  for (let i = 0; i + 16 <= src.length; i += 16) {
    store(loadU8x16(src, i), dst, i);
  }
  console.log(dst[31]);
  return 0;
};

Reading and replacing a lane

extract(v, k) reads lane k, and replace(v, k, x) gives a new vector that is v with lane k set to x; v itself does not change. The lane number has to be a number written in the code, from 0 to one less than the lane count, so the compiler can check it:

import { i32x4, extract } from "nish:simd";

export const main = (): i32 => {
  const k = 1;
  console.log(extract(i32x4(1, 2, 3, 4), k));
  return 0;
};

What a vector can do

A vector is a value, like a number. You can keep one in a variable, a class field or an array, pass it to a function and return it. It has no operators: +, ===, < and the others are refused, and so is printing one directly — use the functions below, and read the lanes with extract.

import { i32x4 } from "nish:simd";

export const main = (): i32 => {
  const a = i32x4(1, 2, 3, 4);
  const b = a + a;
  return 0;
};

A vector cannot be a Map key, cannot be null, and cannot appear in the signature of a function that C or JavaScript calls: --emit-header, --emit-napi and --emit-dts leave out a function whose parameter or result holds a vector anywhere — a vector, an array of them, a Result with a vector arm — and say why. In a C header, a class that holds a vector anywhere, even through another class, is declared without its fields, and a function taking a pointer to one keeps it as an opaque struct Name *.

The same program prints the same thing natively, under --profile wasi and under Node, where each vector is a typed array that is never changed after it is made.

Working on every lane at once

Each operation is a function that works lane by lane: lane 0 of the answer comes from lane 0 of each operand, and so on. Float vectors use add, sub, mul, div, neg, abs and sqrt. Integer vectors use addWrapping, subWrapping and mulWrapping, which wrap around when a lane overflows instead of stopping the program, and the name says so. min and max take any vector, and and, or, xor and not take integer vectors. sum adds the lanes of a u8x16, u16x8 or float vector; sumWrapping adds the lanes of an i32x4 or u32x4, wrapping.

import { f32x4, i32x4, splatF32x4, mul, add, addWrapping, sum, sumWrapping } from "nish:simd";

export const main = (): i32 => {
  const v = add(mul(f32x4(1, 2, 3, 4), splatF32x4(2)), splatF32x4(0.5));
  console.log(sum(v));
  console.log(sumWrapping(addWrapping(i32x4(1, 2, 3, 4), i32x4(10, 20, 30, 40))));
  return 0;
};

That prints 22 and 110. Both operands of an operation are the same type: an i32x4 and a u32x4 are refused together, and asU32x4 and the other as… functions read the same sixteen bytes as different lanes.

Shifting and rotating

shl(v, n) shifts every lane left by n bits and shr(v, n) shifts it right; rotl and rotr rotate, so the bits shifted out at one end come back in at the other. They take a u8x16, u16x8, i32x4 or u32x4. shr fills with zeros on the unsigned types and with copies of the sign bit on i32x4. The count is a number written in the code and smaller than the lane's width in bits (8, 16 or 32), so each is a single instruction. Rotates are what ChaCha20, SHA-256 and similar code are made of:

import { u32x4, addWrapping, xor, rotl, extract } from "nish:simd";

export const main = (): i32 => {
  // Four ChaCha20 states at once: lane k belongs to block k.
  const a = addWrapping(u32x4(1, 2, 3, 4), u32x4(0x10000, 0x20000, 0x30000, 0x40000));
  const d = rotl(xor(u32x4(0, 0, 0, 0), a), 16);
  console.log(extract(d, 0));
  return 0;
};

That prints 65537. A count of 32 or more on a 32-bit lane, or a count held in a variable, is refused:

import { u32x4, rotl, extract } from "nish:simd";

export const main = (): i32 => {
  console.log(extract(rotl(u32x4(1, 2, 3, 4), 32), 0));
  return 0;
};

Comparing lanes

eq, ne, lt, le, gt and ge compare two vectors lane by lane and answer a mask: mask32x4 for four 32-bit lanes, mask8x16 for sixteen bytes, and so on. any(m) and all(m) ask whether some or every lane passed, bitmask(m) gives an i32 whose bit k is lane k, and select(m, a, b) takes each lane from a where the mask is set and from b where it is not.

import { u8x16, splatU8x16, eq, any, bitmask } from "nish:simd";

export const main = (): i32 => {
  const block = u8x16(104, 105, 32, 116, 104, 101, 114, 101, 32, 33, 0, 0, 0, 0, 0, 0);
  const spaces = eq(block, splatU8x16(32));
  if (any(spaces)) {
    console.log(bitmask(spaces));
  }
  return 0;
};

That prints 260: bits 2 and 8, where the spaces are. A mask is only ever a variable, a parameter or what a function returns. It cannot be stored in a field or an array; store its bitmask, or the vectors it selects, instead.