knitting 0.1.63 → 0.1.70

package/src/memory/knitting-buffer.d.ts

@@ -0,0 +1,250 @@
+/**
+ * `KnittingSharedBuffer` -- a thread-level pool of shared byte
+ * regions whose handle mimics `SharedArrayBuffer` rather than `Buffer`.
+ *
+ * Shape:
+ *
+ *   - Each thread owns one pool: its own arena SAB, its own lock sector, its
+ *     own identity space. Nothing is shared between pools except the SABs a
+ *     descriptor points at.
+ *   - `alloc(n)` takes a region from the lazy registry
+ *     (`lazy-region-registry.ts`). Identity exhaustion is not a failure: it
+ *     falls back to a standalone `SharedArrayBuffer`, so the pool never blocks
+ *     and never evicts a live borrow.
+ *   - The **region** owns the bytes. Views are minted from it (`u8()`,
+ *     `view(Ctor)`) and are plain, non-owning typed arrays. That is the same
+ *     split JS already has between a `SharedArrayBuffer` and its views, and it
+ *     is what keeps a `Float64Array` over the region from being silently
+ *     orphaned when some unrelated `Uint8Array` over it is dropped.
+ *   - The wire form is a descriptor, never bytes. A consumer thread attaches
+ *     to the producer's SABs once and materializes its own region handle.
+ *   - Release is one XOR into the owning lane's shared word, from whichever
+ *     thread holds the last handle.
+ *
+ * Why GC-driven release is safe here, given the lazy registry:
+ *
+ *   An identity is reusable only after the owner has *observed* its release
+ *   toggle (`reconcile` clears the used bit only when hostLast ^ workerBits
+ *   agree). So an identity cannot be handed out again while a release for it
+ *   is still outstanding, which means a late release can never apply to a
+ *   newer generation -- there is no ABA to protect against with a generation
+ *   counter. A forgotten handle costs one identity until the collector runs;
+ *   it cannot corrupt a live region. That degradation is capacity-only, and
+ *   the standalone-SAB fallback is what keeps it from turning into a stall.
+ *
+ *   That argument holds for exactly one releaser per identity, which is why
+ *   sending a region is `moveTo()` and not `describe()`. Two releasers
+ *   reintroduce the ABA the toggle cannot see: the first release lets
+ *   `reconcile` recycle the identity into a new region, and the second one
+ *   then frees a live stranger, whose bytes the next `alloc` hands out while
+ *   it is still being read. `describe()` is inspection only.
+ *
+ * What it still cannot do: revoke a view that was already minted. Minting is
+ * checked -- `u8()` after release throws instead of handing back a window onto
+ * somebody else's recycled bytes -- but a view handed out earlier and retained
+ * past release keeps aliasing the region. That is a JS limitation, not a
+ * design choice, and it is why `copy()` exists.
+ */
+import { type LazyRegionRegistryMode } from "./lazy-region-registry.js";
+import { type ReadBodyOrReferOptions } from "./knitting-buffer-http.js";
+import type { KnittingBody } from "./knitting-body.js";
+export declare const KNITTING_BUFFER_CODEC = "knitting.buffer";
+export type KnittingBufferDescriptor = {
+    codec: typeof KNITTING_BUFFER_CODEC;
+    kind: "region";
+    lane: number;
+    slot: number;
+    byteOffset: number;
+    byteLength: number;
+} | {
+    codec: typeof KNITTING_BUFFER_CODEC;
+    kind: "buffer";
+    lane: number;
+    byteLength: number;
+    buffer: SharedArrayBuffer;
+};
+type ViewConstructor<T extends ArrayBufferView> = new (buffer: ArrayBufferLike, byteOffset: number, length: number) => T;
+/**
+ * Module-internal ownership transfer. Reachable only through the allocator's
+ * `moveTo()`, which is the one place a region legitimately stops being ours.
+ */
+declare const DISOWN: unique symbol;
+/**
+ * An owned region of shared memory. Mints views; does not pretend to be one.
+ *
+ * Exported for `instanceof` and for typing. It is not constructible: regions
+ * come from `createKnittingAllocator().alloc()` or from adopting a descriptor.
+ */
+export declare class KnittingSharedBuffer {
+    #private;
+    constructor(mint: symbol, buffer: SharedArrayBuffer, byteOffset: number, byteLength: number, lane?: number, slot?: number, release?: (free: boolean) => void, trim?: (byteLength: number) => void);
+    get byteLength(): number;
+    get byteOffset(): number;
+    /** Owning lane, and the region identity within it (-1 for a standalone SAB). */
+    get lane(): number;
+    get slot(): number;
+    /** True once this handle is spent, whether by `release()` or by a move. */
+    get released(): boolean;
+    /** True when ownership was handed to a consumer by `allocator.moveTo()`. */
+    get moved(): boolean;
+    /**
+     * The standalone SharedArrayBuffer behind an overflow region, or undefined
+     * for a pooled one.
+     *
+     * Pooled regions deliberately have no way to reach their backing store: it
+     * is the whole arena, and handing it out would expose every other live
+     * region's bytes. An overflow region owns its buffer outright, so it is the
+     * only one that can travel as a buffer rather than as a descriptor.
+     */
+    static standaloneBufferOf(region: KnittingSharedBuffer): SharedArrayBuffer | undefined;
+    /**
+     * Surrender the identity without freeing it: after this the handle is inert
+     * and the consumer that adopted the descriptor is the sole releaser.
+     *
+     * A no-op on a spent handle, so a double `moveTo()` cannot hand the same
+     * identity to two consumers -- the second call throws before reaching here.
+     */
+    static [DISOWN](region: KnittingSharedBuffer): void;
+    /** The byte view. Memoized: repeated calls do not construct. */
+    u8(): Uint8Array;
+    /** A typed view over the whole region. Memoized per constructor. */
+    view<T extends ArrayBufferView>(Ctor: ViewConstructor<T>): T;
+    /**
+     * Give back the tail of a region that was reserved larger than needed, and
+     * report the region as `byteLength` bytes from here on.
+     *
+     * The point is streamed input of unknown length: an HTTP body with no
+     * `Content-Length` cannot be sized up front, so reserve an upper bound,
+     * write into it, then commit what actually arrived. Views minted before the
+     * commit are dropped, because their length is now wrong.
+     *
+     * Shrink only. Growing would mean relocating the bytes, which is the copy
+     * this whole path exists to avoid.
+     */
+    commit(byteLength: number): this;
+    /** An independently owned copy, valid after this region is released. */
+    copy(): Uint8Array;
+    release(): void;
+    [Symbol.dispose](): void;
+}
+/** A region handed over directly. One `instanceof`. */
+export declare const detectByInstance: (value: unknown) => KnittingSharedBuffer | undefined;
+/**
+ * A view this pool minted. One WeakMap hit, and it never touches `.buffer` --
+ * which matters because reading `.buffer` on a heap-backed typed array can
+ * materialize the ArrayBuffer wrapper on first access.
+ */
+export declare const detectByMintedView: (value: unknown) => KnittingSharedBuffer | undefined;
+/**
+ * Any view that lands inside a pool arena, including a `subarray` of a minted
+ * view. Costs a `.buffer` read, a WeakMap hit, and a binary search over the
+ * live extent table.
+ */
+export declare const detectByArena: (value: unknown) => KnittingBufferDescriptor | undefined;
+/**
+ * The full check the codec would run on a payload value. Returns a descriptor
+ * to ship by reference, or undefined to serialize the value normally.
+ *
+ * Detection only: like `describe()`, it does not transfer ownership. Whatever
+ * ships the descriptor owes the consumer one of the two safe pairings
+ * documented on `describe()`.
+ */
+export declare const detectRegion: (value: unknown) => KnittingBufferDescriptor | undefined;
+/**
+ * Bump window, and therefore the pool's memory high-water.
+ *
+ * Deliberately small. A wide window makes *allocation* cheaper -- the bump
+ * pointer runs longer before it has to reconcile and reclaim holes -- but that
+ * only counts the bookkeeping, never the bytes. Once real traffic writes them
+ * the ranking inverts: a wide window sprays consecutive regions across cold
+ * memory, and the cache misses cost more than the reconcile it avoided.
+ * Locality wins, so the default is a small multiple of a typical live set
+ * rather than the whole arena.
+ *
+ * It is a default, not a recommendation: size it to `payload x in-flight`.
+ * Two concurrent 1 MiB payloads do not fit here, and a reservation the window
+ * cannot satisfy takes the overflow path rather than waiting. `stats()`
+ * reports `overflows` precisely so this is visible instead of mysterious.
+ */
+export declare const DEFAULT_ARENA_BYTE_LENGTH: number;
+export type KnittingAllocatorOptions = {
+    lane?: number;
+    slots?: number;
+    /** Bump window; see `DEFAULT_ARENA_BYTE_LENGTH` for why small is the default. */
+    arenaByteLength?: number;
+    /**
+     * Collector backstop for a missed release.
+     *   true       register every region
+     *   false      never register: a missed release leaks an identity
+     *   "pressure" register only once live identities cross the watermark
+     *
+     * "pressure" applies the same argument as the lazy reconcile: while the pool
+     * is roomy a forgotten identity costs nothing, so paying the registration
+     * cost on every region to reclaim it early buys nothing. Registration starts
+     * when scarcity makes reclaim worth its price. Worst case is bounded: regions handed out while
+     * roomy are never registered, so at watermark w at most w of the identities
+     * can be stranded before every new region becomes reclaimable.
+     */
+    gcBackstop?: boolean | "pressure";
+    backstopWatermark?: number;
+};
+/** This pool's own counters merged with its region registry's. */
+export type KnittingAllocatorStats = {
+    pooled: number;
+    overflows: number;
+    registered: number;
+    live: number;
+    slots: number;
+    mode: LazyRegionRegistryMode;
+    tableLength: number;
+    tailEnd: number;
+    highWater: number;
+    reconciles: number;
+    firstFits: number;
+    appends: number;
+    resets: number;
+};
+/** What a consumer thread needs to attach: SABs, not pointers. */
+export type KnittingAllocatorTransport = {
+    lane: number;
+    lockSAB: SharedArrayBuffer;
+    arena: SharedArrayBuffer;
+    slots: number;
+    arenaByteLength: number;
+};
+/** Written out rather than inferred: JSR cannot resolve an inferred return type. */
+export type KnittingAllocator = {
+    lane: number;
+    /** Bump window this pool was built with; the ceiling on a pooled region. */
+    arenaByteLength: number;
+    alloc: (byteLength: number) => KnittingSharedBuffer;
+    allocUpTo: (maxByteLength: number) => KnittingSharedBuffer;
+    allocOrRefer: (request: Request, options: ReadBodyOrReferOptions) => Promise<KnittingBody>;
+    describe: (region: KnittingSharedBuffer) => KnittingBufferDescriptor;
+    moveTo: (region: KnittingSharedBuffer) => KnittingBufferDescriptor;
+    reconcile: () => boolean;
+    stats: () => KnittingAllocatorStats;
+    resetCounters: () => void;
+    transport: () => KnittingAllocatorTransport;
+};
+/** The consumer side of another thread's pool: it adopts, it never allocates. */
+export type AttachedKnittingAllocator = {
+    lane: number;
+    adopt: (descriptor: KnittingBufferDescriptor | SharedArrayBuffer, options?: {
+        gcBackstop?: boolean;
+        borrow?: boolean;
+    }) => KnittingSharedBuffer;
+};
+export declare const createKnittingAllocator: ({ lane, slots, arenaByteLength, gcBackstop, backstopWatermark, }?: KnittingAllocatorOptions) => KnittingAllocator;
+/**
+ * The consumer side of another thread's pool. It never allocates; it
+ * materializes regions over the producer's arena and releases the producer's
+ * identity with one XOR into the shared word.
+ */
+export declare const attachKnittingAllocator: ({ lane, lockSAB, arena, slots }: {
+    lane: number;
+    lockSAB: SharedArrayBuffer;
+    arena: SharedArrayBuffer;
+    slots: number;
+}) => AttachedKnittingAllocator;
+export {};