knitting 0.1.50 → 0.1.52

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "knitting",
-  "version": "0.1.50",
+  "version": "0.1.52",
   "description": "Shared-memory IPC runtime for Node.js, Deno, and Bun.",
   "license": "Apache-2.0",
   "repository": {
@@ -23,6 +23,14 @@
     "./process-shared-buffer": {
       "types": "./process-shared-buffer.d.ts",
       "default": "./process-shared-buffer.js"
+    },
+    "./unsafe": {
+      "types": "./unsafe.d.ts",
+      "default": "./unsafe.js"
+    },
+    "./utils": {
+      "types": "./utils.d.ts",
+      "default": "./utils.js"
     }
   },
   "files": [
@@ -38,7 +46,11 @@
     "knitting.d.ts",
     "knitting.js",
     "process-shared-buffer.d.ts",
-    "process-shared-buffer.js"
+    "process-shared-buffer.js",
+    "unsafe.d.ts",
+    "unsafe.js",
+    "utils.d.ts",
+    "utils.js"
   ],
   "scripts": {
     "build": "bun run build.ts",
@@ -66,13 +78,13 @@
     "bun": ">=1.0.0"
   },
   "peerDependencies": {
-    "typescript": "^5.0.0"
+    "typescript": "^5.2.0"
   },
   "devDependencies": {
     "@types/bun": "latest",
     "@types/deno": "latest",
     "@types/node": "latest",
     "mitata": "^1.0.34",
-    "typescript": "^5.0.0"
+    "typescript": "^5.2.0"
   }
 }

package/scripts/build-native-addons.ts

@@ -232,6 +232,11 @@ const addons = [
     source: "src/knitting_shm.cc",
     output: "build/Release/knitting_shm.node",
   },
