knitting 0.1.51 → 0.1.53

package/src/worker/loop.js

@@ -1,4 +1,4 @@
-import { createRuntimeMessageChannel, RUNTIME_IS_MAIN_THREAD, RUNTIME_IS_PROCESS_WORKER, RUNTIME_PARENT_PORT, RUNTIME_WORKER_DATA, } from "../common/worker-runtime.js";
+import { addRuntimeDataListener, createRuntimeMessageChannel, RUNTIME_IS_MAIN_THREAD, RUNTIME_IS_PROCESS_WORKER, RUNTIME_PARENT_PORT, RUNTIME_WORKER_DATA, } from "../common/worker-runtime.js";
 import { isSharedBufferSource } from "../common/shared-buffer-region.js";
 import { isLockBufferTextCompat } from "../common/shared-buffer-text.js";
 import { createWorkerRxQueue } from "./rx-queue.js";
@@ -12,6 +12,8 @@ import { assertWorkerImportsResolved, assertWorkerSharedMemoryBootData, installP
 import { signalAbortFactory } from "../shared/abortSignal.js";
 import { runWorkerBootstrap } from "./bootstrap.js";
 import { getProcessWorkerNativeWaitU32, installProcessWorkerBootstrap, } from "./process-worker-bootstrap.js";
+import { readBufferReferenceReturnReleaseMessage, } from "../connections/buffer-reference.js";
+import { resolveDebugNamespaces } from "../debug/gate.js";
 const WORKER_FATAL_MESSAGE_KEY = "__knittingWorkerFatal";
 const reportWorkerStartupFatal = (error) => {
     const message = String(error?.message ?? error);
@@ -48,14 +50,37 @@ const reportWorkerStartupFatal = (error) => {
         }
     }
 };
