@amritk/nish-aarch64-darwin 0.35.0 → 0.36.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 (119) hide show
  1. package/INSTALL.md +6 -1
  2. package/bin/nish +0 -0
  3. package/docs/AI.md +9 -2
  4. package/package.json +1 -1
  5. package/runtime/nish.d.ts +4612 -430
  6. package/runtime/vite.d.ts +30 -0
  7. package/runtime/vite.mjs +150 -0
  8. package/scripts/build.sh +108 -13
  9. package/std/base64.ts +34 -5
  10. package/std/bytes.ts +256 -40
  11. package/std/cli-args.ts +296 -70
  12. package/std/cli-flags.ts +184 -19
  13. package/std/cli.ts +475 -54
  14. package/std/collections.ts +121 -23
  15. package/std/compress/checksum.ts +44 -14
  16. package/std/compress/deflate.ts +224 -111
  17. package/std/compress/gzip.ts +217 -53
  18. package/std/compress/zlib.ts +63 -7
  19. package/std/crypto/aes.ts +80 -9
  20. package/std/crypto/base64url.ts +22 -0
  21. package/std/crypto/bcrypt-batch.ts +88 -21
  22. package/std/crypto/bcrypt.ts +60 -0
  23. package/std/crypto/chacha20poly1305.ts +53 -0
  24. package/std/crypto/ct.ts +32 -13
  25. package/std/crypto/ed25519.ts +47 -0
  26. package/std/crypto/hkdf.ts +198 -13
  27. package/std/crypto/hmac.ts +235 -31
  28. package/std/crypto/jwt.ts +192 -63
  29. package/std/crypto/p256.ts +159 -16
  30. package/std/crypto/p384.ts +28 -3
  31. package/std/crypto/pki-roots.ts +32 -2
  32. package/std/crypto/pki.ts +81 -15
  33. package/std/crypto/rsa.ts +33 -3
  34. package/std/crypto/sha1.ts +3 -0
  35. package/std/crypto/sha256.ts +24 -1
  36. package/std/crypto/sha512.ts +99 -14
  37. package/std/crypto/x25519.ts +152 -14
  38. package/std/crypto/x509-random.ts +10 -0
  39. package/std/crypto/x509.ts +67 -7
  40. package/std/json-equal.ts +19 -0
  41. package/std/json-format.ts +112 -13
  42. package/std/json-number.ts +64 -14
  43. package/std/json-pointer.ts +23 -1
  44. package/std/json-tokenizer.ts +100 -29
  45. package/std/json-typed.ts +713 -66
  46. package/std/json-value.ts +400 -124
  47. package/std/json.ts +138 -10
  48. package/std/map.ts +25 -7
  49. package/std/math.ts +36 -4
  50. package/std/net/buffer-pool.ts +42 -11
  51. package/std/net/dns-config.ts +109 -23
  52. package/std/net/dns-message.ts +62 -7
  53. package/std/net/dns-resolver.ts +247 -53
  54. package/std/net/dns.ts +203 -35
  55. package/std/net/fetch.ts +151 -61
  56. package/std/net/handler.ts +278 -80
  57. package/std/net/hpack.ts +262 -52
  58. package/std/net/http-compress.ts +125 -15
  59. package/std/net/http-fields.ts +85 -9
  60. package/std/net/http1-client-codec.ts +100 -19
  61. package/std/net/http1-codec.ts +235 -27
  62. package/std/net/http1-server.ts +343 -85
  63. package/std/net/http2-frame.ts +272 -35
  64. package/std/net/http2-tls.ts +135 -34
  65. package/std/net/http2.ts +247 -106
  66. package/std/net/http3-frame.ts +154 -17
  67. package/std/net/http3-server.ts +246 -96
  68. package/std/net/http3.ts +307 -115
  69. package/std/net/outbound.ts +37 -3
  70. package/std/net/postgres-carrier.ts +144 -8
  71. package/std/net/postgres.ts +723 -103
  72. package/std/net/prefork.ts +164 -31
  73. package/std/net/qpack.ts +105 -18
  74. package/std/net/quic-conn-ack.ts +59 -12
  75. package/std/net/quic-conn-cid.ts +124 -27
  76. package/std/net/quic-conn-params.ts +70 -10
  77. package/std/net/quic-datagram.ts +43 -3
  78. package/std/net/quic-frame.ts +286 -12
  79. package/std/net/quic-listener.ts +101 -32
  80. package/std/net/quic-packet.ts +302 -21
  81. package/std/net/quic-recovery.ts +228 -44
  82. package/std/net/quic-stream.ts +353 -91
  83. package/std/net/quic.ts +489 -171
  84. package/std/net/router.ts +87 -40
  85. package/std/net/tls/client.ts +166 -51
  86. package/std/net/tls/codec.ts +413 -56
  87. package/std/net/tls/record-client.ts +110 -55
  88. package/std/net/tls/record-server.ts +159 -59
  89. package/std/net/tls/record.ts +109 -12
  90. package/std/net/tls/schedule.ts +235 -26
  91. package/std/net/tls/ticket.ts +159 -40
  92. package/std/net/tls/verify.ts +49 -3
  93. package/std/net/tls-tcp.ts +250 -45
  94. package/std/net/tls.ts +221 -59
  95. package/std/net/upstream.ts +81 -45
  96. package/std/net/url.ts +97 -13
  97. package/std/net/websocket.ts +122 -12
  98. package/std/net/webtransport.ts +220 -89
  99. package/std/pair.ts +10 -2
  100. package/std/random.ts +34 -9
  101. package/std/regex.ts +352 -198
  102. package/std/region.ts +70 -15
  103. package/std/secret.ts +52 -11
  104. package/std/sort.ts +17 -2
  105. package/std/sqlite.ts +256 -35
  106. package/std/sync/ring.ts +205 -35
  107. package/std/sync/shm.ts +194 -16
  108. package/std/term-io.ts +137 -64
  109. package/std/term-pixels.ts +144 -19
  110. package/std/term-probe.ts +66 -25
  111. package/std/term-rate.ts +128 -57
  112. package/std/term.ts +332 -121
  113. package/std/testing.ts +130 -32
  114. package/std/text.ts +73 -7
  115. package/std/threads.ts +229 -41
  116. package/std/yaml-json.ts +94 -82
  117. package/std/yaml-lines.ts +47 -15
  118. package/std/yaml-write.ts +24 -16
  119. package/std/yaml.ts +764 -384
