@amritk/nish-aarch64-darwin 0.35.0 → 0.37.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (128) hide show
  1. package/INSTALL.md +73 -59
  2. package/bin/nish +0 -0
  3. package/docs/AI.md +50 -4
  4. package/package.json +1 -1
  5. package/runtime/async.d.mts +2 -0
  6. package/runtime/async.mjs +7 -0
  7. package/runtime/nish.d.ts +4849 -430
  8. package/runtime/nish.h +25 -0
  9. package/runtime/page.d.ts +53 -0
  10. package/runtime/page.mjs +146 -0
  11. package/runtime/runtime-async.c +557 -0
  12. package/runtime/runtime-wasm.c +63 -7
  13. package/runtime/vite.d.ts +30 -0
  14. package/runtime/vite.mjs +150 -0
  15. package/scripts/build.sh +252 -15
  16. package/std/README.md +107 -82
  17. package/std/base64.ts +34 -5
  18. package/std/bytes.ts +279 -59
  19. package/std/cli-args.ts +296 -70
  20. package/std/cli-flags.ts +184 -19
  21. package/std/cli.ts +475 -54
  22. package/std/collections.ts +121 -23
  23. package/std/compress/checksum.ts +44 -14
  24. package/std/compress/deflate.ts +224 -111
  25. package/std/compress/gzip.ts +217 -53
  26. package/std/compress/zlib.ts +63 -7
  27. package/std/crypto/aes.ts +128 -52
  28. package/std/crypto/base64url.ts +29 -5
  29. package/std/crypto/bcrypt-batch.ts +101 -34
  30. package/std/crypto/bcrypt.ts +93 -27
  31. package/std/crypto/chacha20poly1305.ts +69 -14
  32. package/std/crypto/ct.ts +32 -13
  33. package/std/crypto/ed25519.ts +66 -16
  34. package/std/crypto/hkdf.ts +198 -13
  35. package/std/crypto/hmac.ts +242 -37
  36. package/std/crypto/jwt.ts +204 -72
  37. package/std/crypto/p256.ts +222 -72
  38. package/std/crypto/p384.ts +51 -23
  39. package/std/crypto/pki-roots.ts +32 -2
  40. package/std/crypto/pki.ts +99 -30
  41. package/std/crypto/rsa.ts +56 -22
  42. package/std/crypto/sha1.ts +3 -0
  43. package/std/crypto/sha256.ts +24 -1
  44. package/std/crypto/sha512.ts +99 -14
  45. package/std/crypto/x25519.ts +163 -24
  46. package/std/crypto/x509-random.ts +10 -0
  47. package/std/crypto/x509.ts +133 -66
  48. package/std/host/ring.ts +124 -0
  49. package/std/json-equal.ts +31 -11
  50. package/std/json-format.ts +112 -13
  51. package/std/json-number.ts +76 -26
  52. package/std/json-pointer.ts +23 -1
  53. package/std/json-tokenizer.ts +126 -51
  54. package/std/json-typed.ts +757 -96
  55. package/std/json-value.ts +438 -157
  56. package/std/json.ts +170 -38
  57. package/std/map.ts +25 -7
  58. package/std/math.ts +36 -4
  59. package/std/net/buffer-pool.ts +42 -11
  60. package/std/net/dns-config.ts +109 -23
  61. package/std/net/dns-message.ts +62 -7
  62. package/std/net/dns-resolver.ts +247 -53
  63. package/std/net/dns.ts +203 -35
  64. package/std/net/fetch.ts +1267 -290
  65. package/std/net/handler.ts +296 -80
  66. package/std/net/hpack.ts +290 -77
  67. package/std/net/http-compress.ts +152 -36
  68. package/std/net/http-fields.ts +85 -9
  69. package/std/net/http1-client-codec.ts +129 -44
  70. package/std/net/http1-codec.ts +279 -114
  71. package/std/net/http1-server.ts +409 -139
  72. package/std/net/http2-frame.ts +289 -51
  73. package/std/net/http2-tls.ts +152 -49
  74. package/std/net/http2.ts +314 -160
  75. package/std/net/http3-frame.ts +165 -27
  76. package/std/net/http3-server.ts +282 -131
  77. package/std/net/http3.ts +377 -173
  78. package/std/net/outbound.ts +37 -3
  79. package/std/net/postgres-carrier.ts +144 -8
  80. package/std/net/postgres.ts +898 -260
  81. package/std/net/prefork.ts +202 -65
  82. package/std/net/qpack.ts +120 -32
  83. package/std/net/quic-conn-ack.ts +60 -12
  84. package/std/net/quic-conn-cid.ts +135 -27
  85. package/std/net/quic-conn-params.ts +109 -22
  86. package/std/net/quic-datagram.ts +50 -3
  87. package/std/net/quic-frame.ts +333 -23
  88. package/std/net/quic-listener.ts +161 -75
  89. package/std/net/quic-packet.ts +373 -73
  90. package/std/net/quic-recovery.ts +287 -65
  91. package/std/net/quic-stream.ts +436 -146
  92. package/std/net/quic.ts +693 -323
  93. package/std/net/router.ts +87 -40
  94. package/std/net/tls/client.ts +167 -51
  95. package/std/net/tls/codec.ts +494 -68
  96. package/std/net/tls/record-client.ts +140 -73
  97. package/std/net/tls/record-server.ts +233 -105
  98. package/std/net/tls/record.ts +142 -36
  99. package/std/net/tls/schedule.ts +235 -26
  100. package/std/net/tls/ticket.ts +161 -40
  101. package/std/net/tls/verify.ts +57 -10
  102. package/std/net/tls-tcp.ts +308 -95
  103. package/std/net/tls.ts +276 -102
  104. package/std/net/upstream.ts +81 -45
  105. package/std/net/url.ts +109 -22
  106. package/std/net/websocket.ts +140 -26
  107. package/std/net/webtransport.ts +243 -106
  108. package/std/pair.ts +10 -2
  109. package/std/random.ts +42 -15
  110. package/std/regex.ts +422 -257
  111. package/std/region.ts +70 -15
  112. package/std/secret.ts +52 -11
  113. package/std/sort.ts +17 -2
  114. package/std/sqlite.ts +256 -35
  115. package/std/sync/ring.ts +229 -56
  116. package/std/sync/shm.ts +203 -23
  117. package/std/term-io.ts +154 -78
  118. package/std/term-pixels.ts +144 -19
  119. package/std/term-probe.ts +77 -35
  120. package/std/term-rate.ts +199 -118
  121. package/std/term.ts +400 -175
  122. package/std/testing.ts +130 -32
  123. package/std/text.ts +84 -17
  124. package/std/threads.ts +248 -56
  125. package/std/yaml-json.ts +111 -97
  126. package/std/yaml-lines.ts +47 -15
  127. package/std/yaml-write.ts +45 -30
  128. package/std/yaml.ts +764 -384
package/std/sync/ring.ts CHANGED
@@ -2,16 +2,17 @@
2
2
  * `nish/sync/ring` — bounded lock-free queues of byte records in a shared
3
3
  * region, for handing work between processes on different cores.
4
4
  *
5
- * import { createRegion, unlinkRegion } from "nish/sync/shm"
5
+ * import { createRegion, openRegion } from "nish/sync/shm"
6
6
  * import { initSpscRing, attachSpscRing, spscRingBytes } from "nish/sync/ring"
7
7
  *
8
8
  * const region = createRegion("jobs", spscRingBytes(65536)).expect("region")
9
9
  * const ring = initSpscRing(region, 0, 65536, true)
10
- * ring.tryPush(job, 0, job.length) // false when full
10
+ * ring.tryPush(job, 0, toI32(job.length)) // false when full
11
11
  *
12
- * // The other process, with the region opened by name:
13
- * const ring = attachSpscRing(region, 0).expect("ring")
14
- * const n = ring.popWait(buf, 0, 1000) // the record's length, or RING_EMPTY
12
+ * // The other process opens the region by name and attaches:
13
+ * const view = openRegion("jobs").expect("open")
14
+ * const rx = attachSpscRing(view, 0).expect("ring")
15
+ * const n = rx.popWait(buf, 0, 1000) // the record's length, or RING_EMPTY
15
16
  *
16
17
  * **Two rings.** `SpscRing` has one producer and one consumer, and holds
17
18
  * records of any length up to its capacity back to back: a record costs its
@@ -47,22 +48,24 @@
47
48
  * ring.tryPop(buf, 0) // none, or one peek cannot lend
