knitting 0.1.46

package/src/connections/deno.js

@@ -0,0 +1,150 @@
+import { DARWIN_O_CREAT, DARWIN_O_EXCL, DARWIN_SHM_MODE, setCloseOnExec, detectPosixPlatform, encodeCString, getPosixLibcPath, makeDarwinSharedMemoryName, MAP_SHARED, O_RDWR, PROT_READ, PROT_WRITE, } from "./posix.js";
+import { expectFd, expectPositiveSize, readCreateName, readCreateSize, } from "./types.js";
+const getDeno = () => {
+    const deno = globalThis.Deno;
+    if (deno === undefined) {
+        throw new Error("Deno shared memory primitives can only run in Deno");
+    }
+    return deno;
+};
+export const openDenoLibc = () => getDeno().dlopen(getPosixLibcPath(), {
+    ...getDenoCreateSymbols(),
+    ftruncate: {
+        parameters: ["i32", "i64"],
+        result: "i32",
+    },
+    dup: {
+        parameters: ["i32"],
+        result: "i32",
+    },
+    fcntl: {
+        parameters: ["i32", "i32", "i32"],
+        result: "i32",
+    },
+    mmap: {
+        parameters: ["pointer", "usize", "i32", "i32", "i32", "i64"],
+        result: "pointer",
+    },
+    munmap: {
+        parameters: ["pointer", "usize"],
+        result: "i32",
+    },
+    close: {
+        parameters: ["i32"],
+        result: "i32",
+    },
+});
+const getDenoCreateSymbols = (platform = detectPosixPlatform()) => platform === "darwin"
+    ? {
+        shm_open: {
+            parameters: ["buffer", "i32", "u32"],
+            result: "i32",
+        },
+        shm_unlink: {
+            parameters: ["buffer"],
+            result: "i32",
+        },
+    }
+    : {
+        memfd_create: {
+            parameters: ["buffer", "u32"],
+            result: "i32",
+        },
+    };
+const checkResult = (result, message) => {
+    if (result < 0)
+        throw new Error(message);
+    return result;
+};
+const isDenoMmapFailed = (pointer) => {
+    if (pointer === null)
+        return true;
+    const value = getDeno().UnsafePointer?.value(pointer);
+    return value === -1n || value === BigInt.asUintN(64, -1n);
+};
+const createDenoSharedMemoryFd = (name, platform, libc) => {
+    if (platform === "darwin") {
+        const shmOpen = libc.symbols.shm_open;
+        const shmUnlink = libc.symbols.shm_unlink;
+        if (shmOpen === undefined || shmUnlink === undefined) {
+            throw new Error("shm_open symbols are not available");
+        }
+        const shmName = encodeCString(makeDarwinSharedMemoryName(name, "deno"));
+        const fd = checkResult(shmOpen(shmName, O_RDWR | DARWIN_O_CREAT | DARWIN_O_EXCL, DARWIN_SHM_MODE), "shm_open failed");
+        shmUnlink(shmName);
+        try {
+            return setCloseOnExec(libc, fd);
+        }
+        catch (error) {
+            libc.symbols.close(fd);
+            throw error;
+        }
+    }
+    const memfdCreate = libc.symbols.memfd_create;
+    if (memfdCreate === undefined) {
+        throw new Error("memfd_create symbol is not available");
+    }
+    const fd = checkResult(memfdCreate(encodeCString(name), 0), "memfd_create failed");
+    try {
+        return setCloseOnExec(libc, fd);
+    }
+    catch (error) {
+        libc.symbols.close(fd);
+        throw error;
+    }
+};
+export const mapDenoSharedMemory = (options, libc = openDenoLibc()) => {
+    const sourceFd = expectFd(options.fd);
+    const size = expectPositiveSize(options.size);
+    let fd = sourceFd;
+    if (options.duplicateFd !== false) {
+        fd = checkResult(libc.symbols.dup(sourceFd), "dup(fd) failed");
+        try {
+            setCloseOnExec(libc, fd);
+        }
+        catch (error) {
+            libc.symbols.close(fd);
+            throw error;
+        }
+    }
+    const pointer = libc.symbols.mmap(null, size, PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0n);
+    if (isDenoMmapFailed(pointer)) {
+        if (options.duplicateFd !== false)
+            libc.symbols.close(fd);
+        throw new Error("mmap failed");
+    }
+    const arrayBuffer = new (getDeno().UnsafePointerView)(pointer)
+        .getArrayBuffer(size);
+    return {
+        runtime: "deno",
+        fd,
+        size,
+        byteLength: arrayBuffer.byteLength,
+        buffer: arrayBuffer,
+        kind: "external-array-buffer",
+        arrayBuffer,
+        unsafePointer: pointer,
+        close: () => {
+            libc.symbols.munmap(pointer, size);
+            libc.symbols.close(fd);
+        },
+    };
+};
+export const createDenoSharedMemory = (options, libc = openDenoLibc()) => {
+    const size = expectPositiveSize(readCreateSize(options));
+    const name = readCreateName(options, "knitting_shared_memory");
+    const fd = createDenoSharedMemoryFd(name, detectPosixPlatform(), libc);
+    try {
+        checkResult(libc.symbols.ftruncate(fd, BigInt(size)), "ftruncate failed");
+        return mapDenoSharedMemory({ fd, size, duplicateFd: false }, libc);
+    }
+    catch (error) {
+        libc.symbols.close(fd);
+        throw error;
+    }
+};
+export const createDenoConnectionPrimitives = (libc = openDenoLibc()) => ({
+    runtime: "deno",
+    createSharedMemory: (options) => createDenoSharedMemory(options, libc),
+    mapSharedMemory: (options) => mapDenoSharedMemory(options, libc),
+});

