knitting 0.1.61 → 0.1.62

package/src/runtime/pool.d.ts

@@ -1,5 +1,5 @@
 import { createHostTxQueue } from "./tx-queue.js";
-import { type ProcessSharedMemoryBacking } from "./process-worker.js";
+import { type ProcessSharedMemoryBacking, type ProcessStealMemoryLayout, type ResolvedProcessSharedMemorySettings } from "./process-worker.js";
 import { type Sab } from "../ipc/transport/shared-memory.js";
 import { ChannelHandler, type DispatcherCheck } from "./dispatcher.js";
 import { lock2, type Task } from "../memory/lock.js";
@@ -20,12 +20,16 @@ import { type PayloadBufferOptions } from "../memory/payload-config.js";
 export declare const resolveStealRegionLanes: (consumers: number) => number;
 /** Maximum claimants that leave the protocol's required spare region. */
 export declare const MAX_STEAL_CONSUMERS: number;
-export declare const createStealPoolBuffers: ({ threads, payload, regionLanes, abortSignalCapacity, usesAbortSignal, }: {
+export declare const createStealPoolBuffers: ({ threads, payload, regionLanes, abortSignalCapacity, usesAbortSignal, processWorker, }: {
     threads: number;
     payload?: PayloadBufferOptions;
     regionLanes?: number;
     abortSignalCapacity?: number;
     usesAbortSignal?: boolean;
+    processWorker?: {
+        signalBytes: number;
+        sharedMemory: ResolvedProcessSharedMemorySettings;
+    };
 }) => {
     submitBuffers: LockBuffers;
     returnBuffers: LockBuffers[];
@@ -48,6 +52,8 @@ export declare const createStealPoolBuffers: ({ threads, payload, regionLanes, a
             shouldSettle?: (task: Task) => boolean;
             activeRejectPlaceholder?: Task["reject"];
         }) => () => number;
+        waitForHostChange: (timeoutMs?: number) => import("../memory/lock.js").WaitAsyncResult | undefined;
+        setHostWaiterArmed: (armed: boolean) => void;
         hasPendingFrames: () => boolean;
         getPendingFrameCount: () => number;
         getPendingPromiseCount: () => number;
@@ -75,6 +81,8 @@ export declare const createStealPoolBuffers: ({ threads, payload, regionLanes, a
             shouldSettle?: (task: Task) => boolean;
             activeRejectPlaceholder?: Task["reject"];
         }) => () => number;
+        waitForHostChange: (timeoutMs?: number) => import("../memory/lock.js").WaitAsyncResult | undefined;
+        setHostWaiterArmed: (armed: boolean) => void;
         hasPendingFrames: () => boolean;
         getPendingFrameCount: () => number;
         getPendingPromiseCount: () => number;
@@ -88,6 +96,8 @@ export declare const createStealPoolBuffers: ({ threads, payload, regionLanes, a
         hasPendingFrames: () => boolean;
         txIdle: () => boolean;
         completeFrame: () => number;
+        waitForCompletion: (onWake: () => void, timeoutMs?: number) => boolean;
+        setCompletionWaiterArmed: (armed: boolean) => void;
         setReturnHooks: (lane: number, hooks: (import("../connections/buffer-reference.js").BufferReferenceReturnHooks | ((token: bigint) => void)) | undefined) => void;
         enqueue: (functionID: number, timeout?: import("../types.js").TaskTimeout, abortSignal?: import("../types.js").AbortSignalOption) => (rawArgs: unknown) => Promise<never> | import("../common/with-resolvers.js").PromiseWithMaybeReject<unknown>;
         flushToWorker: () => boolean;
@@ -95,7 +105,8 @@ export declare const createStealPoolBuffers: ({ threads, payload, regionLanes, a
         settlePromisePayload: (task: Task, isRejected: boolean, value: unknown) => boolean;
     };
     regionLanes: number;
-    abortSignalSAB: SharedArrayBuffer;
+    processMemory: ProcessStealMemoryLayout;
+    abortSignalSAB: SharedArrayBuffer | import("../types.js").SharedBufferRegion;
     abortSignalMax: number;
 };
 export declare const spawnWorkerContext: ({ list, ids, names, sab, thread, debug, hostDebug, totalNumberOfThread, source, at, workerOptions, workerExecArgv, permission, host, payload, bufferReferenceReturn, abortSignalCapacity, usesAbortSignal, sharedChannelHandler, stealPool, }: {
@@ -140,6 +151,7 @@ export declare const spawnWorkerContext: ({ list, ids, names, sab, thread, debug
         regionLanes: number;
         abortSignalSAB?: LockBuffers["headers"];
         abortSignalMax?: number;
+        processMemory?: ProcessStealMemoryLayout;
     };
 }) => (WorkerContext & {
     dispatcherCheck?: never;

package/src/runtime/pool.js

@@ -1,5 +1,5 @@
 import { createHostTxQueue } from "./tx-queue.js";
-import { cleanupProcessWorkerMemoryQuietly, createProcessSharedMemoryAllocator, createProcessWorkerMemoryLayout, createProcessWorkerNativeSignalNotifier, readProcessSharedMemorySettings, readProcessWorkerCommandPrefix, readProcessWorkerRuntime, spawnProcessWorker, toProcessWorkerBootPayload, } from "./process-worker.js";
+import { cleanupProcessWorkerMemoryQuietly, createProcessSharedMemoryAllocator, createProcessStealMemoryLayout, createProcessWorkerMemoryLayout, createProcessWorkerNativeSignalNotifier, readProcessSharedMemorySettings, readProcessWorkerCommandPrefix, readProcessWorkerRuntime, spawnProcessWorker, toProcessWorkerBootPayload, } from "./process-worker.js";
 import { serializeWorkerBootstrapData, terminateWorkerQuietly, toWorkerCompatExecArgv, toWorkerSafeExecArgv, } from "./worker-common.js";
 import { createSharedMemoryTransport, TRANSPORT_SIGNAL_BYTES, } from "../ipc/transport/shared-memory.js";
 import { ChannelHandler, hostDispatcherLoop, } from "./dispatcher.js";
@@ -8,7 +8,7 @@ import { HEADER_SLOT_STRIDE_U32, lock2, LOCK_SECTOR_BYTE_LENGTH, LockBound, } fr
 // see lock.ts). Must run before any lock2() call.
 import "../memory/payloadCodec.js";
 import "../worker/loop.js";
-import { createSharedArrayBuffer, createWasmSharedArrayBuffer, IS_BROWSER, } from "../common/runtime.js";
+import { createSharedArrayBuffer, createWasmSharedArrayBuffer, IS_BROWSER, RUNTIME, } from "../common/runtime.js";
 import { HAS_NODE_WORKER_THREADS, RUNTIME_WORKER, } from "../common/worker-runtime.js";
 import { probeLockBufferTextCompat } from "../common/shared-buffer-text.js";
 import { signalAbortFactory } from "../shared/abortSignal.js";
@@ -67,8 +67,11 @@ export const resolveStealRegionLanes = (consumers) => {
 };
 /** Maximum claimants that leave the protocol's required spare region. */
 export const MAX_STEAL_CONSUMERS = LockBound.slots - 1;
-export const createStealPoolBuffers = ({ threads, payload, regionLanes, abortSignalCapacity, usesAbortSignal, }) => {
-    const payloadConfig = resolvePayloadBufferOptions({ options: payload });
+export const createStealPoolBuffers = ({ threads, payload, regionLanes, abortSignalCapacity, usesAbortSignal, processWorker, }) => {
+    const basePayloadConfig = resolvePayloadBufferOptions({ options: payload });
+    const payloadConfig = processWorker === undefined
+        ? basePayloadConfig
+        : withFixedPayloadConfig(basePayloadConfig);
     const makePayload = () => payloadConfig.mode === "growable"
         ? createSharedArrayBuffer(payloadConfig.payloadInitialBytes, payloadConfig.payloadMaxByteLength)
         : createSharedArrayBuffer(payloadConfig.payloadInitialBytes);
@@ -92,8 +95,25 @@ export const createStealPoolBuffers = ({ threads, payload, regionLanes, abortSig
     const lanes = regionLanes === undefined
         ? maxLanes
         : Math.min(Math.max(1, regionLanes | 0), maxLanes);
-    const submitCarpet = carpet();
-    const submitBuffers = toBuffers(submitCarpet.lock, makePayload());
+    const resolvedAbortSignalCapacity = resolveAbortSignalCapacity(abortSignalCapacity);
+    const processMemory = processWorker === undefined ? undefined : createProcessStealMemoryLayout({
+        threads,
+        signalBytes: processWorker.signalBytes,
+        abortBytes: usesAbortSignal === true
+            ? abortSignalByteLength(resolvedAbortSignalCapacity)
+            : 0,
+        abortSignalMax: usesAbortSignal === true
+            ? resolvedAbortSignalCapacity
+            : undefined,
+        payloadBytes: payloadConfig.payloadMaxByteLength,
+        sharedMemory: processWorker.sharedMemory,
+    });
+    const submitBuffers = processMemory === undefined
+        ? (() => {
+            const submitCarpet = carpet();
+            return toBuffers(submitCarpet.lock, makePayload());
+        })()
+        : toBuffers(processMemory.workers[0].controlLayout.lock, processMemory.workers[0].lockPayload);
     const hostSubmitLock = lock2({
         headers: submitBuffers.headers,
         headerSlotStrideU32: submitBuffers.headerSlotStrideU32,
@@ -104,11 +124,14 @@ export const createStealPoolBuffers = ({ threads, payload, regionLanes, abortSig
         textCompat: submitBuffers.textCompat,
         consumers: threads,
         regionLanes: lanes,
+        processBoundary: processMemory !== undefined,
     });
     const returnBuffers = [];
     const hostReturnLocks = [];
     for (let i = 0; i < threads; i++) {
-        const buffers = toBuffers(carpet().returnLock, makePayload());
+        const buffers = processMemory === undefined
+            ? toBuffers(carpet().returnLock, makePayload())
+            : toBuffers(processMemory.workers[i].controlLayout.returnLock, processMemory.workers[i].returnPayload);
         returnBuffers.push(buffers);
         hostReturnLocks.push(lock2({
             headers: buffers.headers,
@@ -118,14 +141,15 @@ export const createStealPoolBuffers = ({ threads, payload, regionLanes, abortSig
             payloadSector: buffers.payloadSector,
             payloadConfig,
             textCompat: buffers.textCompat,
+            processBoundary: processMemory !== undefined,
         }));
     }
     // Abort-aware tasks can execute on any claimant, so all workers and the
     // pool-global queue must observe one bitmap. Per-lane abort buffers would
     // encode an id from one allocator and test it against another lane's bits.
-    const resolvedAbortSignalCapacity = resolveAbortSignalCapacity(abortSignalCapacity);
     const abortSignalSAB = usesAbortSignal === true
-        ? createSharedArrayBuffer(abortSignalByteLength(resolvedAbortSignalCapacity))
+        ? processMemory?.workers[0]?.controlLayout.abortSignals ??
+            createSharedArrayBuffer(abortSignalByteLength(resolvedAbortSignalCapacity))
         : undefined;
     const abortSignals = abortSignalSAB === undefined
         ? undefined
@@ -146,10 +170,10 @@ export const createStealPoolBuffers = ({ threads, payload, regionLanes, abortSig
         hostReturnLocks,
         sharedQueue,
         regionLanes: lanes,
+        processMemory,
         abortSignalSAB,
-        abortSignalMax: abortSignalSAB === undefined
-            ? undefined
-            : resolvedAbortSignalCapacity,
+        abortSignalMax: processMemory?.abortSignalMax ??
+            (abortSignalSAB === undefined ? undefined : resolvedAbortSignalCapacity),
     };
 };
 export const spawnWorkerContext = ({ list, ids, names, sab, thread, debug, hostDebug, totalNumberOfThread, source, at, workerOptions, workerExecArgv, permission, host, payload, bufferReferenceReturn, abortSignalCapacity, usesAbortSignal, sharedChannelHandler, stealPool, }) => {
@@ -205,15 +229,25 @@ export const spawnWorkerContext = ({ list, ids, names, sab, thread, debug, hostD
     const abortBytes = stealPool === undefined && usesAbortSignal === true
         ? abortSignalByteLength(resolvedAbortSignalCapacity)
         : 0;
-    const processWorkerMemory = useProcessWorkerRuntime
-        ? createProcessWorkerMemoryLayout({
-            signalBytes,
-            abortBytes,
-            payloadBytes: resolvedPayloadConfig.payloadMaxByteLength,
-            thread,
-            sharedMemory: processSharedMemorySettings,
-        })
-        : undefined;
+    // A stealing process pool carves every lane out of one mapping, so lane
+    // `thread` must find its slice there. Falling back to a private layout would
+    // silently give this lane its own submit region — it would boot and then
+    // never see a task the host published to the shared one.
+    const stealProcessMemory = stealPool?.processMemory;
+    const processWorkerMemory = !useProcessWorkerRuntime
+        ? undefined
+        : stealProcessMemory === undefined
+            ? createProcessWorkerMemoryLayout({
+                signalBytes,
+                abortBytes,
+                payloadBytes: resolvedPayloadConfig.payloadMaxByteLength,
+                thread,
+                sharedMemory: processSharedMemorySettings,
+            })
+            : stealProcessMemory.workers[thread] ??
+                (() => {
+                    throw new RangeError(`stealing process pool has no shared-memory slice for worker ${thread}`);
+                })();
     const processSharedMemory = processWorkerMemory === undefined
         ? createProcessSharedMemoryAllocator(debug)
         : undefined;
@@ -401,6 +435,7 @@ export const spawnWorkerContext = ({ list, ids, names, sab, thread, debug, hostD
             channelHandler: ownChannel,
             dispatcherOptions: host,
             notifySignal: nativeNotifySignal,
+            crossProcess: useProcessWorkerRuntime,
         });
     if (ownsChannel && dispatcherCheck !== undefined) {
         ownChannel.open(dispatcherCheck);
@@ -442,6 +477,12 @@ export const spawnWorkerContext = ({ list, ids, names, sab, thread, debug, hostD
         payloadConfig: resolvedPayloadConfig,
         bufferReferenceReturn,
         permission,
+        // Mirrors the dispatcher's `canUseDoorbell`: a cross-process worker cannot
+        // ring the host's waiter, so do not make it pay the atomic op.
+        notifyOnHostPublish: !useProcessWorkerRuntime &&
+            host?.doorbell !== false &&
+            (RUNTIME === "bun" || RUNTIME === "node") &&
+            typeof Atomics.waitAsync === "function",
         steal: stealPool === undefined ? undefined : {
             consumers: stealPool.consumers,
             consumerId: stealPool.consumerId,
@@ -601,7 +642,9 @@ export const spawnWorkerContext = ({ list, ids, names, sab, thread, debug, hostD
         call,
         kills: async () => {
             markWorkerClosed("Thread closed", true);
-            terminateWorkerQuietly(worker);
+            const termination = terminateWorkerQuietly(worker);
+            if (processWorkerMemory !== undefined)
+                await termination;
             cleanupProcessWorkerMemoryQuietly(processWorkerMemory);
         },
         lock,

package/src/runtime/process-worker.d.ts

@@ -29,6 +29,20 @@ export type ProcessWorkerMemoryLayout = {
     returnPayload: SharedBufferSource;
     cleanup: () => void;
 };
+/**
+ * Process-worker memory for a stealing pool.
+ *
+ * The request side is one shared region all child processes may claim from;
+ * each worker keeps its own signals and return region. Every per-worker view
+ * points into the same OS mapping so the existing fd/name boot protocol can
+ * carry all of the slices without adding a second descriptor to WorkerData.
+ */
+export type ProcessStealMemoryLayout = {
+    mapping: SharedMemoryMapping<SharedMemoryBuffer>;
+    descriptor: FileDescriptor;
+    workers: ProcessWorkerMemoryLayout[];
+    abortSignalMax?: number;
+};
 export type ProcessWorkerRuntime = "bun" | "deno" | "node";
 export type ProcessWorkerCommandPrefix = NonNullable<WorkerSettings["processCommandPrefix"]>;
 export type ResolvedProcessSharedMemorySettings = {
@@ -61,6 +75,14 @@ export declare const createProcessWorkerMemoryLayout: ({ signalBytes, abortBytes
     thread: number;
     sharedMemory: ResolvedProcessSharedMemorySettings;
 }) => ProcessWorkerMemoryLayout;
+export declare const createProcessStealMemoryLayout: ({ threads, signalBytes, abortBytes, abortSignalMax, payloadBytes, sharedMemory, }: {
+    threads: number;
+    signalBytes: number;
+    abortBytes: number;
+    abortSignalMax?: number;
+    payloadBytes: number;
+    sharedMemory: ResolvedProcessSharedMemorySettings;
+}) => ProcessStealMemoryLayout;
 export declare const toProcessWorkerBootPayload: (workerData: WorkerData, memory: ProcessWorkerMemoryLayout) => ProcessWorkerBootPayload;
 export declare const readProcessWorkerRuntime: (options: WorkerSettings | undefined) => ProcessWorkerRuntime;
 export declare const readProcessWorkerCommandPrefix: (options: WorkerSettings | undefined) => ProcessWorkerCommandPrefix | undefined;

package/src/runtime/process-worker.js

@@ -191,6 +191,106 @@ export const createProcessWorkerMemoryLayout = ({ signalBytes, abortBytes, paylo
         },
     };
 };
+export const createProcessStealMemoryLayout = ({ threads, signalBytes, abortBytes, abortSignalMax, payloadBytes, sharedMemory, }) => {
+    if (!Number.isInteger(threads) || threads < 2) {
+        throw new RangeError("process stealing needs at least two workers");
+    }
+    const carpet = createByteCarpet();
+    const requestLockSlice = carpet.take("requestLockSector", LOCK_SECTOR_BYTE_LENGTH);
+    const requestHeadersSlice = carpet.take("requestHeaders", getHeaderBlockByteLength({
+        slotCount: LockBound.slots,
+        slotStrideU32: HEADER_SLOT_STRIDE_U32,
+        alignTo: 64,
+    }));
+    const abortSignalsSlice = carpet.take("abortSignals", abortBytes);
+    const requestPayloadSlice = carpet.take("requestPayload", payloadBytes);
+    const workerSlices = Array.from({ length: threads }, (_, thread) => ({
+        signal: carpet.take(`signals-${thread}`, signalBytes),
+        returnLock: carpet.take(`returnLockSector-${thread}`, LOCK_SECTOR_BYTE_LENGTH),
+        returnHeaders: carpet.take(`returnHeaders-${thread}`, getHeaderBlockByteLength({
+            slotCount: LockBound.slots,
+            slotStrideU32: HEADER_SLOT_STRIDE_U32,
+            alignTo: 64,
+        })),
+        returnPayload: carpet.take(`returnPayload-${thread}`, payloadBytes),
+    }));
+    const primitives = getProcessWorkerSharedMemoryPrimitives();
+    const forceNamed = sharedMemory.mode === "named" || isWindowsRuntimeHost();
+    const mapping = primitives.createSharedMemory(forceNamed
+        ? {
+            size: carpet.byteLength(),
+            mode: "create",
+            name: makeProcessWorkerMemoryName(0, sharedMemory.namePrefix),
+        }
+        : { size: carpet.byteLength() });
+    const descriptor = FileDescriptor.fromMapping(mapping);
+    if (isWindowsRuntimeHost() && descriptor.name === undefined) {
+        throw new Error("Windows process worker shared memory must use a named mapping");
+    }
+    if (sharedMemory.mode === "named" && descriptor.name === undefined) {
+        throw new Error("processSharedMemory mode named needs a named shared-memory backend");
+    }
+    const buffer = mapping.buffer;
+    const bind = (slice) => makeSharedBufferRegion(buffer, slice.byteOffset, slice.byteLength);
+    const abortSignals = bind(abortSignalsSlice);
+    const requestLock = {
+        headers: bind(requestHeadersSlice),
+        headerSlotStrideU32: HEADER_SLOT_STRIDE_U32,
+        lockSector: bind(requestLockSlice),
+        payloadSector: bind(requestLockSlice),
+    };
+    // Each worker calls cleanup, so named-memory unlink happens only after every
+    // endpoint has released its view. The per-worker mapping wrappers below do
+    // not expose close(); the host views remain attached until host exit because
+    // Bun's external ArrayBuffer finalizer can race an explicit munmap.
+    let remaining = threads;
+    let cleaned = false;
+    const cleanupSharedMapping = () => {
+        if (cleaned)
+            return;
+        remaining--;
+        if (remaining > 0)
+            return;
+        cleaned = true;
+        const name = descriptor.name;
+        if (name !== undefined && sharedMemory.unlinkOnShutdown) {
+            primitives.unlinkSharedMemory?.(name);
+        }
+    };
+    const workerMapping = {
+        ...mapping,
+        close: undefined,
+    };
+    const workers = workerSlices.map((slices) => {
+        const returnLock = {
+            headers: bind(slices.returnHeaders),
+            headerSlotStrideU32: HEADER_SLOT_STRIDE_U32,
+            lockSector: bind(slices.returnLock),
+            payloadSector: bind(slices.returnLock),
+        };
+        return {
+            mapping: workerMapping,
+            descriptor,
+            controlLayout: {
+                controlSAB: buffer,
+                signals: bind(slices.signal),
+                abortSignals,
+                lock: requestLock,
+                returnLock,
+                slices: carpet.slices,
+            },
+            lockPayload: bind(requestPayloadSlice),
+            returnPayload: bind(slices.returnPayload),
+            cleanup: cleanupSharedMapping,
+        };
+    });
+    return {
+        mapping,
+        descriptor,
+        workers,
+        abortSignalMax,
+    };
+};
 const toChildProcessSharedBufferMetadata = (source, descriptor) => {
     const region = toSharedBufferRegion(source);
     const metadata = descriptor.toMetadata();
@@ -562,9 +662,23 @@ const spawnNodeHostedProcessWorker = ({ workerUrl, bootPayload, memory, processR
         queueMicrotask(() => child.send?.(bootPayload));
     }
     child.on("error", events.emitError);
-    child.on("exit", (code) => events.emitExit(code ?? -1));
+    let resolveExit = () => { };
+    const exited = new Promise((resolve) => {
+        resolveExit = resolve;
+    });
+    child.on("exit", (code) => {
+        resolveExit();
+        events.emitExit(code ?? -1);
+    });
     return {
-        terminate: () => child.kill(),
+        terminate: () => {
+            try {
+                child.kill();
+            }
+            catch {
+            }
+            return exited;
+        },
         unref: () => child.unref?.(),
         on: events.on,
     };

package/src/runtime/tx-queue.d.ts

@@ -33,6 +33,8 @@ export declare function createHostTxQueue({ max, lock, returnLock, extraReturnLo
     hasPendingFrames: () => boolean;
     txIdle: () => boolean;
     completeFrame: () => number;
+    waitForCompletion: (onWake: () => void, timeoutMs?: number) => boolean;
+    setCompletionWaiterArmed: (armed: boolean) => void;
     setReturnHooks: (lane: number, hooks: ReturnHooks | undefined) => void;
     enqueue: (functionID: FunctionID, timeout?: TaskTimeout, abortSignal?: AbortSignalOption) => (rawArgs: RawArguments) => Promise<never> | import("../common/with-resolvers.js").PromiseWithMaybeReject<unknown>;
     flushToWorker: () => boolean;

package/src/runtime/tx-queue.js

@@ -54,6 +54,18 @@ export function createHostTxQueue({ max, lock, returnLock, extraReturnLocks, rel
         activeRejectPlaceholder: PLACE_HOLDER,
         onResolved: onReturnResolved,
     }));
+    const returnWaiters = [
+        returnLock,
+        ...(extraReturnLocks ?? []),
+    ].map((each) => typeof each.waitForHostChange === "function"
+        ? each.waitForHostChange
+        : () => undefined);
+    const returnArmers = [
+        returnLock,
+        ...(extraReturnLocks ?? []),
+    ].map((each) => typeof each.setHostWaiterArmed === "function"
+        ? each.setHostWaiterArmed
+        : (_armed) => { });
     // A stealing queue drains one private return lock per worker. Borrowed
     // BufferReferences must therefore be claimed with the hooks belonging to the
     // worker that produced that particular return. The hooks are bound after the
@@ -84,6 +96,60 @@ export function createHostTxQueue({ max, lock, returnLock, extraReturnLocks, rel
             }
             return resolved;
         };
+    // A stealing queue has one private return lock per worker. Keep at most one
+    // waitAsync waiter per lane: after lane A rings, lane B's unresolved waiter
+    // must survive the next arm or Atomics.notify(..., 1) could wake an obsolete
+    // waiter and starve the live one until the watchdog timeout.
+    const completionArmed = new Uint8Array(returnWaiters.length);
+    let completionWake;
+    let completionGeneration = 0 | 0;
+    const setCompletionWaiterArmed = (armed) => {
+        for (const setArmed of returnArmers)
+            setArmed(armed);
+    };
+    const waitForCompletion = (onWake, timeoutMs) => {
+        completionWake = onWake;
+        // A persistent waiter may still be pending after a send preempted the
+        // dispatcher. Re-arm its shared gate before relying on that waiter again.
+        setCompletionWaiterArmed(true);
+        let supported = true;
+        for (let index = 0; index < returnWaiters.length; index++) {
+            if (completionArmed[index] !== 0)
+                continue;
+            let wait;
+            try {
+                wait = returnWaiters[index](timeoutMs);
+            }
+            catch {
+                wait = undefined;
+            }
+            if (wait === undefined) {
+                supported = false;
+                break;
+            }
+            completionArmed[index] = 1;
+            const generation = completionGeneration;
+            const wakeLane = () => {
+                if (completionArmed[index] === 0)
+                    return;
+                completionArmed[index] = 0;
+                returnArmers[index](false);
+                if (generation !== completionGeneration)
+                    return;
+                completionWake?.();
+            };
+            if (!wait.async)
+                wakeLane();
+            else
+                Promise.resolve(wait.value).then(wakeLane, wakeLane);
+        }
+        if (!supported) {
+            completionWake = undefined;
+            setCompletionWaiterArmed(false);
+            completionGeneration = (completionGeneration + 1) | 0;
+        }
+        return supported;
+    };
     const hasActiveTasks = () => {
         const count = (inUsed - getPendingPromiseCount()) | 0;
         return count > 0;
@@ -116,6 +182,8 @@ export function createHostTxQueue({ max, lock, returnLock, extraReturnLocks, rel
         hasPendingFrames,
         txIdle,
         completeFrame,
+        waitForCompletion,
+        setCompletionWaiterArmed,
         setReturnHooks: (lane, hooks) => {
             if (!Number.isInteger(lane) || lane < 0 || lane >= returnHooks.length) {
                 throw new RangeError(`return lane ${lane} out of range`);

package/src/runtime/worker-common.d.ts

@@ -10,4 +10,4 @@ export type NodeWorkerLike = {
 export declare const toWorkerSafeExecArgv: (flags: string[] | undefined) => string[] | undefined;
 export declare const toWorkerCompatExecArgv: (flags: string[] | undefined) => string[] | undefined;
 export declare const serializeWorkerBootstrapData: (options: WorkerSettings) => WorkerSettings;
-export declare const terminateWorkerQuietly: (worker: SpawnedWorker) => void;
+export declare const terminateWorkerQuietly: (worker: SpawnedWorker) => Promise<void>;

package/src/runtime/worker-common.js

@@ -95,8 +95,9 @@ export const terminateWorkerQuietly = (worker) => {
         // Runaway worker termination can be slow or stuck on some runtimes; once the
         // pool is closing it must not keep the host process alive.
         worker.unref?.();
-        void Promise.resolve(worker.terminate()).catch(() => { });
+        return Promise.resolve(worker.terminate()).then(() => { }, () => { });
     }
     catch {
+        return Promise.resolve();
     }
 };

package/src/types.d.ts

@@ -34,6 +34,8 @@ type WorkerData = {
     payloadConfig?: PayloadBufferOptions;
     bufferReferenceReturn?: "copy" | "borrow";
     permission?: ResolvedPermissionProtocol;
+    /** Whether this host can arm an async completion waiter on the return lock. */
+    notifyOnHostPublish?: boolean;
     /**
      * Work stealing. When present, `lock` is a submit region shared by every
      * worker and this worker claims from it as consumer `consumerId` of
@@ -341,13 +343,46 @@ type WorkerTimers = {
 };
 type DispatcherSettings = {
     /**
-     * How many immediate notify loops before backoff kicks in.
+     * How many immediate notify loops before the dispatcher stops re-arming the
+     * pump for free.
+     *
+     * The default depends on what the dispatcher escalates *to*. Polling
+     * escalates to a `setTimeout` ladder costing ~1.1ms even at delay 0, so it
+     * defaults to 128 — escalating is expensive and the wide window also batches
+     * completions. A doorbell escalates to `Atomics.waitAsync` at roughly the
+     * price of one hop, so pools that have one default to 1. Pools without a
+     * doorbell — Deno, or `doorbell: false` — keep 128.
+     *
+     * Setting this explicitly opts out of that coupling for every pool shape.
      */
     stallFreeLoops?: number;
     /**
      * Max backoff delay (milliseconds).
      */
     maxBackoffMs?: number;
+    /**
+     * Replace idle completion polling with an `Atomics.waitAsync` doorbell when
+     * the host runtime supports it.
+     *
+     * Defaults to enabled on Node and Bun at any worker count, where it costs
+     * 1.6-3.9x less host CPU per completed call. Under HTTP load, where the host
+     * has real work of its own, that converts to +13% to +36% throughput.
+     *
+     * Turn it off for a pool that oversubscribes its machine. The doorbell only
+     * progresses when the host gets scheduled, so once workers occupy every core
+     * a wake must preempt one: measured +5% to +12.6% rps while workers+host fit
+     * within the cores, -22% to -32% once they do not. That is not gated
+     * automatically because the core count cannot be probed portably.
+     *
+     * Forced off, overriding an explicit `true`, where a doorbell cannot work:
+     * on Deno, whose `waitAsync` does not wake an idle event loop, and for
+     * process workers, which live in another process and so cannot ring a host
+     * waiter at all — V8 keeps its Atomics waiter list per isolate, which is why
+     * they wake through a native futex addon instead. Compiled (Porffor) workers
+     * never reach this path: they reject `host` outright and use pipes rather
+     * than shared memory.
+     */
+    doorbell?: boolean;
     /**
      * Host dispatcher topology.
      * - `"per-thread"`: each worker owns its dispatcher and macro channel.
@@ -366,14 +401,12 @@ type DispatcherSettings = {
      * claim from, private return lanes, and a pool-global pending registry. The
      * endpoint that claims a task owns its response.
      *
-     * Enabled by default for multi-worker thread pools unless a balancer or
-     * private-lane dispatcher was explicitly selected. One-worker pools,
-     * inliners, compiled/Porffor workers, process workers, and pools above the
-     * current 31-claimant protocol limit retain their existing transport.
-     * Explicitly requesting `true` with process workers is rejected because
-     * their transport uses separately mapped process-shared memory. Set `false`
-     * (or `KNITTING_STEAL=0`) to opt out; `KNITTING_STEAL=1` explicitly opts in
-     * and overrides a balancer/dispatcher selection.
+     * Enabled by default for compatible multi-worker thread and process pools
+     * unless a balancer or private-lane dispatcher was explicitly selected.
+     * One-worker pools, inliners, compiled/Porffor workers, and pools above the
+     * current 31-claimant protocol limit retain their existing transport. Set
+     * `false` (or `KNITTING_STEAL=0`) to opt out; `KNITTING_STEAL=1` explicitly
+     * opts in and overrides a balancer/dispatcher selection.
      */
     steal?: boolean;
     /**

package/src/worker/loop.js

@@ -73,7 +73,7 @@ export const workerMainLoop = async (startupData) => {
     installTerminationGuard();
     installUnhandledRejectionSilencer();
     installPerformanceNowGuard();
-    const { debug, sab, thread, startAt, workerOptions, lock, returnLock, abortSignalSAB, abortSignalMax, payloadConfig, bufferReferenceReturn, permission, totalNumberOfThread, list, ids, names, at, steal, } = startupData;
+    const { debug, sab, thread, startAt, workerOptions, lock, returnLock, abortSignalSAB, abortSignalMax, payloadConfig, bufferReferenceReturn, permission, notifyOnHostPublish, totalNumberOfThread, list, ids, names, at, steal, } = startupData;
     scrubWorkerDataSensitiveBuffers(startupData);
     assertWorkerSharedMemoryBootData({ sab, lock, returnLock });
     const debugNamespaces = resolveDebugNamespaces(debug);
@@ -120,6 +120,9 @@ export const workerMainLoop = async (startupData) => {
         payloadConfig,
         textCompat: returnLock.textCompat,
         processBoundary: RUNTIME_IS_PROCESS_WORKER,
+        // The host parks on this lock's publication word when it has no work to
+        // flush. Request locks are host-produced and must not wake that waiter.
+        notifyOnHostPublish,
     });
     const timers = workerOptions?.timers;
     const spinMicroseconds = timers?.spinMicroseconds ??
@@ -269,6 +272,10 @@ export const workerMainLoop = async (startupData) => {
                 // a peer withdrawing its intent. Measured to hurt the per-lane path,
                 // where a claim is a cheap private decode and picking work up promptly
                 // matters more, so the classic order is kept below.
+                // Reordering must not make `progressed` sticky: it answers "did this
+                // iteration move anything", so it has to start false every pass or the
+                // park below is unreachable and the worker spins a core forever.
+                progressed = false;
                 if (_hasCompleted()) {
                     if (_writeBatch(WRITE_MAX) > 0)
                         progressed = true;