镜像站点 · 本页由第三方 GitHub 只读镜像提供,非 GitHub 官方站点,不接受任何登录或凭据输入。前往 github.com
Skip to content

ABI: implement strong and weak embedding references #209

Closed

Description

@chrisbbreuer

Parent

Scope

Implement the eight shared pinned reference imports:

  • Bun__StrongRef__clear
  • Bun__StrongRef__delete
  • Bun__StrongRef__new
  • Bun__StrongRef__set
  • Bun__WeakRef__clear
  • Bun__WeakRef__delete
  • Bun__WeakRef__get
  • Bun__WeakRef__new

Acceptance criteria

  • Strong references retain the exact value across full and nursery collection, and set atomically replaces the rooted value without leaking the previous root.
  • Weak references never retain their target, clear after collection when no strong path remains, and return the exact live value beforehand.
  • Primitive, object, symbol, empty, and null/invalid inputs follow the pinned consumer boundary without manufacturing foreign-VM values.
  • Reference wrappers record and enforce owning VM/global lifetime; cross-VM replacement is rejected deterministically.
  • clear and delete are idempotent where the consumer contract permits it, are safe after target collection, and do not leave collector-visible stale pointers.
  • The pinned WeakRefType and optional context are preserved for future callback/lifecycle behavior rather than discarded accidentally.
  • Concurrent root tracing versus set/clear/get/delete is synchronized and covered without collector or wrapper use-after-free.
  • Focused precise-GC, lifecycle, invalid-input, and multi-VM tests pass; Home/Bun inventories, combined fixture, API docs, README evidence, and parent trackers are regenerated.

Activity

  1. chrisbbreuer commented on Jul 17, 2026

    @chrisbbreuer
    MemberAuthor

    Implemented and pushed to main:

    • zig-gc 7b1831e — atomic external weak slots with acquire/CAS clearing
    • zig-gc c67e344 — post-weak-root owner notification outside collector locks
    • zig-js 891829e4 — all eight strong/weak reference exports, precise-GC roots, lifetime ownership, finalization, and the expanded runtime fixture
    • zig-js 0e772b3a — regenerated Home/Bun inventories plus README/API/integration evidence

    Acceptance evidence:

    • PrivateStrongRef.encoded is pinned at offset zero for Bun inline reads; the paired internal value is traced across full collection. Sibling-realm set succeeds, foreign-VM replacement leaves the existing root unchanged, and clear is idempotent.
    • Handles retain their context group until delete, so wrapper storage, encoded cell handles, and root records cannot outlive their VM. Root-list mutations share the collector realm lock.
    • Weak refs accept only the two pinned owner kinds and ordinary objects, preserve owner type/context, never mark the target strongly, and use atomic acquire/swap/CAS operations for embedder/collector synchronization.
    • GC clearing invokes the FetchResponse owner callback exactly once outside zig-gc’s weak lock. Explicit clear/delete suppresses notification; PostgreSQL retains its pinned no-callback behavior.
    • Focused zig-gc atomic-weak and scratch-retention tests pass.
    • zig build test -Dtest-filter="private embedding references" -Doptimize=Debug: 3/3 pass with zero leaks, covering strong survival, weak death, one-shot callback, explicit-clear suppression, metadata, invalid values/types, and null calls.
    • zig build test-home-private-abi -Doptimize=Debug: Home 161/431 implemented, 270 pending; combined fixture 160/160.
    • python3 tools/bun-private-abi.py: Bun core 155/421 implemented, 266 pending. Public/extension accounting remains 117/19.

    README, API docs, Home integration guidance, and both checked-in inventories now report the same evidence.

  2. chrisbbreuer commented on Jul 17, 2026

    @chrisbbreuer
    MemberAuthor

    All eight pinned imports, precise-GC and owner-finalization behavior, expanded consumer fixture, regenerated inventories, and README/API evidence are on main. Closing as complete; remaining private imports continue under the updated parent profiles.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions