@bradensbay/globals-core 0.2.0

package/dist/src/owner.js

@@ -0,0 +1,368 @@
+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 { Header, VerifyMode } from "./layout.js";
+import { publishChecksum } from "./verify.js";
+import { collectBlocks, decodeValue, encodeValue, } from "./values.js";
+import { createDraft, finalizeState } from "./draft.js";
+import { Tag } from "./tags.js";
+import { GlobalsError } from "./errors.js";
+const DEFAULTS = {
+    byteLength: 1 << 20,
+    maxByteLength: 1 << 26,
+    maxReaders: 32,
+    retainedVersions: 64,
+    verify: VerifyMode.Header,
+    historyDepth: 0,
+};
+/**
+ * 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 class ArenaOwner {
+    arena;
+    #allocator;
+    #strings;
+    #readers;
+    #ring;
+    #versionId = 0;
+    #currentSlot = { tag: 0, payload: 0 };
+    /**
+     * The oldest version a reader may still decode. Monotonic: once memory below a version
+     * is freed, no later decision may lower the floor back over it.
+     */
+    #reclaimFloor = 0;
+    #historyDepth = 0;
+    #verify = VerifyMode.Header;
+    /**
+     * Blocks that became unreachable when a version was superseded, keyed by the version
+     * that still referenced them. Insertion order is ascending by version, which the
+     * reclamation scan relies on.
+     */
+    #garbage = new Map();
+    constructor(arena) {
+        this.arena = arena;
+        this.#allocator = new Allocator(arena, (minimum) => this.#growBuffer(minimum));
+        this.#strings = new StringTable(arena, this.#allocator);
+        this.#readers = new ReaderTable(arena);
+        this.#ring = new RetainedRing(arena);
+    }
+    /** Allocate and format a new arena. */
+    static create(options = {}) {
+        const settings = { ...DEFAULTS, ...options };
+        if (settings.maxByteLength < settings.byteLength) {
+            throw new GlobalsError("maxByteLength cannot be smaller than byteLength");
+        }
+        const buffer = new SharedArrayBuffer(settings.byteLength, {
+            maxByteLength: settings.maxByteLength,
+        });
+        const arena = SharedArena.format(buffer, {
+            maxReaders: settings.maxReaders,
+            retainedCapacity: settings.retainedVersions,
+            flags: settings.verify,
+        });
+        const owner = new ArenaOwner(arena);
+        owner.#historyDepth = Math.max(0, Math.min(settings.historyDepth, settings.retainedVersions - 1));
+        owner.#verify = settings.verify;
+        owner.commit(undefined);
+        return owner;
+    }
+    /**
+     * 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) {
+        const arena = SharedArena.attach(buffer);
+        arena.addHeader(Header.OwnerGeneration, 1);
+        const owner = new ArenaOwner(arena);
+        owner.#verify = (arena.loadHeader(Header.Flags) & 0b11);
+        owner.#versionId = arena.loadHeader(Header.VersionId);
+        owner.#reclaimFloor = arena.loadHeader(Header.ReclaimFloor);
+        owner.#currentSlot = {
+            tag: arena.loadHeader(Header.RootTag),
+            payload: arena.loadHeader(Header.RootPayload),
+        };
+        return owner;
+    }
+    get buffer() {
+        return this.arena.buffer;
+    }
+    get versionId() {
+        return this.#versionId;
+    }
+    get strings() {
+        return this.#strings;
+    }
+    get allocator() {
+        return this.#allocator;
+    }
+    get readers() {
+        return this.#readers;
+    }
+    get ring() {
+        return this.#ring;
+    }
+    /**
+     * 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) {
+        const context = this.#newContext();
+        let slot;
+        try {
+            slot = encodeValue(context, value);
+        }
+        catch (error) {
+            this.#rollback(context);
+            throw error;
+        }
+        // A wholesale replacement shares nothing with the previous version, so everything the
+        // old root reached is garbage once that version is unreadable.
+        const retired = collectBlocks(this.arena, this.#currentSlot, context.retired);
+        return this.#install(slot, retired);
+    }
+    /**
+     * 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(recipe) {
+        const context = this.#newContext();
+        const current = this.#currentSlot;
+        if (current.tag !== Tag.Object && current.tag !== Tag.Array) {
+            throw new GlobalsError("update needs an object or array root. Commit one first, or use commit to replace " +
+                "the root outright.");
+        }
+        let slot;
+        try {
+            const draft = createDraft(context, current);
+            recipe(draft.proxy);
+            slot = finalizeState(context, draft.state);
+        }
+        catch (error) {
+            this.#rollback(context);
+            throw error;
+        }
+        if (slot.tag === current.tag && slot.payload === current.payload) {
+            // The recipe changed nothing. Publishing a version anyway would wake every window for
+            // no reason.
+            return this.#versionId;
+        }
+        return this.#install(slot, context.retired);
+    }
+    /**
+     * 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() {
+        return decodeValue(this.arena, this.#currentSlot);
+    }
+    /**
+     * Undo a commit that failed part way.
+     *
+     * Both lists matter. The allocated blocks are obvious. The interning journal is less so:
+     * strings are append only and never freed during normal operation, so without releasing
+     * the ones a rejected write created, a sequence of rejected writes would consume the arena
+     * permanently. A window that can request writes could then exhaust it with writes that
+     * were all refused.
+     */
+    #rollback(context) {
+        for (const offset of context.allocated)
+            this.#allocator.free(offset);
+        this.#strings.forget(context.interned);
+        // Freeing returns the blocks to their size classes, which is not enough on its own: a
+        // write that filled the arena with small records leaves it unable to serve a larger
+        // request, because there is no coalescing. Rewinding the bump pointer past everything
+        // this commit allocated returns the arena to exactly where it was.
+        this.#allocator.rewindTo(context.bumpBefore);
+    }
+    #newContext() {
+        return {
+            arena: this.arena,
+            allocator: this.#allocator,
+            strings: this.#strings,
+            allocated: [],
+            retired: [],
+            interned: [],
+            bumpBefore: this.#allocator.stats().bumpPointer,
+        };
+    }
+    #install(slot, retired) {
+        const previousVersion = this.#versionId;
+        const version = previousVersion + 1;
+        this.#evictForVersion(version);
+        this.#publish(version, slot);
+        if (previousVersion > 0 && retired.length > 0) {
+            const existing = this.#garbage.get(previousVersion);
+            if (existing)
+                existing.push(...retired);
+            else
+                this.#garbage.set(previousVersion, retired);
+        }
+        this.#currentSlot = slot;
+        this.#versionId = version;
+        this.arena.addHeader(Header.StatCommits, 1);
+        this.reclaim();
+        return version;
+    }
+    #publish(version, slot) {
+        const arena = this.arena;
+        // Odd sequence: a commit is in progress and readers must retry.
+        arena.addHeader(Header.Sequence, 1);
+        // The ring entry is written before the header so a reader that observes the new version
+        // can always find it live in the ring.
+        this.#ring.publish(version, slot.tag, slot.payload);
+        arena.storeHeader(Header.RootTag, slot.tag);
+        arena.storeHeader(Header.RootPayload, slot.payload);
+        arena.storeHeader(Header.VersionId, version);
+        // The checksum goes inside the seqlock too, so a reader that observes the new version
+        // always observes the checksum that matches it rather than the previous one.
+        publishChecksum(arena, slot, version, this.#verify);
+        // Even sequence: the root is stable again.
+        arena.addHeader(Header.Sequence, 1);
+    }
+    /**
+     * 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() {
+        const firstScan = this.#readers.minimumPinnedEpoch();
+        // History, when it is switched on, holds versions alive that nothing is pinned to. It is
+        // a deliberate cost rather than a free feature: those versions keep their path copies.
+        const boundary = Math.min(firstScan, this.#versionId - this.#historyDepth);
+        this.#raiseFloor(Number.isFinite(boundary) ? boundary : 0);
+        const secondScan = this.#readers.minimumPinnedEpoch();
+        const safeBelow = Math.min(boundary, secondScan);
+        for (const [versionId, blocks] of this.#garbage) {
+            if (versionId >= safeBelow)
+                break;
+            for (const offset of blocks)
+                this.#allocator.free(offset);
+            this.#garbage.delete(versionId);
+            this.#ring.retire(versionId, false);
+        }
+        this.arena.storeHeader(Header.StatBytesLive, this.#allocator.stats().liveBytes);
+    }
+    /**
+     * Raise the reclaim floor and publish it. Never lowers it: a reader that has been told a
+     * version is gone must not later be told it is available again, because the memory
+     * beneath it has already been handed to a different allocation.
+     */
+    #raiseFloor(value) {
+        if (value <= this.#reclaimFloor)
+            return;
+        this.#reclaimFloor = value;
+        this.arena.storeHeader(Header.ReclaimFloor, value);
+    }
+    /**
+     * The ring slot a new version will occupy may still hold a live version. Free it, even if
+     * a reader is pinned to it.
+     *
+     * This is the bounded retention rule. The alternative is to let one frozen window grow
+     * the arena without limit, which turns a stuck renderer into an out of memory crash for
+     * the whole application. A reader that loses its version this way raises
+     * StaleSnapshotError on its next decode and reacquires, which is a recoverable outcome.
+     */
+    #evictForVersion(version) {
+        const evicted = version - this.#ring.capacity;
+        if (evicted < 1)
+            return;
+        const minimumPinned = this.#readers.minimumPinnedEpoch();
+        if (minimumPinned <= evicted)
+            this.arena.addHeader(Header.StatForcedAdvances, 1);
+        // The floor rises before anything is freed. A reader that is part way through decoding
+        // one of these versions revalidates after its decode and sees the raised floor, so it
+        // reports a stale snapshot instead of returning a value read from reused memory. The
+        // reverse order loses that: the reader would decode recycled bytes and revalidate
+        // against a floor that had not moved yet.
+        this.#raiseFloor(evicted + 1);
+        for (const [versionId, blocks] of this.#garbage) {
+            if (versionId > evicted)
+                break;
+            for (const offset of blocks)
+                this.#allocator.free(offset);
+            this.#garbage.delete(versionId);
+            this.#ring.retire(versionId, versionId >= minimumPinned);
+        }
+    }
+    /**
+     * Grow the buffer. Every holder observes the new length, because a growable
+     * SharedArrayBuffer reserves its maximum at allocation and grow() only publishes more of
+     * it. Views made before the growth are refreshed lazily by SharedArena.
+     */
+    #growBuffer(minimumBytes) {
+        const buffer = this.arena.buffer;
+        const maximum = buffer.maxByteLength ?? buffer.byteLength;
+        if (!buffer.growable || buffer.byteLength >= maximum)
+            return false;
+        const wanted = Math.min(maximum, Math.max(buffer.byteLength * 2, buffer.byteLength + minimumBytes));
+        if (wanted <= buffer.byteLength)
+            return false;
+        buffer.grow(wanted);
+        this.arena.refresh();
+        this.arena.storeHeader(Header.CapacityBytes, this.arena.byteLength);
+        return true;
+    }
+    /** Bump the owner heartbeat. Readers use it to detect an owner that has stopped. */
+    beat() {
+        this.arena.addHeader(Header.OwnerHeartbeat, 1);
+    }
+    stats() {
+        const allocator = this.#allocator.stats();
+        const minimum = this.#readers.minimumPinnedEpoch();
+        return {
+            versionId: this.#versionId,
+            commits: this.arena.loadHeader(Header.StatCommits),
+            forcedAdvances: this.arena.loadHeader(Header.StatForcedAdvances),
+            liveBytes: allocator.liveBytes,
+            bumpPointer: allocator.bumpPointer,
+            capacityBytes: allocator.capacityBytes,
+            freeListBytes: allocator.freeListBytes,
+            strandedBytes: this.#allocator.strandedBytes(),
+            internedStrings: this.#strings.size,
+            pendingGarbageVersions: this.#garbage.size,
+            historyDepth: this.#historyDepth,
+            reclaimFloor: this.arena.loadHeader(Header.ReclaimFloor),
+            claimedReaders: this.#readers.claimedSlots().length,
+            minimumPinnedEpoch: Number.isFinite(minimum) ? minimum : 0,
+        };
+    }
+}
+//# sourceMappingURL=owner.js.map