48
49
  * }
49
50
  *
50
- * A window is a `SharedRegion.lend` window: the ring keeps one for its
51
- * producer and one for its consumer and re-points them on every call, so
52
- * neither path allocates or makes a system call. `commit`, `abandon` and
53
- * `release` give the window back, which empties it: a reference kept past
54
- * them indexes nothing (each index panics) until the next `reserve` or
55
- * `peek` re-points it, and then sees that call's record. A reserved record
56
- * is always contiguous: when the rest of the lap is too short, `commit`
57
- * writes a skip marker there (a length word of -1, "the rest of this lap is
58
- * padding") and the record starts at the next lap. Every pop steps over a
59
- * marker. A record `tryPush` wrapped across the end cannot be lent, so `peek`
60
- * answers an empty window for it and `tryPop` takes it, as it does for a
61
- * record of length 0. A reservation is at most `capacity / 2 - 4` bytes, so
62
- * a ring of 8 can never reserve (it panics) and one of 16 allows 4. The
63
- * reserved bytes are not zeroed: `commit` only what was written. A consumer
64
- * that polls `peek` on a doorbell ring has no wait call yet (`popWait` takes
65
- * records, not windows).
51
+ * A window is a `SharedRegion.lend` window: the ring keeps one for its producer
52
+ * and one for its consumer and re-points them on every call, so neither path
53
+ * allocates or makes a system call. `commit`, `abandon` and `release` give the
54
+ * window back, which empties it: a reference kept past them indexes nothing
55
+ * (each index panics) until the next `reserve` or `peek` re-points it, and then
56
+ * sees that call's record.
57
+ *
58
+ * A reserved record is always contiguous: when the rest of the lap is too
59
+ * short, `commit` writes a skip marker there (a length word of -1, "the rest of
60
+ * this lap is padding") and the record starts at the next lap. Every pop steps
61
+ * over a marker.
62
+ *
63
+ * A record `tryPush` wrapped across the end cannot be lent, so `peek` answers
64
+ * an empty window for it and `tryPop` takes it, as it does for a record of
65
+ * length 0. A reservation is at most `capacity / 2 - 4` bytes, so a ring of 8
66
+ * can never reserve (it panics) and one of 16 allows 4. The reserved bytes are
67
+ * not zeroed: `commit` only what was written. A consumer that polls `peek` on a
68
+ * doorbell ring has no wait call yet (`popWait` takes records, not windows).
66
69
  *
67
70
  * **The format keeps its magic.** A ring no producer `reserve`s into is
68
71
  * byte for byte what it was, and a consumer built before the marker that
@@ -83,11 +86,12 @@
83
86
  * the header and sleeps on Linux's futex, and a push rings it only when that
84
87
  * flag is set (one `SEQ_CST` store and load on each side, so neither can miss
85
88
  * the other). A busy ring makes no system calls; an idle one makes two per
86
- * record, the consumer's wait and the producer's wake. Without the doorbell a
87
- * push is a release store and `popWait` answers `SHM_UNSUPPORTED`, as it does
88
- * off Linux, where the consumer polls `tryPop`. `popWait` reads the monotonic
89
- * clock for its deadline, so a program that imports this module reaches the
90
- * `clock` capability as well as `ffi`.
89
+ * record, the consumer's wait and the producer's wake.
90
+ *
91
+ * Without the doorbell a push is a release store and `popWait` answers
92
+ * `SHM_UNSUPPORTED`, as it does off Linux, where the consumer polls `tryPop`.
93
+ * `popWait` reads the monotonic clock for its deadline, so a program that
94
+ * imports this module reaches the `clock` capability as well as `ffi`.
91
95
  *
92
96
  * Private helpers share the importing program's flat symbol namespace
93
97
  * (`docs/wp26-stdlib.md` §3e), which is why each one carries the module's name.
@@ -141,10 +145,25 @@ const ringCheckPlace = (region: SharedRegion, base: i32, bytes: i64, what: strin
141
145
  }
142
146
  }
143
147
 
144
- /** The bytes an `SpscRing` of `capacity` data bytes takes from its base. */
148
+ /**
149
+ * The bytes an `SpscRing` of `capacity` data bytes takes from its base: the
150
+ * 256-byte header and the data. Nothing is checked here; `initSpscRing`
151
+ * refuses a capacity that is not a power of two from 8.
152
+ * @param capacity the ring's data bytes, as `initSpscRing` will be given them
153
+ * @returns how many bytes from the ring's base the region must hold
154
+ */
145
155
  export const spscRingBytes = (capacity: i32): i32 => RING_DATA_AT + capacity
146
156
 
147
- /** The bytes an `MpscRing` of `slots` slots of `slotBytes` takes from its base. */
157
+ /**
158
+ * The bytes an `MpscRing` of `slots` slots of `slotBytes` takes from its base:
159
+ * the 256-byte header and each slot's 16-byte head and payload. Nothing is
160
+ * checked here; `initMpscRing` refuses a shape it cannot make.
161
+ * @param slots how many records the ring holds at once, as `initMpscRing`
162
+ * will be given it
163
+ * @param slotBytes the longest record, in bytes, as `initMpscRing` will be
164
+ * given it
165
+ * @returns how many bytes from the ring's base the region must hold
166
+ */
148
167
  export const mpscRingBytes = (slots: i32, slotBytes: i32): i32 =>
149
168
  RING_DATA_AT + slots * (RING_SLOT_HEAD + slotBytes)
150
169
 
@@ -202,33 +221,46 @@ const ringSleep = (region: SharedRegion, base: i32, ready: boolean, waitMs: i32)
202
221
  */
203
222
  export class SpscRing {
204
223
  /** The region the ring lives in. */
205
- region: SharedRegion
224
+ private region: SharedRegion
206
225
  /** Its header's offset in the region. */
207
- base: i32
226
+ private base: i32
208
227
  /** Data bytes, a power of two. */
209
228
  capacity: i32
210
229
  /** Whether a push rings the consumer's doorbell. */
211
- doorbell: boolean
230
+ private doorbell: boolean
212
231
  /** The producer's position: bytes ever pushed (this object's, as a producer). */
213
- tail: i64
232
+ private tail: i64
214
233
  /** The consumer's position: bytes ever popped (this object's, as a consumer). */
215
234
  head: i64
216
235
  /** The other side's position, as last loaded. */
217
- seenHead: i64
236
+ private seenHead: i64
237
+ /**
238
+ * The producer's position as this object, consuming, last loaded it: the
239
+ * cache a pop compares `head` with before it loads the producer's counter
240
+ * again. A snapshot, possibly behind the shared counter.
241
+ */
218
242
  seenTail: i64
219
243
  /** `reserve`'s window, re-pointed by each call; null until the first. */
220
- wnd: u8[] | null = null
244
+ private wnd: u8[] | null = null
221
245
  /** `peek`'s window, likewise. */
222
- view: u8[] | null = null
246
+ private view: u8[] | null = null
223
247
  /** The open reservation's bytes, or -1 for none. */
224
- reserved: i32 = -1
248
+ private reserved: i32 = -1
225
249
  /** The padding the open reservation skips at the tail. */
226
- reservedPad: i32 = 0
250
+ private reservedPad: i32 = 0
227
251
  /** The position past the record `peek` lent, or -1 for none. */
228
- peekedEnd: i64 = -1
252
+ private peekedEnd: i64 = -1
229
253
  /** The position of the record `lengthAt` last read, past any skip marker. */
230
- found: i64 = 0
254
+ private found: i64 = 0
231
255
 
256
+ /**
257
+ * Reads the header of the ring at `base`: its capacity and doorbell, and
258
+ * both positions (each an `ACQUIRE` load). It checks nothing; a program
259
+ * gets its ring from `initSpscRing` or `attachSpscRing`, which check the
260
+ * place and the magic first.
261
+ * @param region the region the ring lives in
262
+ * @param base the byte offset of the ring's header in `region`
263
+ */
232
264
  constructor(region: SharedRegion, base: i32) {
233
265
  this.region = region
234
266
  this.base = base
@@ -243,7 +275,15 @@ export class SpscRing {
243
275
  /**
244
276
  * Appends `src[off, off + len)` as one record: false when the ring has no
245
277
  * room for it now. A record longer than the ring could ever hold panics,
246
- * and so does a call while a reservation is open.
278
+ * and so does a call while a reservation is open. The bytes are plain
279
+ * copies, published to the consumer by one store of the producer's position:
280
+ * `RELEASE`, or `SEQ_CST` followed by the doorbell check on a doorbell ring.
281
+ * @param src the bytes to queue
282
+ * @param off where in `src` the record starts
283
+ * @param len the record's length in bytes, from 0; its length rounded up to
284
+ * 4, plus 4, may not exceed `capacity`. A range outside `src` panics
285
+ * @returns true when the record is queued, false when the ring is too full
286
+ * for it now (nothing is written)
247
287
  */
248
288
  tryPush(src: readonly u8[], off: i32, len: i32): boolean {
249
289
  if (this.reserved >= 0) {
@@ -305,6 +345,11 @@ export class SpscRing {
305
345
  * for one; outside that, or while a reservation is open, it panics. A ring
306
346
  * of 8 has no such `n` and always panics; one of 16 allows 4. The bytes
307
347
  * are not zeroed: they hold whatever the ring last held there.
348
+ * @param n the most bytes the record may have; `commit` may publish fewer
349
+ * @returns the producer's window, the same array on every call after the
350
+ * first and re-pointed by each: its bytes are the ring's own memory, so
351
+ * what is written into it lands in the region, which the consumer may
352
+ * read once `commit` publishes it. Length `n`, or 0 when there is no room
308
353
  */
309
354
  reserve(n: i32): u8[] {
310
355
  if (this.reserved >= 0) {
@@ -355,6 +400,8 @@ export class SpscRing {
355
400
  * store `tryPush` makes. The window is given back, so it is empty after.
356
401
  * Panics without a reservation, for `len` outside `[0, n]`, or when a
357
402
  * `push` moved the window out of the ring.
403
+ * @param len how many of the window's bytes, from its start, make the
404
+ * record: from 0 to the `n` that `reserve` was given
358
405
  */
359
406
  commit(len: i32): void {
360
407
  const n: i32 = this.reserved
@@ -432,7 +479,13 @@ export class SpscRing {
432
479
  * Moves the next record into `dst` from `off` and answers its length:
433
480
  * `RING_EMPTY` when there is none, `RING_TOO_SMALL` (keeping it queued)
434
481
  * when it is longer than `dst.length - off`. Panics while `peek` has a
435
- * record lent.
482
+ * record lent. The producer's position is loaded `ACQUIRE` (only when the
483
+ * cache says the ring is empty), and the freed space is handed back with a
484
+ * `RELEASE` store of the consumer's position.
485
+ * @param dst the buffer the record is copied into
486
+ * @param off where in `dst` the record's first byte goes
487
+ * @returns the record's length in bytes, or `RING_EMPTY`, or
488
+ * `RING_TOO_SMALL`
436
489
  */
437
490
  tryPop(dst: u8[], off: i32): i32 {
438
491
  this.notPeeked("tryPop")
@@ -453,7 +506,15 @@ export class SpscRing {
453
506
  * Moves up to `lens.length` records into `dst`, back to back from 0, while
454
507
  * they fit, and sets `lens[i]` to each one's length: how many it moved. One
455
508
  * load of the producer's position and one store of the consumer's, however
456
- * many records it moves. Panics while `peek` has a record lent.
509
+ * many records it moves. Panics while `peek` has a record lent. The load is
510
+ * `ACQUIRE` and the store, made only when a record moved, is `RELEASE`.
511
+ * @param dst the buffer the records are copied into, with no gap between
512
+ * them; the first record that does not fit the room left ends the batch
513
+ * and stays queued
514
+ * @param lens where each moved record's length is written, from index 0;
515
+ * its length is the most records one call moves
516
+ * @returns how many records it moved, 0 when the ring is empty or the next
517
+ * record does not fit `dst`; `lens[0, count)` holds their lengths
457
518
  */
458
519
  popBatch(dst: u8[], lens: i32[]): i32 {
459
520
  this.notPeeked("popBatch")
@@ -489,7 +550,16 @@ export class SpscRing {
489
550
  * limit): `RING_EMPTY` only once that has passed. `SHM_UNSUPPORTED` for a
490
551
  * ring without a doorbell, or off Linux, where the caller polls `tryPop`.
491
552
  * Panics while `peek` has a record lent, from `tryPop`, so the message
492
- * names `tryPop`.
553
+ * names `tryPop`. The deadline is checked between rounds of polling, so a
554
+ * wait can run past it by one round; a ring without a doorbell still polls
555
+ * one round before it answers `SHM_UNSUPPORTED`.
556
+ * @param dst the buffer the record is copied into
557
+ * @param off where in `dst` the record's first byte goes
558
+ * @param timeoutMs the longest wait in milliseconds, from the call; 0 polls
559
+ * one round, negative waits with no limit
560
+ * @returns what `tryPop` answers for the record (its length, or
561
+ * `RING_TOO_SMALL`), `RING_EMPTY` when the time ran out, or
562
+ * `SHM_UNSUPPORTED`
493
563
  */
494
564
  popWait(dst: u8[], off: i32, timeoutMs: i32): i32 {
495
565
  const deadline: i64 = ringDeadline(timeoutMs)
@@ -520,7 +590,12 @@ export class SpscRing {
520
590
  * there is none, and also for a record peek cannot lend: one `tryPush`
521
591
  * wrapped across the end of the ring, or one of length 0. On an empty
522
592
  * answer nothing is lent, and `tryPop` takes the record if there is one.
523
- * Panics while a record is lent.
593
+ * Panics while a record is lent. The producer's position is loaded
594
+ * `ACQUIRE` when the cache says the ring is empty.
595
+ * @returns the consumer's window, the same array on every call after the
596
+ * first and re-pointed by each: its bytes are the ring's own memory, not a
597
+ * copy, and stay the record's until `release`, which empties the window.
598
+ * Length 0 when nothing is lent
524
599
  */
525
600
  peek(): readonly u8[] {
526
601
  this.notPeeked("peek")
@@ -561,7 +636,21 @@ export class SpscRing {
561
636
  /**
562
637
  * Writes an `SpscRing`'s header at `base` and answers the ring: `capacity`
563
638
  * data bytes, a power of two from 8, and `doorbell` for `popWait`. The
564
- * memory is the creator's to give; a ring already there is reset.
639
+ * memory is the creator's to give; a ring already there is reset. The header
640
+ * is stored `RELAXED` and its magic last with `RELEASE`, so an attach whose
641
+ * `ACQUIRE` load reads that store sees the header stored before it. A reset
642
+ * ring had the magic already, so an attach racing a reset has no such
643
+ * promise.
644
+ * @param region the region the ring lives in
645
+ * @param base the byte offset of the ring's header, a multiple of 64 with
646
+ * `spscRingBytes(capacity)` bytes of the region from it; anything else
647
+ * panics
648
+ * @param capacity the ring's data bytes, a power of two from 8 (anything else
649
+ * panics); a record costs its length rounded up to 4, plus 4
650
+ * @param doorbell whether a consumer's `popWait` may sleep on Linux's futex,
651
+ * at the cost of a `SEQ_CST` store and load on every push
652
+ * @returns a new `SpscRing` on the empty ring, for this process's producer
653
+ * or consumer
565
654
  */
566
655
  export const initSpscRing = (region: SharedRegion, base: i32, capacity: i32, doorbell: boolean): SpscRing => {
567
656
  if (capacity < 8 || !ringIsPowerOfTwo(capacity)) {
@@ -577,7 +666,18 @@ export const initSpscRing = (region: SharedRegion, base: i32, capacity: i32, doo
577
666
  return new SpscRing(region, base)
578
667
  }
579
668
 
580
- /** The `SpscRing` an `initSpscRing` wrote at `base`; an error when there is none. */
669
+ /**
670
+ * The `SpscRing` an `initSpscRing` wrote at `base`; an error when there is
671
+ * none. The magic is loaded `ACQUIRE`, which pairs with the `RELEASE` store
672
+ * of it that the init function makes last.
673
+ * @param region the region the ring lives in, as this process mapped it
674
+ * @param base the byte offset of the ring's header, a multiple of 64 inside
675
+ * the region; anything else panics, and so does a ring whose data would run
676
+ * past the region's end
677
+ * @returns a new `SpscRing` that starts from both positions as the header
678
+ * holds them now, or the reason there is no ring at `base`: no SPSC magic,
679
+ * or a capacity no `initSpscRing` writes
680
+ */
581
681
  export const attachSpscRing = (region: SharedRegion, base: i32): Result<SpscRing, string> => {
582
682
  ringCheckPlace(region, base, toI64(RING_DATA_AT), "an SPSC ring")
583
683
  if (region.loadI32(base + RING_MAGIC_AT, ACQUIRE) !== RING_SPSC_MAGIC) {
@@ -597,18 +697,26 @@ export const attachSpscRing = (region: SharedRegion, base: i32): Result<SpscRing
597
697
  */
598
698
  export class MpscRing {
599
699
  /** The region the ring lives in. */
600
- region: SharedRegion
700
+ private region: SharedRegion
601
701
  /** Its header's offset in the region. */
602
- base: i32
702
+ private base: i32
603
703
  /** Slots, a power of two. */
604
- slots: i32
704
+ private slots: i32
605
705
  /** Each slot's payload bytes, a multiple of 8. */
606
- slotBytes: i32
706
+ private slotBytes: i32
607
707
  /** Whether a push rings the consumer's doorbell. */
608
- doorbell: boolean
708
+ private doorbell: boolean
609
709
  /** The consumer's position: records ever popped (this object's, as the consumer). */
610
710
  head: i64
611
711
 
712
+ /**
713
+ * Reads the header of the ring at `base`: its shape, its doorbell and the
714
+ * consumer's position (an `ACQUIRE` load). It checks nothing; a program
715
+ * gets its ring from `initMpscRing` or `attachMpscRing`, which check the
716
+ * place and the magic first.
717
+ * @param region the region the ring lives in
718
+ * @param base the byte offset of the ring's header in `region`
719
+ */
612
720
  constructor(region: SharedRegion, base: i32) {
613
721
  this.region = region
614
722
  this.base = base
@@ -626,7 +734,17 @@ export class MpscRing {
626
734
 
627
735
  /**
628
736
  * Queues `src[off, off + len)` as one record: false when every slot is
629
- * taken now. A record longer than a slot panics.
737
+ * taken now. A record longer than a slot panics. The producer claims a slot
738
+ * with a `RELAXED` compare-exchange on the enqueue position, after an
739
+ * `ACQUIRE` load of the slot's sequence number; it copies the record in and
740
+ * publishes it with one store of that number, `RELEASE`, or `SEQ_CST`
741
+ * followed by the doorbell check on a doorbell ring.
742
+ * @param src the bytes to queue
743
+ * @param off where in `src` the record starts
744
+ * @param len the record's length in bytes, from 0 to `slotBytes`; a range
745
+ * outside `src` panics
746
+ * @returns true when the record is queued, false when the slot it would
747
+ * take has not been freed by the consumer yet (nothing is written)
630
748
  */
631
749
  tryPush(src: readonly u8[], off: i32, len: i32): boolean {
632
750
  if (len < 0 || len > this.slotBytes) {
@@ -684,7 +802,13 @@ export class MpscRing {
684
802
  /**
685
803
  * Moves the next record into `dst` from `off` and answers its length:
686
804
  * `RING_EMPTY` when there is none, `RING_TOO_SMALL` (keeping it queued)
687
- * when it is longer than `dst.length - off`.
805
+ * when it is longer than `dst.length - off`. The slot's sequence number is
806
+ * loaded `ACQUIRE`, and the slot is freed for the producers with a
807
+ * `RELEASE` store of it.
808
+ * @param dst the buffer the record is copied into
809
+ * @param off where in `dst` the record's first byte goes
810
+ * @returns the record's length in bytes, or `RING_EMPTY`, or
811
+ * `RING_TOO_SMALL`
688
812
  */
689
813
  tryPop(dst: u8[], off: i32): i32 {
690
814
  if (!this.ready(ACQUIRE)) {
@@ -703,6 +827,15 @@ export class MpscRing {
703
827
  /**
704
828
  * Moves up to `lens.length` records into `dst`, back to back from 0, while
705
829
  * they fit, and sets `lens[i]` to each one's length: how many it moved.
830
+ * Unlike `SpscRing.popBatch` it costs what as many `tryPop`s would: an
831
+ * `ACQUIRE` load and a `RELEASE` store per record.
832
+ * @param dst the buffer the records are copied into, with no gap between
833
+ * them; the first record that does not fit the room left ends the batch
834
+ * and stays queued
835
+ * @param lens where each moved record's length is written, from index 0;
836
+ * its length is the most records one call moves
837
+ * @returns how many records it moved, 0 when the ring is empty or the next
838
+ * record does not fit `dst`; `lens[0, count)` holds their lengths
706
839
  */
707
840
  popBatch(dst: u8[], lens: i32[]): i32 {
708
841
  let count: i32 = 0
@@ -724,7 +857,20 @@ export class MpscRing {
724
857
  return count
725
858
  }
726
859
 
727
- /** `SpscRing.popWait`, for this ring. */
860
+ /**
861
+ * `SpscRing.popWait`, for this ring: `tryPop`, but on an empty ring it polls
862
+ * briefly and then sleeps until a push rings the doorbell, for at most
863
+ * `timeoutMs`, checked between rounds of polling. A ring without a doorbell,
864
+ * or one off Linux, answers `SHM_UNSUPPORTED` after a round that finds
865
+ * nothing.
866
+ * @param dst the buffer the record is copied into
867
+ * @param off where in `dst` the record's first byte goes
868
+ * @param timeoutMs the longest wait in milliseconds, from the call; 0 polls
869
+ * one round, negative waits with no limit
870
+ * @returns what `tryPop` answers for the record (its length, or
871
+ * `RING_TOO_SMALL`), `RING_EMPTY` when the time ran out, or
872
+ * `SHM_UNSUPPORTED`
873
+ */
728
874
  popWait(dst: u8[], off: i32, timeoutMs: i32): i32 {
729
875
  const deadline: i64 = ringDeadline(timeoutMs)
730
876
  while (true) {
@@ -752,7 +898,23 @@ export class MpscRing {
752
898
  /**
753
899
  * Writes an `MpscRing`'s header at `base` and answers the ring: `slots`
754
900
  * slots, a power of two from 2, of `slotBytes` each, a multiple of 8 from 8,
755
- * and `doorbell` for `popWait`. A ring already there is reset.
901
+ * and `doorbell` for `popWait`. A ring already there is reset. The header and
902
+ * every slot's sequence number are stored `RELAXED` and the magic last with
903
+ * `RELEASE`, so an attach whose `ACQUIRE` load reads that store sees them
904
+ * all. A reset ring had the magic already, so an attach racing a reset has
905
+ * no such promise.
906
+ * @param region the region the ring lives in
907
+ * @param base the byte offset of the ring's header, a multiple of 64 with
908
+ * `mpscRingBytes(slots, slotBytes)` bytes of the region from it; anything
909
+ * else panics
910
+ * @param slots how many records the ring holds at once, a power of two from
911
+ * 2; anything else panics
912
+ * @param slotBytes the longest record, in bytes, a multiple of 8 from 8;
913
+ * anything else panics
914
+ * @param doorbell whether a consumer's `popWait` may sleep on Linux's futex,
915
+ * at the cost of a `SEQ_CST` store and load on every push
916
+ * @returns a new `MpscRing` on the empty ring, for this process's producer
917
+ * or consumer
756
918
  */
757
919
  export const initMpscRing = (
758
920
  region: SharedRegion,
@@ -786,7 +948,18 @@ export const initMpscRing = (
786
948
  return new MpscRing(region, base)
787
949
  }
788
950
 
789
- /** The `MpscRing` an `initMpscRing` wrote at `base`; an error when there is none. */
951
+ /**
952
+ * The `MpscRing` an `initMpscRing` wrote at `base`; an error when there is
953
+ * none. The magic is loaded `ACQUIRE`, which pairs with the `RELEASE` store
954
+ * of it that the init function makes last.
955
+ * @param region the region the ring lives in, as this process mapped it
956
+ * @param base the byte offset of the ring's header, a multiple of 64 inside
957
+ * the region; anything else panics, and so does a ring whose slots would
958
+ * run past the region's end
959
+ * @returns a new `MpscRing` that starts from the consumer's position as the
960
+ * header holds it now, or the reason there is no ring at `base`: no MPSC
961
+ * magic, or a shape no `initMpscRing` writes
962
+ */
790
963
  export const attachMpscRing = (region: SharedRegion, base: i32): Result<MpscRing, string> => {
791
964
  ringCheckPlace(region, base, toI64(RING_DATA_AT), "an MPSC ring")
792
965
  if (region.loadI32(base + RING_MAGIC_AT, ACQUIRE) !== RING_MPSC_MAGIC) {