knitting 0.1.63 → 0.1.70

package/src/worker/rx-queue.js

@@ -1,12 +1,12 @@
 import RingQueue from "../ipc/tools/ring-queue.js";
 import { attachPayloadTransportFinalizer, runTaskFinalizers, TaskFlag, TaskIndex, } from "../memory/lock.js";
 import { composeWorkerRunner } from "./composable-runners.js";
-import { BUFFER_REFERENCE_RETURN_RELEASE_TOKEN } from "../connections/buffer-reference.js";
-export const createWorkerRxQueue = ({ listOfFunctions, workerOptions, lock, returnLock, borrowReturnedBufferReferences, hasAborted, now, stealing, }) => {
+/** Tasks run per `serviceBatchImmediate` call before returning to the loop. */
+const SERVICE_BATCH_MAX = 32;
+export const createWorkerRxQueue = ({ listOfFunctions, workerOptions, lock, returnLock, hasAborted, now, stealing, }) => {
     const PLACE_HOLDER = (_) => {
         throw ("UNREACHABLE FROM PLACE HOLDER (thread)");
     };
-    let hasAnythingFinished = 0;
     let awaiting = 0;
     const jobs = listOfFunctions.reduce((acc, fixed) => (acc.push(fixed.run), acc), []);
     const toWork = new RingQueue();
@@ -26,12 +26,7 @@ export const createWorkerRxQueue = ({ listOfFunctions, workerOptions, lock, retu
     const returnHostBits = returnLock.hostBits;
     const returnWorkerBits = returnLock.workerBits;
     const deferredReleases = [];
-    const explicitReturnReleases = new Map();
-    const drainReturnReleases = () => {
-        if (deferredReleases.length === 0)
-            return;
-        if ((a_load(returnHostBits, 0) ^ a_load(returnWorkerBits, 0)) !== 0)
-            return;
+    const releaseDeferredReturns = () => {
         for (let i = 0; i < deferredReleases.length; i++) {
             try {
                 deferredReleases[i]();
@@ -42,18 +37,17 @@ export const createWorkerRxQueue = ({ listOfFunctions, workerOptions, lock, retu
         }
         deferredReleases.length = 0;
     };
-    const releaseReturnedBufferReference = (token) => {
-        const key = token.toString();
-        const release = explicitReturnReleases.get(key);
-        if (release === undefined)
+    const drainReturnReleases = () => {
+        if (deferredReleases.length === 0)
             return;
-        explicitReturnReleases.delete(key);
-        try {
-            release();
-        }
-        catch {
-            // best effort
-        }
+        // `returnHostBits` is the publication word of the return lock, and only
+        // this thread ever writes it (encode() toggles hostBits, the host toggles
+        // workerBits). Reading our own word plainly skips an `Atomics.load`, which
+        // is a non-inlined call an order of magnitude dearer than a plain read;
+        // the peer's word still needs the atomic.
+        if ((returnHostBits[0] ^ a_load(returnWorkerBits, 0)) !== 0)
+            return;
+        releaseDeferredReturns();
     };
     const runByIndex = listOfFunctions.reduce((acc, fixed, idx) => {
         const job = jobs[idx];
@@ -65,9 +59,13 @@ export const createWorkerRxQueue = ({ listOfFunctions, workerOptions, lock, retu
         }));
         return acc;
     }, []);
+    // A settled task is either written into the return lock straight away or
+    // parked in `pendingFrames`, so the queue's own size already answers "is
+    // there anything left to flush" — the separate counter this used to keep was
+    // an increment and a decrement per task tracking a value it could read.
     const hasCompleted = workerOptions?.resolveAfterFinishingAll === true
-        ? () => hasAnythingFinished !== 0 && toWork.size === 0
-        : () => hasAnythingFinished !== 0;
+        ? () => pendingFrames.size !== 0 && toWork.size === 0
+        : () => pendingFrames.size !== 0;
     const { decode, resolved } = lock;
     const resolvedShift = () => resolved.shiftNoClear();
     const enqueueLock = () => {
@@ -86,34 +84,22 @@ export const createWorkerRxQueue = ({ listOfFunctions, workerOptions, lock, retu
         }
         return true;
     };
-    const encodeReturnSafe = (slot) => {
-        if (!returnLock.encode(slot))
-            return false;
-        return true;
-    };
+    const returnEncode = returnLock.encode;
     const sendReturn = (slot, shouldReject) => {
         slot[IDX_FLAGS] = shouldReject ? FLAG_REJECT : 0;
-        if (!encodeReturnSafe(slot))
+        if (!returnEncode(slot))
             return false;
         // Preserve return finalizers past slot recycle; release after drain.
         if (slot.finalize !== undefined) {
-            const token = slot.finalize[BUFFER_REFERENCE_RETURN_RELEASE_TOKEN];
-            if (token === undefined || borrowReturnedBufferReferences !== true) {
-                deferredReleases.push(slot.finalize);
-            }
-            else {
-                explicitReturnReleases.set(token.toString(), slot.finalize);
-            }
+            deferredReleases.push(slot.finalize);
             slot.finalize = undefined;
         }
-        hasAnythingFinished--;
         recyclePush(slot);
         return true;
     };
     const settleNow = (slot, isError, value, wasAwaited) => {
         runTaskFinalizers(slot);
         slot.value = value;
-        hasAnythingFinished++;
         if (wasAwaited && awaiting > 0)
             awaiting--;
         const shouldReject = isError ||
@@ -145,14 +131,20 @@ export const createWorkerRxQueue = ({ listOfFunctions, workerOptions, lock, retu
         },
         serviceBatchImmediate: () => {
             let processed = 0;
-            while (processed < 5 && toWork.size !== 0) {
+            // Every trip back out to the dispatch loop costs a claim attempt and the
+            // per-pass bookkeeping, so a low cap makes that scaffolding a per-task
+            // tax on cheap tasks. Run a longer run when the return lock is keeping
+            // up, and cut it short the moment a settle lands in `pendingFrames` --
+            // that means the return region is full and the right move is to go
+            // flush it rather than pile up more finished work.
+            while (processed < SERVICE_BATCH_MAX && toWork.size !== 0) {
                 const slot = toWorkShift();
                 try {
                     const fnIndex = slot[TaskIndex.FunctionID] & FUNCTION_ID_MASK;
                     const result = runByIndex[fnIndex](slot);
                     slot[IDX_FLAGS] = 0;
-                    slot.value = null;
                     if (result instanceof Promise) {
+                        slot.value = null;
                         awaiting++;
                         result.then((value) => settleNow(slot, false, value, true), (err) => settleNow(slot, true, err, true));
                     }
@@ -164,12 +156,14 @@ export const createWorkerRxQueue = ({ listOfFunctions, workerOptions, lock, retu
                     settleNow(slot, true, err, false);
                 }
                 ++processed;
+                if (pendingFrames.size !== 0)
+                    break;
             }
             return processed;
         },
         enqueueLock,
         drainReturnReleases,
-        releaseReturnedBufferReference,
+        releaseDeferredReturns,
         hasAwaiting: () => awaiting > 0,
         getAwaiting: () => awaiting,
     };

package/src/worker/shared-return.d.ts

@@ -0,0 +1,9 @@
+/** Point `sharedBytes` at the arena of `payload`, this worker's return lane. */
+export declare const installSharedReturn: (payload: object) => void;
+export declare const resetSharedReturn: () => void;
+/**
+ * Allocate an uninitialized borrowed return buffer. The caller must write every
+ * byte it returns and must not retain the view beyond the borrow window.
+ * Ordinary allocation is used when borrowing is unavailable.
+ */
+export declare const sharedBytes: (byteLength: number, zeroFill?: boolean) => Uint8Array;

package/src/worker/shared-return.js

@@ -0,0 +1,22 @@
+import { getSharedReturnAllocator } from "../memory/payloadCodec.js";
+// `sharedBytes` uses the worker's return-lane arena; outside that context it
+// falls back to an ordinary Uint8Array.
+let allocate;
+/** Point `sharedBytes` at the arena of `payload`, this worker's return lane. */
+export const installSharedReturn = (payload) => {
+    allocate = getSharedReturnAllocator(payload);
+};
+export const resetSharedReturn = () => {
+    allocate = undefined;
+};
+/**
+ * Allocate an uninitialized borrowed return buffer. The caller must write every
+ * byte it returns and must not retain the view beyond the borrow window.
+ * Ordinary allocation is used when borrowing is unavailable.
+ */
+export const sharedBytes = (byteLength, zeroFill = false) => {
+    if (!Number.isInteger(byteLength) || byteLength < 0) {
+        throw new RangeError("sharedBytes(byteLength) requires a non-negative integer");
+    }
+    return allocate?.(byteLength, zeroFill) ?? new Uint8Array(byteLength);
+};

package/src/worker/task-loader.js

@@ -1,7 +1,6 @@
 import { endpointSymbol } from "../common/task-symbol.js";
 import { toImportSpecifier, toModuleUrl } from "../common/module-url.js";
-// const object, not `const enum`: Andromeda's Nova engine can't parse `enum`.
-// No longer inlined, but only read on cold paths.
+// Use a const object; Andromeda's Nova engine cannot parse `enum`.
 export const TimeoutKind = {
     Reject: 0,
     Resolve: 1,

package/src/worker/timers.d.ts

@@ -2,6 +2,7 @@ type PauseOptions = {
     pauseInNanoseconds?: number;
 };
 export type NativeWaitU32 = (buffer: ArrayBuffer | SharedArrayBuffer, byteOffset: number, expected: number, timeoutMs?: number) => unknown;
+export declare const IS_BUN_WINDOWS: boolean;
 export declare const whilePausing: ({ pauseInNanoseconds }: PauseOptions) => () => void;
 export declare const pauseGeneric: () => void;
 export declare const sleepUntilChanged: ({ at, opView, pauseInNanoseconds, rxStatus, txStatus, enqueueLock, write, nativeWaitU32, useSharedMemoryWait, flushBeforeClaim, }: {
@@ -14,12 +15,7 @@ export declare const sleepUntilChanged: ({ at, opView, pauseInNanoseconds, rxSta
     write?: () => number | boolean;
     nativeWaitU32?: NativeWaitU32;
     useSharedMemoryWait?: boolean;
-    /**
-     * Stealing only: write results back before attempting to claim more work.
-     * A claim can spin waiting for a peer to withdraw its intent, so claiming
-     * first puts arbitration latency in front of a finished response. Measured
-     * to hurt the per-lane path, so it stays off by default.
-     */
+    /** Stealing only: flush results before claiming more work. */
     flushBeforeClaim?: boolean;
 }) => (value: number, spinMicroseconds: number, parkMs?: number) => void;
 export {};

package/src/worker/timers.js

@@ -30,8 +30,7 @@ const a_load = Atomics.load;
 const a_store = Atomics.store;
 const a_wait = typeof Atomics.wait === "function" ? Atomics.wait : undefined;
 const p_now = performance.now.bind(performance);
-// `SharedArrayBuffer` is undeclared on pages that are not cross-origin
-// isolated, and this module has to load anyway so the pool can report why.
+// Some pages do not define SharedArrayBuffer; keep this module loadable there.
 const waitFallbackView = a_wait === undefined || typeof SharedArrayBuffer !== "function"
     ? undefined
     : new Int32Array(new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT));
@@ -43,17 +42,16 @@ const isPlainNodeWindows = runtimeGlobals.process?.platform === "win32" &&
     typeof runtimeGlobals.process?.versions?.node === "string" &&
     runtimeGlobals.process?.versions?.bun === undefined &&
     runtimeGlobals.Deno === undefined;
-// Windows has no working cross-process wake. The native wake (WakeByAddress)
-// is keyed to a virtual address, so a host cannot wake a process worker parked
-// on the same physical page mapped at a different address in the child — the
-// addon's FutexWake is a no-op there. A parked Windows Node process worker can
-// therefore never be signalled and must rediscover work by polling. Cap the
-// native wait at 1ms so it re-checks every millisecond instead of sleeping the
-// full parkMs (up to seconds); the long park with no wake is what made CI
-// runners appear to hang. The native wait already polls internally, so this is
-// just bounding each poll slice.
+// Bun on Windows requires special handling for short waits and process rings.
+export const IS_BUN_WINDOWS = runtimeGlobals.process?.platform === "win32" &&
+    typeof runtimeGlobals.process?.versions?.bun === "string";
+// Bun on Windows busy-spins for waits of 1ms or less; use a 2ms minimum.
+const BUN_WINDOWS_MIN_WAIT_MS = 2;
+const floorBunWindowsWait = (ms) => IS_BUN_WINDOWS && ms < BUN_WINDOWS_MIN_WAIT_MS ? BUN_WINDOWS_MIN_WAIT_MS : ms;
+// Windows process workers cannot be woken through the native address-based
+// wait, so cap their wait to 1ms and let polling rediscover work.
 const nativeWaitTimeoutMs = (parkMs) => isPlainNodeWindows ? 1 : Number.isFinite(parkMs) ? parkMs : Infinity;
-const pollingWaitTimeoutMs = (parkMs) => Number.isFinite(parkMs) ? Math.min(Math.max(parkMs, 0), 1) : 1;
+const pollingWaitTimeoutMs = (parkMs) => floorBunWindowsWait(Number.isFinite(parkMs) ? Math.min(Math.max(parkMs, 0), 1) : 1);
 export const whilePausing = ({ pauseInNanoseconds }) => {
     const forNanoseconds = pauseInNanoseconds ?? DEFAULT_PAUSE_TIME;
     if (!a_pause || forNanoseconds <= 0)
@@ -105,15 +103,12 @@ export const sleepUntilChanged = ({ at, opView, pauseInNanoseconds, rxStatus, tx
         else if (useSharedMemoryWait &&
             a_wait &&
             opView.buffer instanceof SharedArrayBuffer) {
-            // This is the notify-able path: a host Atomics.notify on opView wakes it.
-            // An infinite parkMs (debug) is intentional here — the worker blocks until
-            // a real signal instead of re-polling on a timeout.
-            a_wait(opView, at, value, parkMs ?? Infinity);
+            // This path can be woken with Atomics.notify; an infinite debug wait is
+            // intentional.
+            a_wait(opView, at, value, floorBunWindowsWait(parkMs ?? Infinity));
         }
         else if (a_wait && waitFallbackView) {
-            // waitFallbackView is never notified — this wait only ever times out and
-            // re-polls. Keep the slice short and finite so FFI-backed process workers
-            // stay responsive without a cross-process native wake primitive.
+            // This fallback is timeout-driven; keep the slice short for responsiveness.
             a_wait(waitFallbackView, 0, 0, pollingWaitTimeoutMs(parkMs));
         }
         a_store(rxStatus, 0, 1);

package/unsafe.d.ts

@@ -1 +1,2 @@
-export { BUFFER_REFERENCE_CODEC_ID, BUFFER_REFERENCE_KIND, BufferReference, type BufferReferenceMetadata, BufferReferenceReturn, type BufferReferenceRuntime, isBufferReferenceMetadata, } from "./src/connections/buffer-reference.js";
+export { BUFFER_REFERENCE_CODEC_ID, BUFFER_REFERENCE_KIND, BufferReference, type BufferReferenceMetadata, type BufferReferenceRuntime, isBufferReferenceMetadata, } from "./src/connections/buffer-reference.js";
+export { sharedBytes } from "./src/worker/shared-return.js";

package/unsafe.js

@@ -1 +1,2 @@
-export { BUFFER_REFERENCE_CODEC_ID, BUFFER_REFERENCE_KIND, BufferReference, BufferReferenceReturn, isBufferReferenceMetadata, } from "./src/connections/buffer-reference.js";
+export { BUFFER_REFERENCE_CODEC_ID, BUFFER_REFERENCE_KIND, BufferReference, isBufferReferenceMetadata, } from "./src/connections/buffer-reference.js";
+export { sharedBytes } from "./src/worker/shared-return.js";