knitting 0.1.60 → 0.1.62

package/src/api.js

@@ -1,15 +1,16 @@
 import { getCallerFilePath, getCallerHref, setModuleUrl, } from "./common/task-source.js";
 import { DEBUG_ENABLED, resolveDebugNamespaces } from "./debug/gate.js";
-import { genTaskID } from "./common/task-source.js";
+import { genTaskID, stableTaskID } from "./common/task-source.js";
 import { toModuleUrl } from "./common/module-url.js";
 import { endpointSymbol } from "./common/task-symbol.js";
-import { spawnWorkerContext } from "./runtime/pool.js";
-import { ChannelHandler } from "./runtime/dispatcher.js";
-import { RUNTIME } from "./common/runtime.js";
+import { createStealPoolBuffers, MAX_STEAL_CONSUMERS, spawnWorkerContext, } from "./runtime/pool.js";
+import { ChannelHandler, hostDispatcherLoop } from "./runtime/dispatcher.js";
+import { createSharedArrayBuffer, RUNTIME } from "./common/runtime.js";
 import { RUNTIME_IS_MAIN_THREAD, RUNTIME_POOL_DEPTH, RUNTIME_WORKER_DATA, } from "./common/worker-runtime.js";
 import { classifyProcessPermissionCompatibility, enforceProcessPermissionCompatibility, resolvePermissionProtocol, toRuntimePermissionFlags, } from "./permission/index.js";
 import { getNodeProcess } from "./common/node-compat.js";
-import { readProcessWorkerCommandPrefix, readProcessWorkerRuntime, } from "./runtime/process-worker.js";
+import { readProcessSharedMemorySettings, readProcessWorkerNodeMajor, readProcessWorkerRuntime, } from "./runtime/process-worker.js";
+import { TRANSPORT_SIGNAL_BYTES } from "./ipc/transport/shared-memory.js";
 import { inspectCompiledWorkerArtifact } from "./runtime/compiled-artifact.js";
 import { managerMethod } from "./runtime/balancer.js";
 import { createInlineExecutor } from "./runtime/inline-executor.js";
@@ -46,18 +47,6 @@ const readHostCwd = () => {
     }
     return undefined;
 };
-const readKnownProcessWorkerNodeMajor = (worker) => {
-    if (RUNTIME !== "node")
-        return undefined;
-    if (readProcessWorkerCommandPrefix(worker) !== undefined)
-        return undefined;
-    const nodeProcess = getNodeProcess();
-    if (nodeProcess?.env?.NODE_BINARY !== undefined)
-        return undefined;
-    const raw = nodeProcess?.versions?.node;
-    const major = Number.parseInt(String(raw).split(".", 1)[0] ?? "", 10);
-    return Number.isInteger(major) && major > 0 ? major : undefined;
-};
 const formatDebugList = (values, empty = "(none)") => values && values.length > 0 ? values.join(",") : empty;
 const MAX_FUNCTION_ID = 0xFFFF;
 const MAX_FUNCTION_COUNT = MAX_FUNCTION_ID + 1;
@@ -375,6 +364,21 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe,
     hostDebug?.log(`permission=${permissionProtocol?.mode ?? "off"} execArgv=${formatDebugList(execArgv)}`);
     const usesAbortSignal = listOfFunctions.some((fn) => fn.abortSignal !== undefined);
     const resolvedWorker = resolveWorkerSettings(worker, callerHref);
