@bradensbay/globals-core 0.2.0

package/dist/src/layout.js

@@ -0,0 +1,149 @@
+/**
+ * The shared memory layout.
+ *
+ * Everything here is a fixed offset agreed between the owner and every reader. A change to
+ * any of it is a breaking change to the wire format and requires a LAYOUT_VERSION bump,
+ * because an owner and a reader from different builds may map the same buffer.
+ *
+ * Byte map:
+ *
+ *   0                    header, HEADER_BYTES
+ *   HEADER_BYTES         reader table, maxReaders * READER_SLOT_BYTES
+ *   ...                  retained version ring, retainedCap * RETAINED_SLOT_BYTES
+ *   ...                  arena, grows upward from a bump pointer
+ */
+/** "GLOB" in ASCII. A buffer that does not start with this is not one of ours. */
+export const MAGIC = 0x474c4f42;
+/** Bump on any change to the byte map, the block header, or the tag meanings. */
+export const LAYOUT_VERSION = 1;
+export const WORD = 4;
+export const SLOT_BYTES = 8;
+/** Every allocation starts on an eight byte boundary so float64 stores are aligned. */
+export const ALIGNMENT = 8;
+// ---------------------------------------------------------------------------
+// Header, in 32 bit words
+// ---------------------------------------------------------------------------
+export const Header = {
+    Magic: 0,
+    LayoutVersion: 1,
+    /** Total byte length the owner believes the buffer has. Updated on grow. */
+    CapacityBytes: 2,
+    /** Guards the configuration words, so a reader can detect a stomped header. */
+    ConfigChecksum: 3,
+    /**
+     * Seqlock over the root publication. Even means stable, odd means a commit is in
+     * progress. Readers retry rather than block.
+     */
+    Sequence: 4,
+    RootTag: 5,
+    RootPayload: 6,
+    /** Monotonic. Doubles as the epoch a reader pins. */
+    VersionId: 7,
+    /** Byte offset of the next unallocated byte. */
+    BumpPointer: 8,
+    MaxReaders: 9,
+    ReaderTableOffset: 10,
+    RetainedRingOffset: 11,
+    RetainedCapacity: 12,
+    ArenaOffset: 13,
+    /** Oldest version still retained. A snapshot below this is stale. */
+    ReclaimFloor: 14,
+    /** Verification mode, see VerifyMode. */
+    Flags: 15,
+    /** Bumped by the owner on every liveness tick so readers can detect a dead owner. */
+    OwnerHeartbeat: 16,
+    /** Bumped when a new owner adopts the buffer, so stale readers fail closed. */
+    OwnerGeneration: 17,
+    StatCommits: 18,
+    StatBytesAllocated: 19,
+    StatBytesFreed: 20,
+    StatBytesLive: 21,
+    StatForcedAdvances: 22,
+    /** Checksum over the header and the current root, when verification is on. */
+    RootChecksum: 23,
+};
+export const HEADER_WORDS = 32;
+export const HEADER_BYTES = HEADER_WORDS * WORD;
+/** Words the ConfigChecksum covers. These never change after creation. */
+export const CONFIG_WORDS = [
+    Header.Magic,
+    Header.LayoutVersion,
+    Header.MaxReaders,
+    Header.ReaderTableOffset,
+    Header.RetainedRingOffset,
+    Header.RetainedCapacity,
+    Header.ArenaOffset,
+];
+// ---------------------------------------------------------------------------
+// Reader table
+// ---------------------------------------------------------------------------
+export const ReaderSlot = {
+    /** 0 free, 1 claimed. Claimed with compareExchange so two readers cannot share a slot. */
+    State: 0,
+    /** Bumped on each claim. A snapshot from an earlier generation is not valid. */
+    Generation: 1,
+    /** The version this reader is pinned to. Zero means it is not reading. */
+    Epoch: 2,
+    /** Monotonic counter the reader bumps. A stalled counter means a dead or frozen reader. */
+    Heartbeat: 3,
+};
+export const READER_SLOT_WORDS = 4;
+export const READER_SLOT_BYTES = READER_SLOT_WORDS * WORD;
+export const SLOT_FREE = 0;
+export const SLOT_CLAIMED = 1;
+// ---------------------------------------------------------------------------
+// Retained version ring
+// ---------------------------------------------------------------------------
+export const RetainedSlot = {
+    VersionId: 0,
+    RootTag: 1,
+    RootPayload: 2,
+    /** See RetainedState. */
+    State: 3,
+};
+export const RETAINED_SLOT_WORDS = 4;
+export const RETAINED_SLOT_BYTES = RETAINED_SLOT_WORDS * WORD;
+export const RetainedState = {
+    Empty: 0,
+    /** Readers may pin this version. */
+    Live: 1,
+    /** Reclaimed normally, every reader had moved past it. */
+    Reclaimed: 2,
+    /** Reclaimed while a reader was still pinned, because retention hit its cap. */
+    ForceReclaimed: 3,
+};
+// ---------------------------------------------------------------------------
+// Allocation block header
+// ---------------------------------------------------------------------------
+/**
+ * Every allocation is preceded by two words. The magic makes a wild offset detectable
+ * instead of merely wrong, and the size class lets the allocator return the block to the
+ * right free list without a side table.
+ */
+export const Block = {
+    /** BLOCK_MAGIC in the high 24 bits, size class index in the low 8. */
+    Header: -2,
+    /** Payload bytes, not counting this header. */
+    ByteSize: -1,
+};
+export const BLOCK_HEADER_BYTES = 8;
+export const BLOCK_MAGIC = 0x424c4b; // "BLK"
+export const BLOCK_MAGIC_SHIFT = 8;
+export const BLOCK_CLASS_MASK = 0xff;
+/** Size class 255 means the block was allocated at an exact size and has no free list. */
+export const SIZE_CLASS_EXACT = 0xff;
+export const VerifyMode = {
+    Off: 0,
+    Header: 1,
+    Full: 2,
+};
+export function computeGeometry(maxReaders, retainedCapacity) {
+    const readerTableOffset = HEADER_BYTES;
+    const retainedRingOffset = readerTableOffset + maxReaders * READER_SLOT_BYTES;
+    const arenaOffset = align(retainedRingOffset + retainedCapacity * RETAINED_SLOT_BYTES);
+    return { maxReaders, retainedCapacity, readerTableOffset, retainedRingOffset, arenaOffset };
+}
+export function align(bytes) {
+    return (bytes + (ALIGNMENT - 1)) & ~(ALIGNMENT - 1);
+}
+//# sourceMappingURL=layout.js.map

