@amritk/nish-x86_64-linux 0.29.0 → 0.31.0

package/INSTALL.md

@@ -256,7 +256,7 @@ routes are
     runtime/runtime-cross.c runtime/runtime-host.c runtime/runtime-net.c \
     runtime/runtime-simd.c runtime/runtime-aes.c runtime/runtime-sha256.c runtime/runtime-term.c \
     runtime/runtime-bytes.c runtime/runtime-checksum.c runtime/runtime-sandbox.c \
-    runtime/runtime-shm.c -lm -o app
+    runtime/runtime-shm.c runtime/runtime-region.c -lm -o app
   ```
 
   `--link`ing inside the container is the mistake to avoid: it shells out to the
@@ -392,7 +392,7 @@ it into `build/seed/`; `NISH_BOOTSTRAP=<path>` names one you already have and
 skips the download. §2a has what the build does with it.
 
 The published package ships `bin/` (the `nish` command, which is a launcher),
-`runtime/` (the C runtime — fourteen translation units, the wasm subset and their
+`runtime/` (the C runtime — fifteen translation units, the wasm subset and their
 header — and `runtime/sqlite/`, SQLite's vendored source),
 `scripts/build.sh` (the link pipeline), `std/` (the standard library) and
 `docs/AI.md` (the rules card). The
@@ -405,7 +405,7 @@ working directory — and the binary runs from inside its own platform package
 for exactly that reason.
 
 Building the IR yourself rather than through `--link` means naming the runtime
-on the `clang` line, and it is fourteen files:
+on the `clang` line, and it is fifteen files:
 
 ```bash
 clang app.ll runtime/runtime.c runtime/runtime-os.c runtime/runtime-parallel.c \

package/docs/AI.md

@@ -2222,6 +2222,13 @@ system call either way. `setIdlePriority()` moves the program to Linux's `SCHED_
 `main`, never in a task. An unprivileged process can never leave `SCHED_IDLE`
 and an idle one can starve on a saturated machine, so keep a normal-priority
 fallback. Neither exists on wasm; both throw under Node.
+`setCpuAffinity(cpu)` pins the process to one CPU, narrow-only: a CPU outside
+the mask it already has is `-22`; `-95` on Darwin and under Node, refused on
+wasm. `nish/net/prefork`'s `PreforkConfig` takes `pin = true` to pin worker
+`k` to CPU `k` (more workers than CPUs panics), and `listenPort` (with
+`listenHost`, `listenBacklog`, `listenFlags` 0 or 2) to have the supervisor
+bind one `SO_REUSEPORT` listener per worker, steered on Linux by the receiving
+CPU when pinned; a worker takes its own with `preforkListener(process.argv)`.
 
 **Sockets** (`nish:net`, or the same names as globals). `tcpListen(host, port,
 backlog)`, `tcpAccept(fd, peer)`, `netRead(fd, buf, off, len)`,
@@ -2236,10 +2243,10 @@ wait for it to be writable, then `connectResult(fd)` is 0 or the failure. Buffer
 are `u8[]` only; an address is 18 bytes of one (IPv4 as `::ffff:a.b.c.d`, then
 the port big-endian); hosts are numeric literals; to reach a name, resolve it first with
 `nish/net/dns` (`DnsClient` on your loop, or the blocking `resolveHost`).
-To fetch a URL from a CLI, skip all of this: `nish/net/http-client`'s
-`httpFetch(new HttpRequest("GET", url), new HttpOptions())` blocks until the
+To fetch a URL from a CLI, skip all of this: `nish/net/fetch`'s
+`fetchSync(new HttpRequest("GET", url), new HttpOptions())` blocks until the
 response's head is in and answers it with `body.readAll(limit)`, or null on a