package/src/connections/file-descriptor.d.ts

@@ -0,0 +1,37 @@
+import { type ConnectionRuntime, type SharedMemoryBuffer, type SharedMemoryConnectionPrimitives, type SharedMemoryMapping } from "./types.js";
+export type FileDescriptorMetadata = {
+    version: 1;
+    fd: number;
+    size: number;
+    byteLength: number;
+    runtime?: ConnectionRuntime;
+    kind?: SharedMemoryMapping["kind"];
+    baseAddressMod64?: number;
+};
+type FileDescriptorMapper = Pick<SharedMemoryConnectionPrimitives, "mapSharedMemory">;
+export declare class FileDescriptor {
+    #private;
+    readonly fd: number;
+    readonly size: number;
+    readonly byteLength: number;
+    readonly runtime?: ConnectionRuntime;
+    readonly kind?: SharedMemoryMapping["kind"];
+    readonly baseAddressMod64?: number;
+    constructor(metadata: FileDescriptorMetadata, mapping?: SharedMemoryMapping);
+    static fromMapping(mapping: SharedMemoryMapping): FileDescriptor;
+    static fromMetadata(metadata: unknown): FileDescriptor;
+    static parse(serialized: string): FileDescriptor;
+    toMetadata(): FileDescriptorMetadata;
+    toJSON(): FileDescriptorMetadata;
+    stringify(): string;
+    stringifyMetadata(): string;
+    toString(): string;
+    attach(mapping: SharedMemoryMapping): this;
+    get mapping(): SharedMemoryMapping | undefined;
+    map(mapper: FileDescriptorMapper): SharedMemoryMapping;
+    getBuffer(mapper?: FileDescriptorMapper): SharedMemoryBuffer;
+    getSharedArrayBuffer(mapper?: FileDescriptorMapper): SharedArrayBuffer;
+    getSAB(mapper?: FileDescriptorMapper): SharedArrayBuffer;
+}
+export declare const parseFileDescriptorMetadata: (input: unknown) => FileDescriptorMetadata;
+export {};

package/src/connections/file-descriptor.js

