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

Runtime: define heap cap and per-thread OOM contract #24

Closed

Description

@chrisbbreuer

Child tracker from #11/#16/#1.

Goal

Define and maintain the public heap-cap and per-thread OOM contract for zig-js contexts, including how allocation pressure is surfaced to hosts and to shared-realm Thread joiners.

Current status

The original PR-249 blocker semantics/oom-one-thread.js is now promoted. GC-backed capped contexts can collect and retry at safe GC cell allocation failures and ArrayBuffer byte allocation failures, and the reference recovery witness passes.

Implemented contract:

  • Context.Options.heap_limit_bytes applies a thread-safe outstanding-byte budget to Context-owned allocator traffic.
  • Context.heapBudgetStats() reports limit, used, peak, and remaining bytes for capped contexts.
  • Top-level host evaluation reports unrecovered cap pressure as Zig error.OutOfMemory.
  • A capped context prebuilds an immutable OutOfMemoryError object so shared-realm Thread completion can publish a deterministic JS error value even when ordinary heap allocation is exhausted.
  • join() rethrows that reserved object, and already-created asyncJoin() reactions reject with it when they can be delivered.
  • Allocation-site OOM can become catchable by active JS handlers in the covered interpreter/tree-walker paths, including catch-binding pressure that has pre-reserved environment storage.
  • Arena-backed caps remain fail-closed and non-reclaimable unless callers opt into GC-backed recovery.
  • GC-backed capped contexts can recover after unreachable pressure is collected at safe allocation-recovery points.

Remaining linked work

  • Runtime: extend heap-cap emergency recovery beyond current safe allocation classes #30 tracks the remaining emergency-recovery perfection work: no-GIL root-publication recovery, side-store pressure, and avoiding lock-order deadlocks during collect/retry.
  • Keep documenting any new capped allocation classes as either fail-closed, catchable, or recoverable.
  • Keep the PR-249 audit/probe evidence current if a future behavior change affects heap-cap cases.

Acceptance criteria

  • Heap-cap behavior is documented for arena-backed and GC-backed contexts.
  • Allocation failure remains observable as ordinary JS/host errors without corrupting GC state.
  • One capped shared-realm Thread can hit OOM while siblings and cleanup/finalization remain well-defined.
  • Promoted reference coverage and focused unit tests prove the intended supported contract.
  • Remaining uncovered allocation classes are tracked by narrower follow-up issues rather than hidden behind this parent tracker.

Activity

  1. chrisbbreuer commented on Jul 11, 2026

    @chrisbbreuer
    MemberAuthor

    Landed first resource-control primitive in a510e76 (feat(context): add heap allocation limit).

    What changed:

    • Added Context.Options.heap_limit_bytes plus matching Context.TestingOptions.heap_limit_bytes.
    • Added a small atomic BudgetAllocator wrapper that enforces a per-Context outstanding-byte cap and fails closed with error.OutOfMemory.
    • Routed Context-owned allocations through the capped allocator: arena chunks, GC lifecycle state/cell backing, SAB retain tables, thread/GIL/park state, and other Context.gpa users.
    • Tightened partial-create cleanup so quota failures during global installation release the partially-created Context allocation before arena/budget unwind.
    • Documented the boundary in architecture/testing/limits docs and called out that this is an allocator cap, not yet the full per-thread OOM survivor contract.

    Focused validation run locally:

    • zig build test -Dtest-filter='BudgetAllocator enforces outstanding byte limit' --summary none
    • zig build test -Dtest-filter='Context heap_limit_bytes fails closed on allocation pressure' --summary none
    • zig build test -Dtest-filter='Context public Options expose only stable thread controls' --summary none
    • bun run docs:build
    • git diff --check

    Remaining for this issue:

    • Define the deterministic observable per-thread OOM survivor semantics.
    • Promote/adjust the PR-249 OOM witness once the JS-facing contract is exact.
    • Decide whether we want additional public diagnostics for current/peak budget usage, or keep the first version intentionally minimal.
  2. chrisbbreuer commented on Jul 11, 2026

    @chrisbbreuer
    MemberAuthor

    Landed another small #24 slice in 5df46a7 (feat(context): expose heap budget stats).

    What changed:

    • Added Context.heapBudgetStats() for capped contexts, returning limit_bytes, current used_bytes, lifetime successful-allocation peak_bytes, and remaining_bytes.
    • Uncapped contexts return null, keeping the diagnostic tied to the explicit fail-closed allocator boundary.
    • Tightened BudgetAllocator tests so peak accounting stays monotonic and only reflects successful outstanding allocation growth.
    • Documented the diagnostic in the thread limits/testing docs.

    Validation run locally:

    • zig build test -Dtest-filter='BudgetAllocator enforces outstanding byte limit' --summary none
    • zig build test -Dtest-filter='Context heap' --summary none
    • bun run docs:build
    • git diff --check

    Remaining #24 work is still the harder semantics piece: define deterministic per-thread OOM survivor behavior under pressure and then promote the matching WebKit PR-249 witness once that observable contract is nailed down.

  3. chrisbbreuer commented on Jul 11, 2026

    @chrisbbreuer
    MemberAuthor

    Landed the first deterministic per-thread OOM survivor contract slice in ecce653 (fix(threads): publish heap-limit oom sentinel).

    What changed:

    • Added allocation-free Value.staticStr(comptime) for sentinel values that must remain constructible under heap pressure.
    • Spawned shared-realm Threads now publish a static "OutOfMemoryError" completion value when thread startup or body execution hits native error.OutOfMemory, instead of allowing join() to rethrow an ambiguous undefined.
    • Added a focused capped-context witness: one Thread exhausts Context.Options.heap_limit_bytes, join() catches the sentinel, and an already-running sibling Thread still joins successfully afterward.
    • Documented the split contract: top-level host Context.evaluate() reports Zig error.OutOfMemory; spawned Thread completion publishes the allocation-free sentinel for JS-visible joining.

    Validation run locally:

    • zig fmt src/value.zig src/jsthread.zig src/context.zig
    • zig build test -Dtest-filter='Context heap_limit_bytes lets sibling Threads survive one Thread OOM' --summary none
    • zig build test -Dtest-filter='Context heap' --summary none
    • bun run docs:build
    • git diff --check

    Remaining #24 work: stress this survivor contract under more interleavings and then promote or reclassify the PR-249 OOM reference case based on the audited observable behavior.

  4. chrisbbreuer commented on Jul 11, 2026

    @chrisbbreuer
    MemberAuthor

    Opened follow-up #26 for the final polish beyond the current robust sentinel contract: use an emergency reserve/prebuilt value so heap-limit Thread OOM can throw a real OutOfMemoryError object instead of the current allocation-free string sentinel, without depending on ordinary heap headroom.

  5. chrisbbreuer commented on Jul 11, 2026

    @chrisbbreuer
    MemberAuthor

    Follow-up #26 landed in 78c5a4f: the #24 OOM survivor contract now uses a reserved immutable OutOfMemoryError object instead of the temporary primitive sentinel.

    That means the documented spawned-Thread path is now:

    • top-level host Context.evaluate() still reports allocator pressure as Zig error.OutOfMemory;
    • a capped shared-realm Thread that exhausts the context budget publishes a prebuilt OutOfMemoryError object;
    • join() rethrows that object without allocating on the failed path;
    • sibling Threads remain joinable after the exhausted peer.

    Focused validation is listed on #26.

  6. chrisbbreuer commented on Jul 11, 2026

    @chrisbbreuer
    MemberAuthor

    Landed another small #24 slice in f3cb0cc: f3cb0cc

    What changed:

    • The PR-249 semantics/oom-one-thread.js reference probe now maps the inert vendored JSC RAM-cap directive to zig-js's real Context.Options.heap_limit_bytes cap (192MiB).
    • tools/threads-reference-audit.py now classifies that probe under allocation-site catchable OOM semantics and expects the current blocker evidence.
    • Thread docs now distinguish the already-landed reserved thread OOM completion contract from the remaining allocation-site catchability work.

    Validation:

    • zig fmt conformance/threads_test.zig
    • PATH="/Users/chris/.local/bin:$PATH" python3 tools/threads-reference-audit.py --fail-on-uncategorized --run-probes --expect-current-blockers --skip-timeout-probes --probe-timeout 20
    • /Users/chris/.bun/bin/bun run docs:build
    • git diff --check

    Current evidence is now sharper: the probe fails with OutOfMemoryError: Context heap limit exceeded, so the cap is firing. The remaining runtime gap is that JS allocation pressure escapes as whole-Thread completion instead of being catchable by the allocating frame's local try/catch.

    Opened follow-up #27 for that allocation-site catchability work.

  7. chrisbbreuer commented on Jul 11, 2026

    @chrisbbreuer
    MemberAuthor

    Follow-up landed in 75a7e49: 75a7e49

    This improves the heap-cap contract from #24/#27: capped allocation failures can now become catchable JS OutOfMemoryError throws when an active JS handler exists, using the prebuilt OOM object instead of trying to allocate a fresh error while the heap is full.

    Validation:

    Also opened #28 for the separate string-cell OOM panic found during this work.

  8. chrisbbreuer commented on Jul 11, 2026

    @chrisbbreuer
    MemberAuthor

    #27 follow-up from 4a83575: 4a83575

    The simple allocation-site catch-binding blocker improved: capped catch (e) now pre-reserves its catch environment/binding and has a focused green regression.

    The PR-249 semantics/oom-one-thread.js witness still fails with a whole-thread OutOfMemoryError. The remaining shape appears to belong here in the heap-cap contract: the witness expects recovery after dropping JS references, but the current arena-backed heap_limit_bytes budget is outstanding-byte based and does not reclaim individual arena allocations when the hog clears its hoard. We need to decide/implement the intended contract for capped threaded contexts: arena fail-closed only, GC-backed reclaimable caps for PR-249-style recovery, emergency headroom, or a hybrid.

  9. chrisbbreuer commented on Jul 11, 2026

    @chrisbbreuer
    MemberAuthor

    Opened #29 to track the concrete heap-cap recovery policy now blocking PR-249 semantics/oom-one-thread.js after the #27 catch-binding improvement.

    The decision needed here is the contract split: arena-backed caps are fail-closed and non-reclaimable, while GC-backed capped contexts need safe collect/retry or emergency-headroom behavior if we want PR-249-style post-OOM recovery.

  10. chrisbbreuer commented on Jul 11, 2026

    @chrisbbreuer
    MemberAuthor

    Heap-cap contract update: zig-gc b99de49 plus zig-js 78b553a promote semantics/oom-one-thread.js. GC-backed capped contexts now have a GIL-safe GC cell allocation failure collect/retry path, and the PR-249 recovery witness passes.

    The remaining cap-policy surface is narrower now: #30 tracks no-GIL emergency recovery and side-store/ArrayBuffer-byte retry policy. Arena-backed caps remain fail-closed unless callers opt into GC-backed recovery.

  11. chrisbbreuer commented on Jul 11, 2026

    @chrisbbreuer
    MemberAuthor

    Heap-cap contract docs caught up in 34134b7.

    Current status for #24:

    I am leaving #24 open while #30 tracks the remaining perfection work: no-GIL emergency recovery and lock-aware side-store pressure. Arena-backed caps are intentionally documented as fail-closed.

  12. chrisbbreuer commented on Jul 11, 2026

    @chrisbbreuer
    MemberAuthor

    CI follow-up: e179650 tightens the heap-cap recovery contract after TSan caught parked-stack conservative scanning during allocation-failure recovery. The practical contract is now clearer: GIL/single-thread recovery may collect and retry when it can scan only safe roots; live no-GIL peers fail closed until #30 grows an abort-safe recovery collector. Focused TSan checks for semantics/oom-one-thread.js and the sibling-thread OOM unit witness pass locally.

  13. chrisbbreuer commented on Jul 11, 2026

    @chrisbbreuer
    MemberAuthor

    Completed. The heap-cap and per-thread OOM contract is now covered by promoted/reference evidence plus focused unit coverage, including the bounded sibling-Thread OOM witness.

    Fresh full CI is green for b2e7dbe5e9bc2a27a87ff1bad8be8b0be777e46e: https://github.com/zig-utils/zig-js/actions/runs/29170980761

    Remaining narrower heap-cap perfection work stays open in #30.

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

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions