knitting 0.1.63 → 0.1.73

package/src/runtime/deno-doorbell.js

@@ -0,0 +1,117 @@
+import { RUNTIME } from "../common/runtime.js";
+const getDeno = () => globalThis.Deno;
+/**
+ * Creates Deno's native thread-to-event-loop bridge without loading a custom
+ * library. `threadSafe()` is essential: ordinary UnsafeCallbacks may be
+ * called cross-thread, but do not wake an idle Deno event loop.
+ *
+ * The default pool configuration asks Deno for FFI permission once, so the
+ * native wake path is used whenever the caller approves it. `--allow-ffi`
+ * skips the prompt; `--deny-ffi`, `--no-prompt`, or a rejection preserves the
+ * portable polling dispatcher. Set `host.doorbell` to `false` to avoid asking.
+ */
+export const createDenoCompletionDoorbell = () => {
+    if (RUNTIME !== "deno")
+        return undefined;
+    const deno = getDeno();
+    const queryPermission = deno?.permissions?.querySync;
+    const requestPermission = deno?.permissions?.requestSync;
+    const Callback = deno?.UnsafeCallback;
+    const pointerValue = deno?.UnsafePointer?.value;
+    if (typeof queryPermission !== "function" ||
+        typeof Callback?.threadSafe !== "function" ||
+        typeof pointerValue !== "function") {
+        return undefined;
+    }
+    // `querySync` avoids a redundant prompt for an already granted or explicitly
+    // denied capability. Only the normal `prompt` state asks, and a refusal
+    // leaves the portable polling path intact.
+    try {
+        let state = queryPermission({ name: "ffi" }).state;
+        if (state === "prompt" && typeof requestPermission === "function") {
+            state = requestPermission({ name: "ffi" }).state;
+        }
+        if (state !== "granted")
+            return undefined;
+    }
+    catch {
+        return undefined;
+    }
+    const listeners = new Map();
+    let closed = false;
+    let callback;
+    try {
+        callback = Callback.threadSafe({ parameters: ["i32"], result: "void" }, (lane) => {
+            if (closed)
+                return;
+            try {
+                listeners.get(lane)?.();
+            }
+            catch {
+                // FFI callbacks must never propagate an exception into the worker
+                // thread that rang them. The dispatcher watchdog remains a final
+                // liveness backstop if a host pump has already been closed.
+            }
+        });
+        const pointer = pointerValue(callback.pointer);
+        if (typeof pointer !== "bigint" || pointer === 0n) {
+            callback.close();
+            return undefined;
+        }
+        return {
+            pointer,
+            listen: (lane, notify) => {
+                if (!closed)
+                    listeners.set(lane, notify);
+            },
+            unref: () => {
+                try {
+                    callback.unref?.();
+                }
+                catch {
+                    // best effort; a runtime may already be tearing down its callback
+                }
+            },
+            close: () => {
+                if (closed)
+                    return;
+                closed = true;
+                listeners.clear();
+                callback.close();
+            },
+        };
+    }
+    catch {
+        // Creating a callback is native code. Treat an unsupported Deno build just
+        // like a denied FFI capability and keep the portable poll path.
+        try {
+            callback?.close();
+        }
+        catch {
+            // best effort; callback may not have been initialized
+        }
+        return undefined;
+    }
+};
+/**
+ * Reconstruct a host-owned thread-safe callback in a Deno worker. The pointer
+ * stays process-local and is never included in process-worker boot payloads.
+ */
+export const createDenoCompletionNotifier = (pointer) => {
+    if (RUNTIME !== "deno" || pointer === undefined || pointer === 0n) {
+        return undefined;
+    }
+    const deno = getDeno();
+    const FnPointer = deno?.UnsafeFnPointer;
+    const pointerCreate = deno?.UnsafePointer?.create;
+    if (typeof FnPointer !== "function" || typeof pointerCreate !== "function") {
+        return undefined;
+    }
+    try {
+        const callback = new FnPointer(pointerCreate(pointer), { parameters: ["i32"], result: "void" });
+        return (lane) => callback.call(lane);
+    }
+    catch {
+        return undefined;
+    }
+};

package/src/runtime/dispatcher.d.ts

@@ -2,20 +2,30 @@ import { type MultiQueue } from "./tx-queue.js";
 import { type MainSignal } from "../ipc/transport/shared-memory.js";
 import { type RuntimeMessageChannelLike, type RuntimeMessagePortLike } from "../common/worker-runtime.js";
 import type { DispatcherSettings } from "../types.js";
-export declare const hostDispatcherLoop: ({ signalBox: { opView, txStatus, rxStatus, }, queue: { completeFrame, hasPendingFrames, flushToWorker, txIdle, waitForCompletion, setCompletionWaiterArmed, }, channelHandler, dispatcherOptions, notifySignal, crossProcess, }: {
+export declare const hostDispatcherLoop: ({ signalBox: { opView, txStatus, rxStatus, }, queue: { completeFrame, hasPendingFrames, flushToWorker, txIdle, waitForCompletion, armCompletionNotifier, setCompletionWaiterArmed, }, channelHandler, dispatcherOptions, notifySignal, wakeAfterPass, crossProcess, nativeCompletionDoorbell, processCompletionDoorbell, }: {
     queue: MultiQueue;
     signalBox: MainSignal;
     channelHandler: ChannelHandler;
     dispatcherOptions?: DispatcherSettings;
     notifySignal?: () => void;
-    /** Workers live in other processes; disables the doorbell. */
+    /**
+     * Runs at the end of every drain pass. Defaults to waking this lane's worker
+     * if it is parked; a shared queue supplies its own policy.
+     */
+    wakeAfterPass?: () => void;
+    /** Workers live in other processes; disables only the atomic doorbell. */
     crossProcess?: boolean;
+    /** A runtime-native completion ring that wakes the host event loop. */
+    nativeCompletionDoorbell?: boolean;
+    /** A process IPC completion doorbell that wakes the host event loop. */
+    processCompletionDoorbell?: boolean;
 }) => {
     check: {
         (): void;
         isRunning: boolean;
         rerun: boolean;
     };
+    wakeCompletion: () => void;
 };
 type CheckWithState = (() => void) & {
     isRunning: boolean;
@@ -30,10 +40,7 @@ export declare class ChannelHandler {
     port2: RuntimeMessagePortLike | undefined;
     constructor(pump?: ChannelHandlerPump);
     notify(): void;
-    /**
-     * Registers the handler the pump calls back into. On the channel pump this is
-     * also where the ports are opened, so `notify` can reach port 1.
-     */
+    /** Register the pump handler and start channel ports when present. */
     open(f: () => void): void;
     /**
      * Detaches the handler, and closes the channel if this pump has one.

package/src/runtime/dispatcher.js

@@ -1,36 +1,15 @@
 import { createRuntimeMessageChannel, } from "../common/worker-runtime.js";
 import { RUNTIME, SET_IMMEDIATE } from "../common/runtime.js";
-/**
- * Macrotask primitive for the host pump, picked per runtime: a round trip costs
- * 757ns on Bun via MessageChannel but 4662ns on Deno, where `setImmediate` is
- * 1110ns. Bun keeps the channel; browser and Andromeda have no choice.
- *
- * `serial-channel` opts back into the channel explicitly (see `src/api.ts`): one
- * hop drives every lane's check in turn and relies on the channel's delivery to
- * do it, so a merely cheaper pump starves it -- it cost 25% throughput there.
- */
+/** Runtime-specific macrotask primitive used by the host dispatcher. */
 const IMMEDIATE_PUMP = RUNTIME === "deno" || RUNTIME === "node"
     ? SET_IMMEDIATE
     : undefined;
-/**
- * Free drain hops before `scheduleNotify` stops re-arming the pump for free.
- *
- * The window has to match what the dispatcher escalates *to*, so these are
- * chosen together and `canUseDoorbell` picks between them. Polling escalates to
- * the `setTimeout` ladder, whose finest rung is ~1.1ms on every runtime, so it
- * wants a wide window; that sleep is also load-bearing, since it batches
- * completions. A doorbell escalates to `Atomics.waitAsync` at about the price of
- * one hop, so it wants a narrow one.
- *
- * Mixing them is the trap: a doorbell behind the wide window keeps every poll
- * hop *and* adds the arm, and loses to plain polling at every thread count.
- * Measurements behind both values: `docs/host-doorbell-proposal.md`.
- */
+// Polling tolerates a wider free window; a doorbell should arm promptly.
 const POLL_STALL_FREE_LOOPS = 128;
 const DOORBELL_STALL_FREE_LOOPS = 1;
-export const hostDispatcherLoop = ({ signalBox: { opView, txStatus, rxStatus, }, queue: { completeFrame, hasPendingFrames, flushToWorker, txIdle, waitForCompletion, setCompletionWaiterArmed, }, channelHandler, dispatcherOptions, notifySignal, crossProcess, }) => {
+export const hostDispatcherLoop = ({ signalBox: { opView, txStatus, rxStatus, }, queue: { completeFrame, hasPendingFrames, flushToWorker, txIdle, waitForCompletion, armCompletionNotifier, setCompletionWaiterArmed, }, channelHandler, dispatcherOptions, notifySignal, wakeAfterPass, crossProcess, nativeCompletionDoorbell, processCompletionDoorbell, }) => {
+    const a_add = Atomics.add;
     const a_load = Atomics.load;
-    const a_store = Atomics.store;
     const a_notify = Atomics.notify;
     const canNotifySignal = opView.buffer instanceof SharedArrayBuffer;
     const wakeSignal = notifySignal ??
@@ -38,15 +17,25 @@ export const hostDispatcherLoop = ({ signalBox: { opView, txStatus, rxStatus, },
             if (canNotifySignal)
                 a_notify(opView, 0, 1);
         });
+    // Bump rather than store a constant: the worker parks on the value it last
+    // read, so only a changed word makes a ring that lands before its wait count.
+    const wakeLane = () => {
+        a_add(opView, 0, 1);
+        wakeSignal();
+    };
+    const wakeIfParked = wakeAfterPass ?? (() => {
+        if (a_load(rxStatus, 0) === 0)
+            wakeLane();
+    });
     const notify = () => channelHandler.notify();
-    // `crossProcess` is a capability, not a preference, so it overrides an
-    // explicit `doorbell: true`: V8's Atomics waiter list is per isolate, so a
-    // worker in another process can never ring the host's waiter, and an armed
-    // doorbell would just sleep to the watchdog.
-    const canUseDoorbell = crossProcess !== true &&
-        (dispatcherOptions?.doorbell ?? true) &&
-        (RUNTIME === "bun" || RUNTIME === "node") &&
+    // Atomics waiters are process-local, so cross-process workers cannot use this
+    // doorbell.
+    const canUseAtomicDoorbell = (RUNTIME === "bun" || RUNTIME === "node") &&
         typeof Atomics.waitAsync === "function";
+    const canUseDoorbell = (dispatcherOptions?.doorbell ?? true) &&
+        (processCompletionDoorbell === true ||
+            (crossProcess !== true &&
+                (canUseAtomicDoorbell || nativeCompletionDoorbell === true)));
     let doorbellEnabled = canUseDoorbell;
     let doorbellArmed = false;
     let doorbellEpoch = 0 | 0;
@@ -80,24 +69,55 @@ export const hostDispatcherLoop = ({ signalBox: { opView, txStatus, rxStatus, },
         doorbellEpoch = token;
         doorbellArmed = true;
         let woke = false;
-        const wake = () => {
+        const wake = (direct = false) => {
             if (!doorbellArmed || doorbellEpoch !== token || woke)
                 return;
             woke = true;
             doorbellArmed = false;
             doorbellEpoch = (doorbellEpoch + 1) | 0;
             setCompletionWaiterArmed(false);
+            if (direct) {
+                // A native arm that observes an already-published completion has no
+                // callback to wait for. Drain it now: routing this known result back
+                // through setImmediate recreates the very millisecond-sized hop that
+                // the native doorbell exists to remove.
+                check.isRunning = true;
+                check();
+                return;
+            }
             // Keep the existing macrotask boundary. Calling check directly from a
             // resolved waitAsync promise can chain microtasks under a hot workload
             // and starve host I/O.
             notify();
         };
         let supported = false;
-        try {
-            supported = waitForCompletion(wake, DOORBELL_WATCHDOG_MS);
+        if (nativeCompletionDoorbell === true ||
+            processCompletionDoorbell === true) {
+            // A native arm reports two different things and they must not be
+            // conflated: `false` means a completion was already published so the arm
+            // deliberately did not ring, which is a normal hot-path outcome. Only a
+            // throw means the transport is unusable. Treating the race as
+            // "unsupported" disabled the doorbell permanently on its second arm.
+            let armed = false;
+            let usable = true;
+            try {
+                armed = armCompletionNotifier();
+            }
+            catch {
+                usable = false;
+            }
+            supported = usable;
+            // The arm itself drains the completion it just observed.
+            if (usable && !armed)
+                wake(true);
         }
-        catch {
-            supported = false;
+        else {
+            try {
+                supported = waitForCompletion(wake, DOORBELL_WATCHDOG_MS);
+            }
+            catch {
+                supported = false;
+            }
         }
         // Some runtimes reject waitAsync on their SharedArrayBuffer variants; fall
         // back to polling rather than hanging the pool.
@@ -111,7 +131,9 @@ export const hostDispatcherLoop = ({ signalBox: { opView, txStatus, rxStatus, },
             doorbellArmed = false;
             doorbellEpoch = (doorbellEpoch + 1) | 0;
             setCompletionWaiterArmed(false);
-            notify();
+            if (nativeCompletionDoorbell !== true &&
+                processCompletionDoorbell !== true)
+                notify();
         }
     };
     const check = () => {
@@ -124,9 +146,7 @@ export const hostDispatcherLoop = ({ signalBox: { opView, txStatus, rxStatus, },
         // A waitAsync cannot be cancelled, so bumping its epoch makes the eventual
         // callback inert instead.
         cancelDoorbell();
-        // Idle lane: skip the drain. Otherwise it pays a txStatus write, an rxStatus
-        // load, and an Atomics.notify that wakes a parked worker for nothing — the
-        // waste that makes serial-channel latency grow with thread count.
+        // Avoid waking an idle lane.
         if (txIdle()) {
             check.isRunning = false;
             return;
@@ -139,15 +159,12 @@ export const hostDispatcherLoop = ({ signalBox: { opView, txStatus, rxStatus, },
         do {
             check.rerun = false;
             txStatus[0] = 1;
-            // Wake the worker before draining so it can start processing while we flush.
-            if (a_load(rxStatus, 0) === 0) {
-                a_store(opView, 0, 1);
-                wakeSignal();
-            }
-            // Local vars so V8 keeps them as unboxed int32. Only a reaped completion
-            // counts as progress for `stallCount`: the pump exists to notice work a
-            // worker cannot announce, and letting a flush reset the counter would
-            // leave the escalation unreachable for a pool that never runs dry.
+            // Wake a parked worker whenever its receive status is clear, so it is
+            // up by the time the frames land. Pending frames are not a reliable gate
+            // because the queue may have room.
+            if (a_load(rxStatus, 0) === 0)
+                wakeLane();
+            // Only completed frames count as progress for backoff purposes.
             let completed = false;
             let progressed = true;
             while (progressed) {
@@ -162,9 +179,18 @@ export const hostDispatcherLoop = ({ signalBox: { opView, txStatus, rxStatus, },
                     progressed = true;
                 }
             }
+            // The ring above was decided before the frames flushed here existed, and
+            // calls publish straight from enqueue without passing through this loop.
+            // A worker that parked in between saw neither the frames nor a ring and
+            // slept out its whole parkMs. Publishing ends in a seq-cst store and the
+            // worker re-checks after clearing rxStatus, so re-reading rxStatus after
+            // the pass means either the worker sees the frames or this sees it parked.
+            wakeIfParked();
             txStatus[0] = 0;
             if (!txIdle()) {
-                if (completed || hasPendingFrames()) {
+                // Queued frames indicate back-pressure, not progress; only a completion
+                // frees a request slot.
+                if (completed) {
                     stallCount = 0 | 0;
                 }
                 else {
@@ -182,6 +208,15 @@ export const hostDispatcherLoop = ({ signalBox: { opView, txStatus, rxStatus, },
     };
     check.isRunning = false;
     check.rerun = false;
+    /** Enter the drain from a native or IPC completion event. */
+    const wakeCompletion = () => {
+        if (inFlight || check.isRunning) {
+            check.rerun = true;
+            return;
+        }
+        check.isRunning = true;
+        check();
+    };
     const scheduleNotify = () => {
         if (stallCount <= stallFreeLoops) {
             notify();
@@ -213,7 +248,7 @@ export const hostDispatcherLoop = ({ signalBox: { opView, txStatus, rxStatus, },
             }
         }, delay);
     };
-    return { check };
+    return { check, wakeCompletion };
 };
 export class ChannelHandler {
     // Set only when the pump is a MessageChannel. The `setImmediate` pump has no
@@ -223,14 +258,16 @@ export class ChannelHandler {
     port2;
     #handler;
     #notify;
+    #pending = false;
+    #run = () => {
+        // Clear before draining so a busy lane can request the next turn.
+        this.#pending = false;
+        this.#handler?.();
+    };
     constructor(pump = "auto") {
         if (pump === "auto" && IMMEDIATE_PUMP !== undefined) {
             const immediate = IMMEDIATE_PUMP;
-            // Allocated once; the pump fires hundreds of thousands of times a second.
-            // Routing via `#handler` also makes a callback outliving `close()` inert.
-            const run = () => {
-                this.#handler?.();
-            };
+            const run = this.#run;
             this.#notify = () => {
                 immediate(run);
             };
@@ -246,23 +283,24 @@ export class ChannelHandler {
         };
     }
     notify() {
+        // Coalesce notifications into one pending drain.
+        if (this.#pending)
+            return;
+        this.#pending = true;
         this.#notify();
     }
-    /**
-     * Registers the handler the pump calls back into. On the channel pump this is
-     * also where the ports are opened, so `notify` can reach port 1.
-     */
+    /** Register the pump handler and start channel ports when present. */
     open(f) {
         this.#handler = f;
         const port1 = this.port1;
         if (port1 === undefined)
             return;
         if (typeof port1.on === "function") {
-            port1.on("message", f);
+            port1.on("message", this.#run);
         }
         else {
             // @ts-ignore
-            port1.onmessage = f;
+            port1.onmessage = this.#run;
         }
         this.port1?.start?.();
         this.port2?.start?.();

package/src/runtime/host-arg-arena.d.ts

@@ -0,0 +1,3 @@
+export type HostArgAllocator = (byteLength: number) => Uint8Array;
+/** Create an argument allocator with a plain-allocation fallback. */
+export declare const createHostArgAllocator: (payload: object | undefined) => HostArgAllocator;

package/src/runtime/host-arg-arena.js

@@ -0,0 +1,16 @@
+import { getSharedReturnAllocator } from "../memory/payloadCodec.js";
+/** Create an argument allocator with a plain-allocation fallback. */
+export const createHostArgAllocator = (payload) => {
+    const allocate = payload === undefined
+        ? undefined
+        : getSharedReturnAllocator(payload);
+    if (allocate === undefined) {
+        return (byteLength) => new Uint8Array(byteLength);
+    }
+    return (byteLength) => {
+        if (!Number.isInteger(byteLength) || byteLength < 0) {
+            throw new RangeError("sharedArgBytes(byteLength) requires a non-negative integer");
+        }
+        return allocate(byteLength, false) ?? new Uint8Array(byteLength);
+    };
+};

package/src/runtime/inline-executor.js

@@ -1,4 +1,5 @@
 import { withResolvers } from "../common/with-resolvers.js";
+import { KnittingError } from "../error.js";
 import RingQueue from "../ipc/tools/ring-queue.js";
 import { createRuntimeMessageChannel } from "../common/worker-runtime.js";
 // const objects, not `enum`s: Andromeda's Nova engine can't parse `enum`. Same
@@ -270,7 +271,7 @@ export const createInlineExecutor = ({ tasks, genTaskID, batchSize, }) => {
                 if (stateByIndex[index] !== SlotStateMacro.Pending)
                     continue;
                 try {
-                    deferredByIndex[index]?.reject("Thread closed");
+                    deferredByIndex[index]?.reject(new KnittingError("THREAD_CLOSED", "Thread closed"));
                 }
                 catch {
                 }

package/src/runtime/node-doorbell.d.ts

@@ -0,0 +1,14 @@
+export type NodeCompletionDoorbell = {
+    /** Process-local handle a Node thread worker may ring through the addon. */
+    pointer: bigint;
+    /** Invalidates the native handle after every worker that holds it has exited. */
+    close: () => void;
+};
+/**
+ * Bridge a Node worker thread into the host's libuv I/O phase. The addon owns
+ * the `uv_async_t`; this wrapper owns the JS callback and makes missing native
+ * prebuilds a normal capability fallback.
+ */
+export declare const createNodeCompletionDoorbell: (notify: () => void) => NodeCompletionDoorbell | undefined;
+/** Rebuild the process-local native ring in a Node thread worker. */
+export declare const createNodeCompletionNotifier: (pointer: bigint | undefined) => (() => void) | undefined;

package/src/runtime/node-doorbell.js

@@ -0,0 +1,84 @@
+import { RUNTIME } from "../common/runtime.js";
+import { getNodeBuiltinModule } from "../common/node-compat.js";
+import { loadNodeNativeAddon } from "../connections/node-addons.js";
+const loadDoorbellAddon = () => {
+    if (RUNTIME !== "node")
+        return undefined;
+    const nodeModule = getNodeBuiltinModule("node:module");
+    if (nodeModule === undefined)
+        return undefined;
+    try {
+        return loadNodeNativeAddon(nodeModule.createRequire(import.meta.url), "knitting_doorbell");
+    }
+    catch {
+        // Native wakeups are an optional fast path. A missing prebuild must retain
+        // the portable Atomics.waitAsync dispatcher rather than preventing plain
+        // thread workers from starting.
+        return undefined;
+    }
+};
+/**
+ * Bridge a Node worker thread into the host's libuv I/O phase. The addon owns
+ * the `uv_async_t`; this wrapper owns the JS callback and makes missing native
+ * prebuilds a normal capability fallback.
+ */
+export const createNodeCompletionDoorbell = (notify) => {
+    const addon = loadDoorbellAddon();
+    if (addon === undefined)
+        return undefined;
+    let pointer;
+    let closed = false;
+    try {
+        pointer = addon.createCompletionDoorbell(() => {
+            if (closed)
+                return;
+            try {
+                notify();
+            }
+            catch {
+                // An exception must not escape a libuv callback. A scheduled host
+                // drain or the dispatcher watchdog still provides a liveness backstop.
+            }
+        });
+        if (typeof pointer !== "bigint" || pointer === 0n)
+            return undefined;
+        // A dormant pool must not be kept alive solely by an idle uv_async_t.
+        addon.unrefCompletionDoorbell(pointer);
+    }
+    catch {
+        return undefined;
+    }
+    return {
+        pointer,
+        close: () => {
+            if (closed)
+                return;
+            closed = true;
+            try {
+                addon.closeCompletionDoorbell(pointer);
+            }
+            catch {
+                // Shutdown can race Node environment teardown; the addon's environment
+                // cleanup hook owns the remaining lifetime in that case.
+            }
+        },
+    };
+};
+/** Rebuild the process-local native ring in a Node thread worker. */
+export const createNodeCompletionNotifier = (pointer) => {
+    if (RUNTIME !== "node" || pointer === undefined || pointer === 0n) {
+        return undefined;
+    }
+    const addon = loadDoorbellAddon();
+    if (addon === undefined)
+        return undefined;
+    return () => {
+        try {
+            addon.ringCompletionDoorbell(pointer);
+        }
+        catch {
+            // The host can close while a forced worker teardown is in flight. Its
+            // return-lock watchdog covers that final in-flight publication.
+        }
+    };
+};