package/dist/src/owner.js.map

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

package/dist/src/reader.d.ts

@@ -0,0 +1,122 @@
+import { SharedArena } from "./arena.js";
+import { type Slot } from "./values.js";
+export interface SnapshotInfo {
+    readonly versionId: number;
+    readonly ownerGeneration: number;
+}
+/**
+ * A pinned version.
+ *
+ * Holding one guarantees the graph beneath it cannot change, because the writer never
+ * mutates a published node. It does not guarantee the version stays retained forever: past
+ * the retention cap the owner force advances, and the next decode raises
+ * StaleSnapshotError rather than reading recycled memory.
+ */
+export declare class Snapshot {
+    #private;
+    readonly versionId: number;
+    readonly ownerGeneration: number;
+    constructor(reader: ArenaReader, versionId: number, ownerGeneration: number, slot: Slot);
+    get released(): boolean;
+    /**
+     * The root value. Synchronous, no await, no round trip. This is the whole product.
+     *
+     * Validated on both sides of the decode. The check before it rejects a version that is
+     * already gone. The check after it is the one that matters: the owner raises the reclaim
+     * floor before it frees anything, so a version that is still above the floor once the
+     * decode has finished cannot have been freed while the decode was running. Validating
+     * only beforehand leaves a window in which a forced reclaim recycles the block and the
+     * reader returns a well formed but wrong value, which the soak harness found in about two
+     * reads out of four million.
+     */
+    get value(): unknown;
+    /**
+     * The whole version as a detached plain value, with no proxies and no arena references.
+     *
+     * Use it to hand state to something that has to own it, such as a serialiser or a worker.
+     * It costs a full decode, which is exactly what the lazy path exists to avoid, so it is a
+     * deliberate call rather than the default.
+     */
+    toJSON(): unknown;
+    /**
+     * Read one path without building views for the nodes along it.
+     *
+     * The cheapest shape for a selector, and what the framework bindings use.
+     */
+    get(path: readonly (string | number)[]): unknown;
+    /** The root slot, for callers decoding lazily rather than eagerly. */
+    get root(): Slot;
+    /**
+     * Prove this version is still retained. Two atomic loads and two comparisons, run on both
+     * sides of every decode. Cheap enough to sit on the read path, and the only thing standing
+     * between a stalled reader and freed memory.
+     */
+    validate(): void;
+    /**
+     * True when this snapshot can still be decoded. Never throws, and never constructs an
+     * error object, because it runs twice per read and a try/catch around the throwing form
+     * kept the whole path out of the optimising compiler.
+     */
+    isValid(): boolean;
+    release(): void;
+}
+export interface ReaderOptions {
+    /** Bump the heartbeat on every acquire so the owner can tell this reader is alive. */
+    heartbeat?: boolean;
+}
+/**
+ * A reader.
+ *
+ * Attaching claims one slot in the reader table. Acquiring a snapshot is a seqlock read of
+ * the root, one atomic store to publish the pinned epoch, and one atomic load to confirm
+ * the version is above the reclaim floor. Nothing here blocks, allocates a promise, or
+ * sends a message.
+ */
+export declare class ArenaReader {
+    #private;
+    readonly arena: SharedArena;
+    readonly slot: number;
+    readonly generation: number;
+    private constructor();
+    static attach(buffer: SharedArrayBuffer, options?: ReaderOptions): ArenaReader;
+    get detached(): boolean;
+    reclaimFloor(): number;
+    ownerGeneration(): number;
+    /** The version the owner has currently published, without pinning it. */
+    publishedVersion(): number;
+    /**
+     * Acquire the current version and pin it.
+     *
+     * Returns the snapshot already held when the owner has not committed since, so a render
+     * loop that calls this every frame does not churn pins.
+     */
+    acquire(): Snapshot;
+    /** Read the current root value. The synchronous read the whole library exists for. */
+    read(): unknown;
+    /**
+     * Pin a specific retained version rather than the current one.
+     *
+     * For debugging and time travel. It pins that version and everything after it against
+     * reclamation, so a snapshot obtained this way must be released. A render path should
+     * never use it.
+     *
+     * A reader owns one epoch slot, so this suspends the pin the render path was holding until
+     * the returned snapshot is released. A debug panel that browses history while a render
+     * reads should attach its own reader rather than share one, which costs a slot and keeps
+     * the two independent.
+     */
+    acquireVersion(versionId: number): Snapshot;
+    /** Materialise a retained version, pinning it only for the duration of the read. */
+    readVersion(versionId: number): unknown;
+    releaseSnapshot(snapshot: Snapshot): void;
+    /** Release the pin and the reader slot. Always call this before dropping a reader. */
+    detach(): void;
+    stats(): {
+        slot: number;
+        generation: number;
+        pinnedEpoch: number;
+        publishedVersion: number;
+        reclaimFloor: number;
+    };
+}
+//# sourceMappingURL=reader.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reader.d.ts","sourceRoot":"","sources":["../../src/reader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAKzC,OAAO,EAAe,KAAK,IAAI,EAAE,MAAM,aAAa,CAAC;AAWrD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED;;;;;;;GAOG;AACH,qBAAa,QAAQ;;IACnB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IAMjC,YAAY,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAKtF;IAED,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED;;;;;;;;;;OAUG;IACH,IAAI,KAAK,IAAI,OAAO,CAKnB;IAED;;;;;;OAMG;IACH,MAAM,IAAI,OAAO,CAKhB;IAED;;;;OAIG;IACH,GAAG,CAAC,IAAI,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,GAAG,OAAO,CAK/C;IAmBD,sEAAsE;IACtE,IAAI,IAAI,IAAI,IAAI,CAGf;IAED;;;;OAIG;IACH,QAAQ,IAAI,IAAI,CAGf;IAED;;;;OAIG;IACH,OAAO,IAAI,OAAO,CAMjB;IAED,OAAO,IAAI,IAAI,CAId;CACF;AAED,MAAM,WAAW,aAAa;IAC5B,sFAAsF;IACtF,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,qBAAa,WAAW;;IACtB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAgB5B,OAAO,eASN;IAED,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,EAAE,OAAO,GAAE,aAAkB,GAAG,WAAW,CAEjF;IAED,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,YAAY,IAAI,MAAM,CAErB;IAED,eAAe,IAAI,MAAM,CAExB;IAED,yEAAyE;IACzE,gBAAgB,IAAI,MAAM,CAEzB;IAED;;;;;OAKG;IACH,OAAO,IAAI,QAAQ,CAwDlB;IAED,sFAAsF;IACtF,IAAI,IAAI,OAAO,CAEd;IAED;;;;;;;;;;;OAWG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,QAAQ,CAsB1C;IAED,oFAAoF;IACpF,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAWtC;IAED,eAAe,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAcxC;IAED,sFAAsF;IACtF,MAAM,IAAI,IAAI,CAKb;IAED,KAAK,IAAI;QACP,IAAI,EAAE,MAAM,CAAC;QACb,UAAU,EAAE,MAAM,CAAC;QACnB,WAAW,EAAE,MAAM,CAAC;QACpB,gBAAgB,EAAE,MAAM,CAAC;QACzB,YAAY,EAAE,MAAM,CAAC;KACtB,CAQA;CACF"}