knitting 0.1.55 → 0.1.56

package/src/runtime/pool.js

@@ -0,0 +1,404 @@
+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 { 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";
+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";
+import { createLockControlCarpet } from "../memory/byte-carpet.js";
+import { resolvePayloadBufferOptions, } from "../memory/payload-config.js";
+import { createBufferReferenceReturnReleaseMessage } from "../connections/buffer-reference.js";
+const WORKER_FATAL_MESSAGE_KEY = "__knittingWorkerFatal";
+const isWorkerFatalMessage = (value) => !!value &&
+    typeof value === "object" &&
+    typeof value[WORKER_FATAL_MESSAGE_KEY] === "string";
+// Keep idle workers self-healing if an Atomics.notify wake is missed.
+const DEFAULT_WORKER_PARK_MS = 1;
+const withDefaultWorkerTimers = (options) => {
+    const parkMs = options?.timers?.parkMs ?? DEFAULT_WORKER_PARK_MS;
+    if (options === undefined)
+        return { timers: { parkMs } };
+    return {
+        ...options,
+        timers: {
+            ...options.timers,
+            parkMs,
+        },
+    };
+};
+const withFixedPayloadConfig = (config) => ({
+    ...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, sharedChannelHandler, }) => {
+    const tsFileUrl = new URL(import.meta.url);
+    const poliWorker = RUNTIME_WORKER;
+    const resolvedWorkerOptions = serializeWorkerBootstrapData(withDefaultWorkerTimers(workerOptions));
+    const useProcessWorkerRuntime = resolvedWorkerOptions.runtime === "process";
+    const processWorkerRuntime = useProcessWorkerRuntime
+        ? readProcessWorkerRuntime(resolvedWorkerOptions)
+        : undefined;
+    const processWorkerCommandPrefix = useProcessWorkerRuntime
+        ? readProcessWorkerCommandPrefix(resolvedWorkerOptions)
+        : undefined;
+    const processSharedMemorySettings = useProcessWorkerRuntime
+        ? readProcessSharedMemorySettings(resolvedWorkerOptions)
+        : undefined;
+    if (!useProcessWorkerRuntime && typeof poliWorker !== "function") {
+        throw new Error("Worker is not available in this runtime");
+    }
+    const WorkerCtor = poliWorker;
+    // Lock buffers must be shared between host and worker.
+    const sanitizeBytes = (value) => {
+        if (!Number.isFinite(value))
+            return undefined;
+        const bytes = Math.floor(value);
+        return bytes > 0 ? bytes : undefined;
+    };
+    const basePayloadConfig = resolvePayloadBufferOptions({
+        options: payload,
+    });
+    const resolvedPayloadConfig = useProcessWorkerRuntime
+        ? withFixedPayloadConfig(basePayloadConfig)
+        : basePayloadConfig;
+    const defaultAbortSignalCapacity = 258;
+    const requestedAbortSignalCapacity = sanitizeBytes(abortSignalCapacity);
+    const resolvedAbortSignalCapacity = requestedAbortSignalCapacity ??
+        defaultAbortSignalCapacity;
+    const abortSignalWords = Math.max(1, Math.ceil(resolvedAbortSignalCapacity / 32));
+    const requestedSignalBytes = sanitizeBytes(sab?.size);
+    const externalSignalSab = sab?.sharedSab;
+    if (useProcessWorkerRuntime && externalSignalSab != null) {
+        throw new Error("process worker runtime cannot use an external signal buffer");
+    }
+    const signalBytes = Math.max(TRANSPORT_SIGNAL_BYTES, requestedSignalBytes ?? TRANSPORT_SIGNAL_BYTES);
+    const abortBytes = abortSignalWords * Uint32Array.BYTES_PER_ELEMENT;
+    const processWorkerMemory = useProcessWorkerRuntime
+        ? createProcessWorkerMemoryLayout({
+            signalBytes,
+            abortBytes,
+            payloadBytes: resolvedPayloadConfig.payloadMaxByteLength,
+            thread,
+            sharedMemory: processSharedMemorySettings,
+        })
+        : undefined;
+    const processSharedMemory = processWorkerMemory === undefined
+        ? createProcessSharedMemoryAllocator(debug)
+        : undefined;
+    const createControlBuffer = processSharedMemory?.createBuffer ??
+        createWasmSharedArrayBuffer;
+    const createPayloadBuffer = processSharedMemory?.createBuffer;
+    const makePayloadBuffer = () => createPayloadBuffer
+        // ProcessSharedBuffer is fixed-size today, so reserve the configured
+        // payload ceiling instead of relying on SAB growth.
+        ? createPayloadBuffer(resolvedPayloadConfig.payloadMaxByteLength)
+        : resolvedPayloadConfig.mode === "growable"
+            ? createSharedArrayBuffer(resolvedPayloadConfig.payloadInitialBytes, resolvedPayloadConfig.payloadMaxByteLength)
+            : createSharedArrayBuffer(resolvedPayloadConfig.payloadInitialBytes);
+    const makeLockControlLayout = () => {
+        // Keep the hottest control words in one compact front strip:
+        // transport signals -> request lock -> return lock.
+        // Request/return headers stay in separate contiguous slabs to preserve
+        // sequential batching locality.
+        // Abort bitmap stays at the tail.
+        return createLockControlCarpet({
+            signalBytes,
+            abortBytes,
+            lockSectorBytes: LOCK_SECTOR_BYTE_LENGTH,
+            headerSlotStrideU32: HEADER_SLOT_STRIDE_U32,
+            slotCount: LockBound.slots,
+            headerLayout: "split",
+            createBuffer: createControlBuffer,
+        });
+    };
+    const controlLayout = processWorkerMemory?.controlLayout ??
+        makeLockControlLayout();
+    const lockPayload = processWorkerMemory?.lockPayload ?? makePayloadBuffer();
+    const lockBuffers = {
+        ...controlLayout.lock,
+        payload: lockPayload,
+        textCompat: probeLockBufferTextCompat({
+            headers: controlLayout.lock.headers,
+            payload: lockPayload,
+        }),
+    };
+    const returnPayload = processWorkerMemory?.returnPayload ??
+        makePayloadBuffer();
+    const returnLockBuffers = {
+        ...controlLayout.returnLock,
+        payload: returnPayload,
+        textCompat: probeLockBufferTextCompat({
+            headers: controlLayout.returnLock.headers,
+            payload: returnPayload,
+        }),
+    };
+    const lock = lock2({
+        headers: lockBuffers.headers,
+        headerSlotStrideU32: lockBuffers.headerSlotStrideU32,
+        LockBoundSector: lockBuffers.lockSector,
+        payload: lockBuffers.payload,
+        payloadSector: lockBuffers.payloadSector,
+        payloadConfig: resolvedPayloadConfig,
+        textCompat: lockBuffers.textCompat,
+    });
+    const returnLock = lock2({
+        headers: returnLockBuffers.headers,
+        headerSlotStrideU32: returnLockBuffers.headerSlotStrideU32,
+        LockBoundSector: returnLockBuffers.lockSector,
+        payload: returnLockBuffers.payload,
+        payloadSector: returnLockBuffers.payloadSector,
+        payloadConfig: resolvedPayloadConfig,
+        textCompat: returnLockBuffers.textCompat,
+    });
+    const abortSignalSAB = usesAbortSignal === true
+        ? controlLayout.abortSignals
+        : undefined;
+    const abortSignals = abortSignalSAB
+        ? signalAbortFactory({
+            sab: abortSignalSAB,
+            maxSignals: resolvedAbortSignalCapacity,
+        })
+        : undefined;
+    const signals = createSharedMemoryTransport({
+        sabObject: externalSignalSab == null
+            ? {
+                size: requestedSignalBytes,
+                sharedSab: controlLayout.signals,
+            }
+            : sab,
+        isMain: true,
+        thread,
+    });
+    const signalBox = signals;
+    const nativeNotifySignal = createProcessWorkerNativeSignalNotifier({
+        processRuntime: processWorkerRuntime,
+        signal: signalBox.opView,
+    });
+    const queue = createHostTxQueue({
+        lock,
+        returnLock,
+        abortSignals,
+        releaseBufferReferenceReturn: bufferReferenceReturn === "borrow"
+            ? (token) => {
+                worker?.postMessage?.(createBufferReferenceReturnReleaseMessage(token));
+            }
+            : undefined,
+    });
+    const { enqueue, rejectAll, txIdle, } = queue;
+    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: ownChannel,
+        dispatcherOptions: host,
+        notifySignal: nativeNotifySignal,
+    });
+    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
+        ? "process"
+        : HAS_NODE_WORKER_THREADS
+            ? "worker_threads"
+            : "worker";
+    hostDebug?.(`worker thread=${thread} mode=${workerMode}` +
+        `${processWorkerRuntime ? ` runtime=${processWorkerRuntime}` : ""}` +
+        ` url=${String(workerUrl)}`);
+    const workerDataPayload = {
+        sab: signals.sab,
+        abortSignalSAB,
+        abortSignalMax: usesAbortSignal === true
+            ? resolvedAbortSignalCapacity
+            : undefined,
+        list,
+        ids,
+        names,
+        at,
+        thread,
+        debug,
+        workerOptions: resolvedWorkerOptions,
+        totalNumberOfThread,
+        startAt: signalBox.startAt,
+        lock: lockBuffers,
+        returnLock: returnLockBuffers,
+        payloadConfig: resolvedPayloadConfig,
+        bufferReferenceReturn,
+        permission,
+    };
+    const baseWorkerOptions = {
+        //@ts-ignore Reason
+        type: "module",
+        //@ts-ignore
+        workerData: workerDataPayload,
+    };
+    const withExecArgv = workerExecArgv && workerExecArgv.length > 0
+        ? { ...baseWorkerOptions, execArgv: workerExecArgv }
+        : baseWorkerOptions;
+    if (processWorkerMemory !== undefined) {
+        worker = spawnProcessWorker({
+            workerUrl,
+            bootPayload: toProcessWorkerBootPayload(workerDataPayload, processWorkerMemory),
+            memory: processWorkerMemory,
+            processRuntime: processWorkerRuntime,
+            commandPrefix: processWorkerCommandPrefix,
+            permission,
+        });
+    }
+    else if (HAS_NODE_WORKER_THREADS) {
+        try {
+            worker = new WorkerCtor(workerUrl, withExecArgv);
+        }
+        catch (error) {
+            if (error?.code === "ERR_WORKER_INVALID_EXEC_ARGV") {
+                const fallbackExecArgv = toWorkerSafeExecArgv(withExecArgv.execArgv);
+                if (fallbackExecArgv && fallbackExecArgv.length > 0) {
+                    try {
+                        worker = new WorkerCtor(workerUrl, { ...baseWorkerOptions, execArgv: fallbackExecArgv });
+                    }
+                    catch (fallbackError) {
+                        if (fallbackError?.code ===
+                            "ERR_WORKER_INVALID_EXEC_ARGV") {
+                            const compatExecArgv = toWorkerCompatExecArgv(fallbackExecArgv);
+                            if (compatExecArgv && compatExecArgv.length > 0) {
+                                try {
+                                    worker = new WorkerCtor(workerUrl, { ...baseWorkerOptions, execArgv: compatExecArgv });
+                                }
+                                catch {
+                                    worker = new WorkerCtor(workerUrl, baseWorkerOptions);
+                                }
+                            }
+                            else {
+                                worker = new WorkerCtor(workerUrl, baseWorkerOptions);
+                            }
+                        }
+                        else {
+                            throw fallbackError;
+                        }
+                    }
+                }
+                else {
+                    worker = new WorkerCtor(workerUrl, baseWorkerOptions);
+                }
+            }
+            else {
+                throw error;
+            }
+        }
+    }
+    else {
+        worker = new WorkerCtor(workerUrl, {
+            type: "module",
+        });
+        worker.postMessage?.(workerDataPayload);
+    }
+    let closedReason;
+    const markWorkerClosed = (reason) => {
+        if (closedReason)
+            return;
+        closedReason = reason;
+        rejectAll(reason);
+        channelHandler?.close();
+    };
+    const onWorkerMessage = (message) => {
+        if (!isWorkerFatalMessage(message))
+            return;
+        markWorkerClosed(`Worker startup failed: ${message[WORKER_FATAL_MESSAGE_KEY]}`);
+        terminateWorkerQuietly(worker);
+    };
+    const onWorkerError = (error) => {
+        const message = String(error?.message ?? error);
+        markWorkerClosed(`Worker crashed: ${message}`);
+    };
+    const nodeWorker = worker;
+    if (typeof nodeWorker.on === "function") {
+        nodeWorker.on("message", onWorkerMessage);
+        nodeWorker.on("error", onWorkerError);
+        nodeWorker.on("exit", (code) => {
+            if (typeof code === "number" && code === 0)
+                return;
+            const normalized = typeof code === "number" ? code : -1;
+            markWorkerClosed(`Worker exited with code ${normalized}`);
+        });
+    }
+    else {
+        const eventWorker = worker;
+        if (typeof eventWorker.addEventListener === "function") {
+            eventWorker.addEventListener("message", (event) => {
+                onWorkerMessage(event?.data);
+            });
+            eventWorker.addEventListener("error", (event) => {
+                onWorkerError(event?.error ?? event?.message ?? event);
+            });
+        }
+        else {
+            eventWorker.onmessage = (event) => {
+                onWorkerMessage(event?.data);
+            };
+            eventWorker.onerror = (event) => {
+                onWorkerError(event);
+            };
+        }
+    }
+    lock.setPromiseHandler((task, isRejected, value) => {
+        queue.settlePromisePayload(task, isRejected, value);
+        send();
+    });
+    const call = ({ fnNumber, timeout, abortSignal }) => {
+        const enqueues = enqueue(fnNumber, timeout, abortSignal);
+        return (args) => {
+            const pending = enqueues(args);
+            send();
+            return pending;
+        };
+    };
+    const context = {
+        txIdle,
+        call,
+        kills: async () => {
+            markWorkerClosed("Thread closed");
+            terminateWorkerQuietly(worker);
+            cleanupProcessWorkerMemoryQuietly(processWorkerMemory);
+        },
+        lock,
+        processSharedMemoryBackings: processSharedMemory?.backings,
+        dispatcherCheck,
+        laneWake: sharedChannelHandler !== undefined ? laneWake : undefined,
+        bindSend: sharedChannelHandler !== undefined
+            ? ((fn) => void (dispatchSend = fn))
+            : undefined,
+    };
+    return context;
+};

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