-failure (an `HttpClient` keeps the connection and says why in `error`).
+failure (a `FetchSyncClient` keeps the connection and says why in `error`).
 `netRead` / `netWrite` panic on a range outside the buffer.
 `tcpListenFlags(host, port, backlog, flags)` is `tcpListen` with flag 1
 `SO_REUSEPORT`, so several listeners, in one process or many, share a port (Linux
@@ -2596,6 +2603,46 @@ returns. To give memory back sooner, scope it with `using a = arena()`;
 `Arena.release` and `Arena.reset` are gone, and a call to either is an unknown
 builtin (NL2244).
 
+### Regions: `nish:region`
+
+**For memory a long-running program frees itself — per connection, per cache
+entry — use a region.** `region(f)` / `regionWith(arg, f)` make one and run
+`f` in it, and what `f` answers is the root; `enter(r, f)` /
+`enterWith(r, arg, f)` run `f(root)` / `f(root, arg)` in it again; `free(r)`
+gives all of it back. `f` is a named function or an arrow that captures
+nothing. `Region<T>` is a number, not a pointer.
+
+```ts nish:ok
+import { Region, enter, free, region } from "nish:region";
+
+class Session {
+  hits: i32 = 0;
+}
+
+const open = (): Session => new Session();
+const touch = (s: Session): i32 => {
+  s.hits = s.hits + 1;
+  return s.hits;
+};
+
+export const main = (): i32 => {
+  const r: Region<Session> = region(open);
+  console.log(enter(r, touch));
+  free(r);
+  return 0;
+};
+```
+
+The checker refuses every way region memory could outlive `free`, and every way
+outer memory could be pointed at from inside: only numbers, booleans, enums and
+`Region` handles cross. `enter` answers a scalar or a handle (NL2611), `f` may
+not store region memory into `arg` or other outer memory (NL2609) nor outer
+memory into the region (NL2610), nor `push`/`set`/`add` to an outer collection
+(NL2615). A handle stays on its thread (NL2612, NL2613, NL2351), is never a
+`using` (NL2387) and is never `new Region` (NL2618). A bad handle, a double
+`free` or a nested `enter` of one region stops the program. `--emit-ts` refuses
+the module (NL4015).
+
 ## Recipes for what is missing
 
 **Iterate and transform** — there is no `map`, and no function to pass it:
@@ -2705,7 +2752,12 @@ parameter. `paramIntArray(values, start, count)` binds an `i64[]` window;
 element, then `arrayEnd()`, builds a `text[]` straight into the Bind from
 windows of a buffer. An element refused for room answers `false` and leaves
 the array open: end it and send the rest in the next statement. Every other
-`param...` call and `bindEnd()` panic until `arrayEnd()`. (No block, as for
+`param...` call and `bindEnd()` panic until `arrayEnd()`. For a long
+`int4[]` or `int8[]`, `paramInt4Array` / `paramInt8Array` (same window) or
+`binaryArrayStart(23 or 20)`, `binaryArrayInt` / `binaryArrayNull`,
+`arrayEnd()` send it in binary, at a tenth of the client CPU; the element type
+must be the statement's (`int4[]` to an `int8[]` parameter is SQLSTATE
+`42804`), and an `int4` element out of range panics. (No block, as for
 `nish/text`; `tests/postgres/live` runs it against a server, and the user
 guide's [PostgreSQL page](guide/using-nish/postgres.md#array-parameters) its
 walk-through.)
@@ -2743,6 +2795,21 @@ request. It reads no clock: when to take is the loop's choice, or a `PgBatchCloc
 guide's [PostgreSQL page](guide/using-nish/postgres.md#batching-keyed-reads)
 its walk-through.)
 
+**Call another service from a route handler** — there is no `await fetch()`
+in a handler and no event-loop callback: `nish/net/upstream`'s `Upstream(h,
+origin, limits)` is a pool of keep-alive connections to one `http:` origin on
+the `HttpHandler`'s own loop. `users.get(req, path)` returns at once — test it
+for `UPSTREAM_E_FULL`, which holds nothing — and keeps `req` held; after each
+`h.wait(ms)`, `while (users.ready())` `take()`s every finished call, answers
+`r.req` (`r.ok`, `r.status` and `r.body[0 .. r.length)`, or `r.error`: the
+codec's `HTTP1_E_` refusal or an `UPSTREAM_E_` code such as `TIMEOUT`) and
+`release`s it once. The origin is looked up once at start-up; set
+`UpstreamLimits.outbound` when it comes from input. Each connection takes a
+handler watch id from `firstId` (8) up, so keep your own `h.watch` ids below
+it. (No block, as for `nish/text`; `tests/link/net_upstream` is its program,
+and the user guide's [calling-services page](guide/using-nish/calling-services.md)
+its walk-through.)
+
 **Draw to the whole terminal** (a game, a dashboard) — there is no curses and
 no `process.stdout.on("resize")`: `runTerminal(options, state, update, render)`
 from `nish/term-io` opens the terminal, probes what it can draw, steps

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/nish-x86_64-linux",
-  "version": "0.29.0",
+  "version": "0.31.0",
   "description": "The nish native compiler for Linux on x86_64",
   "license": "MIT",
   "os": [

package/runtime/core/host.d.ts

@@ -82,6 +82,8 @@ export declare function readSignal(fd: i32): i32;
 /** These two have no reading under Node: each throws, naming itself. */
 export declare function setNice(n: i32): i32;
 export declare function setIdlePriority(): i32;
+/** -95: there is no affinity call under Node. */
+export declare function setCpuAffinity(cpu: i32): i32;
 /** What each `nish:net` function is under the core: a throw naming `name`. */
 export declare function noNetReading(name: string): never;
 /** What `readStdin`, `waitStdin`, `setRawMode` and `setTerminalRestore` are under the core: a throw naming `name`. */

package/runtime/core/host.mjs

@@ -335,6 +335,15 @@ export function setIdlePriority() {
   return noSchedulingReading("setIdlePriority");
 }
 
+/**
+ * `setCpuAffinity(cpu)` answers -95, the native build's answer on a host with
+ * no affinity call: unlike the two above it has a defined "not supported"
+ * value, so a program that pins where it can runs unpinned here.
+ */
+export function setCpuAffinity() {
+  return -95;
+}
+
 /**
  * `signalFd()` and `readSignal(fd)` have no faithful reading under Node, and
  * these say so rather than answer something else. Node delivers a signal to

package/runtime/nish.d.ts

@@ -378,6 +378,14 @@ declare function setNice(n: i32): i32;
  * normal-priority fallback for work that must finish. Throws under Node.
  */
 declare function setIdlePriority(): i32;
+/**
+ * Pin this process to CPU `cpu` alone (`sched_setaffinity`): 0, or a negative
+ * errno. Narrow-only: a CPU outside the mask the process already has (an
+ * operator's `taskset` or cpuset), a negative one, or one past the kernel's
+ * set size is -22 with no system call. -95 where the host has no affinity
+ * call (Darwin, and under Node).
+ */
+declare function setCpuAffinity(cpu: i32): i32;
 /** One environment variable, or `null` when it is unset (an empty value is a set variable). */
 declare function getenv(name: string): string | null;
 /**
@@ -422,7 +430,13 @@ declare function netAddress(out: u8[], host: string, port: i32): i32;
 declare function netLocalPort(fd: i32): i32;
 /** A listening TCP socket with `SO_REUSEADDR`; `"::"` hears IPv4 and IPv6. */
 declare function tcpListen(host: string, port: i32, backlog: i32): i32;
-/** `tcpListen`'s socket, with `SO_REUSEPORT` for flag 1 and `TCP_NODELAY` on each accepted socket for flag 2; any other bit is -22. */
+/**
+ * `tcpListen`'s socket, with `SO_REUSEPORT` for flag 1 and `TCP_NODELAY` on
+ * each accepted socket for flag 2. Flag 4, with flag 1, steers by CPU: a new
+ * connection goes to the group's listener whose bind order is the index of the
+ * CPU that received it (Linux; -95 elsewhere). Any other bit, or 4 without 1,
+ * is -22.
+ */
 declare function tcpListenFlags(host: string, port: i32, backlog: i32, flags: i32): i32;
 /** The next connection's descriptor, its address in `peer`; -11 when none waits. */
 declare function tcpAccept(fd: i32, peer: u8[]): i32;
@@ -667,6 +681,8 @@ declare module "nish:process" {
    * on a saturated machine, so a caller keeps a normal-priority fallback.
    */
   export function setIdlePriority(): i32;
+  /** Pin this process to CPU `cpu` alone: 0, -22 for a CPU outside the current mask (narrow-only), or -95 off Linux. */
+  export function setCpuAffinity(cpu: i32): i32;
   /**
    * A monotonic clock in nanoseconds. The origin is arbitrary, so only the
    * difference between two reads is meaningful.
@@ -693,7 +709,13 @@ declare module "nish:net" {
   export function netLocalPort(fd: i32): i32;
   /** A listening TCP socket with `SO_REUSEADDR`; `"::"` hears IPv4 and IPv6. */
   export function tcpListen(host: string, port: i32, backlog: i32): i32;
-  /** `tcpListen`'s socket, with `SO_REUSEPORT` for flag 1 and `TCP_NODELAY` on each accepted socket for flag 2; any other bit is -22. */
+  /**
+   * `tcpListen`'s socket, with `SO_REUSEPORT` for flag 1 and `TCP_NODELAY` on
+   * each accepted socket for flag 2. Flag 4, with flag 1, steers by CPU: a new
+   * connection goes to the group's listener whose bind order is the index of the
+   * CPU that received it (Linux; -95 elsewhere). Any other bit, or 4 without 1,
+   * is -22.
+   */
   export function tcpListenFlags(host: string, port: i32, backlog: i32, flags: i32): i32;
   /** The next connection's descriptor, its address in `peer`; -11 when none waits. */
   export function tcpAccept(fd: i32, peer: u8[]): i32;
@@ -936,6 +958,30 @@ declare module "nish:secret" {
   export function wipe(target: object): void;
 }
 
+// `nish:region` has source behind it, `std/region.ts`, but a program imports it
+// by this name. The class has a private constructor, so `tsc` refuses
+// `new Region()` as `nish` does (NL2618). What `nish` refuses about the
+// functions a region runs — keeping its memory outside it, growing outer
+// storage, reaching threads — is flow, which `tsc` cannot see
+// (docs/LANGUAGE.md -> Regions).
+declare module "nish:region" {
+  /** A handle to a region whose root is a `T`: 64 bits, not a pointer. */
+  export class Region<T> {
+    private constructor();
+    private readonly root: T;
+  }
+  /** A new region whose root is what `f` answers; everything `f` allocates is in it. */
+  export function region<T>(f: () => T): Region<T>;
+  /** `region` with one outside argument for `f`, which `f` may read but not keep. */
+  export function regionWith<A, T>(arg: A, f: (arg: A) => T): Region<T>;
+  /** `f(root)`, allocating in the region. What `f` answers is a scalar or a handle. */
+  export function enter<T, R>(r: Region<T>, f: (root: T) => R): R;
+  /** `f(root, arg)`, under `enter`'s rules; `f` may not keep or grow `arg`. */
+  export function enterWith<T, A, R>(r: Region<T>, arg: A, f: (root: T, arg: A) => R): R;
+  /** Give the region's memory back. A freed handle used again stops the program. */
+  export function free<T>(r: Region<T>): void;
+}
+
 // ---- Arena (docs/LANGUAGE.md -> Arena) ---------------------------------------
 
 declare const Arena: {

package/runtime/nish.h

@@ -104,8 +104,9 @@ extern NISH_TLS struct nish_arena nish_arena;
 
 /* Bump allocation: 8-byte rounded and aligned, uninitialised. */
 void *nish_alloc_struct(uint64_t size);
-/* Slow path: push a new chunk (at least 64 KB) and bump from it. Called by
- * the inlined fast path when the current chunk is full; rarely by hosts. */
+/* Slow path: push a new chunk (at least 64 KB, or a region's next size) and
+ * bump from it. Called by the inlined fast path when the current chunk is
+ * full; rarely by hosts. */
 void *nish_arena_grow(uint64_t size);
 /* Recycle everything in O(1): keeps the newest chunk, frees the rest. Every
  * arena string and object becomes invalid. Call it between batches. */
@@ -132,6 +133,25 @@ void *nish_arena_keep(uint64_t mark, void *p);
 /* Bytes bumped in the current chunk (`Arena.used()`); a steady-state loop keeps it flat. */
 uint64_t nish_arena_used(void);
 
+/* ---- Regions (runtime-region.c) -----------------------------------------
+ * Arenas made, entered, left and freed one at a time
+ * (docs/wp46-long-running-memory.md). A handle is a nonzero `uint64_t`: a
+ * 24-bit slot and its 40-bit generation. Every call below panics on a zero
+ * handle, a freed (stale) one and one made on another thread.
+ * `nish_region_new` makes an empty region, owned by the calling thread.
+ * `nish_region_enter` makes the region the thread's arena until the matching
+ * `nish_region_leave`, so every allocation in between lands in it, and
+ * answers the root `leave` last recorded (null at first); entering a region
+ * already entered panics. `nish_region_leave` must name the region entered
+ * last on this thread, puts back the arena its enter displaced and records
+ * `root`. `nish_region_free` frees every chunk of a region that is not
+ * entered and makes its handle stale. The wasm profile has none of these
+ * (scripts/build.sh refuses IR that names them); wasi has. */
+uint64_t nish_region_new(void);
+void *nish_region_enter(uint64_t r);
+void nish_region_leave(uint64_t r, void *root);
+void nish_region_free(uint64_t r);
+
 /* ---- String operations ------------------------------------------------- */
 /* Copy `len` bytes into a new arena string (`bytes` need not be terminated). */
 nish_str *nish_str_new(const char *bytes, uint64_t len);
@@ -557,6 +577,11 @@ int32_t nish_set_nice(int32_t n);
  * negative errno; -95 (Linux's EOPNOTSUPP) elsewhere, -ENOSYS under WASI. An
  * unprivileged process cannot leave the policy again. */
 int32_t nish_set_idle_priority(void);
+/* `setCpuAffinity(cpu)`: this process pinned to CPU `cpu` alone
+ * (`sched_setaffinity`, Linux), 0 or a negative errno. Narrow-only: a CPU not
+ * in the current mask, negative, or past `CPU_SETSIZE` is -22 (-EINVAL) with
+ * no system call. -95 (Linux's EOPNOTSUPP) elsewhere, -ENOSYS under WASI. */
+int32_t nish_set_cpu_affinity(int32_t cpu);
 
 /* ---- The environment (WP19 R1) ------------------------------------------
  * `getenv(name)`: the value of environment variable `name`, copied into the
@@ -659,7 +684,10 @@ bool nish_is_executable(const nish_str *path);
  * `nish_tcp_listen(host, port, backlog)`: `SO_REUSEADDR`, and `::` hears
  * both families, or IPv4 alone on a kernel without IPv6.
  * `nish_tcp_listen_flags(host, port, backlog, flags)`: the same listener,
- * with `SO_REUSEPORT` for flag 1 (any other bit is -22).
+ * with `SO_REUSEPORT` for flag 1, `TCP_NODELAY` on each accepted socket for
+ * flag 2, and, for flag 4 with flag 1, a reuseport program steering each new
+ * connection to the listener bound at the index of the CPU that received it
+ * (Linux; -95 elsewhere). Any other bit, or 4 without 1, is -22.
  * `nish_tcp_accept(fd, peer)`: a new descriptor and the peer's address.
  * `nish_net_read` / `nish_net_write(fd, buf, off, len)`: bytes `[off, off +
  * len)` of `buf`, which the compiled call has range-checked; a write to a

package/runtime/nish.mjs

@@ -121,6 +121,9 @@ for (const name of ["setNice", "setIdlePriority"]) {
     throw new Error(`\`${name}\` has no reading under Node: it changes how the kernel schedules the native program`);
   });
 }