package/std/threads.ts CHANGED
@@ -2,21 +2,36 @@
2
2
  * `std/threads` — data parallelism, a scope for heterogeneous tasks, and a
3
3
  * lock that owns its data (docs/wp29-thread-surface.md §4.1, §4.2 and §4.3).
4
4
  *
5
- * import { AtomicI32, Mutex, parallelFrom, parallelMap, parallelMapInto, parallelReduce, scope, scopeWithStack } from "nish/threads";
5
+ * import { parallelFrom, parallelMap, parallelMapInto, parallelReduce, scope, scopeWithStack } from "nish/threads";
6
6
  *
7
- * parallelMapInto(src, dst, (x) => x * 3);
8
- * const ys = parallelMap(src, (x) => x * k + b); // k, b: `const` locals, read by the body
9
- * const sq = parallelFrom(n, (i) => i * i);
10
- * const total = parallelReduce(src, (a, b) => a + b, 0);
11
- * {
12
- * using s = scope();
13
- * s.spawn(sumOf, xs, out, 0);
14
- * s.spawn(maxOf, ys, out, 1);
15
- * } // both tasks have run, and `out` holds both answers
16
- * {
17
- * using s = scopeWithStack(64 * 1024 * 1024); // each task's thread has a 64 MiB stack
18
- * s.spawn(checkModule, ast, out, 0);
19
- * }
7
+ * const sumOf = (xs: i32[]): i32 => {
8
+ * let total: i32 = 0;
9
+ * for (const x of xs) {
10
+ * total = total + x;
11
+ * }
12
+ * return total;
13
+ * };
14
+ *
15
+ * export const main = (): i32 => {
16
+ * const src: i32[] = [1, 2, 3, 4];
17
+ * const k: i32 = 10;
18
+ * const dst: i32[] = [0, 0, 0, 0];
19
+ * parallelMapInto(src, dst, (x) => x * 3); // dst is [3, 6, 9, 12]
20
+ * const ys = parallelMap(src, (x) => x * k); // [10, 20, 30, 40]: `k` is read by the body
21
+ * const sq = parallelFrom(4, (i) => i * i); // [0, 1, 4, 9]
22
+ * const total = parallelReduce(src, (a, b) => a + b, 0); // 10
23
+ * const out: i32[] = [0, 0];
24
+ * {
25
+ * using s = scope();
26
+ * s.spawn(sumOf, ys, out, 0);
27
+ * s.spawn(sumOf, sq, out, 1);
28
+ * } // both tasks have run, and `out` is [100, 14]
29
+ * {
30
+ * using s = scopeWithStack(64 * 1024 * 1024); // each task's thread has a 64 MiB stack
31
+ * s.spawn(sumOf, src, out, 0);
32
+ * }
33
+ * return total;
34
+ * };
20
35
  *
21
36
  * **What is written here is the meaning, not the implementation.** Each body
22
37
  * below is the sequential program, and it is what runs under Node, what
@@ -31,7 +46,7 @@
31
46
  * allocates first. So the length check, its message and the order a reduce combines in
32
47
  * are this file's, whichever way the program is compiled.
33
48
  *
34
- * What makes the region safe is checked at the call, not trusted
49
+ * **What makes the region safe is checked at the call, not trusted**
35
50
  * (docs/LANGUAGE.md, "Data parallelism"): the function passed as `f` may write
36
51
  * nothing its caller could observe, may allocate only temporaries it drops
37
52
  * before it returns — they are given back after every element — `dst` may not
@@ -42,7 +57,7 @@
42
57
  * body as a parameter of its own, which no body may write through. Importing this module compiles the program with `--threads`,
43
58
  * because every worker needs an arena of its own.
44
59
  *
45
- * A reduce is deterministic. `src` is split into `min(64, ceil(n / BLOCK))`
60
+ * **A reduce is deterministic.** `src` is split into `min(64, ceil(n / BLOCK))`
46
61
  * blocks, each block is folded from `identity`, and the block results are
47
62
  * combined left to right — here, on one thread, and by the compiled program on
48
63
  * any number of them — so an `f64` sum is the same bits on one core or sixty
