@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/shm.ts CHANGED
@@ -16,13 +16,15 @@
16
16
  * **A region is a named POSIX shared-memory object** (`/dev/shm/<name>` on
17
17
  * Linux, `shm_open("/<name>")` on Darwin) mapped shared, so every process that
18
18
  * opens the name sees the same bytes. A name is 1 to 30 of `A-Z a-z 0-9 . _ -`,
19
- * not starting with `.`. `createRegion` makes it with mode 0600 and refuses a
20
- * name that exists (`SHM_EXISTS`), so a name another user planted is never
21
- * adopted; `openRegion` refuses a region this user does not own, that anyone
22
- * else may read or write, or (on Linux) that is not a regular file or has a
23
- * second hard link (`SHM_ACCESS`). The name stays until `unlinkRegion`,
24
- * even after every process has exited, which is how a process that starts later
25
- * finds it; the mapping goes away with `close` or with the process.
19
+ * not starting with `.`.
20
+ *
21
+ * `createRegion` makes it with mode 0600 and refuses a name that exists
22
+ * (`SHM_EXISTS`), so a name another user planted is never adopted; `openRegion`
23
+ * refuses a region this user does not own, that anyone else may read or write,
24
+ * or (on Linux) that is not a regular file or has a second hard link
25
+ * (`SHM_ACCESS`). The name stays until `unlinkRegion`, even after every process
26
+ * has exited, which is how a process that starts later finds it; the mapping
27
+ * goes away with `close` or with the process.
26
28
  *
27
29
  * **Why named, and no anonymous region made before `fork`.** A Nish program
28
30
  * has no `fork`: `spawn` and `nish/net/prefork` start a program with `exec`,
