@bradensbay/globals-core 0.2.0

package/README.md

@@ -0,0 +1,69 @@
+# @bradensbay/globals-core
+
+The runtime agnostic core of [Globals](https://github.com/christianGRogers/globals): one
+shared memory arena, a tagged value encoding, an allocator, and epoch based reclamation.
+
+Nothing in this package imports Electron. That is deliberate, and it is what makes the arena
+testable in plain Node with worker threads.
+
+## Contract
+
+Reads are synchronous. Writes are asynchronous. See
+[docs/contract.md](../../docs/contract.md).
+
+## Usage
+
+```ts
+import { ArenaOwner, ArenaReader } from "@bradensbay/globals-core";
+
+// In the owner, the only process that writes.
+const owner = ArenaOwner.create({ byteLength: 1 << 20 });
+owner.commit(42);
+
+// In any process that holds the same buffer.
+const reader = ArenaReader.attach(owner.buffer);
+reader.read(); // 42, synchronously
+
+// Hold a version across several reads so they cannot disagree.
+const snapshot = reader.acquire();
+snapshot.value;
+snapshot.release();
+
+reader.detach();
+```
+
+## Writing
+
+```ts
+await store.update((draft: State) => {
+  draft.users[3].name = "new name";
+});
+```
+
+Only the paths the recipe touched are rebuilt. Setting one key of an object with ten
+thousand keys allocates fewer than twenty blocks rather than copying the record. See
+[docs/object-layer.md](../../docs/object-layer.md).
+
+## Type ladder
+
+Plain objects, arrays, `Map`, `Set`, `Date`, `RegExp`, `BigInt`, typed arrays, and the
+scalars. Anything else raises `UnencodableValueError` rather than being silently coerced,
+and reaches the asynchronous tier through `ExternalTier` if it needs to be shared at all.
+
+## Errors
+
+| Error | Meaning |
+| --- | --- |
+| `StaleSnapshotError` | The version you held was reclaimed. Reacquire. |
+| `ArenaCorruptError` | A decode found something a correct writer cannot produce. |
+| `ArenaFullError` | The arena is exhausted and cannot grow. |
+| `NoReaderSlotError` | Every reader slot is claimed. |
+| `UnencodableValueError` | The value is outside the type ladder. |
+
+## Testing
+
+```bash
+npm test          # unit, property, and fail closed tests
+npm run soak      # multi process soak, the release gate for arena changes
+npm run bench     # the read latency harness
+```

package/dist/src/allocator.d.ts

@@ -0,0 +1,78 @@
+import type { SharedArena } from "./arena.js";
+/**
+ * Size class slabs above a bump region.
+ *
+ * Sizes are payload bytes, not counting the eight byte block header. They double roughly
+ * every two steps, which caps internal waste at about 25 percent while keeping the class
+ * count small enough that the lookup is a short scan rather than a division.
+ */
+export declare const SIZE_CLASSES: readonly [8, 16, 24, 32, 48, 64, 96, 128, 192, 256, 384, 512, 768, 1024, 1536, 2048, 3072, 4096];
+declare const MAX_CLASS_BYTES: number;
+declare function classForSize(bytes: number): number;
+export interface AllocatorStats {
+    readonly bumpPointer: number;
+    readonly capacityBytes: number;
+    readonly liveBytes: number;
+    readonly freeListBytes: number;
+    readonly allocations: number;
+    readonly frees: number;
+    readonly headerBytes: number;
+}
+/**
+ * The allocator runs only in the owner. That is the single biggest simplification in the
+ * design: there is exactly one writer, so no allocator structure needs a lock, and the free
+ * lists can live on the owner heap rather than in shared memory where a hostile window
+ * could corrupt them.
+ *
+ * Defend that property. Any feature that introduces a second writer costs a lock on every
+ * allocation, and the read path pays for it indirectly through longer commits.
+ */
+export declare class Allocator {
+    #private;
+    constructor(arena: SharedArena, grow?: (minimumBytes: number) => boolean);
+    /**
+     * Allocate `byteSize` payload bytes and return the payload offset. The returned block is
+     * eight byte aligned and preceded by a validated header.
+     *
+     * The contents are not zeroed. Callers write every byte they later read, and the block
+     * header check plus the record specific length field is what makes a partially written
+     * block undecodable rather than plausible.
+     */
+    allocate(byteSize: number): number;
+    /**
+     * Return a block to its free list. Blocks larger than the largest size class are dropped
+     * rather than tracked, because a mixed size free list degrades into a first fit search
+     * and this allocator is not the place to pay for that. Phase 5 measures whether real
+     * workloads produce enough of them to need compaction.
+     */
+    free(offset: number): void;
+    stats(): AllocatorStats;
+    /**
+     * Rewind the bump pointer, discarding everything allocated above it.
+     *
+     * Called after a commit that failed part way, once its blocks have been freed. Freeing
+     * alone is not enough: the blocks go back to their size classes, so an arena that a failed
+     * write filled with sixteen byte records cannot then serve a forty byte request. There is
+     * no coalescing, so those small blocks never merge into a larger one and the store is stuck
+     * until it is restarted.
+     *
+     * Rewinding is safe here and nowhere else. There is exactly one writer, a commit is
+     * synchronous, and every block above the mark belongs to the commit being abandoned, so
+     * nothing published can reference one.
+     *
+     * The free lists are purged of anything above the mark, because a stale entry there would
+     * be handed out again by the free list while the bump allocator hands out the same bytes.
+     */
+    rewindTo(bumpPointer: number): void;
+    /**
+     * Bytes consumed from the arena that are neither live nor reusable.
+     *
+     * Block headers are excluded because they are fixed overhead rather than fragmentation.
+     * What remains is the blocks that were allocated at an exact size, freed, and dropped
+     * rather than tracked. A number that climbs with time is the signal that compaction is
+     * needed, which is the phase 5 question.
+     */
+    strandedBytes(): number;
+}
+export { MAX_CLASS_BYTES, classForSize };
+//# sourceMappingURL=allocator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"allocator.d.ts","sourceRoot":"","sources":["../../src/allocator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAa9C;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,YACvB,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAC7E,CAAC;AAEX,QAAA,MAAM,eAAe,EAA4C,MAAM,CAAC;AAExE,iBAAS,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAK3C;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;GAQG;AACH,qBAAa,SAAS;;IAYpB,YAAY,KAAK,EAAE,WAAW,EAAE,IAAI,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,EAGvE;IAED;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAoBjC;IAED;;;;;OAKG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CASzB;IAED,KAAK,IAAI,cAAc,CAUtB;IAED;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAoBlC;IAED;;;;;;;OAOG;IACH,aAAa,IAAI,MAAM,CAItB;CAgEF;AAED,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,CAAC"}

package/dist/src/allocator.js

@@ -0,0 +1,211 @@
+import { ArenaFullError } from "./errors.js";
+import { BLOCK_HEADER_BYTES, BLOCK_MAGIC, BLOCK_MAGIC_SHIFT, Block, Header, SIZE_CLASS_EXACT, WORD, align, } from "./layout.js";
+/**
+ * Size class slabs above a bump region.
+ *
+ * Sizes are payload bytes, not counting the eight byte block header. They double roughly
+ * every two steps, which caps internal waste at about 25 percent while keeping the class
+ * count small enough that the lookup is a short scan rather than a division.
+ */
+export const SIZE_CLASSES = [
+    8, 16, 24, 32, 48, 64, 96, 128, 192, 256, 384, 512, 768, 1024, 1536, 2048, 3072, 4096,
+];
+const MAX_CLASS_BYTES = SIZE_CLASSES[SIZE_CLASSES.length - 1];
+function classForSize(bytes) {
+    for (let index = 0; index < SIZE_CLASSES.length; index += 1) {
+        if (bytes <= SIZE_CLASSES[index])
+            return index;
+    }
+    return SIZE_CLASS_EXACT;
+}
+/**
+ * The allocator runs only in the owner. That is the single biggest simplification in the
+ * design: there is exactly one writer, so no allocator structure needs a lock, and the free
+ * lists can live on the owner heap rather than in shared memory where a hostile window
+ * could corrupt them.
+ *
+ * Defend that property. Any feature that introduces a second writer costs a lock on every
+ * allocation, and the read path pays for it indirectly through longer commits.
+ */
+export class Allocator {
+    #arena;
+    /** One free list per size class, holding payload offsets of freed blocks. */
+    #freeLists = SIZE_CLASSES.map(() => []);
+    #liveBytes = 0;
+    #freeListBytes = 0;
+    /** Block header bytes consumed by bump allocation. Overhead, never reusable. */
+    #headerBytes = 0;
+    #allocations = 0;
+    #frees = 0;
+    #grow;
+    constructor(arena, grow) {
+        this.#arena = arena;
+        this.#grow = grow;
+    }
+    /**
+     * Allocate `byteSize` payload bytes and return the payload offset. The returned block is
+     * eight byte aligned and preceded by a validated header.
+     *
+     * The contents are not zeroed. Callers write every byte they later read, and the block
+     * header check plus the record specific length field is what makes a partially written
+     * block undecodable rather than plausible.
+     */
+    allocate(byteSize) {
+        if (byteSize <= 0)
+            throw new RangeError(`allocation size must be positive, got ${byteSize}`);
+        const sizeClass = classForSize(byteSize);
+        const blockBytes = sizeClass === SIZE_CLASS_EXACT
+            ? align(byteSize)
+            : SIZE_CLASSES[sizeClass];
+        if (sizeClass !== SIZE_CLASS_EXACT) {
+            const reused = this.#freeLists[sizeClass].pop();
+            if (reused !== undefined) {
+                this.#freeListBytes -= blockBytes;
+                this.#liveBytes += blockBytes;
+                this.#allocations += 1;
+                this.#writeBlockHeader(reused, sizeClass, blockBytes);
+                return reused;
+            }
+        }
+        return this.#bumpAllocate(blockBytes, sizeClass);
+    }
+    /**
+     * Return a block to its free list. Blocks larger than the largest size class are dropped
+     * rather than tracked, because a mixed size free list degrades into a first fit search
+     * and this allocator is not the place to pay for that. Phase 5 measures whether real
+     * workloads produce enough of them to need compaction.
+     */
+    free(offset) {
+        const byteSize = this.#arena.checkBlock(offset, "free");
+        const sizeClass = this.#arena.blockSizeClass(offset);
+        this.#liveBytes -= byteSize;
+        this.#frees += 1;
+        if (sizeClass === SIZE_CLASS_EXACT)
+            return;
+        this.#freeLists[sizeClass].push(offset);
+        this.#freeListBytes += byteSize;
+    }
+    stats() {
+        return {
+            bumpPointer: this.#arena.loadHeader(Header.BumpPointer),
+            capacityBytes: this.#arena.byteLength,
+            liveBytes: this.#liveBytes,
+            freeListBytes: this.#freeListBytes,
+            allocations: this.#allocations,
+            frees: this.#frees,
+            headerBytes: this.#headerBytes,
+        };
+    }
+    /**
+     * Rewind the bump pointer, discarding everything allocated above it.
+     *
+     * Called after a commit that failed part way, once its blocks have been freed. Freeing
+     * alone is not enough: the blocks go back to their size classes, so an arena that a failed
+     * write filled with sixteen byte records cannot then serve a forty byte request. There is
+     * no coalescing, so those small blocks never merge into a larger one and the store is stuck
+     * until it is restarted.
+     *
+     * Rewinding is safe here and nowhere else. There is exactly one writer, a commit is
+     * synchronous, and every block above the mark belongs to the commit being abandoned, so
+     * nothing published can reference one.
+     *
+     * The free lists are purged of anything above the mark, because a stale entry there would
+     * be handed out again by the free list while the bump allocator hands out the same bytes.
+     */
+    rewindTo(bumpPointer) {
+        const arena = this.#arena;
+        if (bumpPointer >= arena.loadHeader(Header.BumpPointer))
+            return;
+        for (let index = 0; index < this.#freeLists.length; index += 1) {
+            const list = this.#freeLists[index];
+            const kept = [];
+            for (const offset of list) {
+                if (offset - BLOCK_HEADER_BYTES >= bumpPointer) {
+                    this.#freeListBytes -= SIZE_CLASSES[index];
+                    // The block header above the mark goes away with the rewind.
+                    this.#headerBytes -= BLOCK_HEADER_BYTES;
+                    continue;
+                }
+                kept.push(offset);
+            }
+            this.#freeLists[index] = kept;
+        }
+        arena.storeHeader(Header.BumpPointer, bumpPointer);
+    }
+    /**
+     * Bytes consumed from the arena that are neither live nor reusable.
+     *
+     * Block headers are excluded because they are fixed overhead rather than fragmentation.
+     * What remains is the blocks that were allocated at an exact size, freed, and dropped
+     * rather than tracked. A number that climbs with time is the signal that compaction is
+     * needed, which is the phase 5 question.
+     */
+    strandedBytes() {
+        const bump = this.#arena.loadHeader(Header.BumpPointer);
+        const used = bump - this.#arena.geometry.arenaOffset;
+        return used - this.#liveBytes - this.#freeListBytes - this.#headerBytes;
+    }
+    #bumpAllocate(blockBytes, sizeClass) {
+        const arena = this.#arena;
+        const bump = arena.loadHeader(Header.BumpPointer);
+        const payloadOffset = bump + BLOCK_HEADER_BYTES;
+        const nextBump = payloadOffset + blockBytes;
+        if (nextBump > arena.byteLength) {
+            const needed = nextBump - arena.byteLength;
+            if (!this.#grow?.(needed)) {
+                // Out of fresh arena. Before giving up, take a block from a larger size class. It
+                // wastes the difference, and wasting some memory beats refusing a write when there is
+                // memory sitting on a list one class up.
+                //
+                // This runs only under exhaustion, so the common path is unchanged. Without it, a
+                // rejected write that freed a thousand forty eight byte blocks could not be followed
+                // by a write that needed sixteen, which makes one bad write brick the store.
+                const scavenged = this.#scavenge(sizeClass);
+                if (scavenged !== undefined)
+                    return scavenged;
+                throw new ArenaFullError(blockBytes + BLOCK_HEADER_BYTES, arena.byteLength);
+            }
+            // Growth succeeded, so the bump pointer is still valid and the buffer is longer.
+            // Views do not track growth on their own, so pick up the longer one before retrying.
+            arena.refresh();
+            return this.#bumpAllocate(blockBytes, sizeClass);
+        }
+        arena.storeHeader(Header.BumpPointer, nextBump);
+        this.#headerBytes += BLOCK_HEADER_BYTES;
+        arena.storeHeader(Header.CapacityBytes, arena.byteLength);
+        this.#writeBlockHeader(payloadOffset, sizeClass, blockBytes);
+        this.#liveBytes += blockBytes;
+        this.#allocations += 1;
+        return payloadOffset;
+    }
+    /**
+     * Take a block from a larger size class.
+     *
+     * The block keeps its own header, so freeing it later returns it to the list it came from
+     * rather than to the smaller one it was lent to. The difference between the request and the
+     * block is wasted until then, which is why this is a last resort rather than a policy.
+     */
+    #scavenge(sizeClass) {
+        if (sizeClass === SIZE_CLASS_EXACT)
+            return undefined;
+        for (let index = sizeClass; index < SIZE_CLASSES.length; index += 1) {
+            const offset = this.#freeLists[index].pop();
+            if (offset === undefined)
+                continue;
+            const classBytes = SIZE_CLASSES[index];
+            this.#freeListBytes -= classBytes;
+            this.#liveBytes += classBytes;
+            this.#allocations += 1;
+            return offset;
+        }
+        return undefined;
+    }
+    #writeBlockHeader(payloadOffset, sizeClass, blockBytes) {
+        const words = this.#arena.words;
+        const base = payloadOffset / WORD;
+        words[base + Block.Header] = (BLOCK_MAGIC << BLOCK_MAGIC_SHIFT) | (sizeClass & 0xff);
+        words[base + Block.ByteSize] = blockBytes;
+    }
+}
+export { MAX_CLASS_BYTES, classForSize };
+//# sourceMappingURL=allocator.js.map

