Memory and GC runtime contract

Platform spec feature

Memory and GC runtime contract

Back to Runtime ◎ Open in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (3)

1. 0005-phase-a-before-phase-b Ship Phase A GC before parallel mutators Accepted

   v0.2 targets single mutator; Phase B requires spec and barrier completion first.

   Context

   Parallel GC mutators need write barriers, stack-map coverage, and scheduler coordination. Shipping partial parallel GC risks data races on the Abfall heap.

   Decision

   Phase	Mutators	Ship order
   A (v0.2)	One Beskid mutator; many cooperative fibers	Default ship
   B (v0.3, opt-in)	Parallel mutators + real gc_write_barrier on pointer-payload channels + syscall-pool guard	Wired behind BESKID_RUNTIME_PHASE_B / set_runtime_phase(RuntimePhase::PhaseB); stays opt-in until preemption emission and concurrent-mark stress land
   B (later)	Phase B becomes the default	Requires AOT/JIT to insert runtime_preempt_check prologues and full concurrent-mark stress coverage

   Phase B must not become the default without updating this feature hub and fiber scheduler contracts.

   Consequences

   Phase A barriers stay correct because Phase B reuses the same Dijkstra insertion barrier; the difference is that Phase B exercises it on multi-mutator workloads and on pointer-payload channel ops. Fiber/feature docs cross-link Phase tables.

   Verification anchors

   GC integration tests under crates/beskid_runtime/tests/:

   • tests/concurrency.rs — channel/scheduler core
   • tests/gc.rs, tests/gc_concurrency.rs — Phase A heap and root handles
   • tests/phase_b_concurrency.rs — Phase B multi-mutator stress, pointer-payload channels with write barriers, syscall-pool guard, optional preemption hook

   Platform-spec Phase diagrams in hub and design model.

   Open full ADR page

2. 0006-abfall-tri-color-heap Abfall tri-color heap with write barriers Accepted

   Reference runtime uses vendored Abfall mark/sweep with barriered stores.

   Context

   The prior arena model needed a collector that supports concurrent marking and precise scanning with compiler-emitted descriptors.

   Decision

   Component	Role
   Abfall	Tri-color mark/sweep heap integrated in beskid_runtime::gc
   Barriers	gc_write_barrier on pointer stores during marking
   STW	Limited stop-the-world for root scan and phase transitions
   Snapshots	GcSnapshot / enter_runtime_scope for host tooling

   Git anchor: 6ecd493 (vendored Abfall + Beskid heap integration).

   Consequences

   Lowering must emit barriers where Phase requires them. Hosts attach runtime scope before JIT/AOT execution.

   Verification anchors

   compiler/crates/beskid_runtime/src/gc/; JIT runtime tests.

   Open full ADR page

3. 0007-heap-type-descriptors Heap objects carry type descriptors for scanning Accepted

   alloc attaches descriptors; roots include stacks, globals, and handles.

   Context

   Conservative stack scanning alone is insufficient for precise Beskid object graphs across fibers and codegen optimizations.

   Decision

   Rule	Detail
   Header	Heap objects begin with a type descriptor pointer for precise scan
   Allocation	alloc(size, type_desc) uses abfall::Heap::allocate_beskid
   Strings / arrays	BeskidStr, BeskidArray headers per builtins layout
   Roots	Stacks (stack maps), globals (registered roots), gc_root_handle externals
   Compiler	Lowers descriptors and stack maps; does not embed collector policy

   Consequences

   Descriptor schema changes are ABI-visible per D-EXEC-ABI-0002.

   Verification anchors

   beskid_codegen stack maps; beskid_runtime alloc/GC tests.

   Open full ADR page

Articles

• Contracts and edge cases MUST rules for allocation, barriers, roots, and Phase A mutator exclusivity. article Standard Reviewed Fri May 22
• Design model Heap ownership, tri-color GC, Phase A mutator rules, and compiler/runtime split. article Standard Reviewed Fri May 22
• Examples Allocation failures, GC pacing triggers, and external root pinning scenarios. article Standard Reviewed Fri May 22
• FAQ and troubleshooting GC pauses, mutator violations, barrier omissions, and heap growth debugging. article Standard Reviewed Fri May 22
• Flow and algorithm Allocation, barrier insertion, collection pacing, and safepoint algorithms. article Standard Reviewed Fri May 22
• Verification and traceability Runtime GC tests, Abfall integration, and compiler stack-map obligations. article Standard Reviewed Fri May 22

History

0 revisions (git unavailable at build; counts may be empty)

Open full history on GitHub

No commits recorded for this path.

Completeness

OKfeature · 3 SpecSection(s) · 1 H2 heading(s)

Section id	Required	Found
what-this-feature-specifies	yes	yes
implementation-anchors	yes	yes

Full tree: run pnpm verify:platform-spec-layout (writes src/generated/platform-spec-layout-report.json).

Related spec docs

• Area
  Runtime

  Parent area

• Area
  Memory model

  Language-level ownership expectations map to runtime behavior

• Area
  Codegen and IR

  Lowering decisions depend on runtime allocation semantics

What this feature specifies

Memory and GC runtime contract defines one operational contract that a newcomer can follow end-to-end: first the model, then execution flow, then strict guarantees, concrete examples, and verification guidance.

GC phases

stateDiagram-v2
  direction LR
  [*] --> PhaseA: default ship
  PhaseA --> PhaseB: parallel mutators
  state PhaseA {
    [*] --> SingleMutator
    SingleMutator --> ManyFibers: cooperative scheduler
  }
  state PhaseB {
    [*] --> ParallelMutators
    ParallelMutators --> WriteBarriers: gc_write_barrier on stores
  }

Phase A: many fibers, one GC mutator thread. Phase B: parallel mutators with insertion barriers; see design model for builtin tables.

Implementation anchors

• Runtime memory exports in compiler/crates/beskid_runtime/src/lib.rs
• ABI contracts in compiler/crates/beskid_abi/src/lib.rs
• JIT linking and call setup in compiler/crates/beskid_engine/src/jit_module.rs
• Runtime integration tests in compiler/crates/beskid_tests/src/runtime/jit.rs

Decisions

No open decisions. Closed choices are normative ADRs under adr/ (D-EXEC-RT-0005 … D-EXEC-RT-0007); use the reader ADRs tab for expandable detail.

Articles

• Ship Phase A GC before parallel mutatorsv0.2 targets single mutator; Phase B requires spec and barrier completion first.
• Contracts and edge casesMUST rules for allocation, barriers, roots, and Phase A mutator exclusivity.
• Design modelHeap ownership, tri-color GC, Phase A mutator rules, and compiler/runtime split.
• ExamplesAllocation failures, GC pacing triggers, and external root pinning scenarios.
• FAQ and troubleshootingGC pauses, mutator violations, barrier omissions, and heap growth debugging.
• Flow and algorithmAllocation, barrier insertion, collection pacing, and safepoint algorithms.
• Verification and traceabilityRuntime GC tests, Abfall integration, and compiler stack-map obligations.