@woosh/meep-engine 2.121.13 → 2.122.1

package/package.json

@@ -5,7 +5,7 @@
   "description": "Fully featured ECS game engine written in JavaScript",
   "type": "module",
   "author": "Alexander Goldring",
-  "version": "2.121.13",
+  "version": "2.122.1",
   "main": "build/meep.module.js",
   "module": "build/meep.module.js",
   "exports": {

package/src/core/binary/allocator/OffsetAllocator.d.ts

@@ -0,0 +1,113 @@
+export const ALLOCATOR_NO_SPACE: 4294967295;
+/**
+ * Fast hard realtime O(1) offset allocator with minimal fragmentation.
+ *
+ * Uses 256 bins with 8 bit floating point distribution (3 bit mantissa + 5 bit exponent) and a two level bitfield to find the next available bin using 2x LZCNT instructions to make all operations O(1). Bin sizes following the floating point distribution ensures hard bounds for memory overhead percentage regardless of size class. Pow2 bins would waste up to +100% memory (+50% on average). Our float bins waste up to +12.5% (+6.25% on average).
+ *
+ * The allocation metadata is stored in a separate data structure, making this allocator suitable for sub-allocating any resources, such as GPU heaps, buffers and arrays. Returns an offset to the first element of the allocated contiguous range.
+ *
+ * @see "A comparison of memory allocators for real-time applications" by Miguel Masmano et al
+ * @example
+ *      const allocator = new Allocator(12345);     // Allocator with 12345 contiguous elements in total
+ *
+ *      const a = allocator.allocate(1337);         // Allocate a 1337 element contiguous range
+ *      const offset_a = a.offset;                  // Provides offset to the first element of the range
+ *      do_something(offset_a);
+ *
+ *      const b = allocator.allocate(123);          // Allocate a 123 element contiguous range
+ *      const offset_b = b.offset;                  // Provides offset to the first element of the range
+ *      do_something(offset_b);
+ *
+ *      allocator.free(a);                          // Free allocation a
+ *      allocator.free(b);                          // Free allocation b
+ */
+export class OffsetAllocator {
+    /**
+     *
+     * @param {number} size
+     * @param {number} maxAllocs
+     */
+    constructor(size: number, maxAllocs?: number);
+    /**
+     * Total managed space
+     * uint32
+     * @type {number}
+     */
+    size: number;
+    /**
+     * Limit on number of allocations
+     * uint32
+     * @type {number}
+     */
+    maxAllocs: number;
+    /**
+     * uint32
+     * @type {number}
+     */
+    freeStorage: number;
+    /**
+     * uint32
+     * @type {number}
+     */
+    usedBinsTop: number;
+    /**
+     *
+     * @type {Uint8Array}
+     */
+    usedBins: Uint8Array;
+    /**
+     *
+     * @type {Uint32Array}
+     */
+    binIndices: Uint32Array;
+    /**
+     *
+     * @type {RowFirstTable}
+     */
+    nodes: RowFirstTable;
+    /**
+     * @type {Uint32Array}
+     */
+    freeNodes: Uint32Array;
+    /**
+     * uint32
+     * @type {number}
+     */
+    freeOffset: number;
+    /**
+     *
+     * @param {number} size
+     * @returns {Allocation}
+     */
+    allocate(size: number): Allocation;
+    /**
+     *
+     * @param {Allocation} allocation
+     */
+    free(allocation: Allocation): void;
+    reset(): void;
+    /**
+     * Useful for debug and UI
+     * @return {StorageReport}
+     */
+    storageReport(): StorageReport;
+    #private;
+}
+import { RowFirstTable } from "../../collection/table/RowFirstTable.js";
+declare class Allocation {
+    /**
+     *
+     * @param {number} offset
+     * @param {number} metadata
+     * @return {Allocation}
+     */
+    static from(offset: number, metadata: number): Allocation;
+    offset: number;
+    metadata: number;
+}
+declare class StorageReport {
+    totalFreeSpace: number;
+    largestFreeRegion: number;
+}
+export {};
+//# sourceMappingURL=OffsetAllocator.d.ts.map

package/src/core/binary/allocator/OffsetAllocator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OffsetAllocator.d.ts","sourceRoot":"","sources":["../../../../../src/core/binary/allocator/OffsetAllocator.js"],"names":[],"mappings":"AAaA,iCAAkC,UAAU,CAAC;AAmF7C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IAwDI;;;;OAIG;IACH,kBAHW,MAAM,cACN,MAAM,EAYhB;IAtED;;;;OAIG;IACH,MAFU,MAAM,CAEP;IAET;;;;OAIG;IACH,WAFU,MAAM,CAEF;IAEd;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,UAFU,UAAU,CAEoB;IAExC;;;OAGG;IACH,YAFU,WAAW,CAEuB;IAE5C;;;OAGG;IACH,OAFU,aAAa,CAEmB;IAE1C;;OAEG;IACH,WAFU,WAAW,CAEX;IAEV;;;OAGG;IACH,YAFU,MAAM,CAED;IAmBf;;;;OAIG;IACH,eAHW,MAAM,GACJ,UAAU,CAkGtB;IAED;;;OAGG;IACH,iBAFW,UAAU,QAsFpB;IAqID,cA4BC;IAED;;;OAGG;IACH,iBAFY,aAAa,CA2BxB;;CACJ;8BA9jB6B,yCAAyC;AAgDvE;IAII;;;;;OAKG;IACH,oBAJW,MAAM,YACN,MAAM,GACL,UAAU,CASrB;IAhBD,eAA4B;IAC5B,iBAA8B;CAgBjC;AAoBD;IACI,uBAAkB;IAClB,0BAAqB;CACxB"}

package/src/core/binary/allocator/OffsetAllocator.js

@@ -0,0 +1,576 @@
+import { assert } from "../../assert.js";
+import { RowFirstTable } from "../../collection/table/RowFirstTable.js";
+import { RowFirstTableSpec } from "../../collection/table/RowFirstTableSpec.js";
+import { ctz32 } from "../ctz32.js";
+import { floatToUint, uintToFloatRoundDown, uintToFloatRoundUp } from "../float/SmallFloat.js";
+import { msb_32 } from "../msb_32.js";
+import { BinaryDataType } from "../type/BinaryDataType.js";
+
+const NUM_TOP_BINS = 32;
+const BINS_PER_LEAF = 8;
+const TOP_BINS_INDEX_SHIFT = 3;
+const LEAF_BINS_INDEX_MASK = 0x7;
+const NUM_LEAF_BINS = NUM_TOP_BINS * BINS_PER_LEAF;
+export const ALLOCATOR_NO_SPACE = 0xffffffff;
+const NODE_UNUSED = 0xffffffff
+
+/**
+ * Can potentially use u16, but number of allocation slots will be limited to 65k, so a severe limitation for little gain
+ * @type {BinaryDataType}
+ */
+const NODE_INDEX_DATA_TYPE = BinaryDataType.Uint32;
+
+const DEBUG_VERBOSE = false;
+
+/**
+ * @see https://github.com/sebbbi/OffsetAllocator/blob/3610a7377088b1e8c8f1525f458c96038a4e6fc0/offsetAllocator.hpp#L70
+ * @type {RowFirstTableSpec}
+ */
+const NODE_TABLE_SPEC = RowFirstTableSpec.get([
+    BinaryDataType.Uint32, // Data Offset
+    BinaryDataType.Uint32, // Data Size
+    NODE_INDEX_DATA_TYPE, // Bin List Prev
+    NODE_INDEX_DATA_TYPE, // Bin List Next
+    NODE_INDEX_DATA_TYPE, // Neighbour Prev
+    NODE_INDEX_DATA_TYPE, // Neighbour Next
+    BinaryDataType.Uint8, // FLAGS
+]);
+
+const NODE_FLAGS_USED = 1;
+
+
+const NODE_FIELD_DATA_OFFSET = 0;
+const NODE_FIELD_DATA_SIZE = 1;
+const NODE_FIELD_BIN_LIST_PREV = 2;
+const NODE_FIELD_BIN_LIST_NEXT = 3;
+const NODE_FIELD_NEIGHBOR_PREV = 4;
+const NODE_FIELD_NEIGHBOR_NEXT = 5;
+const NODE_FIELD_FLAGS = 6;
+
+class Allocation {
+    offset = ALLOCATOR_NO_SPACE;
+    metadata = ALLOCATOR_NO_SPACE;
+
+    /**
+     *
+     * @param {number} offset
+     * @param {number} metadata
+     * @return {Allocation}
+     */
+    static from(offset, metadata) {
+        const r = new Allocation();
+
+        r.offset = offset;
+        r.metadata = metadata;
+
+        return r;
+    }
+}
+
+/**
+ *
+ * @param {number} bitMask
+ * @param {number} startBitIndex
+ * @return {number}
+ */
+function findLowestSetBitAfter(bitMask, startBitIndex) {
+    const maskBeforeStartIndex = (1 << startBitIndex) - 1;
+    const maskAfterStartIndex = ~maskBeforeStartIndex;
+    const bitsAfter = bitMask & maskAfterStartIndex;
+
+    if (bitsAfter === 0) {
+        return ALLOCATOR_NO_SPACE;
+    }
+
+    return ctz32(bitsAfter);
+}
+
+class StorageReport {
+    totalFreeSpace = 0
+    largestFreeRegion = 0
+}
+
+/*
+Largely a port of https://github.com/sebbbi/OffsetAllocator by "Sebastian Aaltonen"
+ */
+
+/**
+ * Fast hard realtime O(1) offset allocator with minimal fragmentation.
+ *
+ * Uses 256 bins with 8 bit floating point distribution (3 bit mantissa + 5 bit exponent) and a two level bitfield to find the next available bin using 2x LZCNT instructions to make all operations O(1). Bin sizes following the floating point distribution ensures hard bounds for memory overhead percentage regardless of size class. Pow2 bins would waste up to +100% memory (+50% on average). Our float bins waste up to +12.5% (+6.25% on average).
+ *
+ * The allocation metadata is stored in a separate data structure, making this allocator suitable for sub-allocating any resources, such as GPU heaps, buffers and arrays. Returns an offset to the first element of the allocated contiguous range.
+ *
+ * @see "A comparison of memory allocators for real-time applications" by Miguel Masmano et al
+ * @example
+ *      const allocator = new Allocator(12345);     // Allocator with 12345 contiguous elements in total
+ *
+ *      const a = allocator.allocate(1337);         // Allocate a 1337 element contiguous range
+ *      const offset_a = a.offset;                  // Provides offset to the first element of the range
+ *      do_something(offset_a);
+ *
+ *      const b = allocator.allocate(123);          // Allocate a 123 element contiguous range
+ *      const offset_b = b.offset;                  // Provides offset to the first element of the range
+ *      do_something(offset_b);
+ *
+ *      allocator.free(a);                          // Free allocation a
+ *      allocator.free(b);                          // Free allocation b
+ */
+export class OffsetAllocator {
+    /**
+     * Total managed space
+     * uint32
+     * @type {number}
+     */
+    size = 0;
+
+    /**
+     * Limit on number of allocations
+     * uint32
+     * @type {number}
+     */
+    maxAllocs = 0;
+
+    /**
+     * uint32
+     * @type {number}
+     */
+    freeStorage = 0;
+
+    /**
+     * uint32
+     * @type {number}
+     */
+    usedBinsTop = 0;
+
+    /**
+     *
+     * @type {Uint8Array}
+     */
+    usedBins = new Uint8Array(NUM_TOP_BINS);
+
+    /**
+     *
+     * @type {Uint32Array}
+     */
+    binIndices = new Uint32Array(NUM_LEAF_BINS);
+
+    /**
+     *
+     * @type {RowFirstTable}
+     */
+    nodes = new RowFirstTable(NODE_TABLE_SPEC)
+
+    /**
+     * @type {Uint32Array}
+     */
+    freeNodes;
+
+    /**
+     * uint32
+     * @type {number}
+     */
+    freeOffset = 0;
+
+    /**
+     *
+     * @param {number} size
+     * @param {number} maxAllocs
+     */
+    constructor(size, maxAllocs = 128 * 1024) {
+        assert.isNonNegativeInteger(size, 'size');
+        assert.isNonNegativeInteger(maxAllocs, 'maxAllocs');
+
+        this.size = size;
+        this.maxAllocs = maxAllocs;
+
+        this.freeNodes = new Uint32Array(this.maxAllocs);
+
+        this.reset();
+    }
+
+    /**
+     *
+     * @param {number} size
+     * @returns {Allocation}
+     */
+    allocate(size) {
+        assert.isNonNegativeInteger(size, 'size');
+
+        // Out of allocations?
+        if (this.freeOffset === 0) {
+            return Allocation.from(ALLOCATOR_NO_SPACE, ALLOCATOR_NO_SPACE);
+        }
+
+        // Round up to bin index to ensure that alloc >= bin
+        // Gives us min bin index that fits the size
+        let minBinIndex = uintToFloatRoundUp(size);
+
+        const minTopBinIndex = minBinIndex >>> TOP_BINS_INDEX_SHIFT;
+        const minLeafBinIndex = minBinIndex & LEAF_BINS_INDEX_MASK;
+
+        let topBinIndex = minTopBinIndex;
+        let leafBinIndex = ALLOCATOR_NO_SPACE;
+
+        // If top bin exists, scan its leaf bin. This can fail (NO_SPACE).
+        if ((this.usedBinsTop & (1 << topBinIndex)) !== 0) {
+            leafBinIndex = findLowestSetBitAfter(this.usedBins[topBinIndex], minLeafBinIndex);
+        }
+
+        // If we didn't find space in top bin, we search top bin from +1
+        if (leafBinIndex === ALLOCATOR_NO_SPACE) {
+            topBinIndex = findLowestSetBitAfter(this.usedBinsTop, minTopBinIndex + 1);
+
+            // Out of space?
+            if (topBinIndex === ALLOCATOR_NO_SPACE) {
+                return Allocation.from(ALLOCATOR_NO_SPACE, ALLOCATOR_NO_SPACE);
+            }
+
+            // All leaf bins here fit the alloc, since the top bin was rounded up. Start leaf search from bit 0.
+            // NOTE: This search can't fail since at least one leaf bit was set because the top bit was set.
+            leafBinIndex = ctz32(this.usedBins[topBinIndex]);
+        }
+
+        let bin_index = ((topBinIndex << TOP_BINS_INDEX_SHIFT) | leafBinIndex) >>> 0; // ">>> 0" shift is to force UINT32
+
+        // Pop the top node of the bin. Bin top = node.next.
+        let node_index = this.binIndices[bin_index];
+
+        const nodes = this.nodes;
+
+        const nodeTotalSize = nodes.readCellValue(node_index, NODE_FIELD_DATA_SIZE);
+        nodes.writeCellValue(node_index, NODE_FIELD_DATA_SIZE, size);
+        nodes.writeCellValue(node_index, NODE_FIELD_FLAGS, NODE_FLAGS_USED); //mark as USED
+
+        const node_bin_list_next = nodes.readCellValue(node_index, NODE_FIELD_BIN_LIST_NEXT);
+        this.binIndices[bin_index] = node_bin_list_next;
+
+        if (node_bin_list_next !== NODE_UNUSED) {
+            nodes.writeCellValue(node_bin_list_next, NODE_FIELD_BIN_LIST_PREV, NODE_UNUSED);
+        }
+
+        this.freeStorage -= nodeTotalSize;
+
+        if (DEBUG_VERBOSE) {
+            console.log(`Free storage: ${this.freeStorage} (-${nodeTotalSize}) (allocate)`);
+        }
+
+        // Bin empty?
+        if (this.binIndices[bin_index] === NODE_UNUSED) {
+            // Remove a leaf bin mask bit
+            this.usedBins[topBinIndex] &= ~(1 << leafBinIndex);
+
+            // All leaf bins empty?
+            if (this.usedBins[topBinIndex] === 0) {
+                // Remove a top bin mask bit
+                this.usedBinsTop &= ~(1 << topBinIndex);
+            }
+        }
+
+        // Push back reminder N elements to a lower bin
+        const reminderSize = nodeTotalSize - size;
+
+        const node_data_offset = nodes.readCellValue(node_index, NODE_FIELD_DATA_OFFSET);
+
+        if (reminderSize > 0) {
+            const new_node_index = this.#insertNodeIntoBin(reminderSize, node_data_offset + size);
+
+            const node_neighbor_next = nodes.readCellValue(node_index, NODE_FIELD_NEIGHBOR_NEXT);
+
+            // Link nodes next to each other so that we can merge them later if both are free
+            // And update the old next neighbor to point to the new node (in middle)
+            if (node_neighbor_next !== NODE_UNUSED) {
+                nodes.writeCellValue(node_neighbor_next, NODE_FIELD_NEIGHBOR_PREV, new_node_index);
+            }
+            nodes.writeCellValue(new_node_index, NODE_FIELD_NEIGHBOR_PREV, node_index);
+            nodes.writeCellValue(new_node_index, NODE_FIELD_NEIGHBOR_NEXT, node_neighbor_next);
+
+            nodes.writeCellValue(node_index, NODE_FIELD_NEIGHBOR_NEXT, new_node_index);
+        }
+
+
+        return Allocation.from(node_data_offset, node_index);
+    }
+
+    /**
+     *
+     * @param {Allocation} allocation
+     */
+    free(allocation) {
+        assert.notEqual(allocation.metadata, ALLOCATOR_NO_SPACE, 'Invalid allocation');
+        // if (!m_nodes) return;
+
+        const node_index = allocation.metadata;
+
+        const nodes = this.nodes;
+        const node_flags = nodes.readCellValue(node_index, NODE_FIELD_FLAGS);
+
+        // Double delete check
+        assert.notEqual(node_flags & NODE_FLAGS_USED, 0, 'Node is not in use');
+
+        // Merge with neighbors...
+        let offset = nodes.readCellValue(node_index, NODE_FIELD_DATA_OFFSET)
+        let size = nodes.readCellValue(node_index, NODE_FIELD_DATA_SIZE);
+
+        const node_neighbour_prev = nodes.readCellValue(node_index, NODE_FIELD_NEIGHBOR_PREV);
+
+        if (
+            (node_neighbour_prev !== NODE_UNUSED)
+            && ((nodes.readCellValue(node_neighbour_prev, NODE_FIELD_FLAGS) & NODE_FLAGS_USED) === 0) // not used
+        ) {
+            // Previous (contiguous) free node: Change offset to previous node offset. Sum sizes
+
+            const previous_offset = nodes.readCellValue(node_neighbour_prev, NODE_FIELD_DATA_OFFSET);
+            const previous_size = nodes.readCellValue(node_neighbour_prev, NODE_FIELD_DATA_SIZE);
+
+            offset = previous_offset;
+            size += previous_size;
+
+            // Remove node from the bin linked list and put it in the freelist
+            this.#removeNodeFromBin(node_neighbour_prev);
+
+            assert.equal(nodes.readCellValue(node_neighbour_prev, NODE_FIELD_NEIGHBOR_NEXT), node_index);
+
+            nodes.writeCellValue(
+                node_index, NODE_FIELD_NEIGHBOR_PREV,
+                nodes.readCellValue(node_neighbour_prev, NODE_FIELD_NEIGHBOR_PREV)
+            );
+        }
+
+        const node_neighbour_next = nodes.readCellValue(node_index, NODE_FIELD_NEIGHBOR_NEXT);
+
+        if (
+            (node_neighbour_next !== NODE_UNUSED)
+            && ((nodes.readCellValue(node_neighbour_next, NODE_FIELD_FLAGS) & NODE_FLAGS_USED) === 0) // not used
+        ) {
+            // Next (contiguous) free node: Offset remains the same. Sum sizes.
+
+            size += nodes.readCellValue(node_neighbour_next, NODE_FIELD_DATA_SIZE);
+
+            // Remove node from the bin linked list and put it in the freelist
+            this.#removeNodeFromBin(node_neighbour_next);
+
+            assert.equal(nodes.readCellValue(node_neighbour_next, NODE_FIELD_NEIGHBOR_PREV), node_index);
+
+            nodes.writeCellValue(
+                node_index, NODE_FIELD_NEIGHBOR_NEXT,
+                nodes.readCellValue(node_neighbour_next, NODE_FIELD_NEIGHBOR_NEXT)
+            );
+        }
+
+        const neighborNext = nodes.readCellValue(node_index, NODE_FIELD_NEIGHBOR_NEXT);
+        const neighborPrev = nodes.readCellValue(node_index, NODE_FIELD_NEIGHBOR_PREV);
+
+        // Insert the removed node to freelist
+        if (DEBUG_VERBOSE) {
+            console.log(`Putting node ${node_index} into freelist[${this.freeOffset + 1}] (free)`);
+        }
+
+        this.freeNodes[++this.freeOffset] = node_index;
+
+        // Insert the (combined) free node to bin
+        const combinedNodeIndex = this.#insertNodeIntoBin(size, offset);
+
+        // Connect neighbors with the new combined node
+        if (neighborNext !== NODE_UNUSED) {
+            nodes.writeCellValue(combinedNodeIndex, NODE_FIELD_NEIGHBOR_NEXT, neighborNext);
+            nodes.writeCellValue(neighborNext, NODE_FIELD_NEIGHBOR_PREV, combinedNodeIndex);
+        }
+        if (neighborPrev !== NODE_UNUSED) {
+            nodes.writeCellValue(combinedNodeIndex, NODE_FIELD_NEIGHBOR_PREV, neighborPrev);
+            nodes.writeCellValue(neighborPrev, NODE_FIELD_NEIGHBOR_NEXT, combinedNodeIndex);
+        }
+    }
+
+    /**
+     *
+     * @param {number} size
+     * @param {number} data_offset
+     * @returns {number}
+     */
+    #insertNodeIntoBin(size, data_offset) {
+        assert.isNonNegativeInteger(size, 'size');
+        assert.isNonNegativeInteger(data_offset, 'size');
+
+        // Round down to bin index to ensure that bin >= alloc
+        const bin_index = uintToFloatRoundDown(size);
+
+        const top_bin_index = bin_index >>> TOP_BINS_INDEX_SHIFT;
+        const leafBinIndex = bin_index & LEAF_BINS_INDEX_MASK;
+
+        // Bin was empty before?
+        if (this.binIndices[bin_index] === NODE_UNUSED) {
+            // Set bin mask bits
+            this.usedBins[top_bin_index] |= 1 << leafBinIndex;
+            this.usedBinsTop |= 1 << top_bin_index;
+        }
+
+        // Take a freelist node and insert on top of the bin linked list (next = old top)
+        const top_node_index = this.binIndices[bin_index];
+        const node_index = this.freeNodes[this.freeOffset--];
+
+        if (DEBUG_VERBOSE) {
+            console.log(`Getting node ${node_index} from freelist[${this.freeOffset + 1}]`);
+        }
+
+        const nodes = this.nodes;
+
+        // initialize node
+
+        nodes.writeCellValue(node_index, NODE_FIELD_DATA_OFFSET, data_offset);
+        nodes.writeCellValue(node_index, NODE_FIELD_DATA_SIZE, size);
+
+        nodes.writeCellValue(node_index, NODE_FIELD_BIN_LIST_PREV, NODE_UNUSED);
+        nodes.writeCellValue(node_index, NODE_FIELD_BIN_LIST_NEXT, top_node_index);
+
+        nodes.writeCellValue(node_index, NODE_FIELD_NEIGHBOR_PREV, NODE_UNUSED);
+        nodes.writeCellValue(node_index, NODE_FIELD_NEIGHBOR_NEXT, NODE_UNUSED);
+
+        nodes.writeCellValue(node_index, NODE_FIELD_FLAGS, 0);
+
+        if (top_node_index !== NODE_UNUSED) {
+            nodes.writeCellValue(top_node_index, NODE_FIELD_BIN_LIST_PREV, node_index);
+        }
+
+        this.binIndices[bin_index] = node_index;
+
+        this.freeStorage += size;
+
+        if (DEBUG_VERBOSE) {
+            console.log(`Free storage: ${this.freeStorage} (+${size}) (insertNodeIntoBin)`);
+        }
+
+        return node_index;
+    }
+
+    /**
+     *
+     * @param {number} node_index
+     */
+    #removeNodeFromBin(node_index) {
+        assert.isNonNegativeInteger(node_index, 'node_index');
+
+        const nodes = this.nodes;
+        const node_bin_list_prev = nodes.readCellValue(node_index, NODE_FIELD_BIN_LIST_PREV);
+        if (node_bin_list_prev !== NODE_UNUSED) {
+            // Easy case: We have previous node. Just remove this node from the middle of the list.
+            const node_bin_list_next = nodes.readCellValue(node_index, NODE_FIELD_BIN_LIST_NEXT);
+            nodes.writeCellValue(
+                node_bin_list_prev, NODE_FIELD_BIN_LIST_NEXT,
+                node_bin_list_next
+            );
+
+            if (node_bin_list_next !== NODE_UNUSED) {
+                nodes.writeCellValue(
+                    node_bin_list_next, NODE_FIELD_BIN_LIST_PREV,
+                    node_bin_list_prev
+                )
+            }
+        } else {
+            // Hard case: We are the first node in a bin. Find the bin.
+
+            // Round down to bin index to ensure that bin >= alloc
+            const node_data_size = nodes.readCellValue(node_index, NODE_FIELD_DATA_SIZE);
+            const binIndex = uintToFloatRoundDown(node_data_size);
+
+            const topBinIndex = binIndex >> TOP_BINS_INDEX_SHIFT;
+            const leafBinIndex = binIndex & LEAF_BINS_INDEX_MASK;
+
+            const node_bin_list_next = nodes.readCellValue(node_index, NODE_FIELD_BIN_LIST_NEXT);
+            this.binIndices[binIndex] = node_bin_list_next;
+            if (node_bin_list_next !== NODE_UNUSED) {
+                nodes.writeCellValue(
+                    node_bin_list_next, NODE_FIELD_BIN_LIST_PREV,
+                    NODE_UNUSED
+                );
+            }
+
+            // Bin empty?
+            if (this.binIndices[binIndex] === NODE_UNUSED) {
+                // Remove a leaf bin mask bit
+                this.usedBins[topBinIndex] &= ~(1 << leafBinIndex);
+
+                // All leaf bins empty?
+                if (this.usedBins[topBinIndex] === 0) {
+                    // Remove a top bin mask bit
+                    this.usedBinsTop &= ~(1 << topBinIndex);
+                }
+            }
+        }
+
+        // Insert the node to freelist
+        if (DEBUG_VERBOSE) {
+            console.log(`Putting node ${node_index} into freelist[${this.freeOffset + 1}] (removeNodeFromBin)`);
+        }
+
+        this.freeNodes[++this.freeOffset] = node_index;
+
+        const node_data_size = nodes.readCellValue(node_index, NODE_FIELD_DATA_SIZE);
+        this.freeStorage -= node_data_size;
+
+        if (DEBUG_VERBOSE) {
+            console.log(`Free storage: ${this.freeStorage} (-${node_data_size}) (removeNodeFromBin)`);
+        }
+    }
+
+    reset() {
+        this.freeStorage = 0;
+        this.usedBinsTop = 0;
+
+        const maxAllocs = this.maxAllocs;
+
+        this.freeOffset = maxAllocs - 1;
+
+        for (let i = 0; i < NUM_TOP_BINS; i++) {
+            this.usedBins[i] = 0;
+        }
+        for (let i = 0; i < NUM_LEAF_BINS; i++) {
+            this.binIndices[i] = NODE_UNUSED;
+        }
+
+        // drop data from the node table
+        this.nodes.length = 0;
+        this.nodes.setCapacity(maxAllocs);
+
+        // Freelist is a stack. Nodes in inverse order so that [0] pops first.
+        for (let i = 0; i < maxAllocs; i++) {
+            this.freeNodes[i] = maxAllocs - i - 1;
+        }
+
+        // Start state: Whole storage as one big node
+        // Algorithm will split remainders and push them back as smaller nodes
+        this.#insertNodeIntoBin(this.size, 0);
+
+    }
+
+    /**
+     * Useful for debug and UI
+     * @return {StorageReport}
+     */
+    storageReport() {
+        let largestFreeRegion = 0;
+        let freeStorage = 0;
+
+        // Out of allocations? -> Zero free space
+        if (this.freeOffset > 0) {
+            freeStorage = this.freeStorage;
+
+            if (this.usedBinsTop !== 0) {
+                const topBinIndex = msb_32(this.usedBinsTop);
+                const leafBinIndex = msb_32(this.usedBins[topBinIndex]);
+
+                largestFreeRegion = floatToUint((topBinIndex << TOP_BINS_INDEX_SHIFT) | leafBinIndex);
+
+                assert.greaterThanOrEqual(freeStorage, largestFreeRegion);
+            }
+
+        }
+
+        const report = new StorageReport();
+
+        report.largestFreeRegion = largestFreeRegion;
+        report.totalFreeSpace = freeStorage;
+
+        return report;
+    }
+}