+    const dispatcherEnv = nodeProcess?.env?.KNITTING_DISPATCHER;
+    const stealEnvRaw = nodeProcess?.env?.KNITTING_STEAL?.trim().toLowerCase();
+    const stealEnv = stealEnvRaw === "1" || stealEnvRaw === "true"
+        ? true
+        : stealEnvRaw === "0" || stealEnvRaw === "false"
+            ? false
+            : undefined;
+    // Shared-submit stealing is the default for compatible multi-worker pools.
+    // An explicit option wins over the environment; compiled and inline
+    // transports retain their existing topology.
+    const dispatcherExplicitlySelected = host?.dispatcher !== undefined ||
+        dispatcherEnv === "serial-channel" || dispatcherEnv === "per-thread";
+    const stealDefaultCompatible = balancer === undefined &&
+        !dispatcherExplicitlySelected && (threads ?? 1) <= MAX_STEAL_CONSUMERS;
+    const stealRequested = host?.steal ?? stealEnv ?? stealDefaultCompatible;
     const usingCompiledWorker = resolvedWorker?.runtime === "compiled";
     if (resolvedWorker?.compiled !== undefined && !usingCompiledWorker) {
         throw new Error("worker.compiled requires worker.runtime to be compiled");
@@ -437,7 +441,7 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe,
             target: {
                 runtime: processRuntime,
                 nodeMajor: processRuntime === "node"
-                    ? readKnownProcessWorkerNodeMajor(resolvedWorker)
+                    ? readProcessWorkerNodeMajor(resolvedWorker)
                     : undefined,
             },
         }));
@@ -454,7 +458,6 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe,
             `(import { isMain } from "knitting") so only the main program starts ` +
             `the pool.`);
     }
-    const dispatcherEnv = nodeProcess?.env?.KNITTING_DISPATCHER;
     const explicitDispatcher = host?.dispatcher ??
         (dispatcherEnv === "serial-channel" || dispatcherEnv === "per-thread"
             ? dispatcherEnv
@@ -470,10 +473,37 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe,
         return "serial-channel";
     })();
     const dispatcher = explicitDispatcher ?? autoDispatcher;
-    const serialChannel = !usingCompiledWorker &&
+    // Work stealing: one shared submit region, private return lanes, one
+    // pool-global pending registry. It is the compatible multi-worker default;
+    // an explicit balancer/dispatcher keeps the private-lane topology unless
+    // stealing itself was explicitly requested.
+    const useSteal = stealRequested &&
+        !usingCompiledWorker &&
+        (threads ?? 1) > 1 &&
+        !usingInliner;
+    const stealBuffers = useSteal
+        ? createStealPoolBuffers({
+            threads: threads ?? 1,
+            payload,
+            regionLanes: host?.stealRegionLanes,
+            abortSignalCapacity,
+            usesAbortSignal,
+            processWorker: resolvedWorker?.runtime === "process"
+                ? {
+                    signalBytes: TRANSPORT_SIGNAL_BYTES,
+                    sharedMemory: readProcessSharedMemorySettings(resolvedWorker),
+                }
+                : undefined,
+        })
+        : undefined;
+    const serialChannel = !usingCompiledWorker && !useSteal &&
         dispatcher === "serial-channel";
+    // One serial-channel hop drives every lane check in turn, and it depends on
+    // the channel's delivery to do that: swapping in the cheaper `setImmediate`
+    // pump cost 25% throughput and tripled p99 here, where every other topology
+    // gained. See ChannelHandler's note.
     const serialDispatcherChannel = serialChannel
-        ? new ChannelHandler()
+        ? new ChannelHandler("channel")
         : undefined;
     let workers = Array.from({
         length: threads ?? 1,
@@ -496,14 +526,85 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe,
         usesAbortSignal,
         permission: permissionProtocol,
         sharedChannelHandler: serialDispatcherChannel,
+        stealPool: stealBuffers === undefined ? undefined : {
+            submitBuffers: stealBuffers.submitBuffers,
+            returnBuffers: stealBuffers.returnBuffers[thread],
+            hostSubmitLock: stealBuffers.hostSubmitLock,
+            hostReturnLock: stealBuffers.hostReturnLocks[thread],
+            sharedQueue: stealBuffers.sharedQueue,
+            consumers: threads ?? 1,
+            consumerId: thread,
+            regionLanes: stealBuffers.regionLanes,
+            abortSignalSAB: stealBuffers.abortSignalSAB,
+            abortSignalMax: stealBuffers.abortSignalMax,
+            processMemory: stealBuffers.processMemory,
+        },
     }));