package/dist/src/layout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.js","sourceRoot":"","sources":["../../src/layout.ts"],"names":[],"mappings":"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"}

package/dist/src/liveness.d.ts

@@ -0,0 +1,48 @@
+import type { ArenaOwner } from "./owner.js";
+/**
+ * Liveness detection for readers.
+ *
+ * A renderer that reloads discards its heap while its slot in the reader table is still
+ * claimed and, worse, while its epoch is still pinned. Nothing in the arena notices, so
+ * retention grows until the ring wraps. A crashed renderer is the same case without the
+ * reload.
+ *
+ * The detector is deliberately conservative. Reclaiming a slot from a reader that is merely
+ * slow costs that reader a StaleSnapshotError and a reacquire, which is recoverable but
+ * pointless. So a reader is declared dead only after its heartbeat has failed to move across
+ * several consecutive ticks while it was holding a pin.
+ *
+ * This lives in the core rather than the Electron package because it is the same problem in
+ * a worker thread, and because it can be tested without a window manager.
+ */
+export interface LivenessOptions {
+    /** How often to sample, in milliseconds. */
+    intervalMs?: number;
+    /** Consecutive unchanged samples before a pinned reader is declared dead. */
+    missesBeforeDead?: number;
+    /** Called when a slot is reclaimed, for logging and metrics. */
+    onReaped?: (slot: number, detail: {
+        epoch: number;
+        generation: number;
+    }) => void;
+}
+export declare class LivenessMonitor {
+    #private;
+    constructor(owner: ArenaOwner, options?: LivenessOptions);
+    get reapedCount(): number;
+    start(): void;
+    stop(): void;
+    /**
+     * One sampling pass. Exposed so tests can drive it without waiting on a timer, and so an
+     * integration can run it on a window lifecycle event rather than only on a clock.
+     */
+    tick(): void;
+    /**
+     * Reclaim a slot straight away, for a window the integration knows is gone.
+     *
+     * A close or crash event is better evidence than any number of missed heartbeats, so an
+     * integration that has one should use it rather than waiting for the detector.
+     */
+    reapSlot(slot: number): void;
+}
+//# sourceMappingURL=liveness.d.ts.map

