ReviewOS

zig-utils/zig-js

ABI: import ArrayBuffer values from shared memfd mappings

#256
Closed chris opened this 9 days ago ·
9 days ago

Parent: #140 Tracked by: #134, #163, #164

Implement the pinned private ArrayBuffer__fromSharedMemfd boundary as a directly testable ownership slice, separately from the opaque native JSC::ArrayBuffer handle API.

Acceptance

  • Match the pinned C ABI and selected Home/Bun JSType tags for ArrayBuffer and Uint8Array results.
  • Validate the file descriptor, total mapping size, and requested byte range without overflow or partial ownership.
  • Create a private read/write mapping of the complete declared region, expose the requested slice without copying, and never close or otherwise take ownership of the caller file descriptor.
  • Return an exact ordinary ArrayBuffer or Uint8Array; reject every other requested type and every invalid or unsupported mapping cleanly.
  • Unmap the complete original mapping exactly once on collection or context teardown, including construction-failure paths.
  • Prove slice identity and mutability, MAP_PRIVATE file isolation, non-zero offsets, invalid descriptors/ranges/types, GC, and teardown behavior with focused unit and compiled consumer tests.
  • Mark the export implemented in both pinned inventories, preserve zero unclassified entries, and update the README/private ABI evidence.

Non-goals

The opaque JSC__ArrayBuffer__ref, JSC__ArrayBuffer__deref, and JSC__ArrayBuffer__asBunArrayBuffer handle contract will be tracked as a separate child because it needs an explicit native handle producer and independent lifetime model.

9 days ago

Completed on main in two small commits:

  • e0164ae9 — runtime, focused ownership/GC tests, compiled consumer coverage, and both inventories
  • ae61fd67 — README and private-ABI documentation/evidence

Evidence:

  • focused unit matrix: shared-memfd slices, MAP_PRIVATE isolation, invalid fd/range/extent/type, manual exactly-once release, precise GC, arena teardown, and caller-fd survival
  • compiled Home consumer: 263/263 symbols linked; runtime matrix passed
  • Home audit: 264/431 private implemented, 167 pending, zero unclassified
  • Bun audit: 258/421 private implemented, 163 pending, zero unclassified
  • Bun-selected JSType compile/runtime fixture: green

The implementation duplicates the fd only to make validation/mapping race-safe, closes that duplicate immediately after mmap, never consumes the caller fd, and releases the complete mapping once. The README retains the latest 1,540-sample benchmark scores because this embedding-only boundary is not part of the benchmark workload.

Sign in to comment on this issue.