@gjsify/sab-native 0.4.12

package/src/vala/sab-helpers.c

@@ -0,0 +1,461 @@
+/*
+ * sab-helpers.c — see sab-helpers.h for the contract.
+ *
+ * Linux-only. Compile with -D_GNU_SOURCE so memfd_create, MFD_CLOEXEC,
+ * and the FUTEX_*_PRIVATE constants are visible.
+ */
+
+#include "sab-helpers.h"
+
+#include <errno.h>
+#include <fcntl.h>
+#include <linux/futex.h>
+#include <stdatomic.h>
+#include <stdint.h>
+#include <string.h>
+#include <sys/mman.h>
+#include <sys/socket.h>
+#include <sys/syscall.h>
+#include <sys/time.h>
+#include <sys/types.h>
+#include <sys/un.h>
+#include <time.h>
+#include <unistd.h>
+
+/* glibc < 2.27 doesn't expose memfd_create() as a libc wrapper. We use the
+ * raw syscall to stay portable across the prebuild distro matrix. */
+#ifndef MFD_CLOEXEC
+#  define MFD_CLOEXEC 0x0001U
+#endif
+
+static int
+gjsify_memfd_create (const char *name, unsigned int flags)
+{
+  return (int) syscall (SYS_memfd_create, name, flags);
+}
+
+/* ────────────────────────────────────────────────────────────────────── *
+ * GjsifySabRegion: opaque shared-memory region
+ * ────────────────────────────────────────────────────────────────────── */
+
+struct _GjsifySabRegion {
+  void  *ptr;
+  gsize  size;
+  gint   fd;
+  /* Refcount for GBytes-borrow lifetimes (read_bytes returns a GBytes that
+   * pins the region until the bytes object is released).  Strong count is
+   * always ≥ 1 (the JS-side SharedBuffer owns one); each outstanding GBytes
+   * adds one more. */
+  gint   refcount;
+};
+
+static GjsifySabRegion *
+region_ref (GjsifySabRegion *region)
+{
+  g_atomic_int_inc (&region->refcount);
+  return region;
+}
+
+static void
+region_unref (gpointer data)
+{
+  GjsifySabRegion *region = (GjsifySabRegion *) data;
+  if (!g_atomic_int_dec_and_test (&region->refcount)) return;
+
+  if (region->ptr != NULL && region->ptr != MAP_FAILED) {
+    munmap (region->ptr, region->size);
+  }
+  if (region->fd >= 0) {
+    close (region->fd);
+  }
+  g_slice_free (GjsifySabRegion, region);
+}
+
+GjsifySabRegion *
+gjsify_sab_region_new_anonymous (gsize size)
+{
+  if (size == 0) { errno = EINVAL; return NULL; }
+
+  int fd = gjsify_memfd_create ("gjsify-sab", MFD_CLOEXEC);
+  if (fd < 0) return NULL;
+
+  if (ftruncate (fd, (off_t) size) < 0) {
+    int e = errno;
+    close (fd);
+    errno = e;
+    return NULL;
+  }
+
+  void *ptr = mmap (NULL, size, PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0);
+  if (ptr == MAP_FAILED) {
+    int e = errno;
+    close (fd);
+    errno = e;
+    return NULL;
+  }
+
+  GjsifySabRegion *region = g_slice_new0 (GjsifySabRegion);
+  region->ptr = ptr;
+  region->size = size;
+  region->fd = fd;
+  region->refcount = 1;
+  return region;
+}
+
+GjsifySabRegion *
+gjsify_sab_region_new_from_fd (gint fd, gsize size)
+{
+  if (fd < 0 || size == 0) { errno = EINVAL; return NULL; }
+
+  /* dup so the caller can close their copy without unmapping ours. */
+  int dup_fd = fcntl (fd, F_DUPFD_CLOEXEC, 0);
+  if (dup_fd < 0) return NULL;
+
+  void *ptr = mmap (NULL, size, PROT_READ | PROT_WRITE, MAP_SHARED, dup_fd, 0);
+  if (ptr == MAP_FAILED) {
+    int e = errno;
+    close (dup_fd);
+    errno = e;
+    return NULL;
+  }
+
+  GjsifySabRegion *region = g_slice_new0 (GjsifySabRegion);
+  region->ptr = ptr;
+  region->size = size;
+  region->fd = dup_fd;
+  region->refcount = 1;
+  return region;
+}
+
+void
+gjsify_sab_region_free (GjsifySabRegion *region)
+{
+  if (region == NULL) return;
+  region_unref (region);
+}
+
+gint  gjsify_sab_region_get_fd   (const GjsifySabRegion *region) { return region->fd;   }
+gsize gjsify_sab_region_get_size (const GjsifySabRegion *region) { return region->size; }
+
+/* ────────────────────────────────────────────────────────────────────── *
+ * Plain read / write
+ * ────────────────────────────────────────────────────────────────────── */
+
+#define BOUNDS_CHECK(reg, off, sz) do {                                                  \
+    if (G_UNLIKELY ((off) + (sz) > (reg)->size)) {                                       \
+      g_error ("gjsify-sab: out-of-bounds access (offset=%" G_GSIZE_FORMAT               \
+               ", size=%zu, region=%" G_GSIZE_FORMAT ")", (gsize)(off), (size_t)(sz),    \
+               (reg)->size);                                                             \
+    }                                                                                    \
+} while (0)
+
+guint8
+gjsify_sab_region_read_u8 (const GjsifySabRegion *region, gsize offset)
+{
+  BOUNDS_CHECK (region, offset, 1);
+  return ((const guint8 *) region->ptr)[offset];
+}
+
+void
+gjsify_sab_region_write_u8 (GjsifySabRegion *region, gsize offset, guint8 v)
+{
+  BOUNDS_CHECK (region, offset, 1);
+  ((guint8 *) region->ptr)[offset] = v;
+}
+
+guint32
+gjsify_sab_region_read_u32_le (const GjsifySabRegion *region, gsize offset)
+{
+  BOUNDS_CHECK (region, offset, 4);
+  guint32 v;
+  memcpy (&v, (const guint8 *) region->ptr + offset, 4);
+  return GUINT32_FROM_LE (v);
+}
+
+void
+gjsify_sab_region_write_u32_le (GjsifySabRegion *region, gsize offset, guint32 v)
+{
+  BOUNDS_CHECK (region, offset, 4);
+  guint32 le = GUINT32_TO_LE (v);
+  memcpy ((guint8 *) region->ptr + offset, &le, 4);
+}
+
+gint32
+gjsify_sab_region_read_i32_le (const GjsifySabRegion *region, gsize offset)
+{
+  BOUNDS_CHECK (region, offset, 4);
+  guint32 u;
+  memcpy (&u, (const guint8 *) region->ptr + offset, 4);
+  u = GUINT32_FROM_LE (u);
+  gint32 i;
+  memcpy (&i, &u, 4);
+  return i;
+}
+
+void
+gjsify_sab_region_write_i32_le (GjsifySabRegion *region, gsize offset, gint32 v)
+{
+  BOUNDS_CHECK (region, offset, 4);
+  guint32 u;
+  memcpy (&u, &v, 4);
+  u = GUINT32_TO_LE (u);
+  memcpy ((guint8 *) region->ptr + offset, &u, 4);
+}
+
+guint64
+gjsify_sab_region_read_u64_le (const GjsifySabRegion *region, gsize offset)
+{
+  BOUNDS_CHECK (region, offset, 8);
+  guint64 v;
+  memcpy (&v, (const guint8 *) region->ptr + offset, 8);
+  return GUINT64_FROM_LE (v);
+}
+
+void
+gjsify_sab_region_write_u64_le (GjsifySabRegion *region, gsize offset, guint64 v)
+{
+  BOUNDS_CHECK (region, offset, 8);
+  guint64 le = GUINT64_TO_LE (v);
+  memcpy ((guint8 *) region->ptr + offset, &le, 8);
+}
+
+/* ────────────────────────────────────────────────────────────────────── *
+ * Bulk read / write (zero-copy for read, memcpy for write)
+ * ────────────────────────────────────────────────────────────────────── */
+
+GBytes *
+gjsify_sab_region_read_bytes (GjsifySabRegion *region, gsize offset, gsize length)
+{
+  BOUNDS_CHECK (region, offset, length);
+  /* GBytes wraps the mmap'd memory without copying. We hand the GBytes a
+   * region_ref so the mmap survives until the bytes object is released. */
+  region_ref (region);
+  return g_bytes_new_with_free_func ((const guint8 *) region->ptr + offset,
+                                     length,
+                                     region_unref,
+                                     region);
+}
+
+void
+gjsify_sab_region_write_bytes (GjsifySabRegion *region, gsize offset, GBytes *data)
+{
+  gsize len = 0;
+  gconstpointer src = g_bytes_get_data (data, &len);
+  BOUNDS_CHECK (region, offset, len);
+  if (len > 0) memcpy ((guint8 *) region->ptr + offset, src, len);
+}
+
+/* ────────────────────────────────────────────────────────────────────── *
+ * Atomics: __atomic_* builtins with SEQ_CST memory order
+ * ────────────────────────────────────────────────────────────────────── */
+
+static inline int32_t *
+i32_ptr (const GjsifySabRegion *region, gsize offset)
+{
+  BOUNDS_CHECK (region, offset, 4);
+  return (int32_t *) ((guint8 *) region->ptr + offset);
+}
+
+gint32
+gjsify_sab_region_atomic_add_i32 (GjsifySabRegion *region, gsize offset, gint32 v)
+{
+  /* fetch_add: returns the value BEFORE the addition. */
+  return __atomic_fetch_add (i32_ptr (region, offset), v, __ATOMIC_SEQ_CST);
+}
+
+gint32
+gjsify_sab_region_atomic_sub_i32 (GjsifySabRegion *region, gsize offset, gint32 v)
+{
+  return __atomic_fetch_sub (i32_ptr (region, offset), v, __ATOMIC_SEQ_CST);
+}
+
+gint32
+gjsify_sab_region_atomic_load_i32 (const GjsifySabRegion *region, gsize offset)
+{
+  return __atomic_load_n (i32_ptr (region, offset), __ATOMIC_SEQ_CST);
+}
+
+void
+gjsify_sab_region_atomic_store_i32 (GjsifySabRegion *region, gsize offset, gint32 v)
+{
+  __atomic_store_n (i32_ptr (region, offset), v, __ATOMIC_SEQ_CST);
+}
+
+gint32
+gjsify_sab_region_atomic_xchg_i32 (GjsifySabRegion *region, gsize offset, gint32 v)
+{
+  return __atomic_exchange_n (i32_ptr (region, offset), v, __ATOMIC_SEQ_CST);
+}
+
+gboolean
+gjsify_sab_region_atomic_cmpxchg_i32 (GjsifySabRegion *region,
+                                      gsize            offset,
+                                      gint32          *expected,
+                                      gint32           desired)
+{
+  /* weak=FALSE so spurious failures don't happen — JS caller expects a
+   * strong CAS. */
+  return __atomic_compare_exchange_n (i32_ptr (region, offset),
+                                      expected, desired,
+                                      FALSE,
+                                      __ATOMIC_SEQ_CST, __ATOMIC_SEQ_CST)
+         ? TRUE : FALSE;
+}
+
+/* ────────────────────────────────────────────────────────────────────── *
+ * Futex wait / wake
+ * ────────────────────────────────────────────────────────────────────── */
+
+gint
+gjsify_sab_region_futex_wait (GjsifySabRegion *region,
+                              gsize            offset,
+                              gint32           expected,
+                              gint64           timeout_ms)
+{
+  BOUNDS_CHECK (region, offset, 4);
+  int32_t *addr = (int32_t *) ((guint8 *) region->ptr + offset);
+
+  struct timespec ts;
+  struct timespec *ts_ptr = NULL;
+  if (timeout_ms >= 0) {
+    ts.tv_sec  = timeout_ms / 1000;
+    ts.tv_nsec = (timeout_ms % 1000) * 1000000L;
+    ts_ptr = &ts;
+  }
+
+  /* FUTEX_WAIT (no _PRIVATE flag) so the kernel keys by underlying
+   * physical page rather than the calling process's virtual address.
+   * SharedBuffer regions are mmap'd at different addresses in each
+   * Worker, but back the same physical pages via memfd_create —
+   * FUTEX_WAIT_PRIVATE would fail to match across processes. */
+  long ret = syscall (SYS_futex, addr, FUTEX_WAIT,
+                      (int) expected, ts_ptr, NULL, 0);
+  if (ret == 0) return 0;             /* woken via FUTEX_WAKE */
+  int e = errno;
+  if (e == EAGAIN)    return -1;      /* value didn't match expected */
+  if (e == ETIMEDOUT) return -2;
+  if (e == EINTR)     return -3;
+  return -e;
+}
+
+gint
+gjsify_sab_region_futex_wake (GjsifySabRegion *region,
+                              gsize            offset,
+                              gint             count)
+{
+  BOUNDS_CHECK (region, offset, 4);
+  int32_t *addr = (int32_t *) ((guint8 *) region->ptr + offset);
+  long ret = syscall (SYS_futex, addr, FUTEX_WAKE, count,
+                      NULL, NULL, 0);
+  return (gint) ret;
+}
+
+/* ────────────────────────────────────────────────────────────────────── *
+ * IPC side-channel: socketpair + SCM_RIGHTS
+ * ────────────────────────────────────────────────────────────────────── */
+
+gboolean
+gjsify_sab_socketpair (gint *parent_fd, gint *child_fd)
+{
+  int sv[2];
+  if (socketpair (AF_UNIX, SOCK_SEQPACKET | SOCK_CLOEXEC, 0, sv) < 0) {
+    return FALSE;
+  }
+  *parent_fd = sv[0];
+  *child_fd  = sv[1];
+  return TRUE;
+}
+
+gboolean
+gjsify_sab_send_fd (gint socket_fd, gint fd_to_send, guint32 tag)
+{
+  struct msghdr msg;
+  struct iovec  iov;
+  union {
+    char           buf[CMSG_SPACE (sizeof (int))];
+    struct cmsghdr align;
+  } cmsg_buf;
+
+  /* Payload: 4-byte big-endian tag. */
+  guint32 tag_be = GUINT32_TO_BE (tag);
+
+  memset (&msg, 0, sizeof msg);
+  memset (&cmsg_buf, 0, sizeof cmsg_buf);
+
+  iov.iov_base = &tag_be;
+  iov.iov_len  = sizeof tag_be;
+  msg.msg_iov  = &iov;
+  msg.msg_iovlen = 1;
+  msg.msg_control    = cmsg_buf.buf;
+  msg.msg_controllen = sizeof cmsg_buf.buf;
+
+  struct cmsghdr *cmsg = CMSG_FIRSTHDR (&msg);
+  cmsg->cmsg_level = SOL_SOCKET;
+  cmsg->cmsg_type  = SCM_RIGHTS;
+  cmsg->cmsg_len   = CMSG_LEN (sizeof (int));
+  memcpy (CMSG_DATA (cmsg), &fd_to_send, sizeof (int));
+
+  ssize_t n;
+  do {
+    n = sendmsg (socket_fd, &msg, MSG_NOSIGNAL);
+  } while (n < 0 && errno == EINTR);
+  return n >= 0;
+}
+
+gint
+gjsify_sab_recv_fd (gint socket_fd, guint32 *tag)
+{
+  struct msghdr msg;
+  struct iovec  iov;
+  union {
+    char           buf[CMSG_SPACE (sizeof (int))];
+    struct cmsghdr align;
+  } cmsg_buf;
+
+  guint32 tag_be = 0;
+
+  memset (&msg, 0, sizeof msg);
+  memset (&cmsg_buf, 0, sizeof cmsg_buf);
+
+  iov.iov_base = &tag_be;
+  iov.iov_len  = sizeof tag_be;
+  msg.msg_iov  = &iov;
+  msg.msg_iovlen = 1;
+  msg.msg_control    = cmsg_buf.buf;
+  msg.msg_controllen = sizeof cmsg_buf.buf;
+
+  ssize_t n;
+  do {
+    n = recvmsg (socket_fd, &msg, MSG_CMSG_CLOEXEC);
+  } while (n < 0 && errno == EINTR);
+
+  if (n == 0) return 0;       /* orderly EOF */
+  if (n < 0)  return -1;      /* error — errno preserved */
+
+  *tag = GUINT32_FROM_BE (tag_be);
+
+  /* Extract the fd from the control message. */
+  for (struct cmsghdr *cm = CMSG_FIRSTHDR (&msg); cm != NULL; cm = CMSG_NXTHDR (&msg, cm)) {
+    if (cm->cmsg_level == SOL_SOCKET && cm->cmsg_type == SCM_RIGHTS) {
+      int fd;
+      memcpy (&fd, CMSG_DATA (cm), sizeof (int));
+      return fd;
+    }
+  }
+
+  /* No fd in the message — protocol violation. */
+  errno = EBADMSG;
+  return -1;
+}
+
+gboolean
+gjsify_sab_close_fd (gint fd)
+{
+  if (fd < 0) return FALSE;
+  int r;
+  do {
+    r = close (fd);
+  } while (r < 0 && errno == EINTR);
+  /* EBADF: already closed (or never opened) — caller's intent satisfied. */
+  return r == 0 || errno == EBADF;
+}

