@zlink-systems/framework 0.30.0 → 0.30.2

package/dist/runtime/backend/mesh-completion-table.js

@@ -4,12 +4,114 @@ exports.ZLinkMeshCompletionTable = void 0;
 exports.closeMeshCompletion = closeMeshCompletion;
 const runtime_message_1 = require("./runtime-message");
 const operation_identity_1 = require("../foundation/operation-identity");
+const COMPLETION_SLOT_BLOCK_SIZE = 64;
+const COMPLETION_HASH_BUCKETS_PER_SLOT = 2;
+const COMPLETION_HASH_WORD_SCALE = 0x1_0000;
+const COMPLETION_HASH_MULTIPLIER = 0x9e37_79b1;
+const COMPLETION_ABORT_OPTIONS = Object.freeze({ once: true });
+class CompletionSlot {
+    abort;
+    generation = 0;
+    next = -1;
+    high;
+    low;
+    hashNext = -1;
+    resolve;
+    reject;
+    signal;
+    constructor(abort) {
+        this.abort = abort;
+    }
+}
 class ZLinkMeshCompletionTable {
     onDiagnostic;
-    pending = new Map();
+    buckets = new Int32Array(0);
+    slots = [];
+    free = -1;
+    activeCount = 0;
     disposed = false;
     constructor(onDiagnostic) {
         this.onDiagnostic = onDiagnostic;
+        this.prepareSlots();
+    }
+    prepareSlots() {
+        const start = this.slots.length;
+        for (let index = start; index < start + COMPLETION_SLOT_BLOCK_SIZE; index++) {
+            const slot = new CompletionSlot(() => {
+                const reject = slot.reject;
+                const signal = slot.signal;
+                if (reject === undefined)
+                    return;
+                this.releaseSlot(index);
+                reject(signal?.reason ?? new DOMException('The operation was aborted.', 'AbortError'));
+            });
+            slot.next = this.free;
+            this.slots.push(slot);
+            this.free = index;
+        }
+        // New slots hold no identity yet. Only a larger bucket array needs the
+        // pending identities placed again; it doubles, so growth to N pending
+        // operations re-indexes O(N) slots in total.
+        const minimumBuckets = this.slots.length * COMPLETION_HASH_BUCKETS_PER_SLOT;
+        if (minimumBuckets <= this.buckets.length)
+            return;
+        this.buckets = new Int32Array(2 ** Math.ceil(Math.log2(minimumBuckets))).fill(-1);
+        for (let index = 0; index < this.slots.length; index++) {
+            const slot = this.slots[index];
+            if (slot.high === undefined)
+                continue;
+            this.indexSlot(index);
+        }
+    }
+    bucket(high, low) {
+        const highWord = Number(high);
+        const lowWord = Number(low);
+        // Bucket selection may collide; the stored 128-bit identity is compared exactly.
+        const hash = Math.imul(highWord ^ Math.trunc(highWord / COMPLETION_HASH_WORD_SCALE), COMPLETION_HASH_MULTIPLIER) ^
+            lowWord ^
+            Math.trunc(lowWord / COMPLETION_HASH_WORD_SCALE);
+        return hash & (this.buckets.length - 1);
+    }
+    indexSlot(index) {
+        const slot = this.slots[index];
+        const bucket = this.bucket(slot.high, slot.low);
+        slot.hashNext = this.buckets[bucket];
+        this.buckets[bucket] = index;
+    }
+    findSlot(operationId) {
+        (0, operation_identity_1.validateOperationIdentity)(operationId);
+        for (let index = this.buckets[this.bucket(operationId.high, operationId.low)]; index !== -1; index = this.slots[index].hashNext) {
+            const slot = this.slots[index];
+            if (slot.high === operationId.high && slot.low === operationId.low)
+                return index;
+        }
+        return -1;
+    }
+    releaseSlot(index) {
+        const slot = this.slots[index];
+        if (slot.high !== undefined) {
+            const bucket = this.bucket(slot.high, slot.low);
+            let previous = -1;
+            let current = this.buckets[bucket];
+            while (current !== index) {
+                previous = current;
+                current = this.slots[current].hashNext;
+            }
+            if (previous === -1)
+                this.buckets[bucket] = slot.hashNext;
+            else
+                this.slots[previous].hashNext = slot.hashNext;
+        }
+        slot.signal?.removeEventListener('abort', slot.abort);
+        slot.high = undefined;
+        slot.low = undefined;
+        slot.hashNext = -1;
+        slot.signal = undefined;
+        slot.resolve = undefined;
+        slot.reject = undefined;
+        slot.next = this.free;
+        this.free = index;
+        this.activeCount--;
     }
     /**
      * Reserves the dispatcher slot before transport submission. The backend
@@ -24,39 +126,32 @@ class ZLinkMeshCompletionTable {
             return Promise.reject(signal.reason ?? new DOMException('The operation was aborted.', 'AbortError'));
         }
         return new Promise((resolve, reject) => {
-            let key = Symbol();
-            const abort = () => {
-                this.pending.delete(key);
-                reject(signal?.reason ?? new DOMException('The operation was aborted.', 'AbortError'));
-            };
-            if (signal?.aborted === true) {
-                abort();
-                return;
-            }
-            signal?.addEventListener('abort', abort, { once: true });
-            const entry = {
-                resolve,
-                reject,
-                removeAbort: signal === undefined ? undefined : () => signal.removeEventListener('abort', abort)
-            };
-            this.pending.set(key, entry);
+            if (this.free === -1)
+                this.prepareSlots();
+            const index = this.free;
+            const slot = this.slots[index];
+            this.free = slot.next;
+            const generation = ++slot.generation;
+            slot.resolve = resolve;
+            slot.reject = reject;
+            slot.signal = signal;
+            this.activeCount++;
             try {
+                signal?.addEventListener('abort', slot.abort, COMPLETION_ABORT_OPTIONS);
                 const operationId = operation();
-                // dispose/abort can consume the reserved slot during submission.
-                if (!this.pending.delete(key))
+                // A reentrant abort may release and reuse this slot during submission.
+                if (slot.generation !== generation || slot.resolve !== resolve)
                     return;
-                key = (0, operation_identity_1.operationIdentityKey)(operationId);
-                if (this.pending.has(key)) {
-                    throw new Error(`Mesh operation '${key}' is already pending.`);
+                if (this.findSlot(operationId) !== -1) {
+                    throw new Error(`Mesh operation '${(0, operation_identity_1.operationIdentityKey)(operationId)}' is already pending.`);
                 }
-                this.pending.set(key, entry);
+                slot.high = operationId.high;
+                slot.low = operationId.low;
+                this.indexSlot(index);
             }
             catch (error) {
-                // Remove only this submission's slot; a duplicate identity retains
-                // the original waiter.
-                if (this.pending.get(key) === entry)
-                    this.pending.delete(key);
-                entry.removeAbort?.();
+                if (slot.generation === generation && slot.resolve === resolve)
+                    this.releaseSlot(index);
                 reject(error);
             }
         });
@@ -65,9 +160,8 @@ class ZLinkMeshCompletionTable {
         return this.disposed;
     }
     complete(record, materialize) {
-        const key = (0, operation_identity_1.operationIdentityKey)(record.operationId);
-        const pending = this.pending.get(key);
-        if (pending === undefined) {
+        const index = this.findSlot(record.operationId);
+        if (index === -1) {
             this.onDiagnostic?.({
                 kind: 'unknownOrLate',
                 operationId: Object.freeze({ ...record.operationId }),
@@ -75,13 +169,15 @@ class ZLinkMeshCompletionTable {
             });
             return;
         }
-        this.pending.delete(key);
-        pending.removeAbort?.();
+        const slot = this.slots[index];
+        const resolve = slot.resolve;
+        const reject = slot.reject;
+        this.releaseSlot(index);
         try {
-            pending.resolve(retainCompletion(materialize === undefined ? record : materialize()));
+            resolve(retainCompletion(materialize === undefined ? record : materialize()));
         }
         catch (error) {
-            pending.reject(error);
+            reject(error);
         }
     }
     dispose(reason = new Error('Mesh completion table is disposed.')) {
@@ -89,34 +185,43 @@ class ZLinkMeshCompletionTable {
             return;
         }
         this.disposed = true;
-        const pending = [...this.pending.values()];
-        this.pending.clear();
-        for (const entry of pending) {
-            entry.removeAbort?.();
-        }
-        for (const entry of pending) {
-            entry.reject(reason);
+        for (let index = 0; index < this.slots.length; index++) {
+            const reject = this.slots[index].reject;
+            if (reject === undefined)
+                continue;
+            this.releaseSlot(index);
+            reject(reason);
         }
     }
     get pendingCount() {
-        return this.pending.size;
+        return this.activeCount;
     }
 }
 exports.ZLinkMeshCompletionTable = ZLinkMeshCompletionTable;
 function retainCompletion(record) {
+    const parts = retainCompletionParts(record.parts);
+    // The retention pass verifies every part is already a managed runtime message.
+    if (parts === record.parts)
+        return record;
     return {
         terminalResult: record.terminalResult,
         failureErrno: record.failureErrno,
         operationKind: record.operationKind,
         kindData: record.kindData,
-        parts: record.parts.map(retainCompletionPart)
+        parts
     };
 }
-function retainCompletionPart(part) {
-    // A runtime message already owns a managed Buffer and close() is a no-op.
-    // Binding-native messages can expose native storage through data(), which
-    // becomes invalid when their owner closes; materialize that one boundary copy.
-    return part instanceof runtime_message_1.ZLinkBufferMessage ? part : runtime_message_1.ZLinkBufferMessage.fromOwned(Buffer.from(part.data()));
+function retainCompletionParts(parts) {
+    // Reuse managed messages and wrap binding payloads in the runtime representation.
+    let retained;
+    for (let index = 0; index < parts.length; index++) {
+        const part = parts[index];
+        if (!(part instanceof runtime_message_1.ZLinkBufferMessage)) {
+            retained ??= parts.slice();
+            retained[index] = runtime_message_1.ZLinkBufferMessage.fromOwned(runtime_message_1.ZLinkBufferMessage.retainPayload(part));
+        }
+    }
+    return retained ?? parts;
 }
 function closeMeshCompletion(completion) {
     closeParts(completion.parts);

package/dist/runtime/backend/mesh-dispatch-pump.d.ts

@@ -29,14 +29,29 @@ export declare class ZLinkMeshDispatchPump {
     private readonly capacityStop;
     private recordsSinceYield;
     private yieldStartedAtMs;
+    /** Drains in progress; the batch budget begins when work starts on an idle pump. */
+    private draining;
+    /** The macrotask boundary every drain waits for once the shared budget is spent. */
+    private pendingYield?;
     constructor(node: ZLinkBackendMeshNode, options: ZLinkMeshDispatchPumpOptions);
     start(): void;
-    dispose(): Promise<void>;
+    dispose(signal?: AbortSignal): Promise<void>;
     private markReady;
     private wakeApplicationWorker;
     private startApplicationWorker;
     private runApplicationWorker;
     private waitForApplicationReady;
+    /**
+     * Starts one record in this worker's turn; a permit's scope covers the
+     * synchronous dispatch. Returns `false` when the dispatch threw (already
+     * reported), `true` when it returned synchronously, or the handler's pending
+     * completion, which the draining turn awaits itself before
+     * {@link finishRecord}.
+     */
+    private dispatchRecord;
+    private failRecord;
+    /** Runs the record's terminal completion, then releases its permit turn. */
+    private finishRecord;
     private reportDispatchError;
     /**
      * Infrastructure controls must not wait for an application permit. During
@@ -48,6 +63,18 @@ export declare class ZLinkMeshDispatchPump {
     private scheduleInfrastructure;
     private drainInfrastructure;
     private drainDomain;
+    /**
+     * Time the pump spent idle is not batch work: when work starts on an idle
+     * pump, its batch budget starts with it (spec 08 §6).
+     */
+    private beginDrain;
+    /** Drains one claimed owner in this worker's turn, in claim order. */
+    private drainClaim;
+    /**
+     * The batch budget is shared by every drain of this pump, so once it is
+     * spent every drain waits for the same macrotask boundary; one drain that
+     * keeps running would otherwise hold the event loop the yield was for.
+     */
     private yieldIfNeeded;
     private nowMs;
     private acquirePermit;