+  {
+    name: "knitting_buffer_pointer",
+    source: "src/knitting_buffer_pointer.cc",
+    output: "build/Release/knitting_buffer_pointer.node",
+  },
 ];
 const ffiLibraries = isWindows
   ? [

package/src/api.d.ts

@@ -1,18 +1,17 @@
 import { endpointSymbol } from "./common/task-symbol.js";
-import type { Args, AbortSignalConfig, AbortSignalOption, AbortSignalToolkit, CreatePool, FixPoint, MaybePromise, Pool, TaskInput, ReturnFixed, ImportTaskOptions, TaskTimeout, tasks } from "./types.js";
+import type { AbortSignalConfig, AbortSignalOption, AbortSignalToolkit, Args, ComposedWithKey, CreatePool, FixPoint, ImportTaskOptions, MaybePromise, Pool, ReturnFixed, TaskInput, tasks, TaskTimeout } from "./types.js";
 type ToListAndIds = {
     list: string[];
     ids: number[];
+    names: string[];
     at: number[];
 };
-type ToListAndIdsFn = (args: tasks) => ToListAndIds;
+type ToListAndIdsFn = (args: ComposedWithKey[]) => ToListAndIds;
 type CreatePoolFactory = (options: CreatePool) => <T extends tasks>(tasks: T) => Pool<T>;
 type InferredTaskFunction = (...args: any[]) => MaybePromise<Args>;
 type InferredTaskInput<F extends InferredTaskFunction, AS extends AbortSignalOption> = Parameters<F> extends [] ? void : AS extends undefined ? Parameters<F> extends [infer A] ? A extends TaskInput ? A : never : never : Parameters<F> extends [infer A] ? A extends TaskInput ? A : never : Parameters<F> extends [infer A, AbortSignalToolkit<AS>] ? A extends TaskInput ? A : never : never;
 type InferredTaskOutput<F extends InferredTaskFunction> = Awaited<ReturnType<F>> extends infer R ? R extends Blob ? never : R extends Args ? R : never : never;
-type InferredTaskShape<F extends InferredTaskFunction, AS extends AbortSignalOption> = [
-    InferredTaskInput<F, AS>
-] extends [never] ? never : [InferredTaskOutput<F>] extends [never] ? never : {
+type InferredTaskShape<F extends InferredTaskFunction, AS extends AbortSignalOption> = [InferredTaskInput<F, AS>] extends [never] ? never : [InferredTaskOutput<F>] extends [never] ? never : {
     readonly f: F;
     readonly timeout?: TaskTimeout;
 } & (AS extends undefined ? {
@@ -23,12 +22,7 @@ type InferredTaskShape<F extends InferredTaskFunction, AS extends AbortSignalOpt
 export declare const isMain: boolean;
 export { endpointSymbol as endpointSymbol };
 /**
- *  With this information we can recreate the logical order of
- *  relevant exported functions from a file, also it helps to
- *  track a task before naming, ` export ` elements have to be declared
- *  at top level and without branching, we take advantage of this to
- *  correctly map them.
- *
+ * Reconstructs stable task order from top-level exports before names are bound.
  */
 export declare const toListAndIds: ToListAndIdsFn;
 export declare const createPool: CreatePoolFactory;

package/src/api.js

@@ -11,7 +11,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 { RUNTIME_IS_MAIN_THREAD, RUNTIME_WORKER_DATA, } from "./common/worker-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";
 import { getNodeProcess } from "./common/node-compat.js";
 import { managerMethod } from "./runtime/balancer.js";
@@ -22,27 +22,25 @@ const DEFAULT_IMPORT_EXPORT_NAME = "default";
 export const isMain = RUNTIME_IS_MAIN_THREAD;
 export { endpointSymbol as endpointSymbol };
 /**
- *  With this information we can recreate the logical order of
- *  relevant exported functions from a file, also it helps to
- *  track a task before naming, ` export ` elements have to be declared
- *  at top level and without branching, we take advantage of this to
- *  correctly map them.
- *
+ * Reconstructs stable task order from top-level exports before names are bound.
  */
 export const toListAndIds = (args) => {
-    const result = Object.values(args)
+    const result = args
         .reduce((acc, v) => (acc[0].add(v.importedFrom),
         acc[1].add(v.id),
         acc[2].add(v.at),
+        acc[3].push(v.name),
         acc), [
         new Set(),
         new Set(),
-        new Set()
+        new Set(),
+        [],
     ]);
     return {
         list: [...result[0]],
         ids: [...result[1]],
         at: [...result[2]],
+        names: result[3],
     };
 };
 const resolveImportHref = (href, callerHref) => {
@@ -73,7 +71,30 @@ const resolveWorkerBootstrapSettings = (worker, callerHref) => {
         },
     };
 };
-export const createPool = ({ threads, debug, inliner, balancer, payload, payloadInitialBytes, payloadMaxBytes, bufferMode, maxPayloadBytes, abortSignalCapacity, source, worker, workerExecArgv, permission, dispatcher, host, }) => (tasks) => {
+const isTaskDefinition = (value) => value != null &&
+    typeof value === "object" &&
+    typeof value.f === "function";
+const toPoolTaskEntries = (input, callerHref) => Object.entries(input).map(([name, value]) => {
+    if (isTaskDefinition(value)) {
+        return {
+            ...value,
+            name,
+        };
+    }
+    if (typeof value === "function") {
+        return {
+            f: value,
+            id: -1,
+            importedFrom: new URL(callerHref).href,
+            at: -1,
+            name,
+            [endpointSymbol]: true,
+        };
+    }
+    throw new TypeError(`createPool task "${name}" must be a task definition or exported function`);
+});
+export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe, payloadInitialBytes, payloadMaxBytes, bufferMode, maxPayloadBytes, abortSignalCapacity, source, worker, workerExecArgv, permission, dispatcher, host, }) => (tasks) => {
+    const bufferReferenceReturn = unsafe?.BufferReferenceReturn;
     /**
      *  This functions is only available in the main thread.
      *  Also triggers when debug extra is enabled.
@@ -97,14 +118,14 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, payload
         //@ts-ignore
         return {
             shutdown: mainThreadOnlyProxy,
+            [Symbol.dispose]: () => { },
             call: mainThreadOnlyProxy,
         };
     }
-    const { list, ids, at } = toListAndIds(tasks), listOfFunctions = Object.entries(tasks).map(([k, v]) => ({
-        ...v,
-        name: k,
-    }))
+    const callerHref = getCallerHref(3);
+    const listOfFunctions = toPoolTaskEntries(tasks, callerHref)
         .sort((a, b) => a.name.localeCompare(b.name));
+    const { list, ids, names, at } = toListAndIds(listOfFunctions);
     if (listOfFunctions.length > MAX_FUNCTION_COUNT) {
         throw new RangeError(`Too many tasks: received ${listOfFunctions.length}. ` +
             `Maximum is ${MAX_FUNCTION_COUNT} (Uint16 function IDs: 0..${MAX_FUNCTION_ID}).`);
@@ -177,18 +198,28 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, payload
     const execArgv = sanitizeExecArgv(combinedExecArgv.length > 0 ? combinedExecArgv : undefined);
     const hostDispatcher = host ?? dispatcher;
     const usesAbortSignal = listOfFunctions.some((fn) => fn.abortSignal !== undefined);
-    const resolvedWorker = resolveWorkerBootstrapSettings(worker, getCallerHref(3));
+    const resolvedWorker = resolveWorkerBootstrapSettings(worker, callerHref);
     if (usingInliner && resolvedWorker?.bootstrap !== undefined) {
         throw new Error("worker.bootstrap cannot be used with the inliner");
     }
     const hardTimeoutMs = Number.isFinite(resolvedWorker?.hardTimeoutMs)
         ? Math.max(1, Math.floor(resolvedWorker?.hardTimeoutMs))
         : undefined;
+    if (RUNTIME_POOL_DEPTH >= 1) {
+        throw new Error(`createPool() tried to spawn workers from inside a worker process ` +
+            `(pool depth ${RUNTIME_POOL_DEPTH}). This usually means a pool is ` +
+            `created at module scope in a module your workers import, so every ` +
+            `worker spawns its own pool recursively. Is your createPool protected ` +
+            `by isMain? Guard pool creation behind \`if (isMain) { ... }\` ` +
+            `(import { isMain } from "knitting") so only the main program starts ` +
+            `the pool.`);
+    }
     let workers = Array.from({
         length: threads ?? 1,
     }).map((_, thread) => spawnWorkerContext({
         list,
         ids,
+        names,
         at,
         thread,
         debug,
@@ -198,6 +229,7 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, payload
         workerExecArgv: execArgv,
         host: hostDispatcher,
         payload,
+        bufferReferenceReturn,
         payloadInitialBytes,
         payloadMaxBytes,
         bufferMode,
@@ -208,7 +240,7 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, payload
     }));
     if (usingInliner) {
         const mainThread = createInlineExecutor({
-            tasks,
+            tasks: listOfFunctions,
             genTaskID,
             batchSize: inliner?.batchSize ?? 1,
         });
@@ -293,11 +325,15 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, payload
         })();
         return shutdownPromise;
     };
+    const disposePool = () => {
+        void shutdownWithDelay();
+    };
     const indexedFunctions = listOfFunctions.map((fn, index) => ({
         name: fn.name,
         index,
         timeout: fn.timeout,
         abortSignal: fn.abortSignal,
+        imported: fn.imported === true,
     }));
     const callHandlers = new Map();
     for (const { name } of indexedFunctions) {
@@ -316,9 +352,38 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, payload
         }
     }
     const useDirectHandler = (threads ?? 1) === 1 && !usingInliner;
-    const buildInvoker = (handlers) => useDirectHandler
-        ? handlers[0]
-        : managerMethod({
+    // Imported tasks must never execute on the host inliner lane: their module
+    // import is meant to happen inside the worker so worker permission policies
+    // apply. When the inliner is active we strip the inline lane from their
+    // handler set so they only ever reach real worker lanes.
+    const buildImportedInvoker = (handlers) => {
+        const workerHandlers = [];
+        const workerContexts = [];
+        for (let lane = 0; lane < handlers.length; lane += 1) {
+            if (lane === inlinerIndex)
+                continue;
+            workerHandlers.push(handlers[lane]);
+            workerContexts.push(workers[lane]);
+        }
+        if (workerHandlers.length === 0) {
+            throw new Error("Imported task has no worker lane to run on: the pool only has the " +
+                "host inliner. Imported tasks are never inlined on the host; add at " +
+                "least one worker thread.");
+        }
+        if (workerHandlers.length === 1)
+            return workerHandlers[0];
+        return managerMethod({
+            contexts: workerContexts,
+            balancer,
+            handlers: workerHandlers,
+            // No inlinerGate: the inline lane is intentionally excluded here.
+        });
+    };
+    const buildInvoker = (handlers, imported) => {
+        if (imported && usingInliner) {
+            return buildImportedInvoker(handlers);
+        }
+        return useDirectHandler ? handlers[0] : managerMethod({
             contexts: workers,
             balancer,
             handlers,
@@ -329,9 +394,23 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, payload
                 }
                 : undefined,
         });
-    const callEntries = Array.from(callHandlers.entries(), ([name, handlers]) => [name, buildInvoker(handlers)]);
+    };
+    let callEntries;
+    try {
+        callEntries = indexedFunctions.map(({ name, imported }) => [name, buildInvoker(callHandlers.get(name), imported)]);
+    }
+    catch (error) {
+        // Building invokers can throw (e.g. an imported task with no worker lane,
+        // or a balancer that needs >=2 lanes). The inline executor and any spawned
+        // workers are already live here, so tear them down before propagating —
+        // otherwise their MessageChannel ports / worker handles keep the event
+        // loop alive and hang the process.
+        void closePoolNow();
+        throw error;
+    }
     return {
         shutdown: shutdownWithDelay,
+        [Symbol.dispose]: disposePool,
         call: Object.fromEntries(callEntries),
     };
 };
@@ -343,15 +422,17 @@ const createSingleTaskPool = (single, options) => {
     return {
         call: pool.call[SINGLE_TASK_KEY],
         shutdown: pool.shutdown,
+        [Symbol.dispose]: pool[Symbol.dispose],
     };
 };
-const buildTaskDefinitionFromCaller = (input, callerHref, at) => {
+const buildTaskDefinitionFromCaller = (input, callerHref, at, imported = false) => {
     const importedFrom = new URL(callerHref).href;
     const out = ({
         ...input,
         id: genTaskID(),
         importedFrom,
         at,
+        imported,
         [endpointSymbol]: true,
     });
     out.createPool = (options) => {
@@ -404,5 +485,5 @@ export function importTask(options) {
     return buildTaskDefinitionFromCaller({
         ...rest,
         f: createImportedTaskFn(resolvedHref, name),
-    }, callerHref, at);
+    }, callerHref, at, true);
 }

package/src/common/envelope.d.ts

@@ -1,11 +1,17 @@
+import type { BufferReference } from "../connections/buffer-reference.js";
+import type { ProcessSharedBuffer } from "../connections/process-shared-buffer.js";
 type EnvelopeHeaderPrimitive = string | number | boolean | null;
 type EnvelopeHeaderValue = EnvelopeHeaderPrimitive | EnvelopeHeaderValue[] | {
     [key: string]: EnvelopeHeaderValue;
 };
 export type EnvelopeHeader = EnvelopeHeaderValue;
-export declare class Envelope<H extends EnvelopeHeader = EnvelopeHeader> {
+export type EnvelopeBody = ArrayBuffer | SharedArrayBuffer | BufferReference | ProcessSharedBuffer;
+declare const PayloadTransportFinalizer: unique symbol;
+export declare class Envelope<H extends EnvelopeHeader = EnvelopeHeader, B extends EnvelopeBody = ArrayBuffer> {
     readonly header: H;
-    readonly payload: ArrayBuffer;
-    constructor(header: H, payload: ArrayBuffer);
+    readonly payload: B;
+    constructor(header: H, payload: B);
+    [Symbol.dispose](): void;
+    [PayloadTransportFinalizer](): (() => void) | undefined;
 }
 export {};

package/src/common/envelope.js

@@ -1,3 +1,4 @@
+const PayloadTransportFinalizer = Symbol.for("knitting.payloadCodec.transportFinalizer");
 export class Envelope {
     header;
     payload;
@@ -5,4 +6,17 @@ export class Envelope {
         this.header = header;
         this.payload = payload;
     }
+    [Symbol.dispose]() {
+        const body = this.payload;
+        if (body !== null && typeof body === "object") {
+            body[Symbol.dispose]?.();
+        }
+    }
+    [PayloadTransportFinalizer]() {
+        const body = this.payload;
+        if (body === null || typeof body !== "object")
+            return undefined;
+        const finalizer = body[PayloadTransportFinalizer];
+        return typeof finalizer === "function" ? finalizer.call(body) : undefined;
+    }
 }

package/src/common/task-source.js

@@ -2,9 +2,13 @@ import { toModuleUrl } from "./module-url.js";
 export const genTaskID = ((counter) => () => counter++)(0);
 const INTERNAL_CALLER_HINTS = [
     "/src/common/task-source.ts",
+    "/src/common/task-source.js",
     "\\src\\common\\task-source.ts",
+    "\\src\\common\\task-source.js",
     "/src/api.ts",
+    "/src/api.js",
     "\\src\\api.ts",
+    "\\src\\api.js",
 ];
 const INTERNAL_CALLER_FUNCTIONS = new Set([
     "collectStackFrames",

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

@@ -28,7 +28,9 @@ export type RuntimeMessageChannelLike = {
 export declare const RUNTIME_PROCESS_WORKER_ENV = "KNITTING_PROCESS_WORKER";
 export declare const RUNTIME_PROCESS_WORKER_BOOT_ENV = "KNITTING_PROCESS_WORKER_BOOT";
 export declare const RUNTIME_PROCESS_WORKER_BOOT_VERSION = 1;
+export declare const RUNTIME_POOL_DEPTH_ENV = "KNITTING_POOL_DEPTH";
 export declare const RUNTIME_IS_PROCESS_WORKER: boolean;
+export declare const RUNTIME_POOL_DEPTH: number;
 export declare const RUNTIME_WORKER: new (specifier: string | URL, options?: Record<string, unknown>) => RuntimeWorkerLike;
 export declare const RUNTIME_MESSAGE_CHANNEL: new () => RuntimeMessageChannelLike;
 export declare const HAS_NODE_WORKER_THREADS: boolean;

package/src/common/worker-runtime.js

@@ -2,8 +2,17 @@ import { getNodeBuiltinModule, getNodeProcess } from "./node-compat.js";
 export const RUNTIME_PROCESS_WORKER_ENV = "KNITTING_PROCESS_WORKER";
 export const RUNTIME_PROCESS_WORKER_BOOT_ENV = "KNITTING_PROCESS_WORKER_BOOT";
 export const RUNTIME_PROCESS_WORKER_BOOT_VERSION = 1;
+export const RUNTIME_POOL_DEPTH_ENV = "KNITTING_POOL_DEPTH";
 const nodeProcess = getNodeProcess();
 export const RUNTIME_IS_PROCESS_WORKER = nodeProcess?.env?.[RUNTIME_PROCESS_WORKER_ENV] === "1";
+const readPoolDepth = () => {
+    const raw = nodeProcess?.env?.[RUNTIME_POOL_DEPTH_ENV];
+    if (typeof raw !== "string")
+        return 0;
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
+};
+export const RUNTIME_POOL_DEPTH = readPoolDepth();
 const workerThreads = getNodeBuiltinModule("node:worker_threads");
 const isWorkerGlobalScope = () => {
     const scopeCtor = globalThis.WorkerGlobalScope;

package/src/connections/buffer-reference-native.d.ts

@@ -0,0 +1,56 @@
+export type BufferReferenceRuntime = "node" | "deno" | "bun";
+/** A backing store the producer has taken exclusive ownership of (source detached). */
+export type ProducedBuffer = {
+    /** Producer-side release handle. */
+    token: bigint;
+    /** Address of the region start (view offset already applied). */
+    pointer: bigint;
+    /** Offset of the region inside the backing store (used by the Node owning adopt). */
+    byteOffset: number;
+    byteLength: number;
+};
+export type AdoptInput = {
+    token: bigint;
+    pointer: bigint;
+    byteOffset: number;
+    byteLength: number;
+};
+/** The materialized region: bytes live in `buffer` at `[byteOffset, byteOffset+byteLength)`. */
+export type AdoptedRegion = {
+    buffer: ArrayBuffer;
+    byteOffset: number;
+    byteLength: number;
+};
+/** Materialized SAB region; `isShared` means `buffer` is a real SharedArrayBuffer. */
+export type SharedAdoptedRegion = {
+    buffer: SharedArrayBuffer | ArrayBuffer;
+    byteOffset: number;
+    byteLength: number;
+    isShared: boolean;
+};
+export type AdoptOptions = {
+    /** Copy when bytes must survive producer release on non-owning runtimes. */
+    copy?: boolean;
+};
+type MovableBufferSource = ArrayBuffer | ArrayBufferView;
+export type BufferReferenceCapabilities = {
+    readonly runtime: BufferReferenceRuntime;
+    /** True when `adopt` returns a buffer that co-owns the store and survives `release`. */
+    readonly supportsOwningAdopt: boolean;
+    /** Take exclusive ownership of `source`'s bytes, detaching the source. */
+    produce(source: MovableBufferSource): ProducedBuffer;
+    /** Materialize the region in the current isolate (owning on Node, alias/copy elsewhere). */
+    adopt(input: AdoptInput, opts?: AdoptOptions): AdoptedRegion;
+    /** Drop the producer's hold on the backing store. */
+    release(token: bigint): void;
+    /** True when `adoptShared` returns a real SharedArrayBuffer (Node). */
+    readonly supportsSharedAdopt: boolean;
+    /** Share a SharedArrayBuffer by reference (no detach — SABs persist). */
+    produceShared(sab: SharedArrayBuffer): ProducedBuffer;
+    /** Materialize a shared region as a non-owning alias over the same bytes. */
+    adoptShared(input: AdoptInput): SharedAdoptedRegion;
+    /** Drop the producer's pin on a shared buffer (JS-side; teardown-safe). */
+    releaseShared(token: bigint): void;
+};
+export declare const getBufferReferenceCapabilities: () => BufferReferenceCapabilities;
+export {};