knitting 0.1.52 → 0.1.54

package/src/utils/http.d.ts

@@ -3,13 +3,21 @@ export type NumberFormat = "f64" | "f32" | "i32";
 export type NumberBufferOptions = {
     format?: NumberFormat;
 };
+/** View ArrayBuffer/SharedArrayBuffer/typed-array bytes as Uint8Array. */
 export declare const bufferToBytes: (source: BufferLike) => Uint8Array;
+/** Copy bytes into a SharedArrayBuffer for zero-copy worker inputs. */
 export declare const bytesToBuffer: (source: BufferLike) => SharedArrayBuffer;
+/** Decode UTF-8 bytes from ArrayBuffer/SharedArrayBuffer/typed-array input. */
 export declare const bufferToString: (source: BufferLike) => string;
+/** Encode UTF-8 text into a SharedArrayBuffer. */
 export declare const stringToBuffer: (text: string) => SharedArrayBuffer;
+/** Decode JSON from UTF-8 bytes. */
 export declare const bufferToJson: <T = unknown>(source: BufferLike) => T;
+/** Encode JSON into a SharedArrayBuffer. */
 export declare const jsonToBuffer: (value: unknown) => SharedArrayBuffer;
+/** Encode numbers into a SharedArrayBuffer (`f64` by default). */
 export declare const numbersToBuffer: (numbers: ArrayLike<number>, options?: NumberBufferOptions) => SharedArrayBuffer;
+/** Decode numeric typed-array views from worker-friendly byte buffers. */
 export declare function bufferToNumbers(source: BufferLike, options?: {
     format?: "f64";
 }): Float64Array;

package/src/utils/http.js

@@ -21,7 +21,9 @@ const toBytes = (source) => {
     }
     throw new TypeError("Expected an ArrayBuffer, SharedArrayBuffer, or typed-array view.");
 };
+/** View ArrayBuffer/SharedArrayBuffer/typed-array bytes as Uint8Array. */
 export const bufferToBytes = (source) => toBytes(source);
+/** Copy bytes into a SharedArrayBuffer for zero-copy worker inputs. */
 export const bytesToBuffer = (source) => {
     const bytes = toBytes(source);
     const sab = new SharedArrayBuffer(bytes.byteLength);
@@ -38,6 +40,7 @@ const makeNumberView = (format, buffer, byteOffset, length) => {
             return new Int32Array(buffer, byteOffset, length);
     }
 };
+/** Decode UTF-8 bytes from ArrayBuffer/SharedArrayBuffer/typed-array input. */
 export const bufferToString = (source) => {
     const bytes = toBytes(source);
     if (hasNodeBuffer) {
@@ -47,6 +50,7 @@ export const bufferToString = (source) => {
     }
     return textDecoder.decode(bytes);
 };
+/** Encode UTF-8 text into a SharedArrayBuffer. */
 export const stringToBuffer = (text) => {
     if (typeof text !== "string") {
         throw new TypeError("stringToBuffer expects a string.");
@@ -62,7 +66,9 @@ export const stringToBuffer = (text) => {
     new Uint8Array(sab).set(encoded);
     return sab;
 };
+/** Decode JSON from UTF-8 bytes. */
 export const bufferToJson = (source) => JSON.parse(bufferToString(source));
+/** Encode JSON into a SharedArrayBuffer. */
 export const jsonToBuffer = (value) => {
     const text = JSON.stringify(value);
     if (typeof text !== "string") {
@@ -70,6 +76,7 @@ export const jsonToBuffer = (value) => {
     }
     return stringToBuffer(text);
 };
+/** Encode numbers into a SharedArrayBuffer (`f64` by default). */
 export const numbersToBuffer = (numbers, options) => {
     const format = options?.format ?? "f64";
     const sab = new SharedArrayBuffer(numbers.length * BYTES_PER_ELEMENT[format]);

package/src/worker/loop.js

@@ -13,6 +13,7 @@ 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);
@@ -72,6 +73,14 @@ export const workerMainLoop = async (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";
@@ -82,7 +91,6 @@ export const workerMainLoop = async (startupData) => {
         },
         isMain: false,
         thread,
-        debug,
         startTime: startAt,
     });
     const lockState = lock2({
@@ -106,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 })
@@ -123,6 +133,7 @@ export const workerMainLoop = async (startupData) => {
         thread,
         totalNumberOfThread,
     });
+    dbg?.envPhase("bootstrap");
     const listOfFunctions = await getFunctions({
         list,
         isWorker: true,
@@ -131,7 +142,9 @@ 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,
@@ -170,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;
@@ -195,15 +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;
@@ -234,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);
             }
         }
     };
@@ -249,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/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 : Infinity;
 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) {
-            a_wait(opView, at, value, parkMs ?? 60);
+            // 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);
         }
         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 : Infinity);
         }
         a_store(rxStatus, 0, 1);
     };