+    const stealChannel = useSteal ? new ChannelHandler() : undefined;
+    if (useSteal) {
+        const channel = stealChannel;
+        const queue = stealBuffers.sharedQueue;
+        // Wake exactly one worker per drain, round-robin. Stealing decouples the
+        // wake target from the assignment: if the woken worker is busy, any other
+        // idle endpoint claims the region instead. So this costs one notify per
+        // publish regardless of pool size, rather than one per lane.
+        let wakeCursor = 0;
+        const wakeOne = () => {
+            const lanes = workers.length;
+            if (lanes === 0)
+                return;
+            const lane = wakeCursor;
+            wakeCursor = wakeCursor + 1 < lanes ? wakeCursor + 1 : 0;
+            workers[lane].laneWake?.();
+        };
+        // The shared dispatcher drives one queue, so it needs signal words of its
+        // own rather than any single lane's; waking is delegated to `wakeOne`.
+        const signalWords = new Int32Array(createSharedArrayBuffer(3 * Int32Array.BYTES_PER_ELEMENT));
+        const { check } = hostDispatcherLoop({
+            signalBox: {
+                opView: signalWords.subarray(0, 1),
+                txStatus: signalWords.subarray(1, 2),
+                rxStatus: signalWords.subarray(2, 3),
+            },
+            queue,
+            channelHandler: channel,
+            dispatcherOptions: host,
+            notifySignal: wakeOne,
+            crossProcess: resolvedWorker?.runtime === "process",
+        });
+        channel.open(check);
+        workers.forEach((context) => {
+            context.bindSend(() => {
+                if (check.isRunning !== true) {
+                    check.isRunning = true;
+                    Promise.resolve().then(check);
+                }
+                wakeOne();
+            });
+        });
+        hostDebug?.log(`dispatcher=steal lanes=${workers.length} g=${stealBuffers.regionLanes}`);
+    }
     const sharedDispatcherChannel = serialDispatcherChannel;
     if (serialChannel) {
         const channel = serialDispatcherChannel;
         const checks = workers.map((context) => context.dispatcherCheck);
+        const laneIdle = workers.map((context) => context.txIdle);
         let serialScheduled = false;
         let serialInFlight = false;
         let serialRerun = false;
+        // Busy-lane set: a tick walks only the lanes that have work, not all of
+        // them. `active` is a dense list of lane indices; `isActive` keeps the
+        // membership test O(1). A lane joins on send() and leaves once its queue
+        // reports idle, so an N-worker pool with one busy lane costs one check per
+        // tick instead of N.
+        const active = [];
+        const isActive = new Uint8Array(checks.length);
+        const markActive = (lane) => {
+            if (isActive[lane] === 1)
+                return;
+            isActive[lane] = 1;
+            active.push(lane);
+        };
         const runSerialChecks = () => {
             if (serialInFlight) {
                 serialRerun = true;
@@ -513,11 +614,19 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe,
             do {
                 serialRerun = false;
                 serialScheduled = false;
-                for (let index = 0; index < checks.length; index++) {
-                    const check = checks[index];
+                // Walk backwards so dropping an idle lane is a swap-with-last pop.
+                for (let index = active.length - 1; index >= 0; index--) {
+                    const lane = active[index];
+                    const check = checks[lane];
                     if (check.isRunning !== true)
                         check.isRunning = true;
                     check();
+                    if (laneIdle[lane]()) {
+                        isActive[lane] = 0;
+                        const last = active.pop();
+                        if (index < active.length)
+                            active[index] = last;
+                    }
                 }
             } while (serialRerun);
             serialInFlight = false;
@@ -533,9 +642,10 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe,
             Promise.resolve().then(runSerialChecks);
         };
         channel.open(runSerialChecks);
-        workers.forEach((context) => {
+        workers.forEach((context, lane) => {
             const wake = context.laneWake;
             context.bindSend(() => {
+                markActive(lane);
                 scheduleSerialCheck();
                 wake();
             });
@@ -580,6 +690,7 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe,
         closePromise = Promise.allSettled(workers.map((context) => context.kills()))
             .then(() => {
             sharedDispatcherChannel?.close();
+            stealChannel?.close();
         });
         return closePromise;
     };
@@ -738,7 +849,7 @@ const buildTaskDefinitionFromCaller = (input, callerHref, at, imported = false)
     const importedFrom = new URL(callerHref).href;
     const out = ({
         ...input,
-        id: genTaskID(),
+        id: stableTaskID(importedFrom, at),
         importedFrom,
         at,
         imported,

package/src/common/runtime.d.ts

@@ -1,8 +1,9 @@
-type RuntimeName = "deno" | "bun" | "node" | "andromeda" | "unknown";
+type RuntimeName = "deno" | "bun" | "node" | "andromeda" | "browser" | "unknown";
 export declare const IS_DENO: boolean;
 export declare const IS_BUN: boolean;
 export declare const IS_NODE: boolean;
 export declare const IS_ANDROMEDA: boolean;
+export declare const IS_BROWSER: boolean;
 export declare const RUNTIME: RuntimeName;
 export declare const SET_IMMEDIATE: typeof setImmediate & ((cb: () => void) => void);
 export declare const HAS_SHARED_WASM_MEMORY: boolean;

package/src/common/runtime.js

@@ -7,6 +7,11 @@ export const IS_NODE = typeof nodeProcess?.versions?.node === "string";
 // Andromeda (Nova engine): no `node:` builtins or `WebAssembly`; detect via
 // its private bootstrap global.
 export const IS_ANDROMEDA = typeof globals.__andromeda__ !== "undefined";
+// A page or a web worker: no `node:` builtins, but `Worker`, `MessageChannel`,
+// and a cross-origin isolated `SharedArrayBuffer` are all the pool needs.
+export const IS_BROWSER = !IS_DENO && !IS_BUN && !IS_NODE && !IS_ANDROMEDA &&
+    (typeof globals.document !== "undefined" ||
+        typeof globals.WorkerGlobalScope === "function");
 export const RUNTIME = (IS_DENO
     ? "deno"
     : IS_BUN
@@ -15,7 +20,9 @@ export const RUNTIME = (IS_DENO
             ? "node"
             : IS_ANDROMEDA
                 ? "andromeda"
-                : "unknown");
+                : IS_BROWSER
+                    ? "browser"
+                    : "unknown");
 // `WebAssembly` may be undeclared (not just undefined) on Andromeda, where a
 // bare reference throws; capture it through `globalThis` so access is safe.
 const WebAssemblyRef = globals.WebAssembly;

package/src/common/task-source.d.ts

@@ -1,4 +1,13 @@
 export declare const genTaskID: () => number;
+/**
+ * Identity of a task, stable across processes.
+ *
+ * `genTaskID` numbers tasks by the order their module happened to be evaluated,
+ * which host and worker do not share: the host imports in its own source order
+ * and the worker imports in task-name order. `(href, at)` is the same pair in
+ * both, because `at` counts `task()` calls within one module.
+ */
+export declare const stableTaskID: (href: string, at: number) => number;
 export declare const setModuleUrl: (url: string | undefined) => void;
 export declare const getModuleUrlOverride: () => string | undefined;
 export declare const getCallerHref: (offset?: number) => string;

package/src/common/task-source.js

@@ -1,5 +1,20 @@
 import { toModuleUrl } from "./module-url.js";
 export const genTaskID = ((counter) => () => counter++)(0);
+/**
+ * Identity of a task, stable across processes.
+ *
+ * `genTaskID` numbers tasks by the order their module happened to be evaluated,
+ * which host and worker do not share: the host imports in its own source order
+ * and the worker imports in task-name order. `(href, at)` is the same pair in
+ * both, because `at` counts `task()` calls within one module.
+ */
+export const stableTaskID = (href, at) => {
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < href.length; index++) {
+        hash = Math.imul(hash ^ href.charCodeAt(index), 0x01000193);
+    }
+    return (Math.imul(hash ^ at, 0x01000193) >>> 0);
+};
 const INTERNAL_CALLER_HINTS = [
     "/src/common/task-source.ts",
     "/src/common/task-source.js",

package/src/memory/lock.d.ts

@@ -159,6 +159,22 @@ export declare const HEADER_SLOT_STRIDE_BYTES: number;
 export declare const HEADER_TASK_LINE_U32: number;
 export declare const HEADER_STATIC_PAYLOAD_U32: number;
 export declare const HEADER_TASK_OFFSET_IN_SLOT_U32: number;
+export declare const STEAL_ACK_SLOT_OFFSET_U32: number;
+export declare const STEAL_WANT_SLOT_OFFSET_U32: number;
+/**
+ * The payload allocator needs its own participant-owned ACK per consumer, since
+ * several workers can free payload slots from one shared allocator. No intent
+ * word: freeing needs no arbitration, a consumer only frees what it drained.
+ */
+export declare const STEAL_PAYLOAD_ACK_SLOT_OFFSET_U32: number;
+/**
+ * Host-owned liveness mask for stealing consumers. A dead claimant may leave
+ * its WANT word set forever; survivors ignore WANT from consumers whose bit is
+ * clear here. This preserves single-writer ownership of every WANT word.
+ */
+export declare const STEAL_LIVE_SLOT_OFFSET_U32: number;
+/** Host-owned arm word for the return-lock completion doorbell. */
+export declare const DOORBELL_ARMED_SLOT_OFFSET_U32: number;
 export declare const HEADER_U32_LENGTH: number;
 export declare const HEADER_BYTE_LENGTH: number;
 export declare const makeTask: () => Task;
@@ -177,7 +193,12 @@ type ResolveHostOptions = {
  *  - encode/decode are not re-entrant; payload codec uses a shared scratch buffer.
  */
 export type Lock2 = ReturnType<typeof lock2>;
-export declare const lock2: ({ headers, headerSlotStrideU32, LockBoundSector, payload, payloadConfig, payloadSector, textCompat, resultList, toSentList, recycleList, processBoundary, }: {
+export type WaitAsyncState = "not-equal" | "ok" | "timed-out";
+export type WaitAsyncResult = {
+    async: boolean;
+    value: WaitAsyncState | PromiseLike<WaitAsyncState>;
+};
+export declare const lock2: ({ headers, headerSlotStrideU32, LockBoundSector, payload, payloadConfig, payloadSector, textCompat, resultList, toSentList, recycleList, processBoundary, consumers, consumerId, regionLanes, notifyOnHostPublish, }: {
     headers?: SharedBufferSource;
     headerSlotStrideU32?: number;
     LockBoundSector?: SharedBufferSource;
@@ -189,6 +210,18 @@ export declare const lock2: ({ headers, headerSlotStrideU32, LockBoundSector, pa
     resultList?: RingQueue<Task>;
     recycleList?: RingQueue<Task>;
     processBoundary?: boolean;
+    /**
+     * Number of consumer endpoints sharing this lock. `1` (default) keeps the
+     * classic single-consumer path. `> 1` enables region-Dekker work stealing and
+     * is only valid on a host->worker submit lock, never on a return lock.
+     */
+    consumers?: number;
+    /** This endpoint's id, `0..consumers-1`. Priority is fixed by id. */
+    consumerId?: number;
+    /** Lanes claimed per Dekker handshake. Paper rule: `slots / regionLanes >= consumers + 1`. */
+    regionLanes?: number;
+    /** Notify a host-side wait after this endpoint publishes a frame. */
+    notifyOnHostPublish?: boolean;
 }) => {
     enlist: (task: Task) => true;
     encode: (task: Task, state?: number) => boolean;
@@ -203,10 +236,13 @@ export declare const lock2: ({ headers, headerSlotStrideU32, LockBoundSector, pa
     workerBits: Int32Array<import("../common/shared-buffer-region.js").SharedBuffer>;
     recyclecList: RingQueue<Task>;
     resolveHost: ({ queue, onResolved, shouldSettle, activeRejectPlaceholder, }: ResolveHostOptions) => () => number;
+    waitForHostChange: (timeoutMs?: number) => WaitAsyncResult | undefined;
+    setHostWaiterArmed: (armed: boolean) => void;
     hasPendingFrames: () => boolean;
     getPendingFrameCount: () => number;
     getPendingPromiseCount: () => number;
     resetPendingState: () => void;
+    deactivateStealConsumer: (id: number) => boolean;
     takeDeferredCount: () => number;
     setPromiseHandler: (handler?: PromisePayloadHandler) => void;
 };