knitting 0.1.55 → 0.1.60

package/src/connections/process-shared-buffer.js

@@ -0,0 +1,245 @@
+import { FileDescriptor, } from "./file-descriptor.js";
+import { RUNTIME } from "../common/runtime.js";
+import { createBunConnectionPrimitives } from "./bun.js";
+import { createDenoConnectionPrimitives } from "./deno.js";
+import { createNodeConnectionPrimitives } from "./node.js";
+export const PROCESS_SHARED_BUFFER_BRAND = Symbol.for("knitting.processSharedBuffer");
+export const PROCESS_SHARED_BUFFER_NUMERIC_TRANSFER = Symbol.for("knitting.processSharedBuffer.numericTransfer");
+const EXTERNAL_PAYLOAD_BRAND = Symbol.for("knitting.payloadCodec");
+const PROCESS_SHARED_BUFFER_CODEC_ID = "knitting.processSharedBuffer";
+const isRecord = (value) => typeof value === "object" && value !== null;
+const NUMERIC_SENTINEL = 0xffffffff;
+const RUNTIME_NODE = 1;
+const RUNTIME_DENO = 2;
+const RUNTIME_BUN = 3;
+const KIND_SHARED_ARRAY_BUFFER = 1;
+const KIND_EXTERNAL_ARRAY_BUFFER = 2;
+const decodeRuntime = (value) => {
+    switch (value) {
+        case RUNTIME_NODE:
+            return "node";
+        case RUNTIME_DENO:
+            return "deno";
+        case RUNTIME_BUN:
+            return "bun";
+        default:
+            return undefined;
+    }
+};
+const decodeKind = (value) => {
+    switch (value) {
+        case KIND_SHARED_ARRAY_BUFFER:
+            return "shared-array-buffer";
+        case KIND_EXTERNAL_ARRAY_BUFFER:
+            return "external-array-buffer";
+        default:
+            return undefined;
+    }
+};
+let defaultPrimitives;
+const processSharedBufferInstances = new WeakSet();
+const createDefaultPrimitives = () => {
+    if (RUNTIME === "bun")
+        return createBunConnectionPrimitives();
+    if (RUNTIME === "deno")
+        return createDenoConnectionPrimitives();
+    if (RUNTIME === "node")
+        return createNodeConnectionPrimitives();
+    throw new TypeError("ProcessSharedBuffer needs connection primitives in this runtime");
+};
+export const setDefaultProcessSharedBufferPrimitives = (primitives) => {
+    defaultPrimitives = primitives;
+};
+export const getDefaultProcessSharedBufferPrimitives = () => {
+    defaultPrimitives ??= createDefaultPrimitives();
+    return defaultPrimitives;
+};
+const expectNonNegativeInteger = (value, label) => {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new RangeError(`${label} must be a non-negative integer`);
+    }
+    return value;
+};
+const readOptionalNonNegativeInteger = (value, label) => {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "number") {
+        throw new TypeError(`${label} must be a number`);
+    }
+    return expectNonNegativeInteger(value, label);
+};
+const expectRange = (byteOffset, byteLength, availableByteLength) => {
+    expectNonNegativeInteger(byteOffset, "process shared buffer byteOffset");
+    if (byteOffset > availableByteLength) {
+        throw new RangeError("process shared buffer byteOffset is out of bounds");
+    }
+    expectNonNegativeInteger(byteLength, "process shared buffer byteLength");
+    if (byteLength > availableByteLength - byteOffset) {
+        throw new RangeError("process shared buffer byteLength is out of bounds");
+    }
+};
+/**
+ * Zero-copy shared bytes for process workers.
+ *
+ * Use this when the boundary is a separate process, container, or sandbox.
+ * For thread workers, `SharedArrayBuffer` or `BufferReference` can be cheaper.
+ */
+export class ProcessSharedBuffer {
+    [PROCESS_SHARED_BUFFER_BRAND] = true;
+    [EXTERNAL_PAYLOAD_BRAND] = PROCESS_SHARED_BUFFER_CODEC_ID;
+    descriptor;
+    byteOffset;
+    byteLength;
+    constructor(descriptor, range = {}) {
+        const byteOffset = range.byteOffset ?? 0;
+        const byteLength = range.byteLength ??
+            descriptor.byteLength - byteOffset;
+        expectRange(byteOffset, byteLength, descriptor.byteLength);
+        this.descriptor = descriptor;
+        this.byteOffset = byteOffset;
+        this.byteLength = byteLength;
+        processSharedBufferInstances.add(this);
+    }
+    static create(options, creator = getDefaultProcessSharedBufferPrimitives()) {
+        return ProcessSharedBuffer.fromMapping(creator.createSharedMemory(options));
+    }
+    static fromMapping(mapping) {
+        return new ProcessSharedBuffer(FileDescriptor.fromMapping(mapping));
+    }
+    static fromDescriptor(descriptor, range = {}) {
+        return new ProcessSharedBuffer(descriptor, range);
+    }
+    static fromMetadata(metadata) {
+        const parsed = parseProcessSharedBufferMetadata(metadata);
+        return new ProcessSharedBuffer(FileDescriptor.fromMetadata(parsed.descriptor), {
+            byteOffset: parsed.byteOffset,
+            byteLength: parsed.byteLength,
+        });
+    }
+    static parse(serialized) {
+        return ProcessSharedBuffer.fromMetadata(serialized);
+    }
+    // Rebuilds from the 8 raw words (no name -> no JSON):
+    // fd, size, descByteLength, byteOffset, byteLength, runtime, kind, baseAddressMod64
+    static [PROCESS_SHARED_BUFFER_NUMERIC_TRANSFER](metadata) {
+        const [fd, size, descriptorByteLength, byteOffset, byteLength, runtime, kind, baseAddressMod64,] = metadata;
+        return new ProcessSharedBuffer(new FileDescriptor({
+            version: 1,
+            fd,
+            size,
+            byteLength: descriptorByteLength,
+            runtime: decodeRuntime(runtime),
+            kind: decodeKind(kind),
+            baseAddressMod64: baseAddressMod64 === NUMERIC_SENTINEL
+                ? undefined
+                : baseAddressMod64,
+        }), {
+            byteOffset,
+            byteLength,
+        });
+    }
+    get fd() {
+        return this.descriptor.fd;
+    }
+    get size() {
+        return this.descriptor.size;
+    }
+    subbuffer(byteOffset, byteLength) {
+        const relativeByteOffset = expectNonNegativeInteger(byteOffset, "process shared buffer subbuffer byteOffset");
+        const relativeByteLength = byteLength === undefined
+            ? this.byteLength - relativeByteOffset
+            : expectNonNegativeInteger(byteLength, "process shared buffer subbuffer byteLength");
+        expectRange(relativeByteOffset, relativeByteLength, this.byteLength);
+        return new ProcessSharedBuffer(this.descriptor, {
+            byteOffset: this.byteOffset + relativeByteOffset,
+            byteLength: relativeByteLength,
+        });
+    }
+    getSharedArrayBuffer(mapper) {
+        return this.descriptor.getSAB(mapper ??
+            (this.descriptor.mapping?.sab === undefined
+                ? getDefaultProcessSharedBufferPrimitives()
+                : undefined));
+    }
+    getSAB(mapper) {
+        return this.getSharedArrayBuffer(mapper);
+    }
+    getBuffer(mapper) {
+        return this.descriptor.getBuffer(mapper ??
+            (this.descriptor.mapping?.buffer === undefined
+                ? getDefaultProcessSharedBufferPrimitives()
+                : undefined));
+    }
+    getRegion(mapper) {
+        return {
+            sab: this.getBuffer(mapper),
+            byteOffset: this.byteOffset,
+            byteLength: this.byteLength,
+        };
+    }
+    view(constructor, mapper) {
+        const bytesPerElement = constructor.BYTES_PER_ELEMENT;
+        if (this.byteOffset % bytesPerElement !== 0) {
+            throw new RangeError("process shared buffer byteOffset is not aligned for this view");
+        }
+        if (this.byteLength % bytesPerElement !== 0) {
+            throw new RangeError("process shared buffer byteLength is not aligned for this view");
+        }
+        return new constructor(this.getBuffer(mapper), this.byteOffset, this.byteLength / bytesPerElement);
+    }
+    bytes(mapper) {
+        return this.view(Uint8Array, mapper);
+    }
+    dataView(mapper) {
+        return new DataView(this.getBuffer(mapper), this.byteOffset, this.byteLength);
+    }
+    toMetadata() {
+        return {
+            version: 1,
+            descriptor: this.descriptor.toMetadata(),
+            byteOffset: this.byteOffset,
+            byteLength: this.byteLength,
+        };
+    }
+    toJSON() {
+        return this.toMetadata();
+    }
+    stringify() {
+        return JSON.stringify(this.toMetadata());
+    }
+    stringifyMetadata() {
+        return this.stringify();
+    }
+    toString() {
+        return this.stringify();
+    }
+}
+export const isProcessSharedBufferValue = (value) => value !== null &&
+    typeof value === "object" &&
+    processSharedBufferInstances.has(value);
+export const parseProcessSharedBufferMetadata = (input) => {
+    const value = typeof input === "string" ? JSON.parse(input) : input;
+    if (!isRecord(value)) {
+        throw new TypeError("process shared buffer metadata must be an object");
+    }
+    if (value.version !== 1) {
+        throw new TypeError("unsupported process shared buffer metadata version");
+    }
+    const descriptor = FileDescriptor.fromMetadata(value.descriptor);
+    const byteOffset = readOptionalNonNegativeInteger(value.byteOffset, "process shared buffer byteOffset") ?? 0;
+    const byteLength = readOptionalNonNegativeInteger(value.byteLength, "process shared buffer byteLength") ?? descriptor.byteLength - byteOffset;
+    expectRange(byteOffset, byteLength, descriptor.byteLength);
+    return {
+        version: 1,
+        descriptor: descriptor.toMetadata(),
+        byteOffset,
+        byteLength,
+    };
+};
+const processSharedBufferGlobal = globalThis;
+const codecs = processSharedBufferGlobal.__KNITTING_PAYLOAD_CODECS__ ??= Object
+    .create(null);
+codecs[PROCESS_SHARED_BUFFER_CODEC_ID] = {
+    decode: (metadata) => ProcessSharedBuffer.fromMetadata(metadata),
+    decodeNumeric: (metadata) => ProcessSharedBuffer[PROCESS_SHARED_BUFFER_NUMERIC_TRANSFER](metadata),
+};