@@ -139,6 +141,12 @@ export class ShmError {
139
141
  /** What it means, such as `File exists`. */
140
142
  message: string
141
143
 
144
+ /**
145
+ * The error for one errno, with its text: `strerror`'s, except that 95
146
+ * (`SHM_UNSUPPORTED` negated) reads "not supported on this platform".
147
+ * @param code the errno the runtime answered, positive (the negation of a
148
+ * failed call's result), such as `SHM_EXISTS`
149
+ */
142
150
  constructor(code: i32) {
143
151
  this.code = code
144
152
  this.message = code === 95 ? "not supported on this platform" : strerror(code)
@@ -156,6 +164,15 @@ const shmDone = (rc: i32): Result<void, ShmError> => {
156
164
  /**
157
165
  * Creates the region `name`, `bytes` long and zeroed, mode 0600, and maps it.
158
166
  * `SHM_EXISTS` when the name is taken: unlink a stale one first.
167
+ * @param name the region's name, 1 to 30 of `A-Z a-z 0-9 . _ -`, not
168
+ * starting with `.`; anything else is `SHM_INVALID`
169
+ * @param bytes the region's length, from 1 to 1 GiB; outside that is
170
+ * `SHM_INVALID`
171
+ * @returns a new `SharedRegion` mapping the fresh region, which this thread
172
+ * alone can use and which stays mapped until its `close` or the process
173
+ * ends; or the `ShmError`: `SHM_EXISTS`, `SHM_INVALID`, `SHM_TOO_MANY`
174
+ * when this thread has 63 regions open, code 95 on wasi, or the errno the
175
+ * system gave
159
176
  */
160
177
  export const createRegion = (name: string, bytes: i32): Result<SharedRegion, ShmError> => {
161
178
  const h: i32 = nishshm_create(name, bytes)
@@ -168,6 +185,15 @@ export const createRegion = (name: string, bytes: i32): Result<SharedRegion, Shm
168
185
  /**
169
186
  * Maps the region `name` that some process of this user created. Its size is
170
187
  * the region's (on Darwin, rounded up to a page).
188
+ * @param name the name the region was created under, with `createRegion`'s
189
+ * rules (`SHM_INVALID` otherwise)
190
+ * @returns a new `SharedRegion` on the same bytes every other mapping of the
191
+ * name sees, which this thread alone can use until its `close`; or the
192
+ * `ShmError`: `SHM_NOT_FOUND`, `SHM_ACCESS` for a region another user owns,
193
+ * that others may read or write, or (on Linux) that is not a regular file
194
+ * or has a second hard link, `SHM_INVALID` for a bad name or a region of
195
+ * size 0 or over 1 GiB, `SHM_TOO_MANY`, code 95 on wasi, or the errno the
196
+ * system gave
171
197
  */
172
198
  export const openRegion = (name: string): Result<SharedRegion, ShmError> => {
173
199
  const h: i32 = nishshm_open(name)
@@ -180,10 +206,21 @@ export const openRegion = (name: string): Result<SharedRegion, ShmError> => {
180
206
  /**
181
207
  * Removes the name, so no process can open it again; every mapping of it
182
208
  * stays valid until it is closed. `SHM_NOT_FOUND` when there is none.
209
+ * @param name the region's name, with `createRegion`'s rules (`SHM_INVALID`
210
+ * otherwise)
211
+ * @returns `Ok()` once the name is gone, or the `ShmError`: `SHM_NOT_FOUND`,
212
+ * `SHM_INVALID`, code 95 on wasi, or the errno the system gave
183
213
  */
184
214
  export const unlinkRegion = (name: string): Result<void, ShmError> => shmDone(nishshm_unlink(name))
185
215
 
186
- /** A fence of `order`, for the accesses around it. */
216
+ /**
217
+ * A fence of `order`, for the accesses around it: C11's
218
+ * `atomic_thread_fence`, so it orders the calling thread's accesses, to
219
+ * regions and to its own memory, exactly as that fence does; `RELAXED` is no
220
+ * fence at all.
221
+ * @param order `RELAXED`, `ACQUIRE`, `RELEASE`, `ACQ_REL` or `SEQ_CST`; any
222
+ * other value panics
223
+ */
187
224
  export const fence = (order: i32): void => {
188
225
  nishshm_fence(order)
189
226
  }
@@ -194,33 +231,72 @@ export const fence = (order: i32): void => {
194
231
  */
195
232
  export class SharedRegion {
196
233
  /** The runtime's handle; it names nothing after `close`. */
197
- handle: i32
234
+ private handle: i32
198
235
 
236
+ /**
237
+ * Wraps a handle the runtime answered. A program gets a region from
238
+ * `createRegion` or `openRegion` instead; a handle that names no region
239
+ * open on this thread makes every access panic, and `close` answer code 9.
240
+ * @param handle the runtime's handle for a mapped region, as
241
+ * `nishshm_create` or `nishshm_open` answered it
242
+ */
199
243
  constructor(handle: i32) {
200
244
  this.handle = handle
201
245
  }
202
246
 
203
- /** The region's length in bytes. */
247
+ /**
248
+ * The region's length in bytes.
249
+ * @returns the mapped length: what `createRegion` was given, or what
250
+ * `openRegion` found (on Darwin, rounded up to a page)
251
+ */
204
252
  size(): i32 {
205
253
  return nishshm_size(this.handle)
206
254
  }
207
255
 
208
- /** The 32-bit slot at `at`. */
256
+ /**
257
+ * Loads the 32-bit slot at `at`, one atomic load.
258
+ * @param at the slot's byte offset from the region's start, a multiple of
259
+ * 4 with the whole slot inside the region; anything else panics
260
+ * @param order `RELAXED`, `ACQUIRE` or `SEQ_CST`; another panics
261
+ * @returns the value the slot held
262
+ */
209
263
  loadI32(at: i32, order: i32): i32 {
210
264
  return nishshm_load_i32(this.handle, at, order)
211
265
  }
212
266
 
213
- /** Sets the 32-bit slot at `at` to `value`. */
267
+ /**
268
+ * Sets the 32-bit slot at `at` to `value`, one atomic store.
269
+ * @param at the slot's byte offset from the region's start, a multiple of
270
+ * 4 with the whole slot inside the region; anything else panics
271
+ * @param value what the slot holds after
272
+ * @param order `RELAXED`, `RELEASE` or `SEQ_CST`; another panics
273
+ */
214
274
  storeI32(at: i32, value: i32, order: i32): void {
215
275
  nishshm_store_i32(this.handle, at, value, order)
216
276
  }
217
277
 
218
- /** Adds `delta` to the 32-bit slot at `at`, wrapping, and answers the value before. */
278
+ /**
279
+ * Adds `delta` to the 32-bit slot at `at`, wrapping, and answers the value
280
+ * before, as one atomic read-modify-write.
281
+ * @param at the slot's byte offset from the region's start, a multiple of
282
+ * 4 with the whole slot inside the region; anything else panics
283
+ * @param delta what is added; negative subtracts
284
+ * @param order any of the five orderings; another value panics
285
+ * @returns the value the slot held just before the add
286
+ */
219
287
  addI32(at: i32, delta: i32, order: i32): i32 {
220
288
  return nishshm_add_i32(this.handle, at, delta, order)
221
289
  }
222
290
 
223
- /** Sets the 32-bit slot at `at` to `value` and answers the value before. */
291
+ /**
292
+ * Sets the 32-bit slot at `at` to `value` and answers the value before, as
293
+ * one atomic read-modify-write.
294
+ * @param at the slot's byte offset from the region's start, a multiple of
295
+ * 4 with the whole slot inside the region; anything else panics
296
+ * @param value what the slot holds after
297
+ * @param order any of the five orderings; another value panics
298
+ * @returns the value the slot held just before
299
+ */
224
300
  exchangeI32(at: i32, value: i32, order: i32): i32 {
225
301
  return nishshm_exchange_i32(this.handle, at, value, order)
226
302
  }
@@ -228,27 +304,65 @@ export class SharedRegion {
228
304
  /**
229
305
  * Sets the 32-bit slot at `at` to `desired` if it holds `expected`, and
230
306
  * answers what it held: the exchange happened when that is `expected`.
307
+ * It never fails spuriously (a strong compare-exchange).
308
+ * @param at the slot's byte offset from the region's start, a multiple of
309
+ * 4 with the whole slot inside the region; anything else panics
310
+ * @param expected the value the slot must hold for the store to happen
311
+ * @param desired what the slot holds after, when it held `expected`
312
+ * @param order the ordering of a successful exchange, any of the five
313
+ * (another value panics); a failed one is a load ordered as C++ derives
314
+ * it (`ACQ_REL` fails `ACQUIRE`, `RELEASE` fails `RELAXED`, the others
315
+ * fail as themselves)
316
+ * @returns what the slot held: `expected` when the exchange happened
231
317
  */
232
318
  compareExchangeI32(at: i32, expected: i32, desired: i32, order: i32): i32 {
233
319
  return nishshm_cas_i32(this.handle, at, expected, desired, order)
234
320
  }
235
321
 
236
- /** The 64-bit slot at `at`. */
322
+ /**
323
+ * Loads the 64-bit slot at `at`, one atomic load.
324
+ * @param at the slot's byte offset from the region's start, a multiple of
325
+ * 8 with the whole slot inside the region; anything else panics
326
+ * @param order `RELAXED`, `ACQUIRE` or `SEQ_CST`; another panics
327
+ * @returns the value the slot held
328
+ */
237
329
  loadI64(at: i32, order: i32): i64 {
238
330
  return nishshm_load_i64(this.handle, at, order)
239
331
  }
240
332
 
241
- /** Sets the 64-bit slot at `at` to `value`. */
333
+ /**
334
+ * Sets the 64-bit slot at `at` to `value`, one atomic store.
335
+ * @param at the slot's byte offset from the region's start, a multiple of
336
+ * 8 with the whole slot inside the region; anything else panics
337
+ * @param value what the slot holds after
338
+ * @param order `RELAXED`, `RELEASE` or `SEQ_CST`; another panics
339
+ */
242
340
  storeI64(at: i32, value: i64, order: i32): void {
243
341
  nishshm_store_i64(this.handle, at, value, order)
244
342
  }
245
343
 
246
- /** Adds `delta` to the 64-bit slot at `at`, wrapping, and answers the value before. */
344
+ /**
345
+ * Adds `delta` to the 64-bit slot at `at`, wrapping, and answers the value
346
+ * before, as one atomic read-modify-write.
347
+ * @param at the slot's byte offset from the region's start, a multiple of
348
+ * 8 with the whole slot inside the region; anything else panics
349
+ * @param delta what is added; negative subtracts
350
+ * @param order any of the five orderings; another value panics
351
+ * @returns the value the slot held just before the add
352
+ */
247
353
  addI64(at: i32, delta: i64, order: i32): i64 {
248
354
  return nishshm_add_i64(this.handle, at, delta, order)
249
355
  }
250
356
 
251
- /** Sets the 64-bit slot at `at` to `value` and answers the value before. */
357
+ /**
358
+ * Sets the 64-bit slot at `at` to `value` and answers the value before, as
359
+ * one atomic read-modify-write.
360
+ * @param at the slot's byte offset from the region's start, a multiple of
361
+ * 8 with the whole slot inside the region; anything else panics
362
+ * @param value what the slot holds after
363
+ * @param order any of the five orderings; another value panics
364
+ * @returns the value the slot held just before
365
+ */
252
366
  exchangeI64(at: i32, value: i64, order: i32): i64 {
253
367
  return nishshm_exchange_i64(this.handle, at, value, order)
254
368
  }
@@ -256,17 +370,45 @@ export class SharedRegion {
256
370
  /**
257
371
  * Sets the 64-bit slot at `at` to `desired` if it holds `expected`, and
258
372
  * answers what it held: the exchange happened when that is `expected`.
373
+ * It never fails spuriously (a strong compare-exchange).
374
+ * @param at the slot's byte offset from the region's start, a multiple of
375
+ * 8 with the whole slot inside the region; anything else panics
376
+ * @param expected the value the slot must hold for the store to happen
377
+ * @param desired what the slot holds after, when it held `expected`
378
+ * @param order the ordering of a successful exchange, any of the five
379
+ * (another value panics); a failed one is a load ordered as C++ derives
380
+ * it (`ACQ_REL` fails `ACQUIRE`, `RELEASE` fails `RELAXED`, the others
381
+ * fail as themselves)
382
+ * @returns what the slot held: `expected` when the exchange happened
259
383
  */
260
384
  compareExchangeI64(at: i32, expected: i64, desired: i64, order: i32): i64 {
261
385
  return nishshm_cas_i64(this.handle, at, expected, desired, order)
262
386
  }
263
387
 
264
- /** Copies `len` bytes of the region at `at` into `dst[off, off + len)`. */
388
+ /**
389
+ * Copies `len` bytes of the region at `at` into `dst[off, off + len)`. A
390
+ * plain copy, not atomic: a writer in another process racing it can tear
391
+ * what it reads, and only the atomics around it order it.
392
+ * @param at where in the region the copy starts, in bytes
393
+ * @param dst the buffer the bytes land in
394
+ * @param off where in `dst` the first byte goes
395
+ * @param len how many bytes to copy; the range must fit both the region from
396
+ * `at` and `dst` from `off`, or it panics
397
+ */
265
398
  read(at: i32, dst: u8[], off: i32, len: i32): void {
266
399
  nishshm_read(this.handle, at, dst, toU64(dst.length), toU64(off), toU64(len))
267
400
  }
268
401
 
269
- /** Copies `src[off, off + len)` into the region at `at`. */
402
+ /**
403
+ * Copies `src[off, off + len)` into the region at `at`. A plain copy, not
404
+ * atomic: publish it to another process with a `RELEASE` (or `SEQ_CST`)
405
+ * store after it.
406
+ * @param at where in the region the first byte goes
407
+ * @param src the bytes to copy
408
+ * @param off where in `src` the copy starts
409
+ * @param len how many bytes to copy; the range must fit both `src` from `off`
410
+ * and the region from `at`, or it panics
411
+ */
270
412
  write(at: i32, src: readonly u8[], off: i32, len: i32): void {
271
413
  nishshm_write(this.handle, at, src, toU64(src.length), toU64(off), toU64(len))
272
414
  }
@@ -274,7 +416,17 @@ export class SharedRegion {
274
416
  /**
275
417
  * Sleeps while the 32-bit slot at `at` holds `expected`, at most
276
418
  * `timeoutMs` (negative: no limit): `SHM_WOKEN`, `SHM_NOT_EQUAL`,
277
- * `SHM_TIMED_OUT`, or `SHM_UNSUPPORTED` off Linux.
419
+ * `SHM_TIMED_OUT`, or `SHM_UNSUPPORTED` off Linux. It promises no
420
+ * ordering: load the slot again, with the ordering the caller needs, after
421
+ * it returns.
422
+ * @param at the 32-bit slot's byte offset, a multiple of 4 inside the
423
+ * region; anything else panics, off Linux too
424
+ * @param expected the value the slot must still hold for the call to sleep
425
+ * @param timeoutMs the longest sleep, in milliseconds; negative for no limit
426
+ * @returns `SHM_WOKEN` when woken, interrupted by a signal or for no reason
427
+ * the caller can see; `SHM_NOT_EQUAL` when the slot did not hold
428
+ * `expected`; `SHM_TIMED_OUT`; `SHM_UNSUPPORTED` off Linux; or another
429
+ * negated errno the futex gave
278
430
  */
279
431
  waitI32(at: i32, expected: i32, timeoutMs: i32): i32 {
280
432
  return nishshm_wait_i32(this.handle, at, expected, timeoutMs)
@@ -283,6 +435,11 @@ export class SharedRegion {
283
435
  /**
284
436
  * Wakes at most `count` of the processes sleeping on the 32-bit slot at
285
437
  * `at`: how many it woke, or `SHM_UNSUPPORTED` off Linux.
438
+ * @param at the 32-bit slot's byte offset, a multiple of 4 inside the
439
+ * region; anything else panics, off Linux too
440
+ * @param count the most sleepers to wake; negative wakes none
441
+ * @returns how many it woke, in any process; `SHM_UNSUPPORTED` off Linux, or
442
+ * another negated errno the futex gave
286
443
  */
287
444
  wake(at: i32, count: i32): i32 {
288
445
  return nishshm_wake(this.handle, at, count)
@@ -296,17 +453,40 @@ export class SharedRegion {
296
453
  * memory, after which it is no window and `giveBack` panics. Pass a window
297
454
  * already given back as `reuse` to lend it again without a new header: each
298
455
  * lend without one keeps a few bytes for the life of the process.
456
+ * @param at where in the region the window starts, in bytes
457
+ * @param len the window's length in bytes; `[at, at + len)` must lie inside
458
+ * the region, or it panics
459
+ * @param reuse null for a new window, or a window this region lent and that
460
+ * was given back, to re-point; any other array panics
461
+ * @returns the window: `reuse` itself when one was passed, otherwise a new
462
+ * array. Its bytes are the region's, shared with every process that maps
463
+ * it, until `giveBack` or `close`
299
464
  */
300
465
  lend(at: i32, len: i32, reuse: u8[] | null = null): u8[] {
301
466
  return shmLend(this.handle, at, len, reuse)
302
467
  }
303
468
 
304
- /** Empties `window`, which this region lent, and answers the length it had. */
469
+ /**
470
+ * Empties `window`, which this region lent, and answers the length it had.
471
+ * After it the array has length 0 and may be passed to `lend` as `reuse`.
472
+ * @param window a window this region lent and that is still lent; one given
473
+ * back already, lent by another region, or moved off the region by a
474
+ * `push` panics
475
+ * @returns the window's length just before (a `pop` may have shortened it)
476
+ */
305
477
  giveBack(window: u8[]): i32 {
306
478
  return shmGiveBack(this.handle, window)
307
479
  }
308
480
 
309
- /** Unmaps the region; the handle names nothing after. The name stays until `unlinkRegion`. */
481
+ /**
482
+ * Unmaps the region; the handle names nothing after. The name stays until
483
+ * `unlinkRegion`. Every window still lent from it is emptied first, so an
484
+ * index into one after this panics rather than reading unmapped memory (a
485
+ * window a `push` moved off the region is the program's own array, and is
486
+ * left alone); any other access through this object panics too.
487
+ * @returns `Ok()` once it is unmapped, or a `ShmError` of code 9 when it was
488
+ * closed already (or on wasi, where no region opens)
489
+ */
310
490
  close(): Result<void, ShmError> {
311
491
  return shmDone(nishshm_close(this.handle))
312
492
  }