knitting 0.1.53 → 0.1.54

package/README.md

@@ -11,18 +11,22 @@
 [![Deno](https://img.shields.io/badge/deno-2%2B-000000?logo=deno&logoColor=white)](https://deno.com/)
 [![Bun](https://img.shields.io/badge/bun-1%2B-f472b6?logo=bun&logoColor=white)](https://bun.sh/)
 
-Knitting is a worker pool over a shared-memory IPC runtime for Node.js, Deno,
-and Bun. Our mission is to make JavaScript a multicore language with real
-inter-runtime communication.
+Website: [knittingdocs.netlify.app](https://knittingdocs.netlify.app/)
 
-Thanks to its memory design, it can be 5x to 25x faster than using
-`postMessages` , bypassing OS socket communication entirely with a novel
-protocol written from scratch.
+If you are an agent trying to understand the project, the website also serves an
+[`llms.txt`](https://knittingdocs.netlify.app/llms.txt) file with a compact map
+of the docs.
 
-Use it for parts of your program that should run in different environments, such
-as CPU-intensive tasks, small jobs, runtime-isolated tasks, custom isolation for
-workers in Docker or bwrap environments, long-running tools, or any processes
-that require speed and type flexibility.
+Knitting is a worker pool built on shared-memory IPC for Node.js, Deno, and Bun.
+It lets you call work running on other threads or processes as if it were a
+normal async function.
+
+Because calls move through shared memory instead of `postMessage` or sockets,
+some workloads can be 5x to 25x faster than the usual worker-message path.
+
+Use it when part of your program should run somewhere else: CPU-heavy work,
+bursty small jobs, runtime-isolated code, Docker or bwrap workers, long-running
+tools, or cross-runtime process work that still needs to be fast and typed.
 
 You export a function or task, spin up a pool, and call it like a normal async
 function:
@@ -31,29 +35,28 @@ function:
 const result = await pool.call.resizeImage(file);
 ```
 
-So you only have to take care of 4 things:
+Most of the time, you only have to take care of four things:
 
 - Export a function or task
 - Create a pool
 - Call it
 - Let `using` or `shutdown()` close the pool
 
-Under the hood, we take care of scheduling and orchestration across worker
-threads or separate processes, also handling signals, timeouts, life cycles,
-memory allocation, garbage collection, and cross-runtime memory over the
-processes.
+Under the hood, Knitting handles scheduling across worker threads or separate
+processes, plus signals, timeouts, lifecycles, memory allocation, cleanup, and
+cross-runtime shared memory.
 
 ## Why use it?
 
-- Easy to use: Have a multithreaded environment or process with few lines of
-  code.
-- Great type support: pass primitives, JSON, Promise of these, and special types
-  (typed arrays, `Node Buffer`, `Envelope`, and `ProcessSharedBuffer`).
+- Easy to use: spin up threads or processes with a small API.
+- Great type support: pass primitives, JSON, promises of those values, and
+  special types like typed arrays, `Node Buffer`, `Envelope`, and
+  `ProcessSharedBuffer`.
 - Runtime flexibility: the same API across Node.js, Deno, and Bun.
 - Worker choices: use threads for fast pools or processes for stronger
   isolation.
-- All out-of-the-box experiences: strict-by-default permissions, payload-size
-  limits, task timeouts, abort-aware tasks, and worker hard timeouts.
+- Practical defaults: strict worker permissions, payload-size limits, task
+  timeouts, abort-aware tasks, and worker hard timeouts.
 
 ## Requirements
 
@@ -96,9 +99,9 @@ if (isMain) {
 }
 ```
 
-The `isMain` guard when the same module is loaded by workers or process. Export
-exposes the tasks or functions at module scope, so knitting maps down the
-imports, then use and use the pool only from the main program.
+Use the `isMain` guard when a module can be loaded by both the host and its
+workers. Export tasks at module scope so Knitting can find them, then create and
+use the pool only from the main program.
 
 ## The Mental Model
 
@@ -335,9 +338,17 @@ Common options you might tweak:
 | `worker.runtime`                  | Choose `"thread"` or `"process"` workers.                                                                                         |
 | `worker.processSharedMemory`      | Process-worker memory discovery: `"inherit"` by default on POSIX, or `"named"` for wrappers/containers that cannot preserve fd 0. |
 | `permission`                      | Runtime permission policy for workers.                                                                                            |
+| `host.dispatcher`                 | Experimental host dispatcher topology: `"per-thread"` or `"serial-channel"`.                                                      |
 | `debug`                           | Enable diagnostics (`host`, `globals`, `signals`, `imports`, `lifecycle`) or use `KNITTING_DEBUG`.                                |
 | `source`                          | Worker source override for advanced runtimes.                                                                                     |
 
+Most users can leave `host.dispatcher` alone. The current default is
+experimental: Bun and single-worker pools use `"per-thread"`, while multi-worker
+Node/Deno pools use `"serial-channel"` because it tends to behave well for
+bursty HTTP-style fan-out. If you are tuning a server or comparing runtimes, you
+can force either mode with `KNITTING_DISPATCHER=per-thread` or
+`KNITTING_DISPATCHER=serial-channel`.
+
 ### Worker bootstrap
 
 Use `worker.bootstrap` when a worker needs privileged setup before task modules

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "knitting",
-  "version": "0.1.53",
+  "version": "0.1.54",
   "description": "Shared-memory IPC runtime for Node.js, Deno, and Bun.",
   "license": "Apache-2.0",
   "repository": {

package/src/api.js

@@ -12,6 +12,7 @@ import { genTaskID } 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 { RUNTIME_IS_MAIN_THREAD, RUNTIME_POOL_DEPTH, RUNTIME_WORKER_DATA, } from "./common/worker-runtime.js";
 import { resolvePermissionProtocol, toRuntimePermissionFlags, } from "./permission/index.js";
@@ -283,6 +284,26 @@ 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
+            : undefined);
+    const autoDispatcher = (() => {
+        // Experimental default for HTTP-style bursts: Bun still favors direct
+        // per-thread channels, while Node/Deno multi-worker pools favor one shared
+        // macro channel over the per-lane dispatcher checks.
+        if (RUNTIME === "bun")
+            return "per-thread";
+        if ((threads ?? 1) <= 1)
+            return "per-thread";
+        return "serial-channel";
+    })();
+    const dispatcher = explicitDispatcher ?? autoDispatcher;
+    const serialChannel = dispatcher === "serial-channel";
+    const serialDispatcherChannel = serialChannel
+        ? new ChannelHandler()
+        : undefined;
     let workers = Array.from({
         length: threads ?? 1,
     }).map((_, thread) => spawnWorkerContext({
@@ -303,7 +324,56 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe,
         abortSignalCapacity,
         usesAbortSignal,
         permission: permissionProtocol,
+        sharedChannelHandler: serialDispatcherChannel,
     }));
+    const sharedDispatcherChannel = serialDispatcherChannel;
+    if (serialChannel) {
+        const channel = serialDispatcherChannel;
+        const checks = workers.map((context) => context.dispatcherCheck);
+        let serialScheduled = false;
+        let serialInFlight = false;
+        let serialRerun = false;
+        const runSerialChecks = () => {
+            if (serialInFlight) {
+                serialRerun = true;
+                return;
+            }
+            serialInFlight = true;
+            do {
+                serialRerun = false;
+                serialScheduled = false;
+                for (let index = 0; index < checks.length; index++) {
+                    const check = checks[index];
+                    if (check.isRunning !== true)
+                        check.isRunning = true;
+                    check();
+                }
+            } while (serialRerun);
+            serialInFlight = false;
+        };
+        const scheduleSerialCheck = () => {
+            if (serialInFlight) {
+                serialRerun = true;
+                return;
+            }
+            if (serialScheduled)
+                return;
+            serialScheduled = true;
+            Promise.resolve().then(runSerialChecks);
+        };
+        channel.open(runSerialChecks);
+        workers.forEach((context) => {
+            const wake = context.laneWake;
+            context.bindSend(() => {
+                scheduleSerialCheck();
+                wake();
+            });
+        });
+        hostDebug?.log(`dispatcher=serial-channel lanes=${checks.length}`);
+    }
+    else {
+        hostDebug?.log(`dispatcher=per-thread lanes=${workers.length}`);
+    }
     if (usingInliner) {
         const mainThread = createInlineExecutor({
             tasks: listOfFunctions,
@@ -337,7 +407,9 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe,
             return closePromise;
         closing = true;
         closePromise = Promise.allSettled(workers.map((context) => context.kills()))
-            .then(() => undefined);
+            .then(() => {
+            sharedDispatcherChannel?.close();
+        });
         return closePromise;
     };
     const wrapGuardedInvoke = ({ invoke, taskName, }) => (args) => {

package/src/runtime/dispatcher.d.ts

@@ -15,6 +15,11 @@ export declare const hostDispatcherLoop: ({ signalBox: { opView, txStatus, rxSta
         rerun: boolean;
     };
 };
+type CheckWithState = (() => void) & {
+    isRunning: boolean;
+    rerun: boolean;
+};
+export type DispatcherCheck = CheckWithState;
 export declare class ChannelHandler {
     #private;
     channel: RuntimeMessageChannelLike;
@@ -32,3 +37,4 @@ export declare class ChannelHandler {
      */
     close(): void;
 }
+export {};

package/src/runtime/pool.d.ts

@@ -1,10 +1,11 @@
 import { type ProcessSharedMemoryBacking } from "./process-worker.js";
 import { type Sab } from "../ipc/transport/shared-memory.js";
+import { ChannelHandler, type DispatcherCheck } from "./dispatcher.js";
 import { lock2 } from "../memory/lock.js";
 import type { DebugOptions, DispatcherSettings, WorkerContext, WorkerData, WorkerSettings } from "../types.js";
 import "../worker/loop.js";
 import { type PayloadBufferOptions } from "../memory/payload-config.js";
-export declare const spawnWorkerContext: ({ list, ids, names, sab, thread, debug, hostDebug, totalNumberOfThread, source, at, workerOptions, workerExecArgv, permission, host, payload, bufferReferenceReturn, abortSignalCapacity, usesAbortSignal, }: {
+export declare const spawnWorkerContext: ({ list, ids, names, sab, thread, debug, hostDebug, totalNumberOfThread, source, at, workerOptions, workerExecArgv, permission, host, payload, bufferReferenceReturn, abortSignalCapacity, usesAbortSignal, sharedChannelHandler, }: {
     list: string[];
     ids: number[];
     names: string[];
@@ -23,8 +24,16 @@ export declare const spawnWorkerContext: ({ list, ids, names, sab, thread, debug
     bufferReferenceReturn?: "copy" | "borrow";
     abortSignalCapacity?: number;
     usesAbortSignal?: boolean;
+    /**
+     * When set, this lane keeps its dispatcher state while the pool owns the
+     * macro channel that runs all lane checks.
+     */
+    sharedChannelHandler?: ChannelHandler;
 }) => WorkerContext & {
     lock: ReturnType<typeof lock2>;
     processSharedMemoryBackings?: readonly ProcessSharedMemoryBacking[];
+    dispatcherCheck?: DispatcherCheck;
+    laneWake?: () => void;
+    bindSend?: (fn: () => void) => void;
 };
 export type CreateContext = WorkerContext;

package/src/runtime/pool.js

@@ -1,7 +1,7 @@
 import { createHostTxQueue } from "./tx-queue.js";
 import { cleanupProcessWorkerMemoryQuietly, createProcessSharedMemoryAllocator, createProcessWorkerMemoryLayout, createProcessWorkerNativeSignalNotifier, readProcessSharedMemorySettings, readProcessWorkerCommandPrefix, readProcessWorkerRuntime, serializeWorkerBootstrapData, spawnProcessWorker, terminateWorkerQuietly, toProcessWorkerBootPayload, toWorkerCompatExecArgv, toWorkerSafeExecArgv, } from "./process-worker.js";
 import { createSharedMemoryTransport, TRANSPORT_SIGNAL_BYTES, } from "../ipc/transport/shared-memory.js";
-import { ChannelHandler, hostDispatcherLoop } from "./dispatcher.js";
+import { ChannelHandler, hostDispatcherLoop, } from "./dispatcher.js";
 import { HEADER_SLOT_STRIDE_U32, lock2, LOCK_SECTOR_BYTE_LENGTH, LockBound, } from "../memory/lock.js";
 import "../worker/loop.js";
 import { createSharedArrayBuffer, createWasmSharedArrayBuffer, } from "../common/runtime.js";
@@ -34,7 +34,7 @@ const withFixedPayloadConfig = (config) => ({
     mode: "fixed",
     payloadInitialBytes: config.payloadMaxByteLength,
 });
-export const spawnWorkerContext = ({ list, ids, names, sab, thread, debug, hostDebug, totalNumberOfThread, source, at, workerOptions, workerExecArgv, permission, host, payload, bufferReferenceReturn, abortSignalCapacity, usesAbortSignal, }) => {
+export const spawnWorkerContext = ({ list, ids, names, sab, thread, debug, hostDebug, totalNumberOfThread, source, at, workerOptions, workerExecArgv, permission, host, payload, bufferReferenceReturn, abortSignalCapacity, usesAbortSignal, sharedChannelHandler, }) => {
     const tsFileUrl = new URL(import.meta.url);
     const poliWorker = RUNTIME_WORKER;
     const resolvedWorkerOptions = serializeWorkerBootstrapData(withDefaultWorkerTimers(workerOptions));
@@ -189,15 +189,44 @@ export const spawnWorkerContext = ({ list, ids, names, sab, thread, debug, hostD
             : undefined,
     });
     const { enqueue, rejectAll, txIdle, } = queue;
-    const channelHandler = new ChannelHandler();
-    const { check } = hostDispatcherLoop({
+    const thisSignal = signalBox.opView;
+    const a_add = Atomics.add;
+    const a_load = Atomics.load;
+    const a_notify = Atomics.notify;
+    const canNotifySignal = thisSignal.buffer instanceof SharedArrayBuffer;
+    const notifySignal = nativeNotifySignal ??
+        (canNotifySignal ? (() => a_notify(thisSignal, 0, 1)) : undefined);
+    // Wakes this lane's worker when it is parked (rxStatus 0). Used by send()
+    // (new work just arrived) — the dispatcher drain wakes it the same way.
+    const laneWake = () => {
+        if (a_load(signalBox.rxStatus, 0) === 0) {
+            a_add(thisSignal, 0, 1);
+            notifySignal?.();
+        }
+    };
+    let dispatchSend = () => { };
+    const send = () => dispatchSend();
+    let channelHandler;
+    const ownsChannel = sharedChannelHandler === undefined;
+    const ownChannel = sharedChannelHandler ?? new ChannelHandler();
+    const { check: dispatcherCheck } = hostDispatcherLoop({
         signalBox,
         queue,
-        channelHandler,
+        channelHandler: ownChannel,
         dispatcherOptions: host,
         notifySignal: nativeNotifySignal,
     });
-    channelHandler.open(check);
+    if (ownsChannel) {
+        ownChannel.open(dispatcherCheck);
+        channelHandler = ownChannel;
+        dispatchSend = () => {
+            if (dispatcherCheck.isRunning === true)
+                return;
+            dispatcherCheck.isRunning = true;
+            Promise.resolve().then(dispatcherCheck);
+            laneWake();
+        };
+    }
     let worker;
     const workerUrl = source ?? tsFileUrl;
     const workerMode = useProcessWorkerRuntime
@@ -301,7 +330,7 @@ export const spawnWorkerContext = ({ list, ids, names, sab, thread, debug, hostD
             return;
         closedReason = reason;
         rejectAll(reason);
-        channelHandler.close();
+        channelHandler?.close();
     };
     const onWorkerMessage = (message) => {
         if (!isWorkerFatalMessage(message))
@@ -343,27 +372,6 @@ export const spawnWorkerContext = ({ list, ids, names, sab, thread, debug, hostD
             };
         }
     }
-    const thisSignal = signalBox.opView;
-    const a_add = Atomics.add;
-    const a_load = Atomics.load;
-    const a_notify = Atomics.notify;
-    const canNotifySignal = thisSignal.buffer instanceof SharedArrayBuffer;
-    const notifySignal = nativeNotifySignal ??
-        (canNotifySignal ? (() => a_notify(thisSignal, 0, 1)) : undefined);
-    //const scheduleFastCheck = queueMicrotask;
-    const send = () => {
-        if (check.isRunning === true)
-            return;
-        check.isRunning = true;
-        Promise.resolve().then(check);
-        // Macro lane: dispatcher check is driven by the channel callback.
-        // channelHandler.notify();
-        // Use opView as a wake token in lock2 mode to avoid lost wakeups.
-        if (a_load(signalBox.rxStatus, 0) === 0) {
-            a_add(thisSignal, 0, 1);
-            notifySignal?.();
-        }
-    };
     lock.setPromiseHandler((task, isRejected, value) => {
         queue.settlePromisePayload(task, isRejected, value);
         send();
@@ -386,6 +394,11 @@ export const spawnWorkerContext = ({ list, ids, names, sab, thread, debug, hostD
         },
         lock,
         processSharedMemoryBackings: processSharedMemory?.backings,
+        dispatcherCheck,
+        laneWake: sharedChannelHandler !== undefined ? laneWake : undefined,
+        bindSend: sharedChannelHandler !== undefined
+            ? ((fn) => void (dispatchSend = fn))
+            : undefined,
     };
     return context;
 };

package/src/runtime/tx-queue.js

@@ -50,7 +50,11 @@ export function createHostTxQueue({ max, lock, returnLock, releaseBufferReferenc
     const completeFrame = releaseBufferReferenceReturn === undefined
         ? resolveReturn
         : () => withBufferReferenceReturnReleaser(releaseBufferReferenceReturn, resolveReturn);
-    const txIdle = () => getPendingFrameCount() === 0 && inUsed === getPendingPromiseCount();
+    const hasActiveTasks = () => {
+        const count = (inUsed - getPendingPromiseCount()) | 0;
+        return count > 0;
+    };
+    const txIdle = () => getPendingFrameCount() === 0 && !hasActiveTasks();
     const rejectAll = (reason) => {
         for (let index = 0; index < queue.length; index++) {
             const slot = queue[index];

package/src/types.d.ts

@@ -98,7 +98,7 @@ type TaskLike<AS extends AbortSignalOption = AbortSignalOption> = {
 });
 type TaskFunctionLike = (...args: any[]) => any;
 type Composed<A extends TaskInput = Args, B extends Args = Args, AS extends AbortSignalOption = undefined> = FixPoint<A, B, AS> & SecondPart;
-type tasks = Record<string, Composed<any, any, AbortSignalOption> | TaskFunctionLike>;
+type tasks = Record<string, Composed<any, any, any> | TaskFunctionLike>;
 type ComposedWithKey = Composed<any, any, AbortSignalOption> & {
     name: string;
 };
@@ -296,6 +296,17 @@ type DispatcherSettings = {
      * Max backoff delay (milliseconds).
      */
     maxBackoffMs?: number;
+    /**
+     * Host dispatcher topology.
+     * - `"per-thread"`: each worker owns its dispatcher and macro channel.
+     * - `"serial-channel"`: each worker keeps its own dispatcher check state, but
+     *   one shared channel runs all lane checks from first to last.
+     *
+     * Experimental default: `"per-thread"` on Bun or with one worker, otherwise
+     * `"serial-channel"` for multi-worker Node/Deno pools. Can also be forced
+     * with the `KNITTING_DISPATCHER` env var (`serial-channel` or `per-thread`).
+     */
+    dispatcher?: "per-thread" | "serial-channel";
 };
 type CreatePool = {
     /** Number of workers. Default: 1. */

package/src/worker/timers.js

@@ -50,7 +50,7 @@ const isPlainNodeWindows = runtimeGlobals.process?.platform === "win32" &&
 // full parkMs (up to seconds); the long park with no wake is what made CI
 // runners appear to hang. The native wait already polls internally, so this is
 // just bounding each poll slice.
-const nativeWaitTimeoutMs = (parkMs) => isPlainNodeWindows ? 1 : Number.isFinite(parkMs) ? parkMs : 60;
+const nativeWaitTimeoutMs = (parkMs) => isPlainNodeWindows ? 1 : Number.isFinite(parkMs) ? parkMs : Infinity;
 export const whilePausing = ({ pauseInNanoseconds }) => {
     const forNanoseconds = pauseInNanoseconds ?? DEFAULT_PAUSE_TIME;
     if (!a_pause || forNanoseconds <= 0)
@@ -104,12 +104,12 @@ export const sleepUntilChanged = ({ at, opView, pauseInNanoseconds, rxStatus, tx
             // This is the notify-able path: a host Atomics.notify on opView wakes it.
             // An infinite parkMs (debug) is intentional here — the worker blocks until
             // a real signal instead of re-polling on a timeout.
-            a_wait(opView, at, value, parkMs ?? 60);
+            a_wait(opView, at, value, parkMs ?? Infinity);
         }
         else if (a_wait && waitFallbackView) {
             // waitFallbackView is never notified — this wait only ever times out and
             // re-polls, so it must stay finite or the worker would hang forever.
-            a_wait(waitFallbackView, 0, 0, Number.isFinite(parkMs) ? parkMs : 1);
+            a_wait(waitFallbackView, 0, 0, Number.isFinite(parkMs) ? parkMs : Infinity);
         }
         a_store(rxStatus, 0, 1);
     };