@gjsify/sab-native 0.36.0 → 0.37.0

package/lib/types/index.d.ts

@@ -35,99 +35,77 @@ export interface GjsifySabNativeModule {
     FdChannel: NativeFdChannelClass;
 }
 /**
- * Resolve the `GjsifySabNative` GI module out of a GJS `imports.gi` object,
- * normalising **every** unavailable case to `null`.
+ * Resolve the `GjsifySabNative` GI module, normalising EVERY unavailable case to
+ * `null`: no `gi` at all (not GJS), a throwing property access (typelib not on
+ * `GI_TYPELIB_PATH` — the macOS/Windows case), and a value that is not the module
+ * we expect (stale, partial or shadowed typelib). The third needs the shape check:
+ * a partial value otherwise leaves `hasNativeSab()` reporting `true` and fails with
+ * an opaque `TypeError` at first use.
  *
- * Exported so the degradation contract can be pinned by a spec without a
- * second process (see `shared-buffer.gjs.spec.ts`). Three ways this returns
- * `null`, all of which must behave identically to the caller:
- *
- * 1. `gi` itself is absent — we are not on GJS at all (Node, browser).
- * 2. The property access throws — GJS raises when the typelib is not on
- *    `GI_TYPELIB_PATH`, i.e. no prebuild for this platform. This is the
- *    macOS/Windows case.
- * 3. The access succeeds but yields something that is not the module we
- *    expect — a stale, partial or shadowed typelib. Without the shape check
- *    a `undefined`/partial value would leave `hasNativeSab()` reporting
- *    `true` and then blow up with an opaque `TypeError` at first use; the
- *    check converts that into the same clean "unavailable" answer.
- *
- * @internal
+ * @internal exported so a spec can pin the degradation contract in-process
+ * (`shared-buffer.gjs.spec.ts`).
  */
 export declare function resolveNativeSab(gi: Record<string, unknown> | undefined): GjsifySabNativeModule | null;
 /** The native GjsifySabNative module, or null if not installed. */
 export declare const nativeSab: GjsifySabNativeModule | null;
 /**
- * Returns true when the GjsifySabNative native library is available.
- *
- * This is THE gate for cross-process `SharedBuffer` support and it is
- * platform-conditional by design: it is `true` only on Linux (see ADR 0013),
- * and `false` on macOS, Windows, Node and the browser. Guard every use of
- * `SharedBuffer` / `atomics` / `fdChannel` with it.
+ * THE gate for cross-process `SharedBuffer`, and platform-conditional by design:
+ * `true` only on Linux (ADR 0013), `false` on macOS, Windows, Node and the browser.
+ * Guard every use of `SharedBuffer` / `atomics` / `fdChannel` with it.
  */
 export declare function hasNativeSab(): boolean;
 /**
- * Message thrown by `SharedBuffer.create()` / `.fromFd()` when the native
- * backend is unavailable. Names the actual situation — a platform-scoped
- * capability — instead of implying a broken install.
+ * Thrown by `SharedBuffer.create()` / `.fromFd()` when the native backend is
+ * unavailable. Says "platform-scoped capability", not "broken install".
  *
  * @internal exported so specs and docs can assert the exact contract text.
  */
 export declare const NATIVE_SAB_UNAVAILABLE: string;
 /**
- * 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).
+ * A shared-memory region backed by an anonymous memfd and mmap(MAP_SHARED). The
+ * `.fd` may be passed to a child over a Unix-domain socket via SCM_RIGHTS; the
+ * child mmaps the same fd with `SharedBuffer.fromFd()` to share the backing store.
  *
- * 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.
+ * Reads and writes are little-endian regardless of host byte-order — the C shim
+ * swaps where needed (s390x / ppc64).
  *
- * Lifecycle: the underlying memfd is closed and the mmap freed when the
- * `SharedBuffer` instance is garbage-collected. Call `.close()` to
- * release explicitly.
+ * Lifecycle: the memfd is closed and the mmap freed by the native destructor, i.e.
+ * when this instance is garbage-collected. `.close()` does NOT release the region;
+ * it only drops our reference so later access throws.
  */
 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.
+     * Allocate a fresh anonymous shared-memory region. `size` SHOULD be a multiple
+     * of the page size — smaller values work but waste a whole page per region.
+     *
+     * @throws if the prebuild is not loaded, or 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.
+     * Map an existing shared-memory fd — typically received via SCM_RIGHTS — into
+     * this process. The fd is dup'd, so the caller keeps ownership of their copy.
      *
-     * @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.
+     * `size` MUST match the sender's view of the region: the kernel does not check
+     * it for a memfd, so a mismatch silently produces a partial map.
      */
     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)`.
+     * File descriptor of the backing memfd — hand it to a child via
+     * `Gio.SubprocessLauncher.take_fd()` pre-spawn or SCM_RIGHTS post-spawn.
      */
     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.
+     * Drop this view of the region. Idempotent. NOT a release: the memfd and mmap go
+     * away with the native GObject's destructor, so this only makes later access
+     * throw rather than segfault. The backing store also survives in any other
+     * process still holding the fd mapped.
      */
     close(): void;
     getUint8(offset: number): number;
@@ -139,64 +117,39 @@ export declare class SharedBuffer {
     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, or `viewBytes()` for a
-     * zero-copy view.
+     * Read a byte range as a Uint8Array. ONE-TIME COPY — modifications do NOT
+     * propagate back; use `writeBytes()` to commit changes.
      */
     readBytes(offset: number, length: number): Uint8Array;
     /**
-     * Return a fresh `Uint8Array` containing the bytes at `[offset, offset+length)`.
-     * Same semantics as `readBytes()` — kept under this name because
-     * downstream tooling (`Buffer.from`, `node:crypto`'s `Hash.update`,
-     * `fs.writeSync`) calls into this method via duck-typing and the
-     * `viewBytes` name reads more naturally there.
-     *
-     * **NOT zero-copy in current GJS.** GJS's `byteArray.fromGBytes`
-     * (`refs/gjs/gjs/byteArray.cpp::from_gbytes_func`) allocates a fresh
-     * `JS::ArrayBuffer` and memcpy's the GBytes data into it — by design,
-     * for alignment + immutability reasons.
-     *
-     * **Why no internal fix is possible**: a true zero-copy view would need
-     * `JS::NewExternalArrayBuffer` against the mmap pointer, but that JSAPI
-     * call requires a `JSContext*` which GJS does not expose to
-     * GObject-introspected `.so` plugins. The fix has to land in GJS
-     * itself (e.g. a `byteArray.fromGBytesShared` helper). Tracked under
-     * status/upstream-patch-candidates.md.
-     *
-     * Modifications to the returned array therefore do NOT propagate back
-     * to the region — use `writeBytes()` to commit changes.
+     * Identical to `readBytes()`, under a second name because downstream tooling
+     * (`Buffer.from`, `node:crypto`'s `Hash.update`, `fs.writeSync`) duck-types into
+     * it and `viewBytes` reads naturally there.
      *
-     * @throws Error if `byteArray.fromGBytes` is not available (GJS < 1.66).
+     * Despite the name it is NOT zero-copy, and cannot be made so from here: GJS's
+     * `byteArray.fromGBytes` (`refs/gjs/gjs/byteArray.cpp::from_gbytes_func`)
+     * allocates a fresh `JS::ArrayBuffer` and memcpys into it, deliberately, for
+     * alignment and immutability. A real view needs `JS::NewExternalArrayBuffer`
+     * over the mmap pointer, which needs a `JSContext*` that GJS does not hand to
+     * introspected `.so` plugins — so the fix belongs in GJS (a
+     * `byteArray.fromGBytesShared`). Tracked in status/upstream-patch-candidates.md.
      */
     viewBytes(offset: number, length: number): Uint8Array;
     /**
-     * Return a `Buffer` containing the bytes at `[offset, offset+length)`.
-     * The Buffer is a fresh allocation (see `viewBytes()` for the "not
-     * zero-copy in current GJS" caveat — the limitation is in GJS'
-     * `byteArray.fromGBytes`, not bypassable from a `.so` plugin without
-     * upstream patching GJS) — `buf.writeUInt32LE(...)`, `buf.subarray(...)`,
-     * `buf.toString('hex')`, `createHash().update(buf)` all work, but
-     * writes do NOT propagate back to the shared region.
+     * The bytes at `[offset, offset+length)` as a `Buffer`, so `writeUInt32LE`,
+     * `subarray`, `toString('hex')` and `createHash().update()` all work — on a
+     * COPY, per `viewBytes()`, so writes do not reach the shared region.
      *
-     * Requires `globalThis.Buffer` to be registered (via
-     * `@gjsify/buffer/register`) — otherwise throws. Consumers running
-     * under the standard gjsify CLI bundle have Buffer registered via
-     * `--globals auto`; for ad-hoc scripts, add an explicit
-     * `import '@gjsify/buffer/register'` at the entry point.
+     * Needs `globalThis.Buffer` registered, which `--globals auto` does for the
+     * standard CLI bundle; an ad-hoc script needs an explicit
+     * `import '@gjsify/buffer/register'`.
      *
-     * Return type is generic to avoid an import dependency on
-     * `@gjsify/buffer` — the concrete return is a `Buffer` (subclass of
-     * `Uint8Array`). Default `T = Uint8Array` is always safe;
-     * `toBuffer<Buffer>()` gets the full Buffer surface.
-     *
-     * @param offset byte offset into the shared region. Defaults to 0.
-     * @param length byte length. Defaults to `byteLength - offset`.
+     * The return type is generic only to avoid a dependency on `@gjsify/buffer`; the
+     * concrete value is always a `Buffer`, so `toBuffer<Buffer>()` gets the full
+     * surface and the `Uint8Array` default is always safe.
      */
     toBuffer<T extends Uint8Array = Uint8Array>(offset?: number, length?: number): T;
-    /**
-     * Write a byte range into the region. memcpy on the C side.
-     */
+    /** 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;
@@ -205,10 +158,9 @@ export declare class SharedBuffer {
 /**
  * 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.
+ * The `Atomics.*` built-ins are not an option: GJS does not expose `Atomics` at all
+ * (verified on gjs 1.88.1), and a `SharedBuffer` is not a typed-array view in any
+ * case. This namespace mirrors the common surface over the memfd-backed region.
  */
 export declare const atomics: {
     /** `[*(int32_t*)(sb+offset)] += v`, returns previous value. */
@@ -238,11 +190,11 @@ export declare const atomics: {
     notify32(sb: SharedBuffer, offset: number, count: number): number;
 };
 /**
- * Unix-domain socket pair + SCM_RIGHTS fd-transfer helper.
+ * Unix-domain socket pair + SCM_RIGHTS fd transfer.
  *
- * **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.
+ * @internal for `@gjsify/worker_threads` to wire up the cross-process SharedBuffer
+ * transfer at `Worker` spawn time; direct consumers use
+ * `Worker.postMessage(value, [sb])`.
  */
 export declare const fdChannel: {
     makePair(): {
@@ -250,23 +202,16 @@ export declare const fdChannel: {
         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).
+     * Send one fd over an open SOCK_SEQPACKET pair via SCM_RIGHTS. `false` on
+     * `sendmsg()` failure, with errno left on the calling thread for the caller
+     * to shape into an error.
      */
     sendFd(socketFd: number, fdToSend: number, tag: number): boolean;
-    /**
-     * Blocking recv of one fd. Returns the received fd + tag, or null on
-     * orderly EOF.
-     */
+    /** Blocking recv of one 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.
-     */
+    /** close(2) on any fd. Idempotent: the shim reports success on EBADF too. */
     closeFd(fd: number): void;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/sab-native",
-    "version": "0.36.0",
+    "version": "0.37.0",
     "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",
@@ -68,8 +68,8 @@
         "@girs/gio-2.0": "^4.1.0"
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.36.0",
-        "@gjsify/unit": "^0.36.0",
+        "@gjsify/cli": "^0.37.0",
+        "@gjsify/unit": "^0.37.0",
         "@ts-for-gir/cli": "^4.1.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
@@ -85,10 +85,10 @@
     },
     "homepage": "https://github.com/gjsify/gjsify/tree/main/packages/node/sab-native#readme",
     "optionalDependencies": {
-        "@gjsify/sab-native-linux-arm64": "0.36.0",
-        "@gjsify/sab-native-linux-ppc64": "0.36.0",
-        "@gjsify/sab-native-linux-riscv64": "0.36.0",
-        "@gjsify/sab-native-linux-s390x": "0.36.0",
-        "@gjsify/sab-native-linux-x64": "0.36.0"
+        "@gjsify/sab-native-linux-arm64": "0.37.0",
+        "@gjsify/sab-native-linux-ppc64": "0.37.0",
+        "@gjsify/sab-native-linux-riscv64": "0.37.0",
+        "@gjsify/sab-native-linux-s390x": "0.37.0",
+        "@gjsify/sab-native-linux-x64": "0.37.0"
     }
 }