+// `setCpuAffinity` answers -95, as on Darwin: Node has no affinity call, and
+// "not supported" is a value a caller already branches on.
+provide("setCpuAffinity", shim.setCpuAffinity);
 provide("getenv", shim.getenv);
 provide("statMtimeSync", shim.statMtimeSync);
 provide("signalFd", shim.signalFd);
@@ -328,11 +331,41 @@ provide("arena", shim.arena);
 // zero-fills it. `nish:unsafe` and `nish:term` are each answered by a module
 // that hands back the globals installed above: its functions are globals of this module either
 // way, and the import is what the compiler requires a program to write.
+// `nish:region` is answered by a module of its own, below.
 // `nish:simd` is `runtime/core.mjs`, whose vectors are typed arrays made once
 // and never written after, so `--emit-ts` output and a program run as it was
 // written share one implementation.
 const UNSAFE_EXPORTS = ["uncheckedGet", "uncheckedSet", "wrappingAdd", "wrappingSub", "wrappingMul"];
 const unsafeSource = UNSAFE_EXPORTS.map((name) => `export const ${name} = globalThis.${name};`).join("\n");
+// `nish:region` has no allocator to swap under Node: a region is an entry in a
+// table, keyed by its handle (a BigInt, as every `i64` is here), `enter` runs
+// its function on the root, and `free` drops the entry. The handle checks the
+// native runtime makes are made here too, so a freed handle or a second
+// `enter` throws where the native program stops.
+const regionSource = `
+const roots = new Map();
+const entered = new Set();
+let next = 0n;
+const rootOf = (r) => {
+  if (!roots.has(r)) throw new Error("nish:region: the region is freed or was never made");
+  if (entered.has(r)) throw new Error("nish:region: the region is entered already");
+  return roots.get(r);
+};
+const run = (r, f, arg, withArg) => {
+  const root = rootOf(r);
+  entered.add(r);
+  try { return withArg ? f(root, arg) : f(root); } finally { entered.delete(r); }
+};
+export class Region {}
+export const region = (f) => { next += 1n; roots.set(next, f()); return next; };
+export const regionWith = (arg, f) => { next += 1n; roots.set(next, f(arg)); return next; };
+export const enter = (r, f) => run(r, f, undefined, false);
+export const enterWith = (r, arg, f) => run(r, f, arg, true);
+export const free = (r) => {
+  if (entered.has(r)) throw new Error("nish:region: the region is freed while it is entered");
+  if (!roots.delete(r)) throw new Error("nish:region: the region is freed or was never made");
+};
+`;
 const TERM_EXPORTS = ["readStdin", "waitStdin", "isTerminal", "terminalSize", "setRawMode", "setTerminalRestore"];
 const termSource = TERM_EXPORTS.map((name) => `export const ${name} = globalThis.${name};`).join("\n");
 registerHooks({
@@ -346,6 +379,9 @@ registerHooks({
     if (specifier === "nish:simd") {
       return next(new URL("./core.mjs", import.meta.url).href, context);
     }
+    if (specifier === "nish:region") {
+      return { url: `data:text/javascript,${encodeURIComponent(regionSource)}`, shortCircuit: true };
+    }
     if (specifier === "nish:term") {
       return { url: `data:text/javascript,${encodeURIComponent(termSource)}`, shortCircuit: true };
     }

package/runtime/runtime-net.c

@@ -73,6 +73,7 @@ typedef int nish_net_unused;
 #include <sys/un.h>
 #include <unistd.h>
 #if defined(__linux__)
+#include <linux/filter.h>
 #include <netinet/udp.h>
 #include <sys/epoll.h>
 /* glibc before 2.29 names neither; the numbers are the kernel's ABI. */
@@ -82,6 +83,10 @@ typedef int nish_net_unused;
 #ifndef UDP_GRO
 #define UDP_GRO 104
 #endif
+/* Linux 4.5's; a header older than the kernel may not name it. */
+#ifndef SO_ATTACH_REUSEPORT_CBPF
+#define SO_ATTACH_REUSEPORT_CBPF 51
+#endif
 #else
 #include <sys/event.h>
 #include <sys/time.h>
@@ -243,7 +248,23 @@ static int32_t nish_net_bound(const nish_str *host, int32_t port, int type, int3
   }
   nish_sockaddr s;
   socklen_t n = nish_net_sockaddr(&s, a, port, v4);
-  if (bad != 0 || bind(fd, &s.sa, n) != 0 || (type == SOCK_STREAM && listen(fd, arg) != 0)) {
+#if defined(__linux__)
+  /* `tcpListenFlags` flag 4's program, two instructions, the kernel
+     selftest's: load the receiving CPU, return it. It is the reuseport
+     group's, so attaching it from every listener installs the same program
+     each time, and it goes on after `listen`, once the socket is in its
+     group. Only a stream listener's `opts` can hold 4. */
+  static struct sock_filter cpu[] = {
+      {BPF_LD | BPF_W | BPF_ABS, 0, 0, (uint32_t)(SKF_AD_OFF + SKF_AD_CPU)},
+      {BPF_RET | BPF_A, 0, 0, 0},
+  };
+  static const struct sock_fprog steer = {2, cpu};
+#endif
+  if (bad != 0 || bind(fd, &s.sa, n) != 0 || (type == SOCK_STREAM && listen(fd, arg) != 0)
+#if defined(__linux__)
+      || ((opts & 4) && setsockopt(fd, SOL_SOCKET, SO_ATTACH_REUSEPORT_CBPF, &steer, sizeof steer) != 0)
+#endif
+  ) {
     int e = errno;
     close(fd);
     return nish_net_err(e);
@@ -262,9 +283,17 @@ int32_t nish_tcp_listen(const nish_str *host, int32_t port, int32_t backlog) {
    `SO_REUSEPORT` for flag 1, so several listeners of one uid share the port
    (Linux spreads new connections across them; Darwin hands them all to one),
    and `TCP_NODELAY` for flag 2, which the listener carries so that
-   `tcpAccept` sets it on each connection it takes. Any other bit is -22. */
+   `tcpAccept` sets it on each connection it takes. Flag 4, which needs flag
+   1, steers by CPU: a reuseport program (`SO_ATTACH_REUSEPORT_CBPF`) hands a
+   new connection to the group's listener whose index is the CPU that received
+   it, the index being the order the group's sockets were bound in, and the
+   kernel falls back to its hash when there is no such listener. Linux alone
+   has it; elsewhere flag 4 is -95. Any other bit, or 4 without 1, is -22. */
 int32_t nish_tcp_listen_flags(const nish_str *host, int32_t port, int32_t backlog, int32_t flags) {
-  if ((uint32_t)flags > 3) return -22;
+  if ((uint32_t)flags > 7 || (flags & 5) == 4) return -22;
+#if !defined(__linux__)
+  if (flags & 4) return -95;
+#endif
   return nish_net_bound(host, port, SOCK_STREAM, backlog, flags);
 }
 

package/runtime/runtime-os.c

@@ -26,7 +26,8 @@
  * from drifting from the contract it is published under.
  */
 #if defined(__linux__) && !defined(_GNU_SOURCE)
-#define _GNU_SOURCE /* `sched_getaffinity` and `CPU_COUNT`, for `nish_cpu_online` */
+#define _GNU_SOURCE /* `sched_getaffinity`, `sched_setaffinity` and `CPU_COUNT`, for
+                       `nish_cpu_online` and `nish_set_cpu_affinity` */
 #endif
 #define _POSIX_C_SOURCE 200809L
 /* `realpath` is XSI rather than POSIX base, so _POSIX_C_SOURCE alone does not
@@ -860,6 +861,37 @@ int32_t nish_set_idle_priority(void) {
 #endif
 }
 
+/* `setCpuAffinity(cpu)`: this process pinned to CPU `cpu` alone, 0 or a
+   negative errno. Narrow-only: `cpu` must be in the mask the process already
+   has (`sched_getaffinity`), so a pin never escapes an operator's `taskset` or
+   cpuset; a CPU outside it, a negative one, or one past `CPU_SETSIZE` is
+   -EINVAL with no `sched_setaffinity` call. Linux alone has the call; Darwin
+   answers -95 as `setIdlePriority` does, WASI -ENOSYS. Like the nice value,
+   the mask is the calling thread's and every thread started after it. */
+int32_t nish_set_cpu_affinity(int32_t cpu) {
+#if defined(__linux__)
+  /* The mask as words: the set to pin is the word holding `cpu` with only its
+     bit, the words below it zero, and the kernel zero-fills a shorter mask.
+     `sched_getaffinity` fails only on a bad pid or size, neither of which
+     this call can pass, so its failure shares the range check's answer. */
+  unsigned long m[CPU_SETSIZE / (8 * sizeof(unsigned long))];
+  uint32_t w = (uint32_t)cpu / (8 * sizeof m[0]);
+  unsigned long bit = 1UL << ((uint32_t)cpu % (8 * sizeof m[0]));
+  if ((uint32_t)cpu >= CPU_SETSIZE || sched_getaffinity(0, sizeof m, (cpu_set_t *)m) != 0 ||
+      !(m[w] & bit))
+    return -EINVAL;
+  for (uint32_t i = 0; i < w; i++) m[i] = 0;
+  m[w] = bit;
+  return sched_setaffinity(0, (w + 1) * sizeof m[0], (cpu_set_t *)m) == 0 ? 0 : -errno;
+#elif defined(__wasi__)
+  (void)cpu;
+  return -ENOSYS;
+#else
+  (void)cpu;
+  return -95;
+#endif
+}
+
 /* `readdirSync(path)`: the listing a driver needs to discover its own inputs.
 
    **Sorted by bytes**, which `readdir(3)` and Node are not, for two reasons