ReviewOS

zig-utils/zig-js

ABI: implement FFI host functions with native data

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

Goal

Implement the four pinned Home/Bun FFI host-function exports as the next layer over #248 and #251: Bun__CreateFFIFunctionValue, Bun__CreateFFIFunctionWithDataValue, Bun__FFIFunction_getDataPtr, and Bun__FFIFunction_setDataPtr.

Parent tracking: #134, #140, #163, #164.

Required implementation

  • Reuse the exact JSC64 CallFrame callback path while preserving FFI symbol names, arity, callable metadata, and optional raw function-pointer field semantics.
  • Store nullable native data independently from engine-private callback metadata and expose exact get/set behavior only for validated FFI functions.
  • Preserve same-VM sibling calls, upstream constructor callbacks, nested/reentrant calls, pending exceptions, and precise-GC liveness; accept any valid FFI cell in data get/set while rejecting ordinary functions and immediates.
  • Define explicit behavior for null callbacks, null names/data, repeated mutation, dynamic-library metadata, and invalid/ordinary values.
  • Promote both inventories and update README/API/Home/ABI evidence.

Evidence gate

  • Compiled consumer invokes all four exports and validates exact CallFrame arguments plus native data through mutation, GC, sibling realms, and error paths.
  • Home/Bun inventories retain zero unclassified declarations.
  • Targeted host-function/FFI runtime matrix passes; broad testing remains batched.
  • Current benchmark remains linked unless measured workload code changes.
9 days ago

Implemented and published directly to main:

  • c3a5c155 — four exports, distinct FFI runtime brand, atomic data, exact ptr property, refreshed inventories, and compiled runtime matrix
  • 584377ea — README/API/Home/ABI evidence and current counts

Final evidence:

  • Home: 259/431 implemented, 172 pending, zero unclassified.
  • Bun core: 253/421 implemented, 168 pending, zero unclassified.
  • Compiled consumer: 258/258 linked; runtime matrix passed.
  • Names and arity are owned; ordinary calls and constructors use the exact JSC64 CallFrame callback path.
  • dataPtr is nullable and atomically mutable. The dynamic-library token is stored independently. ptr preserves the callback-address bits and exact upstream property attributes.
  • Coverage includes mutation/nulling, precise GC, sibling realms, valid FFI cells from another VM, ordinary/immediate rejection, nested reentry, construction, null callback/name/data, pending exceptions, and name ownership.
  • Broad testing remains batched. The benchmark report remains current because no benchmark workload executes these private exports.

Sign in to comment on this issue.