@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
@@ -3,6 +3,7 @@
3
3
  * starts one worker process per core, restarts one that dies, and stops them
4
4
  * all on SIGTERM or SIGINT (`docs/wp42-multicore-server.md` §2.3).
5
5
  *
6
+ * import { tcpListenFlags } from "nish:net";
6
7
  * import { preforkWorkers } from "nish/net/prefork";
7
8
  *
8
9
  * export const main = (): number => {
@@ -40,36 +41,39 @@
40
41
  * a callback. With `serviceWorker` set, every other worker gets a pair to that
41
42
  * worker. The ends go through `spawnWithFds`, from descriptor 3 in a fixed
42
43
  * order: the supervisor channel, then a worker's service channel, or in the
43
- * service worker its end to each other worker by index, skipping its own. Where
44
- * they landed rides in `--nish-prefork-channels=` just before the worker flag,
45
- * and `preforkSupervisorChannel`, `preforkServiceChannel` and
46
- * `preforkServiceChannelOf` read it back. A pair cannot be handed to a worker
47
- * already running, so service channels make the workers one group: when any of
48
- * them exits, the supervisor sends the rest SIGTERM (SIGKILL after `graceMs`),
49
- * and once none is left, starts them all again on fresh pairs, after the
50
- * backoff of the one that exited first. No worker keeps an end whose peer is
51
- * gone longer than that. With `restart` off nothing is signalled; a worker sees
52
- * its peer's exit as a hang-up.
44
+ * service worker its end to each other worker by index, skipping its own.
53
45
  *
54
- * **Listeners and pinning.** With `listenPort` set (0 or above), the
55
- * supervisor binds one `SO_REUSEPORT` listener per worker itself, in index
56
- * order, keeps them for its whole run and hands listener `k` to every start of
57
- * worker `k` after the channel ends; `preforkListener(args)` answers it in the
58
- * worker (`--nish-prefork-listener=`, before the channels flag), so a worker
59
- * serves that descriptor instead of binding its own. Port 0 binds the first
60
- * listener anywhere and the rest to its port. With `pin` on as well, each
61
- * listener steers by CPU (`tcpListenFlags`' flag 4): the kernel hands a
62
- * connection that arrived on CPU `k` to listener `k`, and a worker that is
63
- * restarted takes the same listener, so the order holds across restarts,
64
- * which it would not if each worker bound its own. `pin` alone makes each
65
- * worker call `setCpuAffinity(k)` before `preforkWith` answers it, so worker
66
- * `k` runs on CPU `k` only; a worker the kernel refuses (CPU `k` outside the
67
- * process's mask) says so on stderr and runs unpinned. More workers than
68
- * `availableParallelism()` is refused with a panic, since a worker past the
69
- * last CPU would be pinned nowhere and, steered, handed nothing. Pinning and
70
- * steering are Linux's: elsewhere the supervisor says once that the workers
71
- * run unpinned, and the listeners are plain `SO_REUSEPORT` ones. Both are off
72
- * by default.
46
+ * Where they landed rides in `--nish-prefork-channels=` just before the worker
47
+ * flag, and `preforkSupervisorChannel`, `preforkServiceChannel` and
48
+ * `preforkServiceChannelOf` read it back. A pair cannot be handed to a worker
49
+ * already running, so service channels make the workers one group: when any of
50
+ * them exits, the supervisor sends the rest SIGTERM (SIGKILL after `graceMs`),
51
+ * and once none is left, starts them all again on fresh pairs, after the
52
+ * backoff of the one that exited first. No worker keeps an end whose peer is
53
+ * gone longer than that. With `restart` off nothing is signalled; a worker sees
54
+ * its peer's exit as a hang-up.
55
+ *
56
+ * **Listeners and pinning.** With `listenPort` set (0 or above), the supervisor
57
+ * binds one `SO_REUSEPORT` listener per worker itself, in index order, keeps
58
+ * them for its whole run and hands listener `k` to every start of worker `k`
59
+ * after the channel ends; `preforkListener(args)` answers it in the worker
60
+ * (`--nish-prefork-listener=`, before the channels flag), so a worker serves
61
+ * that descriptor instead of binding its own. Port 0 binds the first listener
62
+ * anywhere and the rest to its port.
63
+ *
64
+ * With `pin` on as well, each listener steers by CPU (`tcpListenFlags`' flag
65
+ * 4): the kernel hands a connection that arrived on CPU `k` to listener `k`,
66
+ * and a worker that is restarted takes the same listener, so the order holds
67
+ * across restarts, which it would not if each worker bound its own. `pin` alone
68
+ * makes each worker call `setCpuAffinity(k)` before `preforkWith` answers it,
69
+ * so worker `k` runs on CPU `k` only; a worker the kernel refuses (CPU `k`
70
+ * outside the process's mask) says so on stderr and runs unpinned.
71
+ *
72
+ * More workers than `availableParallelism()` is refused with a panic, since a
73
+ * worker past the last CPU would be pinned nowhere and, steered, handed
74
+ * nothing. Pinning and steering are Linux's: elsewhere the supervisor says once
75
+ * that the workers run unpinned, and the listeners are plain `SO_REUSEPORT`
76
+ * ones. Both are off by default.
73
77
  *
74
78
  * **How many.** `NISH_WORKERS` when it is a positive whole number, else
75
79
  * `PreforkConfig.workers` when that is positive, else
@@ -222,6 +226,12 @@ const preforkDigits = (s: string): boolean => {
222
226
  * How many workers to start: `env` (`NISH_WORKERS`, `null` when unset) when it
223
227
  * is a positive whole number, else `requested` when positive, else the
224
228
  * platform's default.
229
+ *
230
+ * @param requested the program's own choice, `PreforkConfig.workers`; 0 or
231
+ * less leaves it to the environment or the platform
232
+ * @param env the raw `NISH_WORKERS` text, or `null` when it is unset; text
233
+ * that is not a positive whole number is ignored
234
+ * @returns how many worker processes the supervisor starts, always 1 or more
225
235
  */
226
236
  export const preforkWorkerCount = (requested: i32, env: string | null): i32 => {
227
237
  if (env !== null && preforkDigits(env)) {
@@ -240,7 +250,13 @@ export const preforkWorkerCount = (requested: i32, env: string | null): i32 => {
240
250
  return cores > 0 ? cores : 1
241
251
  }
242
252
 
243
- /** The worker index `args` carries in its last element, or -1 when none. */
253
+ /**
254
+ * The worker index `args` carries in its last element, or -1 when none.
255
+ *
256
+ * @param args the process's arguments, `process.argv`
257
+ * @returns this worker's index, 0 to `N - 1`, or -1 in the supervisor (or any
258
+ * process not started by one)
259
+ */
244
260
  export const preforkIndex = (args: string[]): i32 => {
245
261
  if (args.length < 2) {
246
262
  return -1
@@ -256,6 +272,10 @@ export const preforkIndex = (args: string[]): i32 => {
256
272
  /**
257
273
  * `args` (`process.argv`) without the worker flag and the channels and
258
274
  * listener flags before it, the same in every process.
275
+ *
276
+ * @param args the process's arguments, `process.argv`
277
+ * @returns a new list of the arguments the user gave, without the flags the
278
+ * supervisor appended, so a worker reads the same ones the supervisor did
259
279
  */
260
280
  export const preforkArgs = (args: string[]): string[] => {
261
281
  let keep: i32 = toI32(args.length)
@@ -299,17 +319,41 @@ const preforkChannel = (args: string[], at: i32): i32 => {
299
319
  return preforkDigits(field) ? parseInt(field) : -1
300
320
  }
301
321
 
302
- /** In a worker, its end of its supervisor channel; -1 when it has none. */
322
+ /**
323
+ * In a worker, its end of its supervisor channel; -1 when it has none.
324
+ *
325
+ * @param args the worker's arguments, `process.argv`
326
+ * @returns the descriptor the worker talks to the supervisor through, or -1
327
+ * without `supervisorChannels` or outside a worker
328
+ */
303
329
  export const preforkSupervisorChannel = (args: string[]): i32 => preforkChannel(args, 0)
304
330
 
305
- /** In a worker, its end of its channel to the service worker; -1 in the service worker or when none. */
331
+ /**
332
+ * In a worker, its end of its channel to the service worker; -1 in the service worker or when none.
333
+ *
334
+ * @param args the worker's arguments, `process.argv`
335
+ * @returns the descriptor this worker reaches the service worker through, or -1
336
+ */
306
337
  export const preforkServiceChannel = (args: string[]): i32 => preforkChannel(args, 1)
307
338
 
308
- /** In the service worker, its end of the channel to worker `index`; -1 for itself or elsewhere. */
339
+ /**
340
+ * In the service worker, its end of the channel to worker `index`; -1 for itself or elsewhere.
341
+ *
342
+ * @param args the service worker's arguments, `process.argv`
343
+ * @param index the other worker whose channel to look up, 0 to `N - 1`
344
+ * @returns the descriptor the service worker reaches worker `index` through,
345
+ * or -1 for its own index, an index out of range, or any other process
346
+ */
309
347
  export const preforkServiceChannelOf = (args: string[], index: i32): i32 =>
310
348
  index < 0 || index > 2147483645 ? -1 : preforkChannel(args, 2 + index)
311
349
 
312
- /** In a worker, the listener the supervisor bound for it (`listenPort`); -1 when none. */
350
+ /**
351
+ * In a worker, the listener the supervisor bound for it (`listenPort`); -1 when none.
352
+ *
353
+ * @param args the worker's arguments, `process.argv`
354
+ * @returns the listening socket's descriptor to serve instead of binding one,
355
+ * or -1 when the worker should bind its own
356
+ */
313
357
  export const preforkListener = (args: string[]): i32 => {
314
358
  if (preforkIndex(args) < 0) {
315
359
  return -1
@@ -333,40 +377,89 @@ const PREFORK_SIGKILL: i32 = 9
333
377
 
334
378
  /** One worker's slot in the supervisor. */
335
379
  class PreforkSlot {
336
- /** When the running worker started, or when the waiting one may start. */
380
+ /**
381
+ * When the running worker started, or when the waiting one may start.
382
+ *
383
+ * @internal Read and set by `PreforkSupervisor`'s start, backoff and restart to time a worker's restart.
384
+ */
337
385
  at: i64 = 0
338
- /** The running worker's pid, 0 while it waits to be started again. */
386
+ /**
387
+ * The running worker's pid, 0 while it waits to be started again.
388
+ *
389
+ * @internal Read by `PreforkSupervisor` to match a reaped child to its slot and to signal it.
390
+ */
339
391
  pid: i32 = 0
340
- /** The wait before the last restart, 0 after a worker that ran long. */
392
+ /**
393
+ * The wait before the last restart, 0 after a worker that ran long.
394
+ *
395
+ * @internal Read and set by `PreforkSupervisor.backoff` to double the wait after a quick exit.
396
+ */
341
397
  delay: i32 = 0
342
- /** The worker exited with `restart` off, and is never started again. */
398
+ /**
399
+ * The worker exited with `restart` off, and is never started again.
400
+ *
401
+ * @internal Read by `PreforkSupervisor`'s restarts so a worker that exited with `restart` off stays gone.
402
+ */
343
403
  gone: boolean = false
344
- /** The supervisor's end of the worker's channel, -1 when it has none. */
404
+ /**
405
+ * The supervisor's end of the worker's channel, -1 when it has none.
406
+ *
407
+ * @internal Read by `preforkSupervise` to hand the end to the program's callback, and closed by `PreforkSupervisor.closeChannel`.
408
+ */
345
409
  channel: i32 = -1
346
410
  }
347
411
 
348
412
  /** The supervisor's state while it runs. */
349
413
  class PreforkSupervisor {
350
- config: PreforkConfig
414
+ private config: PreforkConfig
415
+ /**
416
+ * The executable each worker is spawned from: `/proc/self/exe` resolved on
417
+ * Linux, else the program's first argument.
418
+ *
419
+ * @internal Read by `preforkSupervise` to name the program when its first
420
+ * start fails.
421
+ */
351
422
  program: string
352
- args: string[]
423
+ private args: string[]
424
+ /**
425
+ * One slot per worker, by index.
426
+ *
427
+ * @internal Read by `preforkSupervise` to find a worker's channel from the
428
+ * token its readiness event carries.
429
+ */
353
430
  slots: PreforkSlot[]
354
431
  /** While the group starts: each worker's end to the service worker, -1 for none. */
355
- toService: i32[]
432
+ private toService: i32[]
356
433
  /** While the group starts: the service worker's end to each worker, -1 for none. */
357
- fromWorkers: i32[]
434
+ private fromWorkers: i32[]
358
435
  /** When a group still running gets SIGKILL. */
359
- cascadeAt: i64 = 0
436
+ private cascadeAt: i64 = 0
437
+ /**
438
+ * How many workers are running now, started and not yet reaped.
439
+ *
440
+ * @internal Read by `preforkSupervise` to see when, with `restart` off,
441
+ * every worker has exited.
442
+ */
360
443
  running: i32 = 0
361
444
  /** The readiness loop each supervisor channel is added to. */
362
- loop: i32
445
+ private loop: i32
363
446
  /** `config.serviceWorker`: with it at 0 or above, the workers are one group. */
364
- service: i32
447
+ private service: i32
365
448
  /** The group is being stopped, to be started again once none of it is left. */
366
- cascading: boolean = false
449
+ private cascading: boolean = false
367
450
  /** Worker i's listener at i, held for the whole run; empty without `listenPort`. */
368
- listeners: i32[]
451
+ private listeners: i32[]
369
452
 
453
+ /**
454
+ * A supervisor with one empty slot per worker and no worker started yet.
455
+ *
456
+ * @param config the checked settings it runs by, kept and read throughout
457
+ * @param args the supervisor's own arguments, `process.argv`, which every
458
+ * worker is started with
459
+ * @param count how many workers to keep running
460
+ * @param loop the readiness loop each supervisor channel is added to; the
461
+ * caller owns and closes it
462
+ */
370
463
  constructor(config: PreforkConfig, args: string[], count: i32, loop: i32) {
371
464
  this.config = config
372
465
  this.loop = loop
@@ -391,7 +484,7 @@ class PreforkSupervisor {
391
484
  * Start worker `index` with its channel ends, the service ones from
392
485
  * `pairs`; false when a socketpair, the loop or the spawn refused it.
393
486
  */
394
- start(index: i32): boolean {
487
+ private start(index: i32): boolean {
395
488
  const fds: i32[] = []
396
489
  let own: i32 = -1
397
490
  if (this.config.supervisorChannels) {
@@ -458,7 +551,7 @@ class PreforkSupervisor {
458
551
  }
459
552
 
460
553
  /** The slot `pid` ran in, or -1. */
461
- find(pid: i32): i32 {
554
+ private find(pid: i32): i32 {
462
555
  for (let i: i32 = 0; i < toI32(this.slots.length); i++) {
463
556
  if (this.slots[i].pid === pid) {
464
557
  return i
@@ -472,7 +565,7 @@ class PreforkSupervisor {
472
565
  * at least `quickExitMs`, else, or when `failed` (`spawn` refused it), after
473
566
  * a wait that starts at `backoffMs` and doubles up to `backoffCapMs`.
474
567
  */
475
- backoff(slot: PreforkSlot, now: i64, failed: boolean): void {
568
+ private backoff(slot: PreforkSlot, now: i64, failed: boolean): void {
476
569
  if (failed || now - slot.at < toI64(this.config.quickExitMs)) {
477
570
  const cap: i32 = this.config.backoffCapMs
478
571
  if (slot.delay === 0) {
@@ -493,6 +586,8 @@ class PreforkSupervisor {
493
586
  * program spawned itself before calling `preforkWith`) is reaped too, and
494
587
  * its status is discarded. Answers false when `waitPid` fails, which means
495
588
  * no child is left to wait for.
589
+ *
590
+ * @internal Called by `preforkSupervise` on every tick, and by `stop`.
496
591
  */
497
592
  reap(stopping: boolean): boolean {
498
593
  while (this.running > 0) {
@@ -529,7 +624,11 @@ class PreforkSupervisor {
529
624
  return true
530
625
  }
531
626
 
532
- /** Close the supervisor's end of `slot`'s channel, which takes it off the loop. */
627
+ /**
628
+ * Close the supervisor's end of `slot`'s channel, which takes it off the loop.
629
+ *
630
+ * @internal Called by `preforkSupervise` after a channel hangs up.
631
+ */
533
632
  closeChannel(slot: PreforkSlot): void {
534
633
  if (slot.channel >= 0) {
535
634
  netClose(slot.channel)
@@ -538,13 +637,17 @@ class PreforkSupervisor {
538
637
  }
539
638
 
540
639
  /** Stop the group so it starts again whole: SIGTERM now, SIGKILL after `graceMs`. */
541
- cascade(now: i64): void {
640
+ private cascade(now: i64): void {
542
641
  this.cascading = true
543
642
  this.cascadeAt = now + toI64(this.config.graceMs)
544
643
  this.signal(PREFORK_SIGTERM)
545
644
  }
546
645
 
547
- /** SIGKILL a stopping group that outlived `graceMs`, again each `graceMs`. */
646
+ /**
647
+ * SIGKILL a stopping group that outlived `graceMs`, again each `graceMs`.
648
+ *
649
+ * @internal Called by `preforkSupervise` on every tick.
650
+ */
548
651
  escalate(): void {
549
652
  if (!this.cascading || this.running <= 0) {
550
653
  return
@@ -557,7 +660,7 @@ class PreforkSupervisor {
557
660
  }
558
661
 
559
662
  /** A pair from each worker to the service worker; false when one failed. */
560
- pairs(): boolean {
663
+ private pairs(): boolean {
561
664
  for (let i: i32 = 0; i < toI32(this.slots.length); i++) {
562
665
  if (i !== this.service) {
563
666
  const pair: i32[] = [-1, -1]
@@ -572,7 +675,7 @@ class PreforkSupervisor {
572
675
  }
573
676
 
574
677
  /** Close every end `pairs` made: the workers hold their copies now. */
575
- closePairs(): void {
678
+ private closePairs(): void {
576
679
  for (let i: i32 = 0; i < toI32(this.slots.length); i++) {
577
680
  if (this.toService[i] >= 0) {
578
681
  netClose(this.toService[i])
@@ -591,7 +694,7 @@ class PreforkSupervisor {
591
694
  * false when `first`; otherwise it backs off the slot that failed and stops
592
695
  * the workers it started, to be tried again whole.
593
696
  */
594
- restartGroup(first: boolean): boolean {
697
+ private restartGroup(first: boolean): boolean {
595
698
  if (this.running > 0) {
596
699
  return true
597
700
  }
@@ -631,6 +734,8 @@ class PreforkSupervisor {
631
734
  * Start every waiting worker whose time has come. When `first`, answer false
632
735
  * at the first `spawn` that fails; otherwise a failed start waits on the
633
736
  * same backoff as a worker that exited at once, and the answer is true.
737
+ *
738
+ * @internal Called by `preforkSupervise` for the first start and on every tick.
634
739
  */
635
740
  restart(first: boolean): boolean {
636
741
  if (this.service >= 0) {
@@ -653,6 +758,8 @@ class PreforkSupervisor {
653
758
  /**
654
759
  * One listener per worker, in index order, which is the order steering
655
760
  * counts CPUs in; false, with the ones made closed, when one cannot bind.
761
+ *
762
+ * @internal Called by `preforkSupervise` before the first start when `listenPort` is set.
656
763
  */
657
764
  listen(steer: boolean): boolean {
658
765
  const config: PreforkConfig = this.config
@@ -673,7 +780,11 @@ class PreforkSupervisor {
673
780
  return true
674
781
  }
675
782
 
676
- /** Close the listeners `listen` made. */
783
+ /**
784
+ * Close the listeners `listen` made.
785
+ *
786
+ * @internal Called by `preforkSupervise` once the workers are stopped.
787
+ */
677
788
  closeListeners(): void {
678
789
  for (let i: i32 = 0; i < toI32(this.listeners.length); i++) {
679
790
  netClose(this.listeners[i])
@@ -682,7 +793,7 @@ class PreforkSupervisor {
682
793
  }
683
794
 
684
795
  /** Send `sig` to every running worker. */
685
- signal(sig: i32): void {
796
+ private signal(sig: i32): void {
686
797
  for (let i: i32 = 0; i < toI32(this.slots.length); i++) {
687
798
  if (this.slots[i].pid > 0) {
688
799
  kill(this.slots[i].pid, sig)
@@ -697,6 +808,8 @@ class PreforkSupervisor {
697
808
  * child that is not a worker is skipped in both phases, and the SIGKILL
698
809
  * phase ends only when the last worker is reaped or no child is left. The
699
810
  * supervisor's channel ends are closed first, so only `signals` wakes it.
811
+ *
812
+ * @internal Called by `preforkSupervise` once, on shutdown.
700
813
  */
701
814
  stop(loop: i32, signals: i32, ready: i32[]): void {
702
815
  for (let i: i32 = 0; i < toI32(this.slots.length); i++) {
@@ -778,6 +891,13 @@ const preforkDiscard = (buf: u8[], _index: i32, fd: i32, _events: i32): void =>
778
891
  * listener could be made (no worker is started). Panics on a config
779
892
  * `preforkInvalid` names a field of. Supervisor channels are read and
780
893
  * dropped; `preforkSupervise` hands them to the program.
894
+ *
895
+ * @param args the process's arguments, `process.argv`
896
+ * @param config the supervisor's settings, every field checked (a bad one
897
+ * panics) in the supervisor and each worker alike; past that check a
898
+ * worker reads only `pin`
899
+ * @returns in a worker, its index at once; in the supervisor, once it is done,
900
+ * `PREFORK_STOPPED`, `PREFORK_WORKERS_EXITED` or `PREFORK_SPAWN_FAILED`
781
901
  */
782
902
  export const preforkWith = (args: string[], config: PreforkConfig): i32 => {
783
903
  const buf: u8[] = new Array<u8>(512)
@@ -791,13 +911,24 @@ export const preforkWith = (args: string[], config: PreforkConfig): i32 => {
791
911
  * error. The callback reads what is waiting, since an end left readable wakes
792
912
  * the loop again at once, and may write back, but never closes `fd`: the
793
913
  * supervisor closes it after a hang-up, when the worker is reaped and when it
794
- * stops, and a restarted worker comes with a new one. Panics, besides, when
795
- * `serviceWorker` is not below the worker count or the count is above 64 with
796
- * a service worker (63 with `listenPort`), the most `spawnWithFds` hands one
797
- * child; when `pin`, on Linux, asks for more workers than
798
- * `availableParallelism()`; and, through `preforkInvalid`, on seqpacket
914
+ * stops, and a restarted worker comes with a new one.
915
+ *
916
+ * Panics, besides, when `serviceWorker` is not below the worker count or the
917
+ * count is above 64 with a service worker (63 with `listenPort`), the most
918
+ * `spawnWithFds` hands one child; when `pin`, on Linux, asks for more workers
919
+ * than `availableParallelism()`; and, through `preforkInvalid`, on seqpacket
799
920
  * channels off Linux. A listener that cannot bind answers
800
921
  * `PREFORK_SPAWN_FAILED` before any worker starts.
922
+ *
923
+ * @param args the process's arguments, `process.argv`
924
+ * @param config the supervisor's settings, every field checked (a bad one
925
+ * panics) in the supervisor and each worker alike; past that check a
926
+ * worker reads only `pin`
927
+ * @param state the program's own value, passed to every `onChannel` call
928
+ * @param onChannel what the supervisor runs when worker `index`'s channel
929
+ * `fd` wakes it, with `pollWait`'s `events`
930
+ * @returns in a worker, its index at once; in the supervisor, once it is done,
931
+ * `PREFORK_STOPPED`, `PREFORK_WORKERS_EXITED` or `PREFORK_SPAWN_FAILED`
801
932
  */
802
933
  export const preforkSupervise = <S>(
803
934
  args: string[],
@@ -888,5 +1019,11 @@ export const preforkSupervise = <S>(
888
1019
  return result
889
1020
  }
890
1021
 
891
- /** `preforkWith` with the default `PreforkConfig`. */
1022
+ /**
1023
+ * `preforkWith` with the default `PreforkConfig`.
1024
+ *
1025
+ * @param args the process's arguments, `process.argv`
1026
+ * @returns in a worker, its index at once; in the supervisor, once it is done,
1027
+ * `PREFORK_STOPPED` or `PREFORK_SPAWN_FAILED`
1028
+ */
892
1029
  export const preforkWorkers = (args: string[]): i32 => preforkWith(args, new PreforkConfig())