nish/host/ring

A single-producer, single-consumer ring of i32 words over module storage, shared by a wasm module and the page that drives it (docs/wp50-wasm-host.md §11).

import {
  ringCapacity,
  ringClear,
  ringFree,
  ringPush,
  ringShift,
  ringSize,
} from "nish/host/ring";
import { ringShift, ringSize } from "nish/host/ring";

const INPUT = new Int32Array(2 + 64); // head, tail, then 64 slots

export const tick = (): void => {
  while (ringSize(INPUT) > 0) {
    steer(ringShift(INPUT));
  }
}

The ring is an Int32Array the program declares as module storage, so the page reaches the same words through the Layout the loader hands it:

Word 0 is the head and word 1 the tail, each a count of words taken and put kept modulo twice the capacity (the length less two), so neither overflows and tail - head (modulo the same) is the number waiting: 0 is empty and the capacity is full. Slot count % capacity holds the word put at that count. One side only advances the tail and the other only the head: that is the whole protocol, and it needs no atomics because the page and the module run on one thread and never at once. nish/page's ringOver is the page's half, over the same layout and arithmetic.

A zero-filled ring (what module storage starts as) is empty. A ring whose counts a buggy page wrote out of protocol is still never read out of bounds: each count is reduced modulo twice the capacity before it is used, and a size past the capacity reads as full, so ringPush refuses and ringShift takes words until the counts agree again.

Functions

ringCapacity

The number of slots, the ring's length less its header.

const ringCapacity: (ring: Int32Array) => i32
ringInt32Arrayrequired

the ring's storage: head, tail, then its slots

returnsi32

the slot count, or 0 for a ring too short to have one

ringClear

Empties the ring: the head catches up with the tail, and the slots keep their stale words.

const ringClear: (ring: Int32Array) => void
ringInt32Arrayrequired

the ring's storage: head, tail, then its slots

ringFree

The number of words ringPush would still take.

const ringFree: (ring: Int32Array) => i32
ringInt32Arrayrequired

the ring's storage: head, tail, then its slots

returnsi32

the free slots

ringPush

Puts word at the tail, or changes nothing when the ring is full.

const ringPush: (ring: Int32Array, word: i32) => boolean
ringInt32Arrayrequired

the ring's storage: head, tail, then its slots

wordi32required

the word to put

returnsboolean

true when the word was put, false when the ring was full

ringShift

Takes the word at the head. On an empty ring it answers 0 and changes nothing, so a caller that cannot tell 0 from empty asks ringSize first.

const ringShift: (ring: Int32Array) => i32
ringInt32Arrayrequired

the ring's storage: head, tail, then its slots

returnsi32

the word taken, or 0 on an empty ring

ringSize

The number of words put and not yet taken.

const ringSize: (ring: Int32Array) => i32
ringInt32Arrayrequired

the ring's storage: head, tail, then its slots

returnsi32

the words waiting, at most the capacity