Design model

Platform spec article

Design model

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

• Feature
  Fiber scheduler and stacks

  Phase A single mutator

Purpose

Normative model for how Beskid heap objects live, how the Abfall tri-color collector interacts with generated code, and how Phase A scheduling constrains mutators before parallel GC (Phase B).

Primary actors

Actor	Responsibility
Compiler lowering	Emits alloc, write barriers, stack maps, type descriptors
beskid_runtime::gc	enter_runtime_scope, heap attachment, GcSnapshot for hosts
Abfall heap	Concurrent mark/sweep with STW segments
Fiber scheduler	Ensures only one mutator runs Beskid allocations in Phase A

Object model

• Heap objects begin with a type descriptor pointer used for precise scanning.
• alloc(size, type_desc) creates descriptor-backed payloads via abfall::Heap::allocate_beskid.
• Strings use BeskidStr; arrays use BeskidArray headers (backing optional per feature flag).
• Roots: stacks (stack maps), globals (registered roots), external handles (gc_root_handle).

GC architecture

flowchart TB
  mut[Mutator / generated code]
  barrier[gc_write_barrier]
  heap[Abfall tri-color heap]
  stw[STW root scan]
  mut -->|pointer stores| barrier --> heap
  heap -->|mark/sweep| stw
  stw --> heap

Tri-color marking runs concurrently with the mutator where Phase allows; write barriers prevent black→white edges during marking. STW episodes are limited to root scanning and phase transitions.

Phase A vs Phase B

Phase	Mutators	Notes
A (current)	One Beskid mutator at a time	Fibers swap on scheduler threads; syscall pool workers must not allocate as mutators
B (target)	Parallel mutators with barriers	Requires full stack-map coverage and scheduler coordination

See Fiber scheduler and stacks for parking and safepoints.

Related topics

• Flow and algorithm
• Legacy: Concurrent GC