+const installBufferReferenceReleaseListener = (releaseReturnedBufferReference) => {
+    const handleMessage = (message) => {
+        const token = readBufferReferenceReturnReleaseMessage(message);
+        if (token !== undefined)
+            releaseReturnedBufferReference(token);
+    };
+    if (RUNTIME_PARENT_PORT !== undefined) {
+        addRuntimeDataListener(RUNTIME_PARENT_PORT, handleMessage);
+        return;
+    }
+    const scope = globalThis;
+    scope.addEventListener?.("message", (event) => {
+        handleMessage(event?.data);
+    });
+};
 export const workerMainLoop = async (startupData) => {
     // Startup-only safety layer: no per-iteration checks in the hot loop.
     installTerminationGuard();
     installUnhandledRejectionSilencer();
     installPerformanceNowGuard();
-    const { debug, sab, thread, startAt, workerOptions, lock, returnLock, abortSignalSAB, abortSignalMax, payloadConfig, permission, totalNumberOfThread, list, ids, names, at, } = startupData;
+    const { debug, sab, thread, startAt, workerOptions, lock, returnLock, abortSignalSAB, abortSignalMax, payloadConfig, bufferReferenceReturn, permission, totalNumberOfThread, list, ids, names, at, } = startupData;
     scrubWorkerDataSensitiveBuffers(startupData);
     assertWorkerSharedMemoryBootData({ sab, lock, returnLock });
+    const debugNamespaces = resolveDebugNamespaces(debug);
+    const dbg = debugNamespaces.size > 0
+        ? await import("../debug/handle.js").then((module) => module.initDebug({
+            name: `w${thread}`,
+            runtime: RUNTIME,
+            namespaces: debugNamespaces,
+        }))
+        : undefined;
     let Comment;
     (function (Comment) {
         Comment[Comment["thisIsAHint"] = 0] = "thisIsAHint";
@@ -66,7 +91,6 @@ export const workerMainLoop = async (startupData) => {
         },
         isMain: false,
         thread,
-        debug,
         startTime: startAt,
     });
     const lockState = lock2({
@@ -90,8 +114,10 @@ export const workerMainLoop = async (startupData) => {
     const timers = workerOptions?.timers;
     const spinMicroseconds = timers?.spinMicroseconds ??
         Math.max(1, totalNumberOfThread) * 50;
-    const parkMs = timers?.parkMs ??
-        Math.max(1, totalNumberOfThread) * 50;
+    const parkMs = dbg !== undefined
+        ? Number.POSITIVE_INFINITY
+        : (timers?.parkMs ??
+            Math.max(1, totalNumberOfThread) * 50);
     const pauseSpin = (() => {
         const fn = typeof timers?.pauseNanoseconds === "number"
             ? whilePausing({ pauseInNanoseconds: timers.pauseNanoseconds })
@@ -107,6 +133,7 @@ export const workerMainLoop = async (startupData) => {
         thread,
         totalNumberOfThread,
     });
+    dbg?.envPhase("bootstrap");
     const listOfFunctions = await getFunctions({
         list,
         isWorker: true,
@@ -115,20 +142,24 @@ export const workerMainLoop = async (startupData) => {
         at,
         permission,
     });
-    assertWorkerImportsResolved({ debug, list, ids, names, listOfFunctions });
+    dbg?.envPhase("tasks");
+    dbg?.log("imports", `${listOfFunctions.length} task(s) from ${list.map((spec) => spec.split(/[\\/]/).pop() || spec).join(", ")}`);
+    assertWorkerImportsResolved({ list, ids, names, listOfFunctions });
     const abortSignals = abortSignalSAB
         ? signalAbortFactory({
             sab: abortSignalSAB,
             maxSignals: abortSignalMax,
         })
         : undefined;
-    const { enqueueLock, serviceBatchImmediate, hasCompleted, writeBatch, hasPending, getAwaiting, } = createWorkerRxQueue({
+    const { enqueueLock, serviceBatchImmediate, hasCompleted, writeBatch, hasPending, getAwaiting, drainReturnReleases, releaseReturnedBufferReference, } = createWorkerRxQueue({
         listOfFunctions,
         workerOptions,
         lock: lockState,
         returnLock: returnLockState,
+        borrowReturnedBufferReferences: bufferReferenceReturn === "borrow",
         hasAborted: abortSignals?.hasAborted,
     });
+    installBufferReferenceReleaseListener(releaseReturnedBufferReference);
     a_store(rxStatus, 0, 1);
     const WRITE_MAX = 64;
     const pauseUntil = sleepUntilChanged({
@@ -152,7 +183,7 @@ export const workerMainLoop = async (startupData) => {
     let awaitingSpins = 0;
     let lastAwaiting = 0;
     const MAX_AWAITING_MS = 10;
-    let wakeSeq = a_load(opView, 0);
+    let wakeToken = a_load(opView, 0);
     const scheduleMacro = () => {
         if (isInMacro)
             return;
@@ -177,14 +208,43 @@ export const workerMainLoop = async (startupData) => {
         }
         post2(null);
     };
-    const _enqueueLock = enqueueLock;
+    const traceSignals = dbg?.enabled("signals") === true;
     const _hasCompleted = hasCompleted;
-    const _writeBatch = writeBatch;
     const _hasPending = hasPending;
-    const _serviceBatchImmediate = serviceBatchImmediate;
     const _getAwaiting = getAwaiting;
+    const _drainReturnReleases = drainReturnReleases;
     const _pauseSpin = pauseSpin;
-    const _pauseUntil = pauseUntil;
+    const _enqueueLock = traceSignals
+        ? () => {
+            const progressed = enqueueLock();
+            if (progressed) {
+                dbg.log("signals", "work from=host");
+            }
+            return progressed;
+        }
+        : enqueueLock;
+    const _writeBatch = traceSignals
+        ? (max) => {
+            const wrote = writeBatch(max);
+            if (wrote > 0)
+                dbg.log("signals", `result count=${wrote}`);
+            return wrote;
+        }
+        : writeBatch;
+    const _serviceBatchImmediate = traceSignals
+        ? () => {
+            const ran = serviceBatchImmediate();
+            if (ran > 0)
+                dbg.log("signals", `run count=${ran}`);
+            return ran;
+        }
+        : serviceBatchImmediate;
+    const _pauseUntil = traceSignals
+        ? (value, spinMicroseconds, parkMs) => {
+            dbg.log("signals", `idle token=${value}`);
+            pauseUntil(value, spinMicroseconds, parkMs);
+        }
+        : pauseUntil;
     const loop = () => {
         isInMacro = false;
         let progressed = true;
@@ -195,6 +255,7 @@ export const workerMainLoop = async (startupData) => {
                 if (_writeBatch(WRITE_MAX) > 0)
                     progressed = true;
             }
+            _drainReturnReleases();
             if (_hasPending()) {
                 if (_serviceBatchImmediate() > 0)
                     progressed = true;
@@ -214,8 +275,8 @@ export const workerMainLoop = async (startupData) => {
                     _pauseSpin();
                     continue;
                 }
-                _pauseUntil(wakeSeq, spinMicroseconds, parkMs);
-                wakeSeq = a_load(opView, 0);
+                _pauseUntil(wakeToken, spinMicroseconds, parkMs);
+                wakeToken = a_load(opView, 0);
             }
         }
     };
@@ -229,6 +290,7 @@ export const workerMainLoop = async (startupData) => {
     }
     port1Any.start?.();
     port2.start?.();
+    dbg?.log("lifecycle", `ready: ${listOfFunctions.length} task(s) on thread ${thread}/${totalNumberOfThread}, entering dispatch loop`);
     scheduleMacro();
 };
 const isWorkerGlobalScope = () => {

package/src/worker/rx-queue.d.ts

@@ -6,16 +6,19 @@ type ArgumentsForCreateWorkerQueue = {
     workerOptions?: WorkerSettings;
     lock: Lock2;
     returnLock: Lock2;
+    borrowReturnedBufferReferences?: boolean;
     hasAborted?: (signal: number) => boolean;
     now?: () => number;
 };
 export type CreateWorkerRxQueue = ReturnType<typeof createWorkerRxQueue>;
-export declare const createWorkerRxQueue: ({ listOfFunctions, workerOptions, lock, returnLock, hasAborted, now, }: ArgumentsForCreateWorkerQueue) => {
+export declare const createWorkerRxQueue: ({ listOfFunctions, workerOptions, lock, returnLock, borrowReturnedBufferReferences, hasAborted, now, }: ArgumentsForCreateWorkerQueue) => {
     hasCompleted: () => boolean;
     hasPending: () => boolean;
     writeBatch: (max: number) => number;
     serviceBatchImmediate: () => number;
     enqueueLock: () => boolean;
+    drainReturnReleases: () => void;
+    releaseReturnedBufferReference: (token: bigint) => void;
     hasAwaiting: () => boolean;
     getAwaiting: () => number;
 };

package/src/worker/rx-queue.js

@@ -1,8 +1,8 @@
 import RingQueue from "../ipc/tools/ring-queue.js";
-import { TaskFlag, TaskIndex, } from "../memory/lock.js";
+import { attachPayloadTransportFinalizer, runTaskFinalizers, TaskFlag, TaskIndex, } from "../memory/lock.js";
 import { composeWorkerRunner } from "./composable-runners.js";
-// Create and manage a working queue.
-export const createWorkerRxQueue = ({ listOfFunctions, workerOptions, lock, returnLock, hasAborted, now, }) => {
+import { BUFFER_REFERENCE_RETURN_RELEASE_TOKEN } from "../connections/buffer-reference.js";
+export const createWorkerRxQueue = ({ listOfFunctions, workerOptions, lock, returnLock, borrowReturnedBufferReferences, hasAborted, now, }) => {
     const PLACE_HOLDER = (_) => {
         throw ("UNREACHABLE FROM PLACE HOLDER (thread)");
     };
@@ -20,6 +20,41 @@ export const createWorkerRxQueue = ({ listOfFunctions, workerOptions, lock, retu
     const FUNCTION_ID_MASK = 0xFFFF;
     const IDX_FLAGS = TaskIndex.FlagsToHost;
     const FLAG_REJECT = TaskFlag.Reject;
+    // Return-payload finalizers wait until the host consumes the return.
+    // Quiescence (hostBits XOR workerBits == 0) lets us release them in batch.
+    const a_load = Atomics.load;
+    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;
+        for (let i = 0; i < deferredReleases.length; i++) {
+            try {
+                deferredReleases[i]();
+            }
+            catch {
+                // best effort
+            }
+        }
+        deferredReleases.length = 0;
+    };
+    const releaseReturnedBufferReference = (token) => {
+        const key = token.toString();
+        const release = explicitReturnReleases.get(key);
+        if (release === undefined)
+            return;
+        explicitReturnReleases.delete(key);
+        try {
+            release();
+        }
+        catch {
+            // best effort
+        }
+    };
     const runByIndex = listOfFunctions.reduce((acc, fixed, idx) => {
         const job = jobs[idx];
         acc.push(composeWorkerRunner({
@@ -42,6 +77,7 @@ export const createWorkerRxQueue = ({ listOfFunctions, workerOptions, lock, retu
         while (task) {
             task.resolve = PLACE_HOLDER;
             task.reject = PLACE_HOLDER;
+            attachPayloadTransportFinalizer(task, task.value);
             toWorkPush(task);
             task = resolvedShift();
         }
@@ -56,11 +92,23 @@ export const createWorkerRxQueue = ({ listOfFunctions, workerOptions, lock, retu
         slot[IDX_FLAGS] = shouldReject ? FLAG_REJECT : 0;
         if (!encodeReturnSafe(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);
+            }
+            slot.finalize = undefined;
+        }
         hasAnythingFinished--;
         recyclePush(slot);
         return true;
     };
     const settleNow = (slot, isError, value, wasAwaited) => {
+        runTaskFinalizers(slot);
         slot.value = value;
         hasAnythingFinished++;
         if (wasAwaited && awaiting > 0)
@@ -99,7 +147,6 @@ export const createWorkerRxQueue = ({ listOfFunctions, workerOptions, lock, retu
                 try {
                     const fnIndex = slot[TaskIndex.FunctionID] & FUNCTION_ID_MASK;
                     const result = runByIndex[fnIndex](slot);
-                    // Slot 0 is reused for response flags; clear request FunctionID value.
                     slot[IDX_FLAGS] = 0;
                     slot.value = null;
                     if (result instanceof Promise) {
@@ -118,6 +165,8 @@ export const createWorkerRxQueue = ({ listOfFunctions, workerOptions, lock, retu
             return processed;
         },
         enqueueLock,
+        drainReturnReleases,
+        releaseReturnedBufferReference,
         hasAwaiting: () => awaiting > 0,
         getAwaiting: () => awaiting,
     };

package/src/worker/safety/startup.d.ts

@@ -1,17 +1,16 @@
 import { type SharedBufferSource } from "../../common/shared-buffer-region.js";
-import type { DebugOptions, LockBuffers } from "../../types.js";
+import type { LockBuffers } from "../../types.js";
 type SharedMemoryBootData = {
     sab: SharedBufferSource | undefined;
     lock: LockBuffers | undefined;
     returnLock: LockBuffers | undefined;
 };
 type ImportedFunctionsState = {
-    debug: DebugOptions | undefined;
     list: string[];
     ids: number[];
     names?: string[];
     listOfFunctions: readonly unknown[];
 };
 export declare const assertWorkerSharedMemoryBootData: ({ sab, lock, returnLock }: SharedMemoryBootData) => void;
-export declare const assertWorkerImportsResolved: ({ debug, list, ids, names, listOfFunctions }: ImportedFunctionsState) => void;
+export declare const assertWorkerImportsResolved: ({ list, ids, names, listOfFunctions }: ImportedFunctionsState) => void;
 export {};

package/src/worker/safety/startup.js

@@ -17,10 +17,7 @@ export const assertWorkerSharedMemoryBootData = ({ sab, lock, returnLock }) => {
         throw new Error("worker missing return lock SABs");
     }
 };
-export const assertWorkerImportsResolved = ({ debug, list, ids, names, listOfFunctions }) => {
-    if (debug?.logImportedUrl === true) {
-        console.log(list);
-    }
+export const assertWorkerImportsResolved = ({ list, ids, names, listOfFunctions }) => {
     if (listOfFunctions.length > 0 &&
         (names === undefined || listOfFunctions.length === names.length))
         return;

package/src/worker/timers.js

@@ -50,7 +50,7 @@ const isPlainNodeWindows = runtimeGlobals.process?.platform === "win32" &&
 // 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.
-const nativeWaitTimeoutMs = (parkMs) => isPlainNodeWindows ? 1 : parkMs ?? 60;
+const nativeWaitTimeoutMs = (parkMs) => isPlainNodeWindows ? 1 : Number.isFinite(parkMs) ? parkMs : 60;
 export const whilePausing = ({ pauseInNanoseconds }) => {
     const forNanoseconds = pauseInNanoseconds ?? DEFAULT_PAUSE_TIME;
     if (!a_pause || forNanoseconds <= 0)
@@ -101,10 +101,15 @@ 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 ?? 60);
         }
         else if (a_wait && waitFallbackView) {
-            a_wait(waitFallbackView, 0, 0, parkMs ?? 1);
+            // waitFallbackView is never notified — this wait only ever times out and
+            // re-polls, so it must stay finite or the worker would hang forever.
+            a_wait(waitFallbackView, 0, 0, Number.isFinite(parkMs) ? parkMs : 1);
         }
         a_store(rxStatus, 0, 1);
     };

package/unsafe.d.ts

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

package/unsafe.js

@@ -0,0 +1 @@
+export { BUFFER_REFERENCE_CODEC_ID, BUFFER_REFERENCE_KIND, BufferReference, BufferReferenceReturn, isBufferReferenceMetadata, } from "./src/connections/buffer-reference.js";

package/utils.d.ts

@@ -0,0 +1 @@
+export { type BufferLike, bufferToBytes, bufferToJson, bufferToNumbers, bufferToString, bytesToBuffer, jsonToBuffer, type NumberBufferOptions, type NumberFormat, numbersToBuffer, stringToBuffer, } from "./src/utils/http.js";

package/utils.js

@@ -0,0 +1 @@
+export { bufferToBytes, bufferToJson, bufferToNumbers, bufferToString, bytesToBuffer, jsonToBuffer, numbersToBuffer, stringToBuffer, } from "./src/utils/http.js";