Fiber scheduler and stacks - Verification and traceability

Platform spec article

Fiber scheduler and stacks - Verification and traceability

Back to Fiber scheduler and stacks ◎ Open feature in platform map

Missing owner or submitter in frontmatter for this article.

Current document

ADRs (4)

1. 0001-mn-cooperative-scheduler M:N cooperative fiber scheduler Accepted

   Many fibers multiplex on an OS worker pool without async/await lowering.

   Context

   Beskid rejects Rust-style async/await state machines at the language level (D-INC-0008). The runtime must provide cooperative concurrency primitives consumed by corelib_concurrency.

   Decision

   Rule	Detail
   Model	M:N — many fibers on a pool of OS worker threads
   API surface	fiber_* builtins back Fiber<T>; no async lowering in compiler
   Preemption	User fibers are cooperative; preemptive parallelism uses System.Threading (OS threads)
   Work stealing	Per-worker run queues; work-stealing permitted
   Parking	Fibers park on channel ops, join, cancel, and blocking syscalls

   Consequences

   Scheduler modules live under beskid_runtime/src/scheduler/. Deprecated rt_yield (sched feature) is superseded by fiber_yield.

   Verification anchors

   compiler/crates/beskid_runtime/tests/concurrency.rs; corelib concurrency tests; git: 12ee673, 76a58f5.

   Open full ADR page

2. 0002-fiber-stack-sizes Fiber stack initial size and cap Accepted

   Growable stacks with documented overflow behavior at Join.

   Context

   Fiber stacks must balance memory use against deep call chains from generated code and corelib. GC needs precise stack maps at safepoints on every fiber stack.

   Decision

   Parameter	Value
   Initial size	64 KiB per fiber
   Growth	Growable until cap
   Maximum	8 MiB cap per fiber
   Overflow	FiberError::StackOverflow at Join — no undefined behavior
   Switching	Callee stacks ABI-aligned; callee-saved registers saved per platform ABI
   GC	All fiber stacks enumerable at safepoints via compiler stack maps

   Consequences

   Documentation and corelib must cite these limits. Stack switching may use manual swap techniques documented in design model.

   Verification anchors

   Scheduler stack allocator; fiber spawn/join integration tests.

   Open full ADR page

3. 0003-phase-a-single-mutator Phase A single GC mutator on scheduler threads Accepted

   Only one thread holds Beskid mutator role for allocation at a time.

   Context

   Fibers may run on multiple OS threads while Phase A GC still uses one process-wide arena (enter_runtime_scope). Syscall pool workers must not become second mutators.

   Decision

   Rule	Detail
   Phase A (default)	One thread at a time may execute Beskid allocations as GC mutator
   Scheduler	Transfers mutator execution between fibers on that contract
   Syscall pool	Workers run blocking host work without arbitrary Beskid mutator code or generated allocation; runtime tags them and traps stray allocations (assert_mutator_allowed)
   Phase B (opt-in, v0.3)	Multiple Beskid mutators may share one heap by holding a MutatorAttachGuard from attach_phase_b_mutator; pointer-payload channel ops apply gc_write_barrier on send and receive
   Future	Phase B becomes the default once preemption code emission and full concurrent-mark stress coverage land

   Aligns with D-CORE-CONC-0007.

   Consequences

   run_blocking paths park fibers and resume on scheduler threads for mutator work.

   Verification anchors

   beskid_runtime scheduler + enter_runtime_scope; concurrency runtime tests (tests/concurrency.rs, tests/gc_concurrency.rs); Phase B opt-in coverage in tests/phase_b_concurrency.rs exercises multi-mutator allocation, pointer-payload channel write barriers, and the syscall-pool allocation guard.

   Open full ADR page

4. 0004-main-fiber-shutdown-join Main fiber shutdown joins spawned children Accepted

   main returns after joining non-Detached fibers; Detach panics still abort.

   Context

   Process exit must not leak running fibers that share the GC heap. Fire-and-forget tasks still need defined failure behavior.

   Decision

   Rule	Detail
   Main fiber	main() runs on fiber 0; scheduler starts before entry
   Normal exit	When main returns, runtime Joins every spawned fiber that was not Detached
   Detach	Detach fibers are not joined at shutdown
   Detach panic	Unjoined Detach child panic still aborts the process
   Pool shutdown	After joins complete, worker thread pool stops

   Matches D-CORE-CONC-0004.

   Consequences

   Hosts and tests must account for shutdown latency from outstanding joins.

   Verification anchors

   Runtime main harness; corelib concurrency shutdown tests.

   Open full ADR page

Articles

• Fiber scheduler and stacks - Design model Scheduler loops, parking, and stack switching implementation expectations. article Standard Reviewed Wed May 20
• Fiber scheduler and stacks - Verification and traceability Tests and ABI anchors for fiber scheduler work. article Standard Reviewed Wed May 20

History

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

Open full history on GitHub

No commits recorded for this path.

Completeness

OKfeature · 9 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
  Fiber scheduler and stacks

  Parent feature hub

v0.2 minimum conformance (Q30)

• spawn + Join returns Result with child value
• Bounded Channel Send/Receive rendezvous
• Yield schedules another runnable fiber
• Blocking syscall path parks fiber (thread pool smoke test)
• Cancel surfaces on Join and blocked Receive
• Phase A: stress test under single mutator with N fibers
• Hub round-robin: two channels, hot/cold traffic — cold channel receives within bounded turns
• Cancel: OnCancelled runs before Join returns Cancelled
• Default Channel is unbounded (no capacity until Bounded set)
• JoinWouldDeadlock diagnostic for child joining parent
• Hub<T> rejects mixed element types at compile time
• Mutex.TryLock returns None under contention without parking
• Unhandled panic in OnCancelled aborts process (conformance policy)

Anchors

• compiler/crates/beskid_abi/src/symbols.rs
• compiler/crates/beskid_analysis/src/builtins.rs
• compiler/crates/beskid_runtime/ scheduler module
• Deprecate compiler/crates/beskid_runtime/src/builtins/sched.rs after fiber_yield ships