package/dist/src/liveness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"liveness.d.ts","sourceRoot":"","sources":["../../src/liveness.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7C;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,WAAW,eAAe;IAC9B,4CAA4C;IAC5C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gEAAgE;IAChE,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;CAClF;AAaD,qBAAa,eAAe;;IAU1B,YAAY,KAAK,EAAE,UAAU,EAAE,OAAO,GAAE,eAAoB,EAM3D;IAED,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,KAAK,IAAI,IAAI,CAMZ;IAED,IAAI,IAAI,IAAI,CAIX;IAED;;;OAGG;IACH,IAAI,IAAI,IAAI,CAyCX;IAED;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAK3B;CACF"}

package/dist/src/liveness.js

@@ -0,0 +1,92 @@
+const DEFAULTS = {
+    intervalMs: 1000,
+    missesBeforeDead: 5,
+};
+export class LivenessMonitor {
+    #owner;
+    #table;
+    #intervalMs;
+    #missesBeforeDead;
+    #onReaped;
+    #samples = new Map();
+    #timer;
+    #reaped = 0;
+    constructor(owner, options = {}) {
+        this.#owner = owner;
+        this.#table = owner.readers;
+        this.#intervalMs = options.intervalMs ?? DEFAULTS.intervalMs;
+        this.#missesBeforeDead = options.missesBeforeDead ?? DEFAULTS.missesBeforeDead;
+        this.#onReaped = options.onReaped;
+    }
+    get reapedCount() {
+        return this.#reaped;
+    }
+    start() {
+        if (this.#timer !== undefined)
+            return;
+        this.#timer = setInterval(() => this.tick(), this.#intervalMs);
+        // Do not hold the process open. A liveness timer is a housekeeping detail, and an
+        // application that has nothing else to do should be allowed to exit.
+        this.#timer.unref?.();
+    }
+    stop() {
+        if (this.#timer === undefined)
+            return;
+        clearInterval(this.#timer);
+        this.#timer = undefined;
+    }
+    /**
+     * One sampling pass. Exposed so tests can drive it without waiting on a timer, and so an
+     * integration can run it on a window lifecycle event rather than only on a clock.
+     */
+    tick() {
+        this.#owner.beat();
+        const seen = new Set();
+        for (const reader of this.#table.claimedSlots()) {
+            seen.add(reader.slot);
+            const previous = this.#samples.get(reader.slot);
+            if (previous === undefined || previous.generation !== reader.generation) {
+                // A new claimant, or the same slot reclaimed by someone else. Start fresh.
+                this.#samples.set(reader.slot, {
+                    heartbeat: reader.heartbeat,
+                    misses: 0,
+                    generation: reader.generation,
+                });
+                continue;
+            }
+            // An unpinned reader costs nothing, so it is not worth reaping however idle it is.
+            if (reader.epoch === 0 || reader.heartbeat !== previous.heartbeat) {
+                previous.heartbeat = reader.heartbeat;
+                previous.misses = 0;
+                continue;
+            }
+            previous.misses += 1;
+            if (previous.misses < this.#missesBeforeDead)
+                continue;
+            this.#table.forceRelease(reader.slot);
+            this.#samples.delete(reader.slot);
+            this.#reaped += 1;
+            this.#onReaped?.(reader.slot, { epoch: reader.epoch, generation: reader.generation });
+        }
+        for (const slot of this.#samples.keys()) {
+            if (!seen.has(slot))
+                this.#samples.delete(slot);
+        }
+        // Reclaim immediately after reaping, so the memory a dead reader was pinning is returned
+        // in the same pass rather than at the next commit.
+        this.#owner.reclaim();
+    }
+    /**
+     * Reclaim a slot straight away, for a window the integration knows is gone.
+     *
+     * A close or crash event is better evidence than any number of missed heartbeats, so an
+     * integration that has one should use it rather than waiting for the detector.
+     */
+    reapSlot(slot) {
+        this.#table.forceRelease(slot);
+        this.#samples.delete(slot);
+        this.#reaped += 1;
+        this.#owner.reclaim();
+    }
+}
+//# sourceMappingURL=liveness.js.map

package/dist/src/liveness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"liveness.js","sourceRoot":"","sources":["../../src/liveness.ts"],"names":[],"mappings":"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"}

package/dist/src/owner.d.ts

@@ -0,0 +1,130 @@
+import { SharedArena } from "./arena.js";
+import { Allocator } from "./allocator.js";
+import { ReaderTable } from "./readers.js";
+import { RetainedRing } from "./retained.js";
+import { StringTable } from "./strings.js";
+import { type VerifyModeValue } from "./layout.js";
+export interface OwnerOptions {
+    /** Initial arena size in bytes. */
+    byteLength?: number;
+    /** Upper bound the buffer may grow to. Address space is reserved, not resident memory. */
+    maxByteLength?: number;
+    /** Reader slots. One per window, plus headroom for reloads that have not been reaped. */
+    maxReaders?: number;
+    /**
+     * How many versions the ring retains. This bounds how far a stalled reader can hold
+     * memory: past it, the owner force advances and that reader fails closed.
+     */
+    retainedVersions?: number;
+    verify?: VerifyModeValue;
+    /**
+     * How many superseded versions to keep readable for time travel.
+     *
+     * Zero, the default, reclaims a version as soon as no reader is pinned to it, which is the
+     * cheapest thing to do and leaves no history to browse. A positive value keeps that many
+     * versions behind the current one alive, at the cost of holding their path copies. It is
+     * capped at one less than the retained ring, because the ring is what bounds retention.
+     *
+     * Turn it on in development and leave it off in production, unless the application has a
+     * reason to browse history at runtime.
+     */
+    historyDepth?: number;
+}
+export interface OwnerStats {
+    readonly versionId: number;
+    readonly commits: number;
+    readonly forcedAdvances: number;
+    readonly liveBytes: number;
+    readonly bumpPointer: number;
+    readonly capacityBytes: number;
+    readonly freeListBytes: number;
+    readonly strandedBytes: number;
+    readonly internedStrings: number;
+    readonly pendingGarbageVersions: number;
+    readonly historyDepth: number;
+    readonly reclaimFloor: number;
+    readonly claimedReaders: number;
+    readonly minimumPinnedEpoch: number;
+}
+/**
+ * The sole writer.
+ *
+ * In Electron this runs in the hidden owner window. In tests it runs on the main thread of
+ * a plain Node process, which is exactly the point of keeping this package free of Electron
+ * imports.
+ *
+ * The single writer property is load bearing. It removes allocator locking, it makes the
+ * free lists safe to keep on the writer heap where no other window can corrupt them, and it
+ * makes the commit sequence a plain store rather than a contended compare and exchange.
+ */
+export declare class ArenaOwner {
+    #private;
+    readonly arena: SharedArena;
+    private constructor();
+    /** Allocate and format a new arena. */
+    static create(options?: OwnerOptions): ArenaOwner;
+    /**
+     * Adopt a buffer that a previous owner formatted. Bumps the owner generation so readers
+     * attached to the dead owner can detect the change.
+     *
+     * The free lists cannot be recovered, so an adopted arena starts with a bump pointer
+     * where the previous owner left it and no reusable blocks. That is acceptable because
+     * adoption follows an owner crash, which is rare and already costs a rehydrate.
+     */
+    static adopt(buffer: SharedArrayBuffer): ArenaOwner;
+    get buffer(): SharedArrayBuffer;
+    get versionId(): number;
+    get strings(): StringTable;
+    get allocator(): Allocator;
+    get readers(): ReaderTable;
+    get ring(): RetainedRing;
+    /**
+     * Encode `value`, publish it as the new root, and reclaim what the previous version was
+     * keeping alive.
+     *
+     * The publication is a seqlock write. Readers never block on it: they observe an odd
+     * sequence, spin briefly, and retry. The window is a handful of stores wide.
+     */
+    commit(value: unknown): number;
+    /**
+     * Apply a recipe to a draft of the current state and commit the result.
+     *
+     * This is the path that makes retention affordable. Only the paths the recipe touched are
+     * rebuilt, so setting one field of a large object copies a handful of nodes rather than
+     * the tree.
+     *
+     *     owner.update((draft) => {
+     *       draft.users[3].name = "new name";
+     *     });
+     */
+    update<T>(recipe: (draft: T) => void): number;
+    /**
+     * The current state as a detached plain value.
+     *
+     * The owner reads through this rather than through a reader, because it already knows the
+     * current root and does not need to pin anything: nothing can reclaim a version while the
+     * only writer is inside a synchronous method.
+     */
+    readSnapshot(): unknown;
+    /**
+     * Reclaim every version that no reader can still be pinned to.
+     *
+     * The order below is the whole correctness argument, so it is written out rather than
+     * left to be rediscovered:
+     *
+     *   1. Scan the reader table for the minimum pinned epoch.
+     *   2. Publish the resulting floor.
+     *   3. Scan again.
+     *   4. Free only below the minimum of the two scans.
+     *
+     * Step 3 is what closes the race. A reader that pinned between steps 1 and 2 is seen by
+     * the second scan. A reader that pinned after step 2 must load the floor after the store
+     * that published it, sees its version is below the floor, and retries. There is no
+     * interleaving in which a reader proceeds with a version this method then frees.
+     */
+    reclaim(): void;
+    /** Bump the owner heartbeat. Readers use it to detect an owner that has stopped. */
+    beat(): void;
+    stats(): OwnerStats;
+}
+//# sourceMappingURL=owner.d.ts.map

package/dist/src/owner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"owner.d.ts","sourceRoot":"","sources":["../../src/owner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAsB,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAavE,MAAM,WAAW,YAAY;IAC3B,mCAAmC;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0FAA0F;IAC1F,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,yFAAyF;IACzF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB;;;;;;;;;;OAUG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAWD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;IACxC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;CACrC;AAED;;;;;;;;;;GAUG;AACH,qBAAa,UAAU;;IACrB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAsB5B,OAAO,eAMN;IAED,uCAAuC;IACvC,MAAM,CAAC,MAAM,CAAC,OAAO,GAAE,YAAiB,GAAG,UAAU,CAqBpD;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,iBAAiB,GAAG,UAAU,CAYlD;IAED,IAAI,MAAM,IAAI,iBAAiB,CAE9B;IAED,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,IAAI,OAAO,IAAI,WAAW,CAEzB;IAED,IAAI,SAAS,IAAI,SAAS,CAEzB;IAED,IAAI,OAAO,IAAI,WAAW,CAEzB;IAED,IAAI,IAAI,IAAI,YAAY,CAEvB;IAED;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAe7B;IAED;;;;;;;;;;OAUG;IACH,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAAG,MAAM,CA4B5C;IAED;;;;;;OAMG;IACH,YAAY,IAAI,OAAO,CAEtB;IAsED;;;;;;;;;;;;;;;OAeG;IACH,OAAO,IAAI,IAAI,CAkBd;IAkED,oFAAoF;IACpF,IAAI,IAAI,IAAI,CAEX;IAED,KAAK,IAAI,UAAU,CAmBlB;CACF"}