@amritk/nish-x86_64-linux 0.18.0 → 0.21.0

package/std/text.ts

@@ -3,17 +3,18 @@
  *
  * The language gives a string `length`, `charCodeAt`, `substring`, `indexOf`,
  * `startsWith`, `endsWith` and `===` by content, and an array `join`. It does
- * **not** give `split`, `trim`, `toLowerCase` or a regular expression, and that
- * is a decision rather than a gap: each of those allocates, and several of them
- * need a locale or a character table that this runtime has no room for
+ * **not** give `split`, `trim`, `toLowerCase` or a regular expression (that is
+ * `std/regex`), and that is a decision rather than a gap: each allocates, and
+ * several need a locale or a character table this runtime has no room for
  * (`docs/wp7-runtime.md` keeps the runtime under a measured byte budget).
  *
  * So a program that reads a file and wants its lines writes the loop. This
  * module is that loop, written once. Every offset here is a **byte** offset,
- * like `s.length` itself, and every function is ASCII-only where it inspects
- * characters at all — a UTF-8 string passes through `splitLines` and `split`
- * untouched, because a newline and a space cannot appear inside a multi-byte
- * sequence.
+ * like `s.length` itself, and every function but one is ASCII-only where it
+ * inspects characters at all — a UTF-8 string passes through `splitLines` and
+ * `split` untouched, because a newline and a space cannot appear inside a
+ * multi-byte sequence. The one is `codePointLength`, which counts code points
+ * rather than bytes and answers the same natively and under Node; it says how.
  *
  * Every width this module declares is spelled (`i32`, never `number`) *and*
  * every value a builtin hands it is converted at the read: `s.length`,
@@ -268,3 +269,85 @@ const indexOfAnyFrom = (text: string, bytes: string, from: i32): i32 => {
   }
   return -1
 }
+
+/** The top two bits of a UTF-8 byte, which say whether it starts a code point. */
+const UTF8_TOP_BITS: i32 = 0xc0
+
+/** What those two bits are on a continuation byte: `10xxxxxx`, never a code point's first byte. */
+const UTF8_CONTINUATION: i32 = 0x80
+
+/** The first high surrogate, the unit that opens a UTF-16 pair. */
+const HIGH_SURROGATE: i32 = 0xd800
+
+/** The first low surrogate, the unit that closes a pair; the high ones end just below it. */
+const LOW_SURROGATE: i32 = 0xdc00
+
+/** One past the last low surrogate. */
+const SURROGATE_END: i32 = 0xe000
+
+/**
+ * Whether a string's units are UTF-8 bytes, as they are natively, rather than
+ * UTF-16 units, as they are under Node.
+ *
+ * `é` is two bytes and one UTF-16 unit, so its length says which host is
+ * running. It is written as an escape so that how this file is saved, `é` as
+ * one code point or as `e` and a combining accent, cannot change the answer.
+ * Natively the length of a literal is a load from a constant, and the
+ * optimiser folds this call to `true` and drops the other walk in
+ * `codePointLength`. The name is long for the reason `isTextBlankByte`'s is.
+ */
+const textUnitsAreBytes = (): boolean => toI32("\u00e9".length) === 2
+
+/**
+ * The number of Unicode code points in `text`: what JSON Schema's
+ * `minLength` and `maxLength` count, and not what `text.length` counts.
+ * `codePointLength("é")` is 1 where `"é".length` is 2, and
+ * `codePointLength("😀")` is 1 where its length is 4.
+ *
+ * Natively a string is its UTF-8 bytes, and every code point has exactly one
+ * byte that is not a continuation byte (`10xxxxxx`), so that is what is
+ * counted. Under Node the same `charCodeAt` reads UTF-16 units, where a byte
+ * rule would miscount: `"©®±"` is three units in `0x80`–`0xBF`, which are
+ * continuation bytes in UTF-8 but whole characters here. So the function asks
+ * which host it is on (`textUnitsAreBytes`) and, under Node, counts every unit
+ * except the low half of a surrogate pair. Both walks answer the same for any
+ * string literal, a lone surrogate escape included: it is three WTF-8 bytes
+ * with one leading byte natively, and one unit under Node. They differ for
+ * text built from bytes: `String.fromBytes` and `String.fromCharCode` give one
+ * unit per byte under Node, so a string decoded that way, as `nish/json`
+ * decodes a `\u` escape, counts its UTF-8 bytes there. They also differ for text
+ * that is not well-formed — bytes that are not UTF-8 natively, where each
+ * stray continuation byte counts nothing, or the two halves of a pair joined
+ * at run time, which are one string under Node and two lone surrogates
+ * natively.
+ */
+export const codePointLength = (text: string): i32 => {
+  const length: i32 = toI32(text.length)
+  // `count` never passes `i`, which stays below `length`, so it never wraps.
+  // It is a `u32` because unsigned addition carries no overflow check: an
+  // `i32` would need a panic branch, or a `count < length` guard to prove it
+  // away, and either one keeps the byte walk from vectorizing.
+  let count: u32 = 0
+  let i: i32 = 0
+  if (textUnitsAreBytes()) {
+    while (i < length) {
+      if ((toI32(text.charCodeAt(i)) & UTF8_TOP_BITS) !== UTF8_CONTINUATION) {
+        count += 1
+      }
+      i += 1
+    }
+    return toI32(count)
+  }
+  // A low surrogate right after a high one closes a pair the high one already
+  // counted. Any other unit, a lone surrogate included, is a code point.
+  let afterHigh: boolean = false
+  while (i < length) {
+    const unit: i32 = toI32(text.charCodeAt(i))
+    if (!(afterHigh && unit >= LOW_SURROGATE && unit < SURROGATE_END)) {
+      count += 1
+    }
+    afterHigh = unit >= HIGH_SURROGATE && unit < LOW_SURROGATE
+    i += 1
+  }
+  return toI32(count)
+}

package/std/threads.ts

@@ -1,10 +1,12 @@
 /**
- * `std/threads` — data parallelism, and a scope for heterogeneous tasks
- * (docs/wp29-thread-surface.md §4.1 and §4.2).
+ * `std/threads` — data parallelism, a scope for heterogeneous tasks, and a
+ * lock that owns its data (docs/wp29-thread-surface.md §4.1, §4.2 and §4.3).
  *
- *     import { parallelMapInto, parallelReduce, scope } from "nish/threads";
+ *     import { AtomicI32, Mutex, parallelFrom, parallelMap, parallelMapInto, parallelReduce, scope } from "nish/threads";
  *
  *     parallelMapInto(src, dst, (x) => x * 3);
+ *     const ys = parallelMap(src, (x) => x * k + b); // k, b: `const` locals, read by the body
+ *     const sq = parallelFrom(n, (i) => i * i);
  *     const total = parallelReduce(src, (a, b) => a + b, 0);
  *     {
  *       using s = scope();
@@ -15,20 +17,25 @@
  * **What is written here is the meaning, not the implementation.** Each body
  * below is the sequential program, and it is what runs under Node, what
  * `npm run check` type-checks, and what the compiler checks the call against.
- * The compiler then recognises the two exported templates by module and name
- * and lowers an instance of either onto `nish_parallel_range`
- * (runtime/runtime-parallel.c): it replaces the one call that walks the whole
- * range — `mapRange` for a map, `reduceBlocks` for a reduce — with a region that
- * hands each thread a contiguous piece of it, and emits the rest of the body as
- * written. So the length check, its message and the order a reduce combines in
+ * The compiler then recognises the exported templates by module and name
+ * and lowers an instance of `parallelMapInto`, `parallelFrom` or
+ * `parallelReduce` onto `nish_parallel_range` (runtime/runtime-parallel.c): it
+ * replaces the one call that walks the whole range — `mapRange` for a map,
+ * `fromRange` for a `parallelFrom`, `reduceBlocks` for a reduce — with a region
+ * that hands each thread a contiguous piece of it, and emits the rest of the
+ * body as written. `parallelMap` is `parallelMapInto` into an array it
+ * allocates first. So the length check, its message and the order a reduce combines in
  * are this file's, whichever way the program is compiled.
  *
  * What makes the region safe is checked at the call, not trusted
  * (docs/LANGUAGE.md, "Data parallelism"): the function passed as `f` may write
  * nothing its caller could observe, may allocate only temporaries it drops
  * before it returns — they are given back after every element — `dst` may not
- * be reachable from an element of `src`, and the result type is a number or a
- * `boolean`. Importing this module compiles the program with `--threads`,
+ * be reachable from an element of `src`, and the result type is a number, a
+ * `boolean` or an enum — or, for a map, a `string` or an array of those
+ * scalars, which the join copies out of the worker's arena. An arrow written at the call may read the `const` locals and
+ * the parameters of the function it is written in: each one is handed to the
+ * body as a parameter of its own, which no body may write through. Importing this module compiles the program with `--threads`,
  * because every worker needs an arena of its own.
  *
  * A reduce is deterministic. `src` is split into `min(64, ceil(n / BLOCK))`
@@ -40,6 +47,8 @@
  * parameters and cannot see through a named function.
  */
 
+import { wrappingAdd, wrappingSub } from "nish:unsafe"
+
 /**
  * Elements per block of a reduce: 2^20, about a millisecond of simple work
  * (docs/wp20-threads.md §8e). It decides the blocking, and so the answer's
@@ -55,14 +64,17 @@ const MAX_BLOCKS: i32 = 64
 
 /**
  * Writes `f(src[i])` into `dst[i]` for every `i` in `[lo, hi)`: one thread's
- * share of a map. Each length is read in the loop condition and `dst`'s again
+ * share of a map. Both lengths are read in the loop condition and `dst`'s again
  * after the call, because a call ends every length fact the bounds proof holds
  * (docs/LANGUAGE.md, "Arrays") and this is what keeps both accesses unchecked.
  * The caller has already checked that the range is inside both arrays, so
- * neither test is ever the one that stops the loop.
+ * neither test is ever the one that stops the loop. `dst`'s in the condition
+ * lets the loop vectorise (#619) when `f` inlines with no panic path: LLVM
+ * sees the test after the call repeat one the condition made, drops it, and
+ * the store is unconditional. `fromRange` has the same shape.
  */
 const mapRange = <T, U>(src: T[], dst: U[], f: (x: T) => U, lo: i32, hi: i32): void => {
-  for (let i: i32 = lo; i >= 0 && i < hi && i < toI32(src.length); i++) {
+  for (let i: i32 = lo; i >= 0 && i < hi && i < toI32(src.length) && i < toI32(dst.length); i++) {
     const y = f(src[i])
     if (i < toI32(dst.length)) {
       dst[i] = y
@@ -172,6 +184,42 @@ export const parallelReduce = <T>(src: T[], f: (acc: T, x: T) => T, identity: T)
   return acc
 }
 
+/**
+ * A new array of `f(src[i])` for every index of `src`: `parallelMapInto` into
+ * an array this call allocates, before any element is computed, so nothing
+ * but the map itself can hold it while the region runs.
+ */
+export const parallelMap = <T, U>(src: T[], f: (x: T) => U): U[] => {
+  const dst = new Array<U>(toI32(src.length))
+  parallelMapInto(src, dst, f)
+  return dst
+}
+
+/**
+ * Writes `f(i)` into `dst[i]` for every `i` in `[lo, hi)`: one thread's share
+ * of a `parallelFrom`. The length is read in the loop condition and again
+ * after the call, for the reason `mapRange` gives.
+ */
+const fromRange = <U>(dst: U[], f: (i: i32) => U, lo: i32, hi: i32): void => {
+  for (let i: i32 = lo; i >= 0 && i < hi && i < toI32(dst.length); i++) {
+    const y = f(i)
+    if (i < toI32(dst.length)) {
+      dst[i] = y
+    }
+  }
+}
+
+/**
+ * A new array of `n` elements, `f(i)` at index `i`, computed on as many
+ * threads as the machine has and the length is worth: `Array.from({ length:
+ * n }, (_, i) => f(i))`, with the array allocated before any element is.
+ */
+export const parallelFrom = <U>(n: i32, f: (i: i32) => U): U[] => {
+  const dst = new Array<U>(n)
+  fromRange(dst, f, 0, toI32(dst.length))
+  return dst
+}
+
 /**
  * The panic of a task whose destination slot is not in its array. A function of
  * its own for the reason `dstTooShort` is one: the message is its allocation.
@@ -199,6 +247,31 @@ const storeResult = <R>(dst: R[], at: i32, r: R): void => {
 const runTask = <A, R>(entry: (arg: A) => R, arg: A, dst: R[], at: i32): void =>
   storeResult(dst, at, entry(arg))
 
+/**
+ * One task with no destination: `entry(arg)`, whose answer, if it has one,
+ * nothing stores — the checker holds such an entry to `void`. Natively the
+ * compiler files this call as a task as it files `runTask`'s, with no store
+ * at the join; nothing under Node reaches it (see `spawn`).
+ */
+const runWith = <A, R>(entry: (arg: A) => R, arg: A): void => {
+  entry(arg)
+}
+
+/** `runWith` for an entry of no parameters, such as `() => work(xs)`, whose captures are its arguments. */
+const runThunk = <R>(entry: () => R): void => {
+  entry()
+}
+
+/**
+ * Whether a call of `spawn` wrote a destination slot. Natively every call
+ * that reaches `spawn` did, so this is always true there: the compiler gives
+ * `s.spawn(entry, arg)` and `s.spawn(() => ...)` the methods written for
+ * them below, `spawnWith` and `spawnThunk`. Under Node the source runs as
+ * it is written and every form reaches `spawn`, where a slot the call left
+ * out is `undefined`, which is neither below zero nor at or above it.
+ */
+const slotWritten = (at: i32): boolean => at < 0 || at >= 0
+
 /**
  * A scope of tasks, joined when the block that declares it ends
  * (docs/wp29-thread-surface.md §4.2). It is only ever made by `scope()` in a
@@ -218,12 +291,40 @@ export class ThreadScope {
    * again when its answer is stored.
    */
   spawn<A, R>(entry: (arg: A) => R, arg: A, dst: R[], at: i32): void {
+    if (!slotWritten(at)) {
+      // Under Node only: `s.spawn(entry, arg)` or `s.spawn(() => ...)`, run
+      // at the spawn with nothing to store (`slotWritten`).
+      entry(arg)
+      return
+    }
     if (at < 0 || at >= toI32(dst.length)) {
       slotOutOfRange(at, toI32(dst.length))
     }
     runTask(entry, arg, dst, at)
   }
 
+  /**
+   * `s.spawn(entry, arg)` as the compiler reads it: run `entry(arg)` on a
+   * thread of its own when the scope closes, and store nothing. `entry`
+   * answers `void`. Only the compiler names this method (see `slotWritten`):
+   * a scope is only ever the receiver of a `spawn` statement, so `s.spawnWith(...)`
+   * written in a program is refused by that rule (NL2389), as passing the
+   * scope would be.
+   */
+  spawnWith<A, R>(entry: (arg: A) => R, arg: A): void {
+    runWith(entry, arg)
+  }
+
+  /**
+   * `s.spawn(() => work(xs))` as the compiler reads it: run the arrow, whose
+   * captured `const` locals are its arguments, on a thread of its own when the
+   * scope closes, and store nothing. Only the compiler names this method, and
+   * a program that names it is refused as `spawnWith`'s is (NL2389).
+   */
+  spawnThunk<R>(entry: () => R): void {
+    runThunk(entry)
+  }
+
   /**
    * What `using` calls when the block ends. Natively the compiler emits the
    * join itself at every exit of the block, and under Node every task has
@@ -236,3 +337,326 @@ export class ThreadScope {
 
 /** A new scope, for a `using` declaration: `using s = scope()`. */
 export const scope = (): ThreadScope => new ThreadScope()
+
+/**
+ * What a `Mutex` hands out: its data, as `value`, for as long as the block of
+ * the `using` declaration that took the lock (docs/LANGUAGE.md, "A lock that
+ * owns its data"). A guard is only ever named as `g.value`, and `g.value`
+ * only as the base of a field or element access, so nothing read through it
+ * outlives the lock.
+ *
+ * Each `Mutex` makes exactly one guard, when it is made, and every lock hands
+ * out that one: taking the lock allocates nothing.
+ */
+export class MutexGuard<T> {
+  /** The data the lock owns. */
+  value: T
+
+  /**
+   * The lock word: 0 when the lock is free, 1 while a guard's block holds it.
+   * Nothing written here reads or writes it. Natively the compiler takes it
+   * with an acquire compare-and-swap in `lock()` and gives it back with a
+   * release store at every exit of the guard's block (`src/emit-parallel.ts`);
+   * under Node one task runs at a time and there is nothing to exclude.
+   */
+  word: i32 = 0
+
+  constructor(value: T) {
+    this.value = value
+  }
+
+  /**
+   * What `using` calls when the guard's block ends. Natively the compiler
+   * emits the release itself at every exit of the block, and under Node
+   * nothing was taken, so there is nothing to give back.
+   */
+  [Symbol.dispose](): void {
+    // Nothing to release: see above.
+  }
+}
+
+/**
+ * A lock that owns its data (docs/wp29-thread-surface.md §4.3). The data is
+ * reachable only through the guard `lock()` answers, bound by `using`, so no
+ * path to it skips the lock: `new Mutex<Hist>(new Hist())` takes a fresh
+ * value, and `using g = m.lock()` is the only way to read or write it.
+ *
+ * Under Node a scope's tasks run one at a time, at their spawn, so `lock()`
+ * answers the guard and waits for nothing: that is one of the orders the
+ * native program can run its critical sections in, and a program whose
+ * guarded updates commute prints the same either way.
+ */
+export class Mutex<T> {
+  /** The one guard, which holds the data; only `lock()` hands it out. */
+  guard: MutexGuard<T>
+
+  constructor(init: T) {
+    this.guard = new MutexGuard<T>(init)
+  }
+
+  /**
+   * The guard over the data, for a `using` declaration: `using g = m.lock()`.
+   * Natively the call waits until the lock is free and takes it.
+   */
+  lock(): MutexGuard<T> {
+    return this.guard
+  }
+}
+
+/**
+ * An `i32` that a scope's tasks and a parallel body may update together
+ * (docs/LANGUAGE.md, "Atomics"). Each method is one indivisible operation:
+ * natively the compiler emits each body itself, as a sequentially consistent
+ * `load atomic`, `store atomic`, `atomicrmw` or `cmpxchg` on `value`
+ * (docs/IR_COOKBOOK.md, "Atomics"), and what is written below is the meaning,
+ * which is what runs under Node. `add` and `sub` wrap at 32 bits, as the
+ * native instruction does; `add`, `sub`, `min`, `max` and `exchange` answer
+ * the value before the update, and `compareExchange` the value it saw.
+ *
+ * It reaches a task by the routes a `Mutex` does, and a parallel body through
+ * a capture; its value is named only through these methods. Results that do
+ * not depend on the order the updates land in need the updates to commute,
+ * which the checker does not prove.
+ */
+export class AtomicI32 {
+  /** The value; named only by this class's methods, which the compiler emits. */
+  value: i32
+
+  constructor(value: i32) {
+    this.value = value
+  }
+
+  /** The value. */
+  load(): i32 {
+    return this.value
+  }
+
+  /** Sets the value to `value`. */
+  store(value: i32): void {
+    this.value = value
+  }
+
+  /** Adds `delta`, wrapping, and answers the value before. */
+  add(delta: i32): i32 {
+    const old = this.value
+    this.value = wrappingAdd(old, delta)
+    return old
+  }
+
+  /** Subtracts `delta`, wrapping, and answers the value before. */
+  sub(delta: i32): i32 {
+    const old = this.value
+    this.value = wrappingSub(old, delta)
+    return old
+  }
+
+  /** Keeps the smaller of the value and `value`, and answers the value before. */
+  min(value: i32): i32 {
+    const old = this.value
+    if (value < old) {
+      this.value = value
+    }
+    return old
+  }
+
+  /** Keeps the larger of the value and `value`, and answers the value before. */
+  max(value: i32): i32 {
+    const old = this.value
+    if (value > old) {
+      this.value = value
+    }
+    return old
+  }
+
+  /** Sets the value to `value` and answers the value before. */
+  exchange(value: i32): i32 {
+    const old = this.value
+    this.value = value
+    return old
+  }
+
+  /** Sets the value to `desired` if it is `expected`, and answers the value it saw. */
+  compareExchange(expected: i32, desired: i32): i32 {
+    const old = this.value
+    if (old === expected) {
+      this.value = desired
+    }
+    return old
+  }
+}
+
+/**
+ * An `i64` that a scope's tasks and a parallel body may update together
+ * (docs/LANGUAGE.md, "Atomics"). Each method is one indivisible operation:
+ * natively the compiler emits each body itself, as a sequentially consistent
+ * `load atomic`, `store atomic`, `atomicrmw` or `cmpxchg` on `value`
+ * (docs/IR_COOKBOOK.md, "Atomics"), and what is written below is the meaning,
+ * which is what runs under Node. Node holds it as a `number`, so `add` and
+ * `sub` are `+` and `-` there, and it agrees with native while values stay
+ * within ±2^53; wrapping at 2^63 is native-only, the same limit as every `i64`.
+ * `add`, `sub`, `min`, `max` and `exchange` answer the value before the
+ * update, and `compareExchange` the value it saw.
+ *
+ * It reaches a task by the routes a `Mutex` does, and a parallel body through
+ * a capture; its value is named only through these methods. Results that do
+ * not depend on the order the updates land in need the updates to commute,
+ * which the checker does not prove.
+ */
+export class AtomicI64 {
+  /** The value; named only by this class's methods, which the compiler emits. */
+  value: i64
+
+  constructor(value: i64) {
+    this.value = value
+  }
+
+  /** The value. */
+  load(): i64 {
+    return this.value
+  }
+
+  /** Sets the value to `value`. */
+  store(value: i64): void {
+    this.value = value
+  }
+
+  /** Adds `delta` and answers the value before; natively the sum wraps at 64 bits. */
+  add(delta: i64): i64 {
+    const old = this.value
+    this.value = old + delta
+    return old
+  }
+
+  /** Subtracts `delta` and answers the value before; natively the difference wraps at 64 bits. */
+  sub(delta: i64): i64 {
+    const old = this.value
+    this.value = old - delta
+    return old
+  }
+
+  /** Keeps the smaller of the value and `value`, and answers the value before. */
+  min(value: i64): i64 {
+    const old = this.value
+    if (value < old) {
+      this.value = value
+    }
+    return old
+  }
+
+  /** Keeps the larger of the value and `value`, and answers the value before. */
+  max(value: i64): i64 {
+    const old = this.value
+    if (value > old) {
+      this.value = value
+    }
+    return old
+  }
+
+  /** Sets the value to `value` and answers the value before. */
+  exchange(value: i64): i64 {
+    const old = this.value
+    this.value = value
+    return old
+  }
+
+  /** Sets the value to `desired` if it is `expected`, and answers the value it saw. */
+  compareExchange(expected: i64, desired: i64): i64 {
+    const old = this.value
+    if (old === expected) {
+      this.value = desired
+    }
+    return old
+  }
+}
+
+/**
+ * A channel of scalars or strings between a scope's tasks (docs/wp29-thread-surface.md
+ * §4.4); a string is copied out of the sender's arena at `send` and into the
+ * receiver's at the loop: `send` from the tasks that produce, `for (const x of ch)` in the one
+ * that consumes, or in the parent once the scope has joined.
+ *
+ *     const ch = new Channel<i32>()
+ *     {
+ *       using s = scope()
+ *       s.spawn(produce, new Pipe(ch, 100), done, 0) // every sender first
+ *       s.spawn(consume, new Pipe(ch, 0), sums, 0)   // then the one receiver
+ *     }
+ *
+ * Nobody closes a channel: it closes when its scope has started to join and
+ * every task that may send on it has returned (docs/LANGUAGE.md, "Channels").
+ *
+ * **What is written here is the meaning under Node**, where a scope's tasks run
+ * one at a time at their spawns: `send` pushes onto `queue`, and a loop takes
+ * values off its front until it is empty. That is correct because every
+ * sender is spawned before the receiver, so every sender has run by the time
+ * the receiver's loop starts. Natively the compiler writes `send` and the loop
+ * itself (`src/emit-parallel.ts`), onto a buffer the runtime keeps outside
+ * every arena behind `state`, and the loop waits while the channel is empty
+ * and still open.
+ */
+export class Channel<T> {
+  /** Under Node: every value sent, in the order it was sent. */
+  queue: T[]
+
+  /** Under Node: how many of `queue`'s values a loop has taken. */
+  head: i32 = 0
+
+  /**
+   * Natively: the runtime's handle on the channel (runtime/runtime-parallel.c),
+   * 0 until the channel is first used. Nothing written here reads or writes it.
+   */
+  state: i64 = 0
+
+  constructor() {
+    this.queue = []
+  }
+
+  /** Hand `x` to the receiver. It never waits: a channel holds as many values as are sent. */
+  send(x: T): void {
+    this.queue.push(x)
+  }
+
+  /**
+   * The next value, for a loop that has found one waiting (`ChannelWalk`).
+   * Natively the loop is the compiler's, which takes a value with the runtime
+   * instead, and nothing calls this.
+   */
+  take(): T {
+    const x = this.queue[this.head]
+    this.head = this.head + 1
+    return x
+  }
+
+  /** Whether a value is waiting, under Node, where nothing is sent while a loop runs. */
+  ready(): boolean {
+    return this.head < toI32(this.queue.length)
+  }
+
+  /**
+   * What `for (const x of ch)` asks for under Node: a walk that takes each
+   * value as it reaches it, so a second loop over the channel finds it empty,
+   * as it does natively.
+   */
+  [Symbol.iterator](): ChannelWalk<T> {
+    return new ChannelWalk<T>(this)
+  }
+}
+
+/**
+ * The iterator a `for...of` over a `Channel` walks under Node. Natively it is
+ * never made: the compiler lowers the loop itself.
+ */
+class ChannelWalk<T> {
+  channel: Channel<T>
+
+  constructor(channel: Channel<T>) {
+    this.channel = channel
+  }
+
+  next(): IteratorResult<T> {
+    if (!this.channel.ready()) {
+      return { done: true, value: 0 }
+    }
+    return { done: false, value: this.channel.take() }
+  }
+}