package/src/connections/shared-array-buffer-payload.d.ts

@@ -0,0 +1,36 @@
+export declare const SHARED_ARRAY_BUFFER_CODEC_ID: "knitting.sharedArrayBuffer";
+export declare const SHARED_ARRAY_BUFFER_NUMERIC_TRANSFER: unique symbol;
+export declare const SHARED_ARRAY_BUFFER_NUMERIC_WORDS = 8;
+declare const EXTERNAL_PAYLOAD_BRAND: unique symbol;
+type SharedArrayBufferMetadata = {
+    readonly kind: typeof SHARED_ARRAY_BUFFER_CODEC_ID;
+    readonly origin: string;
+    readonly runtime: string;
+    readonly pointer: string;
+    readonly token: string;
+    readonly byteLength: number;
+};
+type SharedArrayBufferNumericMetadata = readonly [
+    tokenLow: number,
+    tokenHigh: number,
+    pointerLow: number,
+    pointerHigh: number,
+    byteLength: number,
+    runtime: number,
+    originPid: number,
+    mode: number
+];
+type SharedArrayBufferTokenNumericMetadata = readonly [
+    tokenLow: number,
+    tokenHigh: number
+];
+type SharedArrayBufferPayload = {
+    readonly [EXTERNAL_PAYLOAD_BRAND]: typeof SHARED_ARRAY_BUFFER_CODEC_ID;
+    readonly toMetadata: () => SharedArrayBufferMetadata;
+    readonly [SHARED_ARRAY_BUFFER_NUMERIC_TRANSFER]: (transportKey?: object) => SharedArrayBufferNumericMetadata | SharedArrayBufferTokenNumericMetadata | undefined;
+};
+export declare const isSharedArrayBufferValue: (value: unknown) => value is SharedArrayBuffer;
+/** Wrap a SAB as external payload; GC-managed pins mean no settle finalizer. */
+export declare const wrapSharedArrayBufferPayload: (sab: SharedArrayBuffer) => SharedArrayBufferPayload;
+export declare const getSharedArrayBufferPayload: (value: object) => SharedArrayBufferPayload | undefined;
+export {};

package/src/connections/shared-array-buffer-payload.js

@@ -0,0 +1,235 @@
+import { RUNTIME } from "../common/runtime.js";
+import { getNodeProcess } from "../common/node-compat.js";
+import { getBufferReferenceCapabilities } from "./buffer-reference-native.js";
+// Thread-worker SharedArrayBuffer transport by process-local pointer.
+// SABs are shared, not moved or detached; process workers reject them.
+export const SHARED_ARRAY_BUFFER_CODEC_ID = "knitting.sharedArrayBuffer";
+export const SHARED_ARRAY_BUFFER_NUMERIC_TRANSFER = Symbol.for("knitting.sharedArrayBuffer.numericTransfer");
+export const SHARED_ARRAY_BUFFER_NUMERIC_WORDS = 8;
+const SHARED_ARRAY_BUFFER_TOKEN_NUMERIC_WORDS = 2;
+const EXTERNAL_PAYLOAD_BRAND = Symbol.for("knitting.payloadCodec");
+const getProcessId = () => {
+    const proc = getNodeProcess();
+    if (proc !== undefined && typeof proc.pid === "number")
+        return proc.pid;
+    const deno = globalThis.Deno;
+    if (typeof deno?.pid === "number")
+        return deno.pid;
+    return 0;
+};
+const PROCESS_ORIGIN = `${RUNTIME}:${getProcessId()}`;
+const hasSharedArrayBuffer = typeof SharedArrayBuffer === "function";
+export const isSharedArrayBufferValue = (value) => hasSharedArrayBuffer && value instanceof SharedArrayBuffer;
+const pinnedBySab = new WeakMap();
+const payloadBySharedBuffer = new WeakMap();
+const warmedTokensByTransport = new WeakMap();
+const cachedSharedBuffersByToken = new Map();
+const pinFinalizer = typeof FinalizationRegistry === "function"
+    ? new FinalizationRegistry((token) => {
+        try {
+            getBufferReferenceCapabilities().releaseShared(token);
+        }
+        catch {
+            // best effort
+        }
+    })
+    : undefined;
+const splitU64 = (value) => [
+    Number(value & 0xffffffffn) >>> 0,
+    Number((value >> 32n) & 0xffffffffn) >>> 0,
+];
+const joinU64 = (low, high) => (BigInt(high >>> 0) << 32n) | BigInt(low >>> 0);
+const encodeRuntime = (runtime) => {
+    switch (runtime) {
+        case "node":
+            return 1;
+        case "deno":
+            return 2;
+        case "bun":
+            return 3;
+        default:
+            return 0;
+    }
+};
+const decodeRuntime = (value) => {
+    switch (value) {
+        case 1:
+            return "node";
+        case 2:
+            return "deno";
+        case 3:
+            return "bun";
+        default:
+            return undefined;
+    }
+};
+const getWarmTokens = (transportKey) => {
+    if (transportKey === undefined)
+        return undefined;
+    let warmTokens = warmedTokensByTransport.get(transportKey);
+    if (warmTokens === undefined) {
+        warmTokens = new Set();
+        warmedTokensByTransport.set(transportKey, warmTokens);
+    }
+    return warmTokens;
+};
+const pinSab = (sab) => {
+    let pin = pinnedBySab.get(sab);
+    if (pin === undefined) {
+        const produced = getBufferReferenceCapabilities().produceShared(sab);
+        pin = {
+            token: produced.token,
+            pointer: produced.pointer,
+            byteLength: produced.byteLength,
+        };
+        pinnedBySab.set(sab, pin);
+        pinFinalizer?.register(sab, pin.token);
+    }
+    return pin;
+};
+const makeMetadata = (pin) => ({
+    kind: SHARED_ARRAY_BUFFER_CODEC_ID,
+    origin: PROCESS_ORIGIN,
+    runtime: RUNTIME,
+    pointer: pin.pointer.toString(),
+    token: pin.token.toString(),
+    byteLength: pin.byteLength,
+});
+const makeFullNumericMetadata = (pin) => {
+    if (pin.byteLength > 0xffffffff)
+        return undefined;
+    const [tokenLow, tokenHigh] = splitU64(pin.token);
+    const [pointerLow, pointerHigh] = splitU64(pin.pointer);
+    return [
+        tokenLow,
+        tokenHigh,
+        pointerLow,
+        pointerHigh,
+        pin.byteLength >>> 0,
+        encodeRuntime(RUNTIME),
+        getProcessId() >>> 0,
+        0,
+    ];
+};
+const makeTokenNumericMetadata = (pin) => {
+    const [tokenLow, tokenHigh] = splitU64(pin.token);
+    return [tokenLow, tokenHigh];
+};
+/** Wrap a SAB as external payload; GC-managed pins mean no settle finalizer. */
+export const wrapSharedArrayBufferPayload = (sab) => {
+    let payload = payloadBySharedBuffer.get(sab);
+    if (payload !== undefined)
+        return payload;
+    const pin = pinSab(sab);
+    payload = createSharedArrayBufferPayload(sab, pin, makeMetadata(pin));
+    return payload;
+};
+const createSharedArrayBufferPayload = (buffer, pin, metadata) => {
+    let payload = payloadBySharedBuffer.get(buffer);
+    if (payload !== undefined)
+        return payload;
+    const fullNumeric = makeFullNumericMetadata(pin);
+    const tokenOnlyNumeric = makeTokenNumericMetadata(pin);
+    payload = {
+        [EXTERNAL_PAYLOAD_BRAND]: SHARED_ARRAY_BUFFER_CODEC_ID,
+        toMetadata: () => metadata,
+        [SHARED_ARRAY_BUFFER_NUMERIC_TRANSFER]: (transportKey) => {
+            if (fullNumeric === undefined) {
+                return undefined;
+            }
+            const warmTokens = getWarmTokens(transportKey);
+            if (warmTokens === undefined)
+                return fullNumeric;
+            if (warmTokens.has(pin.token))
+                return tokenOnlyNumeric;
+            warmTokens.add(pin.token);
+            return fullNumeric;
+        },
+    };
+    payloadBySharedBuffer.set(buffer, payload);
+    return payload;
+};
+export const getSharedArrayBufferPayload = (value) => {
+    if (isSharedArrayBufferValue(value))
+        return wrapSharedArrayBufferPayload(value);
+    return payloadBySharedBuffer.get(value);
+};
+const isSharedArrayBufferMetadata = (value) => {
+    if (value === null || typeof value !== "object")
+        return false;
+    const meta = value;
+    return (meta.kind === SHARED_ARRAY_BUFFER_CODEC_ID &&
+        typeof meta.origin === "string" &&
+        typeof meta.runtime === "string" &&
+        typeof meta.pointer === "string" &&
+        typeof meta.token === "string" &&
+        typeof meta.byteLength === "number" &&
+        Number.isInteger(meta.byteLength) &&
+        meta.byteLength >= 0);
+};
+const materializeSharedBuffer = (metadata, warmOnly) => {
+    if (metadata.origin !== PROCESS_ORIGIN) {
+        throw new Error(`SharedArrayBuffer cannot cross a process boundary (origin ${metadata.origin} ` +
+            `!= ${PROCESS_ORIGIN}); it is shared by reference to thread workers only.`);
+    }
+    const token = BigInt(metadata.token);
+    const cached = cachedSharedBuffersByToken.get(token);
+    if (cached !== undefined)
+        return cached;
+    if (warmOnly) {
+        throw new TypeError("SharedArrayBuffer cache miss for warm token payload");
+    }
+    const region = getBufferReferenceCapabilities().adoptShared({
+        token,
+        pointer: BigInt(metadata.pointer),
+        byteOffset: 0,
+        byteLength: metadata.byteLength,
+    });
+    cachedSharedBuffersByToken.set(token, region.buffer);
+    createSharedArrayBufferPayload(region.buffer, {
+        token,
+        pointer: BigInt(metadata.pointer),
+        byteLength: metadata.byteLength,
+    }, metadata);
+    return region.buffer;
+};
+const decode = (metadata) => {
+    if (!isSharedArrayBufferMetadata(metadata)) {
+        throw new TypeError("Invalid SharedArrayBuffer payload metadata");
+    }
+    return materializeSharedBuffer(metadata, false);
+};
+const decodeNumeric = (words) => {
+    if (words.length === SHARED_ARRAY_BUFFER_TOKEN_NUMERIC_WORDS) {
+        const token = joinU64(words[0] ?? 0, words[1] ?? 0);
+        const cached = cachedSharedBuffersByToken.get(token);
+        if (cached !== undefined)
+            return cached;
+        throw new TypeError("SharedArrayBuffer cache miss for warm token payload");
+    }
+    const runtime = decodeRuntime(words[5] ?? 0);
+    if (runtime === undefined) {
+        throw new TypeError("Invalid SharedArrayBuffer numeric runtime");
+    }
+    const originPid = words[6];
+    if (originPid === undefined ||
+        !Number.isInteger(originPid) ||
+        originPid < 0) {
+        throw new TypeError("Invalid SharedArrayBuffer numeric origin");
+    }
+    if (words.length !== SHARED_ARRAY_BUFFER_NUMERIC_WORDS) {
+        throw new TypeError("Invalid SharedArrayBuffer numeric word count");
+    }
+    const metadata = {
+        kind: SHARED_ARRAY_BUFFER_CODEC_ID,
+        origin: `${runtime}:${originPid >>> 0}`,
+        runtime,
+        pointer: joinU64(words[2] ?? 0, words[3] ?? 0).toString(),
+        token: joinU64(words[0] ?? 0, words[1] ?? 0).toString(),
+        byteLength: words[4] ?? 0,
+    };
+    return materializeSharedBuffer(metadata, false);
+};
+const codecGlobal = globalThis;
+const codecs = codecGlobal.__KNITTING_PAYLOAD_CODECS__ ??= Object.create(null);
+codecs[SHARED_ARRAY_BUFFER_CODEC_ID] = { decode, decodeNumeric };

