@amritk/nish-x86_64-linux 0.17.0 → 0.20.0

package/std/text.ts

@@ -191,3 +191,80 @@ export const firstDifference = (left: string[], right: string[]): i32 => {
   }
   return leftLength === rightLength ? -1 : i
 }
+
+/** The most bytes `indexOfAny` takes in its set: what one 16-byte vector of the runtime kernel compares. */
+const INDEX_OF_ANY_MAX_SET: i32 = 16
+
+/** The first byte that is not ASCII; `indexOfAny`'s set must stay below it. */
+const NON_ASCII: i32 = 128
+
+/**
+ * The first index at or after `from` whose byte is one of `bytes`, or -1.
+ *
+ * `bytes` is a set of 1 to 16 ASCII bytes, and anything else panics: an empty
+ * set matches nothing, more than 16 is more than one vector of the runtime
+ * kernel compares, and an ASCII set is what keeps the answer the same under Node,
+ * where `charCodeAt` reads a UTF-16 unit rather than a byte. An ASCII byte
+ * never occurs inside a multi-byte UTF-8 sequence, so a non-ASCII `text`
+ * passes through and only its ASCII bytes can match — as in `splitLines`, the
+ * index is a byte offset natively. `from` is clamped to `[0, text.length]`,
+ * as `substring` clamps, so a negative `from` searches from the start and one
+ * past the end answers -1.
+ *
+ * Natively the search is the runtime's `nish_str_index_of_any`, which reads
+ * 16 or 32 bytes at a time (docs/LANGUAGE.md, "Byte search"). It is
+ * **variable-time**: how long it takes says where the first match is, so it is
+ * never for secret data.
+ */
+export const indexOfAny = (text: string, bytes: string, from: i32): i32 => {
+  const count: i32 = toI32(bytes.length)
+  if (count < 1 || count > INDEX_OF_ANY_MAX_SET) {
+    panic("indexOfAny: the set must hold 1 to 16 bytes")
+  }
+  let j: i32 = 0
+  while (j < count) {
+    if (toI32(bytes.charCodeAt(j)) >= NON_ASCII) {
+      panic("indexOfAny: every byte of the set must be ASCII")
+    }
+    j += 1
+  }
+  const length: i32 = toI32(text.length)
+  let start: i32 = from
+  if (start < 0) {
+    start = 0
+  }
+  if (start > length) {
+    start = length
+  }
+  return indexOfAnyFrom(text, bytes, start)
+}
+
+/**
+ * `indexOfAny`'s walk, once its arguments are checked: the first index at or
+ * after `from` whose byte is in `bytes`, or -1.
+ *
+ * This loop is what runs under Node. Natively the compiler recognises the one
+ * call `indexOfAny` makes to it and calls the runtime kernel instead
+ * (`src/kernels.ts`), so the loop is the kernel's meaning written in the
+ * language rather than its implementation. The name is long for the reason
+ * `isTextBlankByte`'s is.
+ */
+const indexOfAnyFrom = (text: string, bytes: string, from: i32): i32 => {
+  const length: i32 = toI32(text.length)
+  const count: i32 = toI32(bytes.length)
+  let i: i32 = from
+  // `from` is never negative, because `indexOfAny` clamped it; the test is
+  // written because it is what proves `i` within `text`, as in `splitLines`.
+  while (i >= 0 && i < length) {
+    const code: i32 = toI32(text.charCodeAt(i))
+    let j: i32 = 0
+    while (j < count) {
+      if (toI32(bytes.charCodeAt(j)) === code) {
+        return i
+      }
+      j += 1
+    }
+    i += 1
+  }
+  return -1
+}

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() }
+  }
+}