@@ -0,0 +1,139 @@
+import { expectFd, expectPositiveSize, requireSharedArrayBuffer, } from "./types.js";
+const isRecord = (value) => typeof value === "object" && value !== null;
+const readOptionalRuntime = (value) => {
+    if (value === undefined)
+        return undefined;
+    if (value === "node" || value === "deno" || value === "bun")
+        return value;
+    throw new TypeError("file descriptor runtime is invalid");
+};
+const readOptionalKind = (value) => {
+    if (value === undefined)
+        return undefined;
+    if (value === "shared-array-buffer" ||
+        value === "external-array-buffer") {
+        return value;
+    }
+    throw new TypeError("file descriptor buffer kind is invalid");
+};
+const readOptionalNumber = (value, label) => {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new TypeError(`file descriptor ${label} must be a finite number`);
+    }
+    return Math.trunc(value);
+};
+export class FileDescriptor {
+    fd;
+    size;
+    byteLength;
+    runtime;
+    kind;
+    baseAddressMod64;
+    #mapping;
+    constructor(metadata, mapping) {
+        this.fd = expectFd(metadata.fd);
+        this.size = expectPositiveSize(metadata.size);
+        this.byteLength = expectPositiveSize(metadata.byteLength);
+        this.runtime = metadata.runtime;
+        this.kind = metadata.kind;
+        this.baseAddressMod64 = metadata.baseAddressMod64;
+        this.#mapping = mapping;
+    }
+    static fromMapping(mapping) {
+        return new FileDescriptor({
+            version: 1,
+            fd: mapping.fd,
+            size: mapping.size,
+            byteLength: mapping.byteLength,
+            runtime: mapping.runtime,
+            kind: mapping.kind,
+            baseAddressMod64: mapping.baseAddressMod64,
+        }, mapping);
+    }
+    static fromMetadata(metadata) {
+        return new FileDescriptor(parseFileDescriptorMetadata(metadata));
+    }
+    static parse(serialized) {
+        return FileDescriptor.fromMetadata(serialized);
+    }
+    toMetadata() {
+        return {
+            version: 1,
+            fd: this.fd,
+            size: this.size,
+            byteLength: this.byteLength,
+            runtime: this.runtime,
+            kind: this.kind,
+            baseAddressMod64: this.baseAddressMod64,
+        };
+    }
+    toJSON() {
+        return this.toMetadata();
+    }
+    stringify() {
+        return JSON.stringify(this.toMetadata());
+    }
+    stringifyMetadata() {
+        // This describes an fd; it does not transfer fd ownership to another process.
+        return this.stringify();
+    }
+    toString() {
+        return this.stringify();
+    }
+    attach(mapping) {
+        this.#mapping = mapping;
+        return this;
+    }
+    get mapping() {
+        return this.#mapping;
+    }
+    map(mapper) {
+        const options = {
+            fd: this.fd,
+            size: this.size,
+        };
+        this.#mapping = mapper.mapSharedMemory(options);
+        return this.#mapping;
+    }
+    getBuffer(mapper) {
+        if (this.#mapping?.buffer !== undefined)
+            return this.#mapping.buffer;
+        if (mapper === undefined) {
+            throw new TypeError("file descriptor is not attached to a shared memory mapping");
+        }
+        return this.map(mapper).buffer;
+    }
+    getSharedArrayBuffer(mapper) {
+        if (this.#mapping?.sab !== undefined)
+            return this.#mapping.sab;
+        if (mapper === undefined) {
+            throw new TypeError("file descriptor is not attached to a SharedArrayBuffer mapping");
+        }
+        return requireSharedArrayBuffer(this.map(mapper));
+    }
+    getSAB(mapper) {
+        return this.getSharedArrayBuffer(mapper);
+    }
+}
+export const parseFileDescriptorMetadata = (input) => {
+    const value = typeof input === "string" ? JSON.parse(input) : input;
+    if (!isRecord(value)) {
+        throw new TypeError("file descriptor metadata must be an object");
+    }
+    if (value.version !== 1) {
+        throw new TypeError("unsupported file descriptor metadata version");
+    }
+    return {
+        version: 1,
+        fd: expectFd(readOptionalNumber(value.fd, "fd") ?? -1),
+        size: expectPositiveSize(readOptionalNumber(value.size, "size") ?? 0),
+        byteLength: expectPositiveSize(readOptionalNumber(value.byteLength, "byteLength") ??
+            readOptionalNumber(value.size, "size") ??
+            0),
+        runtime: readOptionalRuntime(value.runtime),
+        kind: readOptionalKind(value.kind),
+        baseAddressMod64: readOptionalNumber(value.baseAddressMod64, "baseAddressMod64"),
+    };
+};

package/src/connections/index.d.ts

@@ -0,0 +1,3 @@
+export { alignToCacheLine, CACHE_LINE_SIZE, type ConnectionRuntime, type CreateSharedMemoryOptions, expectFd, expectPositiveSize, type MapSharedMemoryOptions, requireSharedArrayBuffer, type SharedMemoryBuffer, type SharedMemoryBufferKind, type SharedMemoryConnectionPrimitives, type SharedMemoryMapping, } from "./types.js";
+export { FileDescriptor, type FileDescriptorMetadata, parseFileDescriptorMetadata, } from "./file-descriptor.js";
+export { getDefaultProcessSharedBufferPrimitives, parseProcessSharedBufferMetadata, PROCESS_SHARED_BUFFER_BRAND, ProcessSharedBuffer, type ProcessSharedBufferCreator, type ProcessSharedBufferMapper, type ProcessSharedBufferMetadata, type ProcessSharedBufferPrimitives, type ProcessSharedBufferRange, type ProcessSharedBufferView, type ProcessSharedBufferViewConstructor, setDefaultProcessSharedBufferPrimitives, } from "./process-shared-buffer.js";

package/src/connections/index.js

@@ -0,0 +1,3 @@
+export { alignToCacheLine, CACHE_LINE_SIZE, expectFd, expectPositiveSize, requireSharedArrayBuffer, } from "./types.js";
+export { FileDescriptor, parseFileDescriptorMetadata, } from "./file-descriptor.js";
+export { getDefaultProcessSharedBufferPrimitives, parseProcessSharedBufferMetadata, PROCESS_SHARED_BUFFER_BRAND, ProcessSharedBuffer, setDefaultProcessSharedBufferPrimitives, } from "./process-shared-buffer.js";

package/src/connections/node-addons.d.ts

@@ -0,0 +1,5 @@
+type NodeRequire = (specifier: string) => unknown;
+export type NodeNativeAddonName = "knitting_shared_memory" | "knitting_shm";
+export declare const nodeNativeAddonSpecifiers: (name: NodeNativeAddonName) => readonly string[];
+export declare const loadNodeNativeAddon: <T>(require: NodeRequire, name: NodeNativeAddonName, specifier?: string) => T;
+export {};

package/src/connections/node-addons.js

@@ -0,0 +1,43 @@
+const readNodePlatformInfo = () => {
+    const processLike = globalThis.process;
+    if (typeof processLike?.platform !== "string" ||
+        typeof processLike.arch !== "string") {
+        return undefined;
+    }
+    return {
+        arch: processLike.arch,
+        modules: processLike.versions?.modules,
+        platform: processLike.platform,
+    };
+};
+export const nodeNativeAddonSpecifiers = (name) => {
+    const platformInfo = readNodePlatformInfo();
+    const fallback = `../../build/Release/${name}.node`;
+    if (platformInfo === undefined)
+        return [fallback];
+    const nodeModuleAbi = platformInfo.modules;
+    if (typeof nodeModuleAbi === "string" && nodeModuleAbi.length > 0) {
+        return [
+            `../../prebuilds/${platformInfo.platform}-${platformInfo.arch}-node-${nodeModuleAbi}/${name}.node`,
+            fallback,
+        ];
+    }
+    return [
+        `../../prebuilds/${platformInfo.platform}-${platformInfo.arch}/${name}.node`,
+        fallback,
+    ];
+};
+export const loadNodeNativeAddon = (require, name, specifier) => {
+    if (specifier !== undefined)
+        return require(specifier);
+    const errors = [];
+    for (const candidate of nodeNativeAddonSpecifiers(name)) {
+        try {
+            return require(candidate);
+        }
+        catch (error) {
+            errors.push(`${candidate}: ${String(error)}`);
+        }
+    }
+    throw new Error(`Could not load native addon ${name}. Tried:\n${errors.join("\n")}`);
+};

package/src/connections/node.d.ts

@@ -0,0 +1,29 @@
+import { type CreateSharedMemoryOptions, type MapSharedMemoryOptions, type SharedMemoryConnectionPrimitives, type SharedMemoryMapping } from "./types.js";
+export type NodeSharedMemoryNativeMapping = {
+    sab: SharedArrayBuffer;
+    fd: number;
+    size: number;
+    baseAddressMod64?: number;
+};
+export type NodeSharedMemoryAddon = {
+    createSharedMemory: (size: number, name?: string, mode?: CreateSharedMemoryOptions["mode"]) => NodeSharedMemoryNativeMapping;
+    mapSharedMemory: (fd: number, size: number) => NodeSharedMemoryNativeMapping;
+    unlinkSharedMemory?: (name: string) => boolean;
+};
+export type NodeFutexWaitResult = "woken" | "changed" | "interrupted" | "timed-out";
+export type NodeFutexAddon = {
+    waitU32: (buffer: ArrayBuffer | SharedArrayBuffer, byteOffset: number, expected: number, timeoutMs?: number) => NodeFutexWaitResult;
+    wakeU32: (buffer: ArrayBuffer | SharedArrayBuffer, byteOffset: number, count?: number) => number;
+    notifyU32?: (buffer: ArrayBuffer | SharedArrayBuffer, byteOffset: number, count?: number) => number;
+    sleep?: (milliseconds?: number) => void;
+    yield?: () => void;
+};
+export declare const DEFAULT_NODE_SHARED_MEMORY_ADDON = "../../build/Release/knitting_shared_memory.node";
+export declare const DEFAULT_NODE_FUTEX_ADDON = "../../build/Release/knitting_shm.node";
+export declare const loadNodeSharedMemoryAddon: (specifier?: string) => NodeSharedMemoryAddon;
+export declare const loadNodeFutexAddon: (specifier?: string) => NodeFutexAddon;
+export declare const fromNodeNativeMapping: (mapped: NodeSharedMemoryNativeMapping) => SharedMemoryMapping<SharedArrayBuffer>;
+export declare const createNodeSharedMemory: (options: number | CreateSharedMemoryOptions, addon?: NodeSharedMemoryAddon) => SharedMemoryMapping<SharedArrayBuffer>;
+export declare const mapNodeSharedMemory: (options: MapSharedMemoryOptions, addon?: NodeSharedMemoryAddon) => SharedMemoryMapping<SharedArrayBuffer>;
+export declare const createNodeConnectionPrimitives: (addon?: NodeSharedMemoryAddon) => SharedMemoryConnectionPrimitives<SharedMemoryMapping<SharedArrayBuffer>>;
+export declare const unlinkNodeSharedMemory: (name: string, addon?: NodeSharedMemoryAddon) => boolean;

package/src/connections/node.js

@@ -0,0 +1,59 @@
+import { getNodeBuiltinModule } from "../common/node-compat.js";
+import { loadNodeNativeAddon } from "./node-addons.js";
+import { assertPosixSharedMemoryPlatform } from "./posix.js";
+import { expectFd, expectPositiveSize, readCreateMode, readCreateName, readRequiredCreateName, readCreateSize, } from "./types.js";
+export const DEFAULT_NODE_SHARED_MEMORY_ADDON = "../../build/Release/knitting_shared_memory.node";
+export const DEFAULT_NODE_FUTEX_ADDON = "../../build/Release/knitting_shm.node";
+export const loadNodeSharedMemoryAddon = (specifier) => {
+    assertPosixSharedMemoryPlatform("Node native shared memory");
+    const nodeModule = getNodeBuiltinModule("node:module");
+    if (nodeModule === undefined) {
+        throw new Error("Node shared memory addon can only be loaded in Node");
+    }
+    const require = nodeModule.createRequire(import.meta.url);
+    return loadNodeNativeAddon(require, "knitting_shared_memory", specifier);
+};
+export const loadNodeFutexAddon = (specifier) => {
+    assertPosixSharedMemoryPlatform("Node native futex helpers");
+    const nodeModule = getNodeBuiltinModule("node:module");
+    if (nodeModule === undefined) {
+        throw new Error("Node futex addon can only be loaded in Node");
+    }
+    const require = nodeModule.createRequire(import.meta.url);
+    return loadNodeNativeAddon(require, "knitting_shm", specifier);
+};
+export const fromNodeNativeMapping = (mapped) => ({
+    runtime: "node",
+    fd: mapped.fd,
+    size: mapped.size,
+    byteLength: mapped.sab.byteLength,
+    buffer: mapped.sab,
+    kind: "shared-array-buffer",
+    sab: mapped.sab,
+    baseAddressMod64: mapped.baseAddressMod64,
+});
+export const createNodeSharedMemory = (options, addon = loadNodeSharedMemoryAddon()) => {
+    const size = expectPositiveSize(readCreateSize(options));
+    const mode = readCreateMode(options);
+    const name = mode === "anonymous"
+        ? readCreateName(options, "knitting_shared_memory")
+        : readRequiredCreateName(options);
+    return fromNodeNativeMapping(addon.createSharedMemory(size, name, mode));
+};
+export const mapNodeSharedMemory = (options, addon = loadNodeSharedMemoryAddon()) => {
+    const fd = expectFd(options.fd);
+    const size = expectPositiveSize(options.size);
+    return fromNodeNativeMapping(addon.mapSharedMemory(fd, size));
+};
+export const createNodeConnectionPrimitives = (addon = loadNodeSharedMemoryAddon()) => ({
+    runtime: "node",
+    createSharedMemory: (options) => createNodeSharedMemory(options, addon),
+    mapSharedMemory: (options) => mapNodeSharedMemory(options, addon),
+    unlinkSharedMemory: (name) => unlinkNodeSharedMemory(name, addon),
+});
+export const unlinkNodeSharedMemory = (name, addon = loadNodeSharedMemoryAddon()) => {
+    if (typeof addon.unlinkSharedMemory !== "function") {
+        throw new Error("Node shared memory addon cannot unlink named mappings");
+    }
+    return addon.unlinkSharedMemory(name);
+};

package/src/connections/posix.d.ts

@@ -0,0 +1,31 @@
+export type PosixPlatform = "linux" | "darwin";
+export declare const LINUX_LIBC_SO = "libc.so.6";
+export declare const DARWIN_LIBSYSTEM = "/usr/lib/libSystem.B.dylib";
+export declare const PROT_READ = 1;
+export declare const PROT_WRITE = 2;
+export declare const MAP_SHARED = 1;
+export declare const O_RDWR = 2;
+export declare const LINUX_O_CREAT = 64;
+export declare const LINUX_O_EXCL = 128;
+export declare const DARWIN_O_CREAT = 512;
+export declare const DARWIN_O_EXCL = 2048;
+export declare const DARWIN_SHM_MODE = 384;
+export declare const POSIX_SHM_MODE = 384;
+export declare const F_GETFD = 1;
+export declare const F_SETFD = 2;
+export declare const FD_CLOEXEC = 1;
+export declare const encodeCString: (value: string) => Uint8Array;
+type FcntlLibc = {
+    symbols: {
+        fcntl: (fd: number, cmd: number, arg: number) => number;
+    };
+};
+export declare const setCloseOnExec: <T extends FcntlLibc>(libc: T, fd: number) => number;
+export declare const shmOpenCreateFlag: (platform: PosixPlatform) => number;
+export declare const shmOpenExclusiveFlag: (platform: PosixPlatform) => number;
+export declare const toPosixSharedMemoryName: (name: string) => string;
+export declare const detectPosixPlatform: () => PosixPlatform;
+export declare const assertPosixSharedMemoryPlatform: (feature: string) => void;
+export declare const getPosixLibcPath: (platform?: PosixPlatform) => string;
+export declare const makeDarwinSharedMemoryName: (_name: string, runtime: string) => string;
+export {};

package/src/connections/posix.js

@@ -0,0 +1,71 @@
+export const LINUX_LIBC_SO = "libc.so.6";
+export const DARWIN_LIBSYSTEM = "/usr/lib/libSystem.B.dylib";
+export const PROT_READ = 1;
+export const PROT_WRITE = 2;
+export const MAP_SHARED = 1;
+export const O_RDWR = 0x0002;
+export const LINUX_O_CREAT = 0x0040;
+export const LINUX_O_EXCL = 0x0080;
+export const DARWIN_O_CREAT = 0x0200;
+export const DARWIN_O_EXCL = 0x0800;
+export const DARWIN_SHM_MODE = 0o600;
+export const POSIX_SHM_MODE = 0o600;
+export const F_GETFD = 1;
+export const F_SETFD = 2;
+export const FD_CLOEXEC = 1;
+export const encodeCString = (value) => new TextEncoder().encode(`${value}\0`);
+export const setCloseOnExec = (libc, fd) => {
+    const flags = libc.symbols.fcntl(fd, F_GETFD, 0);
+    if (flags < 0) {
+        throw new Error("fcntl(F_GETFD) failed");
+    }
+    const result = libc.symbols.fcntl(fd, F_SETFD, flags | FD_CLOEXEC);
+    if (result < 0) {
+        throw new Error("fcntl(F_SETFD) failed");
+    }
+    return fd;
+};
+export const shmOpenCreateFlag = (platform) => platform === "darwin" ? DARWIN_O_CREAT : LINUX_O_CREAT;
+export const shmOpenExclusiveFlag = (platform) => platform === "darwin" ? DARWIN_O_EXCL : LINUX_O_EXCL;
+export const toPosixSharedMemoryName = (name) => {
+    if (name.length === 0) {
+        throw new TypeError("shared memory name must be non-empty");
+    }
+    if (name.includes("\0")) {
+        throw new TypeError("shared memory name must not contain NUL bytes");
+    }
+    const out = name.startsWith("/") ? name : `/${name}`;
+    if (out.length < 2 || out.slice(1).includes("/")) {
+        throw new TypeError("POSIX shared memory name must not contain path separators");
+    }
+    return out;
+};
+export const detectPosixPlatform = () => {
+    const denoOs = globalThis.Deno?.build?.os;
+    if (denoOs === "darwin" || denoOs === "linux")
+        return denoOs;
+    const processPlatform = globalThis.process?.platform;
+    if (processPlatform === "darwin" || processPlatform === "linux") {
+        return processPlatform;
+    }
+    throw new Error("shared memory connections support Linux and macOS only");
+};
+export const assertPosixSharedMemoryPlatform = (feature) => {
+    try {
+        detectPosixPlatform();
+    }
+    catch {
+        throw new Error(`${feature} is supported on Linux and macOS only`);
+    }
+};
+export const getPosixLibcPath = (platform = detectPosixPlatform()) => platform === "darwin" ? DARWIN_LIBSYSTEM : LINUX_LIBC_SO;
+export const makeDarwinSharedMemoryName = (_name, runtime) => {
+    const processId = globalThis.process?.pid ??
+        globalThis.Deno?.pid ??
+        0;
+    const runtimeTag = runtime.slice(0, 1) || "x";
+    const pidTag = Math.abs(processId).toString(36).slice(-5);
+    const timeTag = Date.now().toString(36).slice(-6);
+    const nonce = Math.random().toString(36).slice(2, 6);
+    return `/knit_${runtimeTag}_${pidTag}_${timeTag}_${nonce}`;
+};

package/src/connections/process-shared-buffer.d.ts

@@ -0,0 +1,67 @@
+import type { SharedBuffer, SharedBufferRegion } from "../common/shared-buffer-region.js";
+import { FileDescriptor, type FileDescriptorMetadata } from "./file-descriptor.js";
+import { type CreateSharedMemoryOptions, type SharedMemoryConnectionPrimitives, type SharedMemoryMapping } from "./types.js";
+export type ProcessSharedBufferMetadata = {
+    version: 1;
+    descriptor: FileDescriptorMetadata;
+    byteOffset: number;
+    byteLength: number;
+};
+export declare const PROCESS_SHARED_BUFFER_BRAND: unique symbol;
+export declare const PROCESS_SHARED_BUFFER_NUMERIC_TRANSFER: unique symbol;
+declare const EXTERNAL_PAYLOAD_BRAND: unique symbol;
+export type ProcessSharedBufferNumericMetadata = readonly [
+    fd: number,
+    size: number,
+    descriptorByteLength: number,
+    byteOffset: number,
+    byteLength: number,
+    runtime: number,
+    kind: number,
+    baseAddressMod64: number
+];
+export type ProcessSharedBufferRange = {
+    byteOffset?: number;
+    byteLength?: number;
+};
+export type ProcessSharedBufferCreator = Pick<SharedMemoryConnectionPrimitives, "createSharedMemory">;
+export type ProcessSharedBufferMapper = Pick<SharedMemoryConnectionPrimitives, "mapSharedMemory">;
+export type ProcessSharedBufferPrimitives = Pick<SharedMemoryConnectionPrimitives, "createSharedMemory" | "mapSharedMemory">;
+export type ProcessSharedBufferView = Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint16Array | Int32Array | Uint32Array | BigInt64Array | BigUint64Array | Float32Array | Float64Array;
+export type ProcessSharedBufferViewConstructor<View extends ProcessSharedBufferView = ProcessSharedBufferView> = {
+    readonly BYTES_PER_ELEMENT: number;
+    new (buffer: SharedBuffer, byteOffset: number, length: number): View;
+};
+export declare const setDefaultProcessSharedBufferPrimitives: (primitives: ProcessSharedBufferPrimitives | undefined) => void;
+export declare const getDefaultProcessSharedBufferPrimitives: () => ProcessSharedBufferPrimitives;
+export declare class ProcessSharedBuffer {
+    readonly [PROCESS_SHARED_BUFFER_BRAND] = true;
+    readonly [EXTERNAL_PAYLOAD_BRAND] = "knitting.processSharedBuffer";
+    readonly descriptor: FileDescriptor;
+    readonly byteOffset: number;
+    readonly byteLength: number;
+    constructor(descriptor: FileDescriptor, range?: ProcessSharedBufferRange);
+    static create(options: number | CreateSharedMemoryOptions, creator?: ProcessSharedBufferCreator): ProcessSharedBuffer;
+    static fromMapping(mapping: SharedMemoryMapping): ProcessSharedBuffer;
+    static fromDescriptor(descriptor: FileDescriptor, range?: ProcessSharedBufferRange): ProcessSharedBuffer;
+    static fromMetadata(metadata: unknown): ProcessSharedBuffer;
+    static parse(serialized: string): ProcessSharedBuffer;
+    static [PROCESS_SHARED_BUFFER_NUMERIC_TRANSFER](metadata: ProcessSharedBufferNumericMetadata): ProcessSharedBuffer;
+    get fd(): number;
+    get size(): number;
+    subbuffer(byteOffset: number, byteLength?: number): ProcessSharedBuffer;
+    getSharedArrayBuffer(mapper?: ProcessSharedBufferMapper): SharedArrayBuffer;
+    getSAB(mapper?: ProcessSharedBufferMapper): SharedArrayBuffer;
+    getBuffer(mapper?: ProcessSharedBufferMapper): SharedBuffer;
+    getRegion(mapper?: ProcessSharedBufferMapper): SharedBufferRegion;
+    view<View extends ProcessSharedBufferView>(constructor: ProcessSharedBufferViewConstructor<View>, mapper?: ProcessSharedBufferMapper): View;
+    bytes(mapper?: ProcessSharedBufferMapper): Uint8Array;
+    dataView(mapper?: ProcessSharedBufferMapper): DataView;
+    toMetadata(): ProcessSharedBufferMetadata;
+    toJSON(): ProcessSharedBufferMetadata;
+    stringify(): string;
+    stringifyMetadata(): string;
+    toString(): string;
+}
+export declare const parseProcessSharedBufferMetadata: (input: unknown) => ProcessSharedBufferMetadata;
+export {};