package/dist/src/allocator.js.map

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

package/dist/src/arena.d.ts

@@ -0,0 +1,81 @@
+import { type ArenaGeometry } from "./layout.js";
+/**
+ * A typed view over one shared buffer, plus the bounds checks that make every dereference
+ * provably in range.
+ *
+ * Both the owner and every reader hold one of these. It carries no writer state, so it is
+ * safe to construct in a process that must never mutate the arena.
+ */
+export declare class SharedArena {
+    #private;
+    readonly buffer: SharedArrayBuffer;
+    readonly geometry: ArenaGeometry;
+    private constructor();
+    /**
+     * Attach to a buffer an owner has already formatted. Validates the magic, the layout
+     * version, and the configuration checksum, so a reader never starts decoding a buffer it
+     * does not understand.
+     */
+    static attach(buffer: SharedArrayBuffer): SharedArena;
+    /** Format a fresh buffer. Only the owner calls this. */
+    static format(buffer: SharedArrayBuffer, options: {
+        maxReaders: number;
+        retainedCapacity: number;
+        flags: number;
+    }): SharedArena;
+    /**
+     * The cached views.
+     *
+     * These do not probe the buffer for growth. Probing here was measurably the most
+     * expensive thing on the read path: reading `byteLength` from a growable
+     * SharedArrayBuffer is not an inlined field load, and a single bounds checked decode
+     * touches these accessors half a dozen times.
+     *
+     * Growth is picked up by `refresh()` instead, which callers invoke at the one point
+     * where a longer view can matter: acquiring a version newer than the one they last saw.
+     * Anything a reader decodes through a pinned version was allocated before that version
+     * was published, so it is inside the view the reader had when it acquired.
+     */
+    get words(): Int32Array;
+    get floats(): Float64Array;
+    get units(): Uint16Array;
+    get bytes(): Uint8Array;
+    get byteLength(): number;
+    /**
+     * Header accessors read the cached view directly rather than going through the growth
+     * check in `words`.
+     *
+     * That is safe because the header sits at offset zero and its size is fixed, so it is
+     * inside every view this arena has ever had, including one made before a grow(). It is
+     * also worth doing: a read touches the header eight times, and routing each of those
+     * through a SharedArrayBuffer byteLength getter on a growable buffer cost more than the
+     * rest of the read path put together.
+     */
+    loadHeader(field: number): number;
+    storeHeader(field: number, value: number): void;
+    addHeader(field: number, delta: number): number;
+    /**
+     * Pick up a growth that another process performed. Callers that are about to read arena
+     * payload, rather than only the header, call this once rather than paying for the check
+     * on every access.
+     */
+    refresh(): void;
+    /** Bumped when a new owner adopts the buffer. A reader uses it to fail closed. */
+    get ownerGeneration(): number;
+    writeConfigChecksum(): void;
+    verifyConfigChecksum(): void;
+    /**
+     * Prove that `byteCount` bytes at `offset` lie inside the arena region and are aligned.
+     * Called before every dereference. A failure means the arena was written by something
+     * that is not a correct writer.
+     */
+    checkRange(offset: number, byteCount: number, what: string): void;
+    /**
+     * Validate the two word header preceding every allocation and return its payload size.
+     * This is the check that turns a wild offset into a typed error rather than a plausible
+     * looking value.
+     */
+    checkBlock(offset: number, what: string): number;
+    blockSizeClass(offset: number): number;
+}
+//# sourceMappingURL=arena.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"arena.d.ts","sourceRoot":"","sources":["../../src/arena.ts"],"names":[],"mappings":"AACA,OAAO,EAaL,KAAK,aAAa,EACnB,MAAM,aAAa,CAAC;AAGrB;;;;;;GAMG;AACH,qBAAa,WAAW;;IACtB,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IAQjC,OAAO,eAQN;IAED;;;;OAIG;IACH,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,GAAG,WAAW,CA4BpD;IAED,wDAAwD;IACxD,MAAM,CAAC,MAAM,CACX,MAAM,EAAE,iBAAiB,EACzB,OAAO,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,gBAAgB,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GACvE,WAAW,CAyBb;IAED;;;;;;;;;;;;OAYG;IACH,IAAI,KAAK,IAAI,UAAU,CAEtB;IAED,IAAI,MAAM,IAAI,YAAY,CAEzB;IAED,IAAI,KAAK,IAAI,WAAW,CAEvB;IAED,IAAI,KAAK,IAAI,UAAU,CAEtB;IAED,IAAI,UAAU,IAAI,MAAM,CAEvB;IAWD;;;;;;;;;OASG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhC;IAED,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAE9C;IAED,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAE9C;IAED;;;;OAIG;IACH,OAAO,IAAI,IAAI,CAEd;IAED,kFAAkF;IAClF,IAAI,eAAe,IAAI,MAAM,CAE5B;IAED,mBAAmB,IAAI,IAAI,CAG1B;IAED,oBAAoB,IAAI,IAAI,CAU3B;IAWD;;;;OAIG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAiBhE;IAED;;;;OAIG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAsB/C;IAED,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAGrC;CACF"}