@@ -160,6 +175,14 @@ const dstTooShort = (have: i32, want: i32): void => {
160
175
  * `dst[i] = f(src[i])` for every index of `src`, on as many threads as the
161
176
  * machine has and the length is worth. `dst` must be at least as long as
162
177
  * `src`, which is checked once, before any element is written.
178
+ *
179
+ * @param src the elements to map, read and not written.
180
+ * @param dst where `f(src[i])` is written, at the same index. If it is shorter
181
+ * than `src` the program stops before any element is written; any elements
182
+ * past `src.length` are left as they were.
183
+ * @param f computes one element from one element of `src`. It is called once
184
+ * per element, natively on any thread and in no set order, so it may write
185
+ * nothing its caller could observe (see the module header).
163
186
  */
164
187
  export const parallelMapInto = <T, U>(src: T[], dst: U[], f: (x: T) => U): void => {
165
188
  const n: i32 = toI32(src.length)
@@ -173,6 +196,15 @@ export const parallelMapInto = <T, U>(src: T[], dst: U[], f: (x: T) => U): void
173
196
  * `f` folded over `src`, blockwise from `identity` and then left to right over
174
197
  * the blocks, so the answer does not depend on how many threads computed it.
175
198
  * An empty `src` answers `identity`.
199
+ *
200
+ * @param src the elements to fold, read and not written.
201
+ * @param f combines an accumulator with an element, and the blocks' results
202
+ * with each other, so it must be associative for the answer to mean the
203
+ * fold it reads as.
204
+ * @param identity what each block's fold starts from, which must be `f`'s
205
+ * identity, such as `0` for `+`.
206
+ * @returns the fold of every element of `src`, the same however many threads
207
+ * computed it.
176
208
  */
177
209
  export const parallelReduce = <T>(src: T[], f: (acc: T, x: T) => T, identity: T): T => {
178
210
  const blocks: i32 = reduceBlockCount(toI32(src.length))
@@ -192,6 +224,11 @@ export const parallelReduce = <T>(src: T[], f: (acc: T, x: T) => T, identity: T)
192
224
  * A new array of `f(src[i])` for every index of `src`: `parallelMapInto` into
193
225
  * an array this call allocates, before any element is computed, so nothing
194
226
  * but the map itself can hold it while the region runs.
227
+ *
228
+ * @param src the elements to map, read and not written.
229
+ * @param f computes one element from one element of `src`, under the rules
230
+ * `parallelMapInto` gives its `f`.
231
+ * @returns a new array of `src.length` elements, which the caller owns.
195
232
  */
196
233
  export const parallelMap = <T, U>(src: T[], f: (x: T) => U): U[] => {
197
234
  const dst = new Array<U>(toI32(src.length))
@@ -217,6 +254,11 @@ const fromRange = <U>(dst: U[], f: (i: i32) => U, lo: i32, hi: i32): void => {
217
254
  * A new array of `n` elements, `f(i)` at index `i`, computed on as many
218
255
  * threads as the machine has and the length is worth: `Array.from({ length:
219
256
  * n }, (_, i) => f(i))`, with the array allocated before any element is.
257
+ *
258
+ * @param n how many elements the array has.
259
+ * @param f computes the element at an index from the index alone, under the
260
+ * rules `parallelMapInto` gives its `f`.
261
+ * @returns a new array of `n` elements, which the caller owns.
220
262
  */
221
263
  export const parallelFrom = <U>(n: i32, f: (i: i32) => U): U[] => {
222
264
  const dst = new Array<U>(n)
@@ -284,6 +326,7 @@ const slotWritten = (at: i32): boolean => at < 0 || at >= 0
284
326
  */
285
327
  export class ThreadScope {
286
328
  /**
329
+ * @internal Used by `scopeWithStack`.
287
330
  * The stack, in bytes, of each thread the scope's tasks run on, or 0 for the
288
331
  * platform's default. Only `scopeWithStack` writes it, and only
289
332
  * `nish_scope_join` (runtime/runtime-parallel.c) reads it, as the scope's
@@ -296,6 +339,14 @@ export class ThreadScope {
296
339
  * Run `entry(arg)` on a thread of its own and store its answer in `dst[at]`
297
340
  * when the scope closes. `at` is checked here, before the task is taken, and
298
341
  * again when its answer is stored.
342
+ *
343
+ * @param entry the task: a function of one argument, run on a thread of its
344
+ * own when the scope closes.
345
+ * @param arg what `entry` is called with when the task runs.
346
+ * @param dst the array the task's answer is stored in, once every task of
347
+ * the scope has finished.
348
+ * @param at the index in `dst` the answer goes to. One outside `dst` stops
349
+ * the program here, before the task is taken.
299
350
  */
300
351
  spawn<A, R>(entry: (arg: A) => R, arg: A, dst: R[], at: i32): void {
301
352
  if (!slotWritten(at)) {
@@ -317,6 +368,9 @@ export class ThreadScope {
317
368
  * a scope is only ever the receiver of a `spawn` statement, so `s.spawnWith(...)`
318
369
  * written in a program is refused by that rule (NL2389), as passing the
319
370
  * scope would be.
371
+ *
372
+ * @param entry the task, whose answer is dropped.
373
+ * @param arg what `entry` is called with when the task runs.
320
374
  */
321
375
  spawnWith<A, R>(entry: (arg: A) => R, arg: A): void {
322
376
  runWith(entry, arg)
@@ -327,6 +381,8 @@ export class ThreadScope {
327
381
  * captured `const` locals are its arguments, on a thread of its own when the
328
382
  * scope closes, and store nothing. Only the compiler names this method, and
329
383
  * a program that names it is refused as `spawnWith`'s is (NL2389).
384
+ *
385
+ * @param entry the task: an arrow of no parameters, whose answer is dropped.
330
386
  */
331
387
  spawnThunk<R>(entry: () => R): void {
332
388
  runThunk(entry)
@@ -342,7 +398,12 @@ export class ThreadScope {
342
398
  }
343
399
  }
344
400
 
345
- /** A new scope, for a `using` declaration: `using s = scope()`. */
401
+ /**
402
+ * A new scope, for a `using` declaration: `using s = scope()`.
403
+ *
404
+ * @returns a new scope of its own, whose tasks run on threads of the
405
+ * platform's default stack size and are joined when the block ends.
406
+ */
346
407
  export const scope = (): ThreadScope => new ThreadScope()
347
408
 
348
409
  /**
@@ -360,6 +421,11 @@ const MIN_STACK: i32 = 131072
360
421
  * rounds `bytes` up to the page size and adds a guard page below it, so a task
361
422
  * that overflows it faults instead of writing past it. Under Node, and on a
362
423
  * target without threads, the size is checked and has no other effect.
424
+ *
425
+ * @param bytes the least stack each task's thread gets, in bytes. Below
426
+ * 131,072 (128 KiB) is a compile error when it is a constant (NL2584) and
427
+ * stops the program when it is computed.
428
+ * @returns a new scope of its own, joined when the block ends.
363
429
  */
364
430
  export const scopeWithStack = (bytes: i32): ThreadScope => {
365
431
  if (bytes < MIN_STACK) {
@@ -385,6 +451,7 @@ export class MutexGuard<T> {
385
451
  value: T
386
452
 
387
453
  /**
454
+ * @internal Read by nothing written here.
388
455
  * The lock word: 0 when the lock is free, 1 while a guard's block holds it.
389
456
  * Nothing written here reads or writes it. Natively the compiler takes it
390
457
  * with an acquire compare-and-swap in `lock()` and gives it back with a
@@ -393,6 +460,12 @@ export class MutexGuard<T> {
393
460
  */
394
461
  word: i32 = 0
395
462
 
463
+ /**
464
+ * A guard over `value`, with the lock free. `Mutex` makes its one guard
465
+ * with this.
466
+ *
467
+ * @param value the data the lock owns, held as it is, not copied.
468
+ */
396
469
  constructor(value: T) {
397
470
  this.value = value
398
471
  }
@@ -420,8 +493,15 @@ export class MutexGuard<T> {
420
493
  */
421
494
  export class Mutex<T> {
422
495
  /** The one guard, which holds the data; only `lock()` hands it out. */
423
- guard: MutexGuard<T>
496
+ private guard: MutexGuard<T>
424
497
 
498
+ /**
499
+ * A free lock that owns `init`.
500
+ *
501
+ * @param init the data the lock owns. It must be fresh all the way down: a
502
+ * scalar, or a `new` expression or a literal built only from fresh values
503
+ * (NL2463), so that nothing else holds a path to it that skips the lock.
504
+ */
425
505
  constructor(init: T) {
426
506
  this.guard = new MutexGuard<T>(init)
427
507
  }
@@ -429,6 +509,9 @@ export class Mutex<T> {
429
509
  /**
430
510
  * The guard over the data, for a `using` declaration: `using g = m.lock()`.
431
511
  * Natively the call waits until the lock is free and takes it.
512
+ *
513
+ * @returns the lock's one guard, the same object on every call, through
514
+ * whose `value` the data is read and written.
432
515
  */
433
516
  lock(): MutexGuard<T> {
434
517
  return this.guard
@@ -452,37 +535,65 @@ export class Mutex<T> {
452
535
  */
453
536
  export class AtomicI32 {
454
537
  /** The value; named only by this class's methods, which the compiler emits. */
455
- value: i32
538
+ private value: i32
456
539
 
540
+ /**
541
+ * An atomic holding `value`.
542
+ *
543
+ * @param value the starting value.
544
+ */
457
545
  constructor(value: i32) {
458
546
  this.value = value
459
547
  }
460
548
 
461
- /** The value. */
549
+ /**
550
+ * The value.
551
+ *
552
+ * @returns the value at the moment of the read.
553
+ */
462
554
  load(): i32 {
463
555
  return this.value
464
556
  }
465
557
 
466
- /** Sets the value to `value`. */
558
+ /**
559
+ * Sets the value to `value`.
560
+ *
561
+ * @param value the new value.
562
+ */
467
563
  store(value: i32): void {
468
564
  this.value = value
469
565
  }
470
566
 
471
- /** Adds `delta`, wrapping, and answers the value before. */
567
+ /**
568
+ * Adds `delta`, wrapping, and answers the value before.
569
+ *
570
+ * @param delta how much to add; a negative one subtracts.
571
+ * @returns the value just before the addition.
572
+ */
472
573
  add(delta: i32): i32 {
473
574
  const old = this.value
474
575
  this.value = wrappingAdd(old, delta)
475
576
  return old
476
577
  }
477
578
 
478
- /** Subtracts `delta`, wrapping, and answers the value before. */
579
+ /**
580
+ * Subtracts `delta`, wrapping, and answers the value before.
581
+ *
582
+ * @param delta how much to subtract; a negative one adds.
583
+ * @returns the value just before the subtraction.
584
+ */
479
585
  sub(delta: i32): i32 {
480
586
  const old = this.value
481
587
  this.value = wrappingSub(old, delta)
482
588
  return old
483
589
  }
484
590
 
485
- /** Keeps the smaller of the value and `value`, and answers the value before. */
591
+ /**
592
+ * Keeps the smaller of the value and `value`, and answers the value before.
593
+ *
594
+ * @param value the candidate, stored only when it is below the value.
595
+ * @returns the value just before the update.
596
+ */
486
597
  min(value: i32): i32 {
487
598
  const old = this.value
488
599
  if (value < old) {
@@ -491,7 +602,12 @@ export class AtomicI32 {
491
602
  return old
492
603
  }
493
604
 
494
- /** Keeps the larger of the value and `value`, and answers the value before. */
605
+ /**
606
+ * Keeps the larger of the value and `value`, and answers the value before.
607
+ *
608
+ * @param value the candidate, stored only when it is above the value.
609
+ * @returns the value just before the update.
610
+ */
495
611
  max(value: i32): i32 {
496
612
  const old = this.value
497
613
  if (value > old) {
@@ -500,14 +616,27 @@ export class AtomicI32 {
500
616
  return old
501
617
  }
502
618
 
503
- /** Sets the value to `value` and answers the value before. */
619
+ /**
620
+ * Sets the value to `value` and answers the value before.
621
+ *
622
+ * @param value the new value.
623
+ * @returns the value it replaced.
624
+ */
504
625
  exchange(value: i32): i32 {
505
626
  const old = this.value
506
627
  this.value = value
507
628
  return old
508
629
  }
509
630
 
510
- /** Sets the value to `desired` if it is `expected`, and answers the value it saw. */
631
+ /**
632
+ * Sets the value to `desired` if it is `expected`, and answers the value it
633
+ * saw.
634
+ *
635
+ * @param expected the value the update requires.
636
+ * @param desired the value stored when the value is `expected`.
637
+ * @returns the value seen before the update: `expected` exactly when the
638
+ * update happened.
639
+ */
511
640
  compareExchange(expected: i32, desired: i32): i32 {
512
641
  const old = this.value
513
642
  if (old === expected) {
@@ -536,37 +665,67 @@ export class AtomicI32 {
536
665
  */
537
666
  export class AtomicI64 {
538
667
  /** The value; named only by this class's methods, which the compiler emits. */
539
- value: i64
668
+ private value: i64
540
669
 
670
+ /**
671
+ * An atomic holding `value`.
672
+ *
673
+ * @param value the starting value.
674
+ */
541
675
  constructor(value: i64) {
542
676
  this.value = value
543
677
  }
544
678
 
545
- /** The value. */
679
+ /**
680
+ * The value.
681
+ *
682
+ * @returns the value at the moment of the read.
683
+ */
546
684
  load(): i64 {
547
685
  return this.value
548
686
  }
549
687
 
550
- /** Sets the value to `value`. */
688
+ /**
689
+ * Sets the value to `value`.
690
+ *
691
+ * @param value the new value.
692
+ */
551
693
  store(value: i64): void {
552
694
  this.value = value
553
695
  }
554
696
 
555
- /** Adds `delta` and answers the value before; natively the sum wraps at 64 bits. */
697
+ /**
698
+ * Adds `delta` and answers the value before; natively the sum wraps at 64
699
+ * bits.
700
+ *
701
+ * @param delta how much to add; a negative one subtracts.
702
+ * @returns the value just before the addition.
703
+ */
556
704
  add(delta: i64): i64 {
557
705
  const old = this.value
558
706
  this.value = old + delta
559
707
  return old
560
708
  }
561
709
 
562
- /** Subtracts `delta` and answers the value before; natively the difference wraps at 64 bits. */
710
+ /**
711
+ * Subtracts `delta` and answers the value before; natively the difference
712
+ * wraps at 64 bits.
713
+ *
714
+ * @param delta how much to subtract; a negative one adds.
715
+ * @returns the value just before the subtraction.
716
+ */
563
717
  sub(delta: i64): i64 {
564
718
  const old = this.value
565
719
  this.value = old - delta
566
720
  return old
567
721
  }
568
722
 
569
- /** Keeps the smaller of the value and `value`, and answers the value before. */
723
+ /**
724
+ * Keeps the smaller of the value and `value`, and answers the value before.
725
+ *
726
+ * @param value the candidate, stored only when it is below the value.
727
+ * @returns the value just before the update.
728
+ */
570
729
  min(value: i64): i64 {
571
730
  const old = this.value
572
731
  if (value < old) {
@@ -575,7 +734,12 @@ export class AtomicI64 {
575
734
  return old
576
735
  }
577
736
 
578
- /** Keeps the larger of the value and `value`, and answers the value before. */
737
+ /**
738
+ * Keeps the larger of the value and `value`, and answers the value before.
739
+ *
740
+ * @param value the candidate, stored only when it is above the value.
741
+ * @returns the value just before the update.
742
+ */
579
743
  max(value: i64): i64 {
580
744
  const old = this.value
581
745
  if (value > old) {
@@ -584,14 +748,27 @@ export class AtomicI64 {
584
748
  return old
585
749
  }
586
750
 
587
- /** Sets the value to `value` and answers the value before. */
751
+ /**
752
+ * Sets the value to `value` and answers the value before.
753
+ *
754
+ * @param value the new value.
755
+ * @returns the value it replaced.
756
+ */
588
757
  exchange(value: i64): i64 {
589
758
  const old = this.value
590
759
  this.value = value
591
760
  return old
592
761
  }
593
762
 
594
- /** Sets the value to `desired` if it is `expected`, and answers the value it saw. */
763
+ /**
764
+ * Sets the value to `desired` if it is `expected`, and answers the value it
765
+ * saw.
766
+ *
767
+ * @param expected the value the update requires.
768
+ * @param desired the value stored when the value is `expected`.
769
+ * @returns the value seen before the update: `expected` exactly when the
770
+ * update happened.
771
+ */
595
772
  compareExchange(expected: i64, desired: i64): i64 {
596
773
  const old = this.value
597
774
  if (old === expected) {
@@ -628,27 +805,35 @@ export class AtomicI64 {
628
805
  */
629
806
  export class Channel<T> {
630
807
  /** Under Node: every value sent, in the order it was sent. */
631
- queue: T[]
808
+ private queue: T[]
632
809
 
633
810
  /** Under Node: how many of `queue`'s values a loop has taken. */
634
- head: i32 = 0
811
+ private head: i32 = 0
635
812
 
636
813
  /**
814
+ * @internal Read by nothing written here.
637
815
  * Natively: the runtime's handle on the channel (runtime/runtime-parallel.c),
638
816
  * 0 until the channel is first used. Nothing written here reads or writes it.
639
817
  */
640
818
  state: i64 = 0
641
819
 
820
+ /** An empty channel, open until its scope joins. */
642
821
  constructor() {
643
822
  this.queue = []
644
823
  }
645
824
 
646
- /** Hand `x` to the receiver. It never waits: a channel holds as many values as are sent. */
825
+ /**
826
+ * Hand `x` to the receiver. It never waits: a channel holds as many values
827
+ * as are sent.
828
+ *
829
+ * @param x the value to send. A string is copied out of the sender's arena.
830
+ */
647
831
  send(x: T): void {
648
832
  this.queue.push(x)
649
833
  }
650
834
 
651
835
  /**
836
+ * @internal Called by `ChannelWalk`.
652
837
  * The next value, for a loop that has found one waiting (`ChannelWalk`).
653
838
  * Natively the loop is the compiler's, which takes a value with the runtime
654
839
  * instead, and nothing calls this.
@@ -659,7 +844,7 @@ export class Channel<T> {
659
844
  return x
660
845
  }
661
846
 
662
- /** Whether a value is waiting, under Node, where nothing is sent while a loop runs. */
847
+ /** @internal Called by `ChannelWalk`. Whether a value is waiting, under Node, where nothing is sent while a loop runs. */
663
848
  ready(): boolean {
664
849
  return this.head < toI32(this.queue.length)
665
850
  }
@@ -668,6 +853,9 @@ export class Channel<T> {
668
853
  * What `for (const x of ch)` asks for under Node: a walk that takes each
669
854
  * value as it reaches it, so a second loop over the channel finds it empty,
670
855
  * as it does natively.
856
+ *
857
+ * @returns A fresh walk over this channel; each step takes a value, and
858
+ * the walk ends at the first step that finds none waiting.
671
859
  */
672
860
  [Symbol.iterator](): ChannelWalk<T> {
673
861
  return new ChannelWalk<T>(this)
@@ -679,7 +867,7 @@ export class Channel<T> {
679
867
  * never made: the compiler lowers the loop itself.
680
868
  */
681
869
  class ChannelWalk<T> {
682
- channel: Channel<T>
870
+ private channel: Channel<T>
683
871
 
684
872
  constructor(channel: Channel<T>) {
685
873
  this.channel = channel