Flow and algorithm

Platform spec article

Flow and algorithm

Back to Memory and GC runtime contract ◎ Open feature 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

• Feature
  Memory and GC runtime contract

  Parent feature hub

Purpose

Algorithms for allocation, collection, and barrier execution. Architecture diagram: design model.

Allocation path

1. Lowering emits alloc(size, type_descriptor_ptr) at object creation sites.
2. Runtime enters current heap scope (enter_runtime_scope / TLS hooks).
3. alloc delegates to Abfall allocate_beskid with descriptor metadata for scanning.
4. On failure, runtime traps (panic) — no silent null returns for required objects.

Write barrier path

1. After each pointer store in generated code, lowering emits gc_write_barrier(parent, child).
2. Barrier grays or marks child so concurrent marking retains reachability.
3. Phase A may elide heavy barrier work when collector is idle, but the call site remains for ABI stability.

Collection pacing

1. Mutator allocation increases gc_bytes_allocated.
2. gc_collect_if_needed compares growth against pacing policy (heap vs CPU tradeoff).
3. When triggered, phases transition: idle → mark (STW root scan, concurrent mark) → mark termination STW → sweep.
4. gc_phase export reports 0=Idle, 1=Marking, 2=Sweeping for tests and tooling.

Safepoints

1. Implicit safepoints at calls and loop backedges (compiler-inserted).
2. Stack maps at safepoints let STW scan precise roots.
3. Fiber stack switching must register alternate stacks for enumeration (fiber scheduler).

Host inspection

Rust hosts call beskid_runtime::runtime::GcSnapshot instead of parsing raw gc_* exports when displaying heap stats or forcing collect.

Related topics

• Contracts and edge cases
• Write barriers (legacy)