package/src/connections/types.d.ts

@@ -0,0 +1,54 @@
+export declare const CACHE_LINE_SIZE = 64;
+export type ConnectionRuntime = "node" | "deno" | "bun";
+export type SharedMemoryBuffer = ArrayBuffer | SharedArrayBuffer;
+export type SharedMemoryBufferKind = "shared-array-buffer" | "external-array-buffer";
+export type SharedMemoryCreateMode = "anonymous" | "create" | "open";
+export type SharedMemoryMapping<Buffer extends SharedMemoryBuffer = SharedMemoryBuffer> = {
+    runtime: ConnectionRuntime;
+    fd: number;
+    name?: string;
+    size: number;
+    byteLength: number;
+    buffer: Buffer;
+    kind: SharedMemoryBufferKind;
+    sab?: SharedArrayBuffer;
+    arrayBuffer?: ArrayBuffer;
+    baseAddressMod64?: number;
+    unsafePointer?: unknown;
+    close?: () => void;
+};
+export type CreateSharedMemoryOptions = {
+    size: number;
+    /**
+     * `anonymous` keeps the current fd-backed private mapping behavior.
+     * `create` and `open` use a named shared-memory object so independent
+     * processes can rendezvous by name.
+     */
+    mode?: SharedMemoryCreateMode;
+    name?: string;
+};
+export type MapSharedMemoryOptions = {
+    fd: number;
+    name?: string;
+    size: number;
+    /**
+     * When false, map the supplied descriptor directly. Ownership transfers to
+     * the returned mapping only after mapping succeeds; failures leave it open.
+     */
+    duplicateFd?: boolean;
+};
+export type SharedMemoryConnectionPrimitives<Mapping extends SharedMemoryMapping = SharedMemoryMapping> = {
+    runtime: ConnectionRuntime;
+    createSharedMemory: (options: number | CreateSharedMemoryOptions) => Mapping;
+    mapSharedMemory: (options: MapSharedMemoryOptions) => Mapping;
+    unlinkSharedMemory?: (name: string) => boolean;
+};
+export declare const alignToCacheLine: (size: number) => number;
+export declare const readCreateSize: (options: number | CreateSharedMemoryOptions) => number;
+export declare const readCreateName: (options: number | CreateSharedMemoryOptions, fallback: string) => string;
+export declare const readCreateMode: (options: number | CreateSharedMemoryOptions) => SharedMemoryCreateMode;
+export declare const expectSharedMemoryName: (name: string) => string;
+export declare const readRequiredCreateName: (options: number | CreateSharedMemoryOptions) => string;
+export declare const expectPositiveSize: (size: number) => number;
+export declare const expectFd: (fd: number) => number;
+export declare const requireSharedArrayBuffer: (mapping: SharedMemoryMapping) => SharedArrayBuffer;

package/src/connections/types.js

@@ -0,0 +1,37 @@
+export const CACHE_LINE_SIZE = 64;
+export const alignToCacheLine = (size) => size + ((CACHE_LINE_SIZE - (size % CACHE_LINE_SIZE)) % CACHE_LINE_SIZE);
+export const readCreateSize = (options) => typeof options === "number" ? options : options.size;
+export const readCreateName = (options, fallback) => typeof options === "number" ? fallback : options.name ?? fallback;
+export const readCreateMode = (options) => typeof options === "number" ? "anonymous" : options.mode ?? "anonymous";
+export const expectSharedMemoryName = (name) => {
+    if (typeof name !== "string" || name.length === 0) {
+        throw new TypeError("shared memory name must be a non-empty string");
+    }
+    if (name.includes("\0")) {
+        throw new TypeError("shared memory name must not contain NUL bytes");
+    }
+    return name;
+};
+export const readRequiredCreateName = (options) => {
+    if (typeof options === "number" || options.name === undefined) {
+        throw new TypeError("named shared memory requires a name");
+    }
+    return expectSharedMemoryName(options.name);
+};
+export const expectPositiveSize = (size) => {
+    if (!Number.isFinite(size) || size <= 0) {
+        throw new RangeError("shared memory size must be positive");
+    }
+    return alignToCacheLine(Math.trunc(size));
+};
+export const expectFd = (fd) => {
+    if (!Number.isInteger(fd) || fd < 0) {
+        throw new RangeError("shared memory fd must be non-negative");
+    }
+    return fd;
+};
+export const requireSharedArrayBuffer = (mapping) => {
+    if (mapping.sab !== undefined)
+        return mapping.sab;
+    throw new TypeError(`${mapping.runtime} mapping is ${mapping.kind}; a native SAB wrapper is required`);
+};

package/src/connections/windows.d.ts

@@ -0,0 +1,37 @@
+import { type NodeFfiLibrary } from "./node-ffi-api.js";
+import { type CreateSharedMemoryOptions, type MapSharedMemoryOptions, type SharedMemoryConnectionPrimitives, type SharedMemoryMapping } from "./types.js";
+declare const WINDOWS_CREATE_SHARED_MEMORY = "knitting_windows_create_shared_memory";
+declare const WINDOWS_MAP_SHARED_MEMORY = "knitting_windows_map_shared_memory";
+declare const WINDOWS_CLOSE_SHARED_MEMORY = "knitting_windows_close_shared_memory";
+type WindowsSharedMemorySymbols = {
+    [WINDOWS_CREATE_SHARED_MEMORY]: (size: bigint, name: Uint16Array, mode: number, out: Uint8Array) => number;
+    [WINDOWS_MAP_SHARED_MEMORY]: (handle: bigint, size: bigint, name: Uint16Array, out: Uint8Array) => number;
+    [WINDOWS_CLOSE_SHARED_MEMORY]: (mapping: Uint8Array) => number;
+};
+type DenoWindowsLibrary = {
+    symbols: WindowsSharedMemorySymbols;
+    close: () => void;
+};
+type BunWindowsLibrary = {
+    symbols: WindowsSharedMemorySymbols;
+};
+type NodeWindowsLibrary = {
+    functions: WindowsSharedMemorySymbols;
+    lib: NodeFfiLibrary;
+};
+export declare const isWindowsRuntime: () => boolean;
+export declare const windowsSharedMemoryPrebuildPath: () => string;
+export declare const makeWindowsAnonymousSharedMemoryName: (runtime: string) => string;
+export declare const openDenoWindowsSharedMemoryLibrary: () => DenoWindowsLibrary;
+export declare const openBunWindowsSharedMemoryLibrary: () => BunWindowsLibrary;
+export declare const openNodeWindowsSharedMemoryLibrary: () => NodeWindowsLibrary;
+export declare const createDenoWindowsSharedMemory: (options: number | CreateSharedMemoryOptions, lib?: DenoWindowsLibrary) => SharedMemoryMapping<ArrayBuffer>;
+export declare const mapDenoWindowsSharedMemory: (options: MapSharedMemoryOptions, lib?: DenoWindowsLibrary) => SharedMemoryMapping<ArrayBuffer>;
+export declare const createDenoWindowsConnectionPrimitives: (lib?: DenoWindowsLibrary) => SharedMemoryConnectionPrimitives<SharedMemoryMapping<ArrayBuffer>>;
+export declare const createBunWindowsSharedMemory: (options: number | CreateSharedMemoryOptions, lib?: BunWindowsLibrary) => SharedMemoryMapping<ArrayBuffer>;
+export declare const mapBunWindowsSharedMemory: (options: MapSharedMemoryOptions, lib?: BunWindowsLibrary) => SharedMemoryMapping<ArrayBuffer>;
+export declare const createBunWindowsConnectionPrimitives: (lib?: BunWindowsLibrary) => SharedMemoryConnectionPrimitives<SharedMemoryMapping<ArrayBuffer>>;
+export declare const createNodeWindowsSharedMemory: (options: number | CreateSharedMemoryOptions, lib?: NodeWindowsLibrary) => SharedMemoryMapping<ArrayBuffer>;
+export declare const mapNodeWindowsSharedMemory: (options: MapSharedMemoryOptions, lib?: NodeWindowsLibrary) => SharedMemoryMapping<ArrayBuffer>;
+export declare const createNodeWindowsConnectionPrimitives: (lib?: NodeWindowsLibrary) => SharedMemoryConnectionPrimitives<SharedMemoryMapping<ArrayBuffer>>;
+export {};