@gjsify/sab-native 0.4.12

package/lib/esm/_virtual/_rolldown/runtime.js

@@ -0,0 +1 @@
+var e=Object.defineProperty,__name=(t,n)=>e(t,`name`,{value:n,configurable:!0});export{__name};

package/lib/esm/index.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";let e=null;const t=globalThis.imports?.gi;if(t)try{e=t.GjsifySabNative}catch{}const n=e;function hasNativeSab(){return e!==null}const r="@gjsify/sab-native prebuild is not loaded — install the package on a Linux system with the prebuild available, or build locally via `meson compile` in packages/node/sab-native/.";var i=class SharedBuffer{_native;constructor(e){this._native=e}static create(t){if(!e)throw Error(r);if(!Number.isInteger(t)||t<=0)throw TypeError(`SharedBuffer.create: size must be a positive integer`);let n=e.SharedBuffer.create(t);if(!n)throw Error(`memfd_create or mmap failed`);return new SharedBuffer(n)}static fromFd(t,n){if(!e)throw Error(r);if(!Number.isInteger(t)||t<0)throw TypeError(`SharedBuffer.fromFd: fd must be a non-negative integer`);if(!Number.isInteger(n)||n<=0)throw TypeError(`SharedBuffer.fromFd: size must be a positive integer`);let i=e.SharedBuffer.from_fd(t,n);if(!i)throw Error(`mmap failed`);return new SharedBuffer(i)}get byteLength(){return this._assertOpen().byte_length}get fd(){return this._assertOpen().fd}get closed(){return this._native===null}close(){this._native=null}getUint8(e){return this._assertOpen().get_u8(e)}setUint8(e,t){this._assertOpen().set_u8(e,t&255)}getUint32LE(e){return this._assertOpen().get_u32_le(e)}setUint32LE(e,t){this._assertOpen().set_u32_le(e,t>>>0)}getInt32LE(e){return this._assertOpen().get_i32_le(e)}setInt32LE(e,t){this._assertOpen().set_i32_le(e,t|0)}getBigUint64LE(e){return this._assertOpen().get_u64_le(e)}setBigUint64LE(e,t){this._assertOpen().set_u64_le(e,t)}readBytes(e,t){let n=this._assertOpen().read_bytes(e,t),r=globalThis.imports?.byteArray;if(r&&typeof r.fromGBytes==`function`){let e=r.fromGBytes(n);return new Uint8Array(e)}return new Uint8Array(n.toArray())}writeBytes(e,t){let n=globalThis.imports?.byteArray,r;if(n&&typeof n.toGBytes==`function`)r=n.toGBytes(t);else{let e=globalThis.imports?.gi?.GLib;r=e?.Bytes?new e.Bytes(t):t}this._assertOpen().write_bytes(e,r)}get _nativeHandle(){return this._assertOpen()}_assertOpen(){if(!this._native)throw Error(`SharedBuffer has been closed`);return this._native}};const a={add32(e,t,n){return e._nativeHandle.atomic_add_i32(t,n|0)},sub32(e,t,n){return e._nativeHandle.atomic_sub_i32(t,n|0)},load32(e,t){return e._nativeHandle.atomic_load_i32(t)},store32(e,t,n){e._nativeHandle.atomic_store_i32(t,n|0)},exchange32(e,t,n){return e._nativeHandle.atomic_xchg_i32(t,n|0)},compareExchange32(e,t,n,r){return e._nativeHandle.atomic_cmpxchg_i32(t,n|0,r|0)},wait32(e,t,n,r){let i=e._nativeHandle.futex_wait(t,n|0,r|0);if(i===0)return`ok`;if(i===-1)return`not-equal`;if(i===-2)return`timed-out`;if(i===-3)return`interrupted`;throw Error(`futex_wait returned errno ${-i}`)},notify32(e,t,n){return e._nativeHandle.futex_wake(t,n|0)}},o=e?{makePair(){let[t,n,r]=e.FdChannel.make_pair();if(!t)throw Error(`socketpair() failed`);return{parentFd:n,childFd:r}},sendFd(t,n,r){return e.FdChannel.send_fd(t,n,r>>>0)},recvFd(t){let[n,r]=e.FdChannel.recv_fd(t);if(n===0)return null;if(n<0)throw Error(`recvmsg failed`);return{fd:n,tag:r>>>0}},closeFd(t){e.FdChannel.close_fd(t)}}:null;export{i as SharedBuffer,a as atomics,o as fdChannel,hasNativeSab,n as nativeSab};

package/lib/types/index.d.ts

@@ -0,0 +1,186 @@
+export interface NativeSharedBuffer {
+    readonly fd: number;
+    readonly byte_length: number;
+    get_u8(offset: number): number;
+    set_u8(offset: number, v: number): void;
+    get_u32_le(offset: number): number;
+    set_u32_le(offset: number, v: number): void;
+    get_i32_le(offset: number): number;
+    set_i32_le(offset: number, v: number): void;
+    get_u64_le(offset: number): bigint;
+    set_u64_le(offset: number, v: bigint): void;
+    read_bytes(offset: number, length: number): unknown;
+    write_bytes(offset: number, data: unknown): void;
+    atomic_add_i32(offset: number, v: number): number;
+    atomic_sub_i32(offset: number, v: number): number;
+    atomic_load_i32(offset: number): number;
+    atomic_store_i32(offset: number, v: number): void;
+    atomic_xchg_i32(offset: number, v: number): number;
+    atomic_cmpxchg_i32(offset: number, expected: number, desired: number): number;
+    futex_wait(offset: number, expected: number, timeout_ms: number): number;
+    futex_wake(offset: number, count: number): number;
+}
+export interface NativeSharedBufferClass {
+    create(size: number): NativeSharedBuffer | null;
+    from_fd(fd: number, size: number): NativeSharedBuffer | null;
+}
+export interface NativeFdChannelClass {
+    make_pair(): [boolean, number, number];
+    send_fd(socket_fd: number, fd_to_send: number, tag: number): boolean;
+    recv_fd(socket_fd: number): [number, number];
+    close_fd(fd: number): boolean;
+}
+export interface GjsifySabNativeModule {
+    SharedBuffer: NativeSharedBufferClass;
+    FdChannel: NativeFdChannelClass;
+}
+/** The native GjsifySabNative module, or null if not installed. */
+export declare const nativeSab: GjsifySabNativeModule | null;
+/** Returns true when the GjsifySabNative native library is available. */
+export declare function hasNativeSab(): boolean;
+/**
+ * A shared-memory region backed by an anonymous memfd (Linux) and
+ * mmap(MAP_SHARED). The `.fd` may be passed to a child process via
+ * SCM_RIGHTS over a Unix-domain socket; the child mmaps the same fd via
+ * `SharedBuffer.fromFd()` to share the backing store.
+ *
+ * Reads and writes are explicitly little-endian regardless of host
+ * byte-order — the C shim swaps where needed (s390x / ppc64).
+ *
+ * Atomic operations on `SharedBuffer` go through the `atomics` namespace
+ * exported from this module — they cannot use JS's built-in
+ * `Atomics` because `Atomics` rejects non-SharedArrayBuffer views.
+ *
+ * Lifecycle: the underlying memfd is closed and the mmap freed when the
+ * `SharedBuffer` instance is garbage-collected. Call `.close()` to
+ * release explicitly.
+ */
+export declare class SharedBuffer {
+    /** @internal */
+    private _native;
+    private constructor();
+    /**
+     * Allocate a fresh anonymous shared-memory region.
+     * @param size byte length. SHOULD be a multiple of the system page size
+     *             (4096 on x86_64) for efficient mmap; smaller values work
+     *             but waste a whole page per region.
+     * @throws Error if the prebuild is not loaded, or if memfd_create/mmap fail.
+     */
+    static create(size: number): SharedBuffer;
+    /**
+     * Map an existing shared-memory fd into this process. The fd is dup'd
+     * — the caller retains ownership of their copy and may close it.
+     *
+     * @param fd file descriptor for a shared-memory object (typically
+     *           received via SCM_RIGHTS from a parent process).
+     * @param size MUST match the sender's view of the region size; the
+     *             kernel does not check this for memfd, so a mismatch
+     *             results in silent partial maps.
+     */
+    static fromFd(fd: number, size: number): SharedBuffer;
+    /** Region size in bytes. */
+    get byteLength(): number;
+    /**
+     * File descriptor of the backing memfd. Pass this to a child process
+     * via Gio.SubprocessLauncher.take_fd() (pre-spawn) or SCM_RIGHTS
+     * (post-spawn) so the child can call `SharedBuffer.fromFd(fd, size)`.
+     */
+    get fd(): number;
+    /** True if this region has been released via close(). */
+    get closed(): boolean;
+    /**
+     * Release the underlying memfd + mmap explicitly. Idempotent. The
+     * backing store survives in any other process that still has the fd
+     * mapped.
+     */
+    close(): void;
+    getUint8(offset: number): number;
+    setUint8(offset: number, v: number): void;
+    getUint32LE(offset: number): number;
+    setUint32LE(offset: number, v: number): void;
+    getInt32LE(offset: number): number;
+    setInt32LE(offset: number, v: number): void;
+    getBigUint64LE(offset: number): bigint;
+    setBigUint64LE(offset: number, v: bigint): void;
+    /**
+     * Read a byte range out as a Uint8Array. ONE-TIME COPY — modifications
+     * to the returned array do NOT propagate back to the region. Use
+     * `writeBytes()` to commit changes back.
+     */
+    readBytes(offset: number, length: number): Uint8Array;
+    /**
+     * Write a byte range into the region. memcpy on the C side.
+     */
+    writeBytes(offset: number, data: Uint8Array): void;
+    /** @internal Internal escape-hatch for atomics + worker_threads transfer. */
+    get _nativeHandle(): NativeSharedBuffer;
+    private _assertOpen;
+}
+/**
+ * Atomic operations against a `SharedBuffer`. Memory order: SEQ_CST.
+ *
+ * **Cannot be used with `Atomics.*` built-ins** — those reject anything
+ * that isn't a typed-array view over a real `SharedArrayBuffer`. This
+ * namespace mirrors the most common Atomics surface against our
+ * memfd-backed regions instead.
+ */
+export declare const atomics: {
+    /** `[*(int32_t*)(sb+offset)] += v`, returns previous value. */
+    add32(sb: SharedBuffer, offset: number, v: number): number;
+    sub32(sb: SharedBuffer, offset: number, v: number): number;
+    load32(sb: SharedBuffer, offset: number): number;
+    store32(sb: SharedBuffer, offset: number, v: number): void;
+    exchange32(sb: SharedBuffer, offset: number, v: number): number;
+    /**
+     * Strong compare-and-swap. Returns the previous value. CAS succeeded iff
+     * `returned === expected`.
+     */
+    compareExchange32(sb: SharedBuffer, offset: number, expected: number, desired: number): number;
+    /**
+     * Linux futex_wait. Compare `*(int32_t*)(sb+offset)` to `expected`; if
+     * equal, block until woken or timeout (0 ms = non-blocking probe;
+     * `-1` ms = infinite).
+     *
+     * Returns:
+     *   - `'ok'`         — woken by a matching `notify32()` call.
+     *   - `'not-equal'`  — value didn't match `expected`; no wait happened.
+     *   - `'timed-out'`  — timeout expired before any wake.
+     *   - `'interrupted'` — interrupted by signal (EINTR); caller may retry.
+     */
+    wait32(sb: SharedBuffer, offset: number, expected: number, timeoutMs: number): "ok" | "not-equal" | "timed-out" | "interrupted";
+    /** Wake up to `count` waiters on `sb+offset`. Returns number actually woken. */
+    notify32(sb: SharedBuffer, offset: number, count: number): number;
+};
+/**
+ * Unix-domain socket pair + SCM_RIGHTS fd-transfer helper.
+ *
+ * **Internal API.** Exposed for `@gjsify/worker_threads` to wire up the
+ * cross-process SharedBuffer transfer at `Worker` spawn time. Direct
+ * consumers should use `Worker.postMessage(value, [sb])` instead.
+ */
+export declare const fdChannel: {
+    makePair(): {
+        parentFd: number;
+        childFd: number;
+    };
+    /**
+     * Send one fd over an open SOCK_SEQPACKET pair via SCM_RIGHTS. Returns
+     * `true` on success, `false` on `sendmsg()` failure (errno preserved on
+     * the calling thread — caller surfaces the error in whatever shape
+     * makes sense for the situation).
+     */
+    sendFd(socketFd: number, fdToSend: number, tag: number): boolean;
+    /**
+     * Blocking recv of one fd. Returns the received fd + tag, or null on
+     * orderly EOF.
+     */
+    recvFd(socketFd: number): {
+        fd: number;
+        tag: number;
+    } | null;
+    /**
+     * close(2) on a fd previously created by `makePair()` (or any fd, really).
+     * Idempotent — closing an already-closed fd is fine.
+     */
+    closeFd(fd: number): void;
+};

package/lib/types/shared-buffer.gjs.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/meson.build

@@ -0,0 +1,57 @@
+project('GjsifySabNative', ['c', 'vala'], version: '1.0')
+
+root_dir = meson.current_source_dir()
+
+# Required system packages (Fedora 43+):
+#   dnf install vala meson ninja-build
+#
+# No external C libraries — sab-native uses libc-only primitives:
+#   memfd_create(2), mmap(2), syscall(SYS_futex), __atomic_* GCC builtins,
+#   AF_UNIX socketpair + SCM_RIGHTS.  All available on every Linux glibc since 3.17.
+#
+# Vala can't express the futex syscall + SCM_RIGHTS ancillary-data dance
+# cleanly, so we wrap them in a small C shim (src/vala/sab-helpers.{h,c})
+# and call into it from Vala via [CCode] extern declarations. Buffer ownership
+# stays C-side, mirroring the @gjsify/http2-native nghttp2-helpers pattern.
+
+vala_deps = [
+    dependency('glib-2.0'),
+    dependency('gobject-2.0'),
+    dependency('gio-2.0'),
+]
+
+sources = files(
+    'src/vala/sab-helpers.c',
+    'src/vala/shared-buffer.vala',
+    'src/vala/fd-passing.vala',
+)
+
+# Compiler picks up sab-helpers.h via the include dir.
+inc = include_directories('src/vala')
+
+# -D_GNU_SOURCE: needed for memfd_create + MFD_CLOEXEC + SYS_futex visibility.
+c_args = ['-D_GNU_SOURCE']
+
+libGjsifySabNative = library('gjsifysabnative', sources,
+    dependencies: vala_deps,
+    include_directories: inc,
+    c_args: c_args,
+    vala_gir: meson.project_name() + '-1.0.gir',
+    install: true,
+    install_dir: [true, true, true, true],
+)
+
+g_ir_compiler = find_program('g-ir-compiler')
+
+custom_target(meson.project_name() + '-1.0.typelib',
+    command: [
+        g_ir_compiler,
+        '--shared-library', 'libgjsifysabnative.so',
+        '--output', '@OUTPUT@',
+        meson.current_build_dir() / meson.project_name() + '-1.0.gir',
+    ],
+    output: meson.project_name() + '-1.0.typelib',
+    depends: libGjsifySabNative,
+    install: true,
+    install_dir: get_option('libdir') / 'girepository-1.0',
+)