package/src/vala/sab-helpers.h

@@ -0,0 +1,150 @@
+/*
+ * Tiny C shim around Linux shared-memory + atomics primitives that Vala
+ * can't express cleanly:
+ *
+ *   - memfd_create(2)         — anonymous shared-memory fd (no path needed)
+ *   - mmap(2) / munmap(2)     — MAP_SHARED region creation
+ *   - SYS_futex (FUTEX_WAIT_PRIVATE / FUTEX_WAKE_PRIVATE) — wait/notify
+ *   - __atomic_* GCC builtins — load/store/add/cmpxchg with SEQ_CST
+ *   - socketpair(AF_UNIX, SOCK_SEQPACKET) — IPC side-channel for fd-passing
+ *   - sendmsg/recvmsg + SCM_RIGHTS — cross-process fd transfer
+ *
+ * Same design as @gjsify/http2-native: opaque struct (full definition in .c),
+ * `gjsify_sab_<verb>` naming, `_free` paired with `_new`. Buffer ownership
+ * stays C-side; JS only sees the GObject wrapper from shared-buffer.vala
+ * and the GBytes objects returned by read_bytes (which borrow the mmap'd
+ * memory, so callers can do zero-copy reads via imports.byteArray.toArray).
+ *
+ * Reference: man 2 memfd_create, man 2 mmap, man 2 futex, man 3 cmsg.
+ */
+
+#ifndef GJSIFY_SAB_HELPERS_H
+#define GJSIFY_SAB_HELPERS_H
+
+#include <glib.h>
+#include <glib-object.h>
+
+G_BEGIN_DECLS
+
+/* ────────────────────────────────────────────────────────────────────── *
+ * Shared-memory region (opaque)
+ * ────────────────────────────────────────────────────────────────────── */
+
+typedef struct _GjsifySabRegion GjsifySabRegion;
+
+/**
+ * gjsify_sab_region_new_anonymous:
+ * @size: byte length of the region (multiple-of-page strongly preferred)
+ *
+ * Allocate a fresh memfd, ftruncate it to @size, and mmap it MAP_SHARED.
+ * Region owns the fd and will close+munmap it on free. Returns %NULL on
+ * any syscall failure (errno preserved).
+ */
+GjsifySabRegion *gjsify_sab_region_new_anonymous (gsize size);
+
+/**
+ * gjsify_sab_region_new_from_fd:
+ * @fd:   caller-owned fd referring to a shared-memory object (typically
+ *        received via SCM_RIGHTS from a parent process). Will be dup'd —
+ *        caller retains ownership of the original fd.
+ * @size: byte length of the region (must match the sender's view)
+ *
+ * mmap the fd MAP_SHARED into the calling process's address space.
+ * Returns %NULL on dup() or mmap() failure (errno preserved).
+ */
+GjsifySabRegion *gjsify_sab_region_new_from_fd  (gint fd, gsize size);
+
+void              gjsify_sab_region_free        (GjsifySabRegion *region);
+
+gint  gjsify_sab_region_get_fd   (const GjsifySabRegion *region);
+gsize gjsify_sab_region_get_size (const GjsifySabRegion *region);
+
+/* ────────────────────────────────────────────────────────────────────── *
+ * Plain read / write (no memory barriers — see _atomic_* below for SEQ_CST)
+ * ────────────────────────────────────────────────────────────────────── *
+ *
+ * All multi-byte accessors are little-endian on the wire. On x86_64 /
+ * aarch64 (the native arches) this is a no-op; on s390x / ppc64 the C
+ * shim swaps via __builtin_bswap*. Bounds-check `offset + sizeof(T) <=
+ * size`; on overflow we g_error() (programmer error, fail-fast).
+ */
+guint8  gjsify_sab_region_read_u8     (const GjsifySabRegion *region, gsize offset);
+void    gjsify_sab_region_write_u8    (GjsifySabRegion *region,       gsize offset, guint8  v);
+guint32 gjsify_sab_region_read_u32_le (const GjsifySabRegion *region, gsize offset);
+void    gjsify_sab_region_write_u32_le(GjsifySabRegion *region,       gsize offset, guint32 v);
+gint32  gjsify_sab_region_read_i32_le (const GjsifySabRegion *region, gsize offset);
+void    gjsify_sab_region_write_i32_le(GjsifySabRegion *region,       gsize offset, gint32  v);
+guint64 gjsify_sab_region_read_u64_le (const GjsifySabRegion *region, gsize offset);
+void    gjsify_sab_region_write_u64_le(GjsifySabRegion *region,       gsize offset, guint64 v);
+
+/* Bulk: return a fresh GBytes that borrows the mmap'd memory (no copy).
+ * Caller must release the GBytes BEFORE freeing the region — we wrap with
+ * g_bytes_new_with_free_func(ptr, length, region_ref, region_unref) so the
+ * region is reference-counted via a tiny refcount in the shim. */
+GBytes *gjsify_sab_region_read_bytes (GjsifySabRegion *region, gsize offset, gsize length);
+void    gjsify_sab_region_write_bytes(GjsifySabRegion *region, gsize offset, GBytes *data);
+
+/* ────────────────────────────────────────────────────────────────────── *
+ * Atomics — __atomic_* builtins, memory_order = SEQ_CST
+ * ────────────────────────────────────────────────────────────────────── *
+ *
+ * `cmpxchg32`: weak compare-and-swap. *expected is updated to the actual
+ * value on failure (standard C11 pattern). Returns TRUE on success.
+ */
+gint32   gjsify_sab_region_atomic_add_i32     (GjsifySabRegion *region, gsize offset, gint32 v);
+gint32   gjsify_sab_region_atomic_sub_i32     (GjsifySabRegion *region, gsize offset, gint32 v);
+gint32   gjsify_sab_region_atomic_load_i32    (const GjsifySabRegion *region, gsize offset);
+void     gjsify_sab_region_atomic_store_i32   (GjsifySabRegion *region, gsize offset, gint32 v);
+gint32   gjsify_sab_region_atomic_xchg_i32    (GjsifySabRegion *region, gsize offset, gint32 v);
+gboolean gjsify_sab_region_atomic_cmpxchg_i32 (GjsifySabRegion *region, gsize offset, gint32 *expected, gint32 desired);
+
+/* ────────────────────────────────────────────────────────────────────── *
+ * Futex wait / wake (Linux SYS_futex, FUTEX_*_PRIVATE flavour)
+ * ────────────────────────────────────────────────────────────────────── *
+ *
+ * `futex_wait`:
+ *   - Compares *(int32_t*)(ptr+offset) against `expected`.
+ *   - If equal: blocks until woken or timeout (`timeout_ms` < 0 = infinite).
+ *   - If not equal: returns immediately (no block).
+ * Returns:
+ *    0 = woken via FUTEX_WAKE
+ *   -1 = value did not match expected (EAGAIN) — no wait happened
+ *   -2 = timed out (ETIMEDOUT)
+ *   -3 = interrupted by signal (EINTR) — caller may retry
+ *   other negative = generic errno, sign-flipped
+ *
+ * `futex_wake`:
+ *   Wakes up to @count waiters on the address. Returns number actually woken.
+ */
+gint    gjsify_sab_region_futex_wait (GjsifySabRegion *region, gsize offset, gint32 expected, gint64 timeout_ms);
+gint    gjsify_sab_region_futex_wake (GjsifySabRegion *region, gsize offset, gint count);
+
+/* ────────────────────────────────────────────────────────────────────── *
+ * IPC side-channel: AF_UNIX/SOCK_SEQPACKET pair + SCM_RIGHTS fd transfer
+ * ────────────────────────────────────────────────────────────────────── *
+ *
+ * Used by @gjsify/worker_threads to attach the fd of a SharedBuffer to a
+ * postMessage() call. The parent calls _socketpair() at worker spawn,
+ * inherits the child end via Gio.SubprocessLauncher.take_fd(child_fd, 3),
+ * then send_fd() each SharedBuffer's fd over the parent end. Child runs a
+ * recv_fd() loop on its end to pick them up in lockstep with the JSON IPC.
+ *
+ * Tag is a 4-byte sequence number the sender encodes so the receiver can
+ * map the received fd back to the JSON placeholder {__sab: <tag>, size: N}.
+ */
+gboolean gjsify_sab_socketpair (gint *parent_fd, gint *child_fd);
+gboolean gjsify_sab_send_fd    (gint socket_fd, gint fd_to_send, guint32 tag);
+
+/* recv_fd: returns received fd, or -1 on error (errno preserved).
+ * Returns 0 on orderly EOF (peer closed socket). *tag receives the
+ * sender-encoded tag value. */
+gint     gjsify_sab_recv_fd    (gint socket_fd, guint32 *tag);
+
+/* close_fd: just `close(2)` wrapped so JS callers don't have to drag in
+ * GioUnix's typelib for a single syscall. Returns TRUE on success
+ * (or EBADF — already closed is harmless), FALSE on other errno. */
+gboolean gjsify_sab_close_fd   (gint fd);
+
+G_END_DECLS
+
+#endif /* GJSIFY_SAB_HELPERS_H */