knitting 0.1.61 → 0.1.63

package/src/runtime/dispatcher.js

@@ -1,5 +1,34 @@
 import { createRuntimeMessageChannel, } from "../common/worker-runtime.js";
-export const hostDispatcherLoop = ({ signalBox: { opView, txStatus, rxStatus, }, queue: { completeFrame, hasPendingFrames, flushToWorker, txIdle, }, channelHandler, dispatcherOptions, notifySignal, }) => {
+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.
+ */
+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`.
+ */
+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, }) => {
     const a_load = Atomics.load;
     const a_store = Atomics.store;
     const a_notify = Atomics.notify;
@@ -10,13 +39,81 @@ export const hostDispatcherLoop = ({ signalBox: { opView, txStatus, rxStatus, },
                 a_notify(opView, 0, 1);
         });
     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") &&
+        typeof Atomics.waitAsync === "function";
+    let doorbellEnabled = canUseDoorbell;
+    let doorbellArmed = false;
+    let doorbellEpoch = 0 | 0;
+    const DOORBELL_WATCHDOG_MS = 1000;
     let stallCount = 0 | 0;
-    const STALL_FREE_LOOPS = Math.max(0, (dispatcherOptions?.stallFreeLoops ?? 128) | 0);
+    const requestedStallFreeLoops = dispatcherOptions?.stallFreeLoops;
+    let stallFreeLoops = requestedStallFreeLoops !== undefined
+        ? Math.max(0, requestedStallFreeLoops | 0)
+        : canUseDoorbell
+            ? DOORBELL_STALL_FREE_LOOPS
+            : POLL_STALL_FREE_LOOPS;
     const MAX_BACKOFF_MS = Math.max(0, (dispatcherOptions?.maxBackoffMs ?? 10) | 0);
     let backoffTimer;
     // inFlight prevents re-entrancy when pool.ts fires check() concurrently
     // from both send() and the channel callback. Cheaper than try/finally.
     let inFlight = false;
+    const cancelDoorbell = () => {
+        if (!doorbellArmed)
+            return;
+        doorbellEpoch = (doorbellEpoch + 1) | 0;
+        doorbellArmed = false;
+        setCompletionWaiterArmed(false);
+    };
+    const armDoorbell = () => {
+        if (!doorbellEnabled || doorbellArmed === true) {
+            if (!doorbellEnabled)
+                notify();
+            return;
+        }
+        const token = (doorbellEpoch + 1) | 0;
+        doorbellEpoch = token;
+        doorbellArmed = true;
+        let woke = false;
+        const wake = () => {
+            if (!doorbellArmed || doorbellEpoch !== token || woke)
+                return;
+            woke = true;
+            doorbellArmed = false;
+            doorbellEpoch = (doorbellEpoch + 1) | 0;
+            setCompletionWaiterArmed(false);
+            // 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);
+        }
+        catch {
+            supported = false;
+        }
+        // Some runtimes reject waitAsync on their SharedArrayBuffer variants; fall
+        // back to polling rather than hanging the pool.
+        if (!supported) {
+            doorbellEnabled = false;
+            // The window was narrowed for a doorbell that no longer exists; widen it
+            // back or the ladder fires after a single fruitless drain.
+            if (requestedStallFreeLoops === undefined) {
+                stallFreeLoops = POLL_STALL_FREE_LOOPS;
+            }
+            doorbellArmed = false;
+            doorbellEpoch = (doorbellEpoch + 1) | 0;
+            setCompletionWaiterArmed(false);
+            notify();
+        }
+    };
     const check = () => {
         if (inFlight) {
             // Another check() is already mid-drain; mark that a re-run is needed
@@ -24,11 +121,12 @@ export const hostDispatcherLoop = ({ signalBox: { opView, txStatus, rxStatus, },
             check.rerun = true;
             return;
         }
-        // Nothing enqueued and nothing outstanding at the worker: skip the drain.
-        // Without this an idle lane still pays a txStatus write, an rxStatus load
-        // and — worst of all — an Atomics.notify that wakes a parked worker for no
-        // reason. Under the serial-channel dispatcher every lane is checked on
-        // every tick, so that waste is what makes latency grow with thread count.
+        // 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.
         if (txIdle()) {
             check.isRunning = false;
             return;
@@ -46,25 +144,27 @@ export const hostDispatcherLoop = ({ signalBox: { opView, txStatus, rxStatus, },
                 a_store(opView, 0, 1);
                 wakeSignal();
             }
-            // Drain loop: local vars so V8 keeps them as unboxed int32.
-            let anyProgressed = false;
+            // 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.
+            let completed = false;
             let progressed = true;
             while (progressed) {
                 progressed = false;
                 if (completeFrame() > 0) {
                     progressed = true;
-                    anyProgressed = true;
+                    completed = true;
                 }
                 while (hasPendingFrames()) {
                     if (!flushToWorker())
                         break;
                     progressed = true;
-                    anyProgressed = true;
                 }
             }
             txStatus[0] = 0;
             if (!txIdle()) {
-                if (anyProgressed || hasPendingFrames()) {
+                if (completed || hasPendingFrames()) {
                     stallCount = 0 | 0;
                 }
                 else {
@@ -83,14 +183,22 @@ export const hostDispatcherLoop = ({ signalBox: { opView, txStatus, rxStatus, },
     check.isRunning = false;
     check.rerun = false;
     const scheduleNotify = () => {
-        if (stallCount <= STALL_FREE_LOOPS) {
+        if (stallCount <= stallFreeLoops) {
             notify();
             return;
         }
+        if (doorbellEnabled) {
+            // Release isRunning during the wait so a fresh send() can restart the
+            // dispatcher immediately. The epoch in cancelDoorbell() invalidates the
+            // old waiter in that case.
+            check.isRunning = false;
+            armDoorbell();
+            return;
+        }
         // One delayed wakeup at a time; fresh send() calls preempt via check directly.
         if (backoffTimer !== undefined)
             return;
-        let delay = (stallCount - STALL_FREE_LOOPS - 1) | 0;
+        let delay = (stallCount - stallFreeLoops - 1) | 0;
         if (delay < 0)
             delay = 0;
         else if (delay > MAX_BACKOFF_MS)
@@ -108,25 +216,47 @@ export const hostDispatcherLoop = ({ signalBox: { opView, txStatus, rxStatus, },
     return { check };
 };
 export class ChannelHandler {
+    // Set only when the pump is a MessageChannel. The `setImmediate` pump has no
+    // ports, and nothing outside this class reads them.
     channel;
     port1;
     port2;
-    #post2;
-    constructor() {
-        this.channel = createRuntimeMessageChannel();
-        this.port1 = this.channel.port1;
-        this.port2 = this.channel.port2;
-        this.#post2 = (message) => this.port2.postMessage(message);
+    #handler;
+    #notify;
+    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?.();
+            };
+            this.#notify = () => {
+                immediate(run);
+            };
+            return;
+        }
+        const channel = createRuntimeMessageChannel();
+        const port2 = channel.port2;
+        this.channel = channel;
+        this.port1 = channel.port1;
+        this.port2 = port2;
+        this.#notify = () => {
+            port2.postMessage(null);
+        };
     }
     notify() {
-        this.#post2(null);
+        this.#notify();
     }
     /**
-     * Opens the channel (if not already open) and sets the onmessage handler.
-     * This is the setup so `notify` can send a message to the port 1.
+     * 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.
      */
     open(f) {
+        this.#handler = f;
         const port1 = this.port1;
+        if (port1 === undefined)
+            return;
         if (typeof port1.on === "function") {
             port1.on("message", f);
         }
@@ -134,13 +264,16 @@ export class ChannelHandler {
             // @ts-ignore
             port1.onmessage = f;
         }
-        this.port1.start?.();
-        this.port2.start?.();
+        this.port1?.start?.();
+        this.port2?.start?.();
     }
     /**
-     * Closes the channel if it is open.
+     * Detaches the handler, and closes the channel if this pump has one.
      */
     close() {
+        this.#handler = undefined;
+        if (this.port1 === undefined || this.port2 === undefined)
+            return;
         //@ts-ignore
         this.port1.onmessage = null;
         //@ts-ignore

package/src/runtime/inline-executor.js

@@ -81,9 +81,14 @@ const composeInlineCallable = (fn, timeout, useAbortToolkit = false) => {
     };
 };
 export const createInlineExecutor = ({ tasks, genTaskID, batchSize, }) => {
+    // `createPool` passes an already name-sorted array, which is the order
+    // `fnNumber` indexes into. The object form has to reach the same order on its
+    // own: task ids identify a task, they do not rank it, so sorting by id would
+    // hand callers a different lane than the one they addressed.
     const entries = Array.isArray(tasks)
         ? tasks
-        : Object.values(tasks).sort((a, b) => a.id - b.id);
+        : Object.values(tasks)
+            .sort((a, b) => a.name.localeCompare(b.name));
     const runners = entries.map((entry) => {
         // Imported tasks must never execute on the host inline lane: their module
         // import is meant to stay inside the worker so worker permission policies

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,10 +105,11 @@ 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, }: {
+export declare const spawnWorkerContext: ({ list, ids, names, sab, thread, debug, hostDebug, totalNumberOfThread, workerCount, source, at, workerOptions, workerExecArgv, permission, host, payload, bufferReferenceReturn, abortSignalCapacity, usesAbortSignal, sharedChannelHandler, stealPool, }: {
     list: string[];
     ids: number[];
     names: string[];
@@ -108,6 +119,12 @@ export declare const spawnWorkerContext: ({ list, ids, names, sab, thread, debug
     debug?: DebugOptions;
     hostDebug?: (message: string) => void;
     totalNumberOfThread: number;
+    /**
+     * Workers only, excluding any host inline lane. Drives the spin policy:
+     * the inliner runs on the host thread and never spins, so counting it
+     * would strip a one-worker pool of the budget it should keep.
+     */
+    workerCount?: number;
     source?: string;
     workerOptions?: WorkerSettings;
     workerExecArgv?: string[];
@@ -140,6 +157,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,14 +1,14 @@
 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 { createSharedMemoryTransport, TRANSPORT_SIGNAL_BYTES, WORKER_STOP, } from "../ipc/transport/shared-memory.js";
 import { ChannelHandler, hostDispatcherLoop, } from "./dispatcher.js";
 import { HEADER_SLOT_STRIDE_U32, lock2, LOCK_SECTOR_BYTE_LENGTH, LockBound, } from "../memory/lock.js";
 // Side-effect import: registers the payload codec (cycle break for Andromeda;
 // 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";
@@ -20,8 +20,12 @@ const WORKER_FATAL_MESSAGE_KEY = "__knittingWorkerFatal";
 const isWorkerFatalMessage = (value) => !!value &&
     typeof value === "object" &&
     typeof value[WORKER_FATAL_MESSAGE_KEY] === "string";
+// Bound the wait for a worker to acknowledge loop exit.
+const WORKER_STOP_ACK_TIMEOUT_MS = 50;
+const WORKER_STOP_NEEDS_ACK = RUNTIME === "deno";
 // Keep idle workers self-healing if an Atomics.notify wake is missed.
 const DEFAULT_WORKER_PARK_MS = 1;
+const SINGLE_WORKER_SPIN_US = 50;
 const DEFAULT_ABORT_SIGNAL_CAPACITY = 258;
 const sanitizePositiveInteger = (value) => {
     if (!Number.isFinite(value))
@@ -31,15 +35,20 @@ const sanitizePositiveInteger = (value) => {
 };
 const resolveAbortSignalCapacity = (value) => sanitizePositiveInteger(value) ?? DEFAULT_ABORT_SIGNAL_CAPACITY;
 const abortSignalByteLength = (capacity) => Math.max(1, Math.ceil(capacity / 32)) * Uint32Array.BYTES_PER_ELEMENT;
-const withDefaultWorkerTimers = (options) => {
+const withDefaultWorkerTimers = (options, workerCount) => {
     const parkMs = options?.timers?.parkMs ?? DEFAULT_WORKER_PARK_MS;
+    // `??` and not `||`: an explicit `spinMicroseconds: 0` is the whole point of
+    // the multi-worker default and must not fall through to it.
+    const spinMicroseconds = options?.timers?.spinMicroseconds ??
+        (workerCount <= 1 ? SINGLE_WORKER_SPIN_US : 0);
     if (options === undefined)
-        return { timers: { parkMs } };
+        return { timers: { parkMs, spinMicroseconds } };
     return {
         ...options,
         timers: {
             ...options.timers,
             parkMs,
+            spinMicroseconds,
         },
     };
 };
@@ -67,8 +76,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 +104,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 +133,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 +150,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,13 +179,13 @@ 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, }) => {
+export const spawnWorkerContext = ({ list, ids, names, sab, thread, debug, hostDebug, totalNumberOfThread, workerCount, source, at, workerOptions, workerExecArgv, permission, host, payload, bufferReferenceReturn, abortSignalCapacity, usesAbortSignal, sharedChannelHandler, stealPool, }) => {
     if (workerOptions?.runtime === "compiled") {
         return spawnCompiledWorkerContext({
             list,
@@ -165,7 +198,7 @@ export const spawnWorkerContext = ({ list, ids, names, sab, thread, debug, hostD
     }
     const tsFileUrl = new URL(import.meta.url);
     const poliWorker = RUNTIME_WORKER;
-    const resolvedWorkerOptions = serializeWorkerBootstrapData(withDefaultWorkerTimers(workerOptions));
+    const resolvedWorkerOptions = serializeWorkerBootstrapData(withDefaultWorkerTimers(workerOptions, workerCount ?? totalNumberOfThread));
     const useProcessWorkerRuntime = resolvedWorkerOptions.runtime === "process";
     const processWorkerRuntime = useProcessWorkerRuntime
         ? readProcessWorkerRuntime(resolvedWorkerOptions)
@@ -205,15 +238,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 +444,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 +486,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,
@@ -596,12 +646,39 @@ export const spawnWorkerContext = ({ list, ids, names, sab, thread, debug, hostD
             return pending;
         };
     };
+    // Ask the worker to leave its loop before termination.
+    const requestWorkerStop = async () => {
+        const stopView = signalBox.stopView;
+        if (stopView === undefined)
+            return;
+        try {
+            Atomics.store(stopView, 0, WORKER_STOP.requested);
+            laneWake();
+            notifySignal?.();
+        }
+        catch {
+            return;
+        }
+        if (!WORKER_STOP_NEEDS_ACK)
+            return;
+        const deadline = Date.now() + WORKER_STOP_ACK_TIMEOUT_MS;
+        while (Atomics.load(stopView, 0) !== WORKER_STOP.acknowledged) {
+            if (Date.now() >= deadline)
+                return;
+            await new Promise((resolve) => setTimeout(resolve, 1));
+        }
+    };
     const context = {
         txIdle,
         call,
+        requestStop: requestWorkerStop,
         kills: async () => {
             markWorkerClosed("Thread closed", true);
-            terminateWorkerQuietly(worker);
+            // Process workers must exit before their shared memory is unmapped.
+            const awaitExit = processWorkerMemory !== undefined;
+            const termination = terminateWorkerQuietly(worker, awaitExit);
+            if (awaitExit)
+                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;