package/package.json

@@ -0,0 +1,65 @@
+{
+    "name": "@gjsify/sab-native",
+    "version": "0.4.12",
+    "description": "Optional Vala/GObject bridge providing cross-process shared memory + atomics for @gjsify/worker_threads. Wraps Linux memfd_create(2) + mmap(MAP_SHARED) to back JS-visible SharedBuffer regions whose fds can be passed to child workers via SCM_RIGHTS over a Unix-domain socket; exposes typed accessors (getInt32LE / setUint8 / etc.) plus atomics built on __atomic_* GCC builtins and SYS_futex for wait/notify. Workaround for the stock-GJS gap where SharedArrayBuffer is unavailable (Mozilla disables the SAB constructor without COOP/COEP opts) and SAB cannot share backing stores across Gio.Subprocess workers anyway.",
+    "type": "module",
+    "main": "lib/esm/index.js",
+    "module": "lib/esm/index.js",
+    "types": "lib/types/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./lib/types/index.d.ts",
+            "default": "./lib/esm/index.js"
+        }
+    },
+    "files": [
+        "lib",
+        "prebuilds",
+        "meson.build",
+        "src/vala"
+    ],
+    "gjsify": {
+        "prebuilds": "prebuilds"
+    },
+    "scripts": {
+        "clear": "rm -rf lib build tsconfig.tsbuildinfo tsconfig.types.tsbuildinfo test.gjs.mjs || exit 0",
+        "check": "tsc --noEmit",
+        "init:meson": "meson setup build .",
+        "init:meson:wipe": "gjsify run init:meson --wipe",
+        "build": "gjsify run build:gjsify && gjsify run build:types",
+        "build:gjsify": "gjsify build --library 'src/ts/**/*.{ts,js}' --exclude 'src/ts/**/*.spec.{mts,ts}' 'src/ts/test.{mts,ts}'",
+        "build:meson": "gjsify run init:meson && meson compile -C build",
+        "build:types": "tsc",
+        "build:prebuilds": "gjsify run build:meson && mkdir -p prebuilds/linux-x86_64 && cp build/libgjsifysabnative.so build/GjsifySabNative-1.0.gir build/GjsifySabNative-1.0.typelib prebuilds/linux-x86_64/",
+        "build:gir-types": "ts-for-gir generate --externalDeps --allowMissingDeps --girDirectories=./prebuilds/linux-x86_64 --girDirectories=/usr/share/gir-1.0 --modules=GjsifySabNative-1.0 --outdir=src/ts --npmScope=@girs --package=false --ignoreVersionConflicts=true",
+        "build:test": "gjsify run build:test:gjs",
+        "build:test:gjs": "gjsify build src/ts/test.mts --app gjs --outfile test.gjs.mjs",
+        "test": "gjsify run build:gjsify && gjsify run build:test && gjsify run test:gjs",
+        "test:gjs": "gjsify run test.gjs.mjs"
+    },
+    "keywords": [
+        "gjs",
+        "shared-memory",
+        "shared-array-buffer",
+        "atomics",
+        "memfd",
+        "mmap",
+        "futex",
+        "worker-threads",
+        "vala",
+        "native"
+    ],
+    "dependencies": {
+        "@girs/gjs": "4.0.0-rc.15",
+        "@girs/glib-2.0": "2.88.0-4.0.0-rc.15",
+        "@girs/gobject-2.0": "2.88.0-4.0.0-rc.15",
+        "@girs/gio-2.0": "2.88.0-4.0.0-rc.15"
+    },
+    "devDependencies": {
+        "@gjsify/cli": "^0.4.12",
+        "@gjsify/unit": "^0.4.12",
+        "@ts-for-gir/cli": "^4.0.0-rc.15",
+        "@types/node": "^25.6.2",
+        "typescript": "^6.0.3"
+    }
+}