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));
}
}
ringCapacity
The number of slots, the ring's length less its header.
ringClear
Empties the ring: the head catches up with the tail, and the slots keep their stale words.
ringFree
The number of words ringPush would still take.
ringPush
Puts word at the tail, or changes nothing when the ring is full.
ringShift
Takes the word at the head.
ringSize
The number of words put and not yet taken.
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
ringInt32Arrayrequiredthe ring's storage: head, tail, then its slots
returnsi32the 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
ringInt32Arrayrequiredthe ring's storage: head, tail, then its slots
ringFree
The number of words ringPush would still take.
const ringFree: (ring: Int32Array) => i32
ringInt32Arrayrequiredthe ring's storage: head, tail, then its slots
returnsi32the free slots
ringPush
Puts word at the tail, or changes nothing when the ring is full.
const ringPush: (ring: Int32Array, word: i32) => boolean
ringInt32Arrayrequiredthe ring's storage: head, tail, then its slots
wordi32requiredthe word to put
returnsbooleantrue 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
ringInt32Arrayrequiredthe ring's storage: head, tail, then its slots
returnsi32the word taken, or 0 on an empty ring
ringSize
The number of words put and not yet taken.
const ringSize: (ring: Int32Array) => i32
ringInt32Arrayrequiredthe ring's storage: head, tail, then its slots
returnsi32the words waiting, at most the capacity