@@ -0,0 +1,92 @@
+import { type LockControlCarpet } from "../memory/byte-carpet.js";
+import type { DebugOptions, LockBuffers, WorkerData, WorkerSettings } from "../types.js";
+import { RUNTIME_PROCESS_WORKER_BOOT_VERSION } from "../common/worker-runtime.js";
+import { type SharedBufferSource } from "../common/shared-buffer-region.js";
+import { FileDescriptor, type ProcessSharedBufferMetadata } from "../connections/index.js";
+import type { SharedMemoryBuffer, SharedMemoryMapping } from "../connections/types.js";
+export type SpawnedWorker = {
+    terminate: () => unknown;
+    unref?: () => unknown;
+    postMessage?: (message: unknown) => void;
+};
+export type NodeWorkerLike = {
+    on?: (event: "error" | "exit" | "message", listener: (...args: unknown[]) => void) => void;
+};
+type ProcessWorkerWireLockBuffers = Omit<LockBuffers, "headers" | "lockSector" | "payload" | "payloadSector"> & {
+    headers: ProcessSharedBufferMetadata;
+    lockSector: ProcessSharedBufferMetadata;
+    payload: ProcessSharedBufferMetadata;
+    payloadSector: ProcessSharedBufferMetadata;
+};
+type ProcessWorkerWireData = Omit<WorkerData, "sab" | "abortSignalSAB" | "lock" | "returnLock"> & {
+    sab: ProcessSharedBufferMetadata;
+    abortSignalSAB?: ProcessSharedBufferMetadata;
+    lock: ProcessWorkerWireLockBuffers;
+    returnLock: ProcessWorkerWireLockBuffers;
+};
+export type ProcessWorkerBootPayload = {
+    version: typeof RUNTIME_PROCESS_WORKER_BOOT_VERSION;
+    workerData: ProcessWorkerWireData;
+};
+export type ProcessWorkerMemoryLayout = {
+    mapping: SharedMemoryMapping<SharedMemoryBuffer>;
+    descriptor: FileDescriptor;
+    controlLayout: LockControlCarpet;
+    lockPayload: SharedBufferSource;
+    returnPayload: SharedBufferSource;
+    cleanup: () => void;
+};
+export type ProcessWorkerRuntime = NonNullable<WorkerSettings["processRuntime"]>;
+export type ProcessWorkerCommandPrefix = NonNullable<WorkerSettings["processCommandPrefix"]>;
+export type ResolvedProcessSharedMemorySettings = {
+    mode: "inherit" | "named";
+    namePrefix?: string;
+    unlinkOnShutdown: boolean;
+};
+type ProcessSharedMemoryNativeMapping = {
+    sab: SharedArrayBuffer;
+    fd: number;
+    name?: string;
+    size: number;
+    baseAddressMod64?: number;
+};
+export type ProcessSharedMemoryBacking = ProcessSharedMemoryNativeMapping & {
+    runtime: "node";
+    buffer: SharedArrayBuffer;
+    kind: "shared-array-buffer";
+    byteLength: number;
+};
+type ProcessSharedMemoryAllocator = {
+    createBuffer: (byteLength: number) => SharedArrayBuffer;
+    backings: ProcessSharedMemoryBacking[];
+};
+export declare const toWorkerSafeExecArgv: (flags: string[] | undefined) => string[] | undefined;
+export declare const toWorkerCompatExecArgv: (flags: string[] | undefined) => string[] | undefined;
+export declare const createProcessSharedMemoryAllocator: (debug: DebugOptions | undefined) => ProcessSharedMemoryAllocator | undefined;
+export declare const createProcessWorkerMemoryLayout: ({ signalBytes, abortBytes, payloadBytes, thread, sharedMemory, }: {
+    signalBytes: number;
+    abortBytes: number;
+    payloadBytes: number;
+    thread: number;
+    sharedMemory: ResolvedProcessSharedMemorySettings;
+}) => ProcessWorkerMemoryLayout;
+export declare const serializeWorkerBootstrapData: (options: WorkerSettings) => WorkerSettings;
+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;
+export declare const readProcessSharedMemorySettings: (options: WorkerSettings | undefined) => ResolvedProcessSharedMemorySettings;
+export declare const createProcessWorkerNativeSignalNotifier: ({ processRuntime, signal, }: {
+    processRuntime: ProcessWorkerRuntime | undefined;
+    signal: Int32Array;
+}) => (() => void) | undefined;
+export declare const spawnProcessWorker: (options: {
+    workerUrl: string | URL;
+    bootPayload: ProcessWorkerBootPayload;
+    memory: ProcessWorkerMemoryLayout;
+    processRuntime: ProcessWorkerRuntime;
+    commandPrefix?: ProcessWorkerCommandPrefix;
+    permission?: WorkerData["permission"];
+}) => SpawnedWorker & NodeWorkerLike;
+export declare const terminateWorkerQuietly: (worker: SpawnedWorker) => void;
+export declare const cleanupProcessWorkerMemoryQuietly: (memory: ProcessWorkerMemoryLayout | undefined) => void;
+export {};