Concurrency package - Design model

Platform spec article

Concurrency package - Design model

Back to Concurrency package ◎ Open feature in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (14)

1. 0001-channel-default-unbounded Channel default capacity is unbounded Accepted

   Factory defaults and explicit bounded/unbounded options for Channel construction.

   Context

   Authors need predictable queue semantics without implicit blocking on the default channel.

   Decision

   Rule	Detail
   Default	Unbounded when ChannelOptions is omitted or no bounded capacity is set
   Bounded	ChannelOptions.Bounded(n) with n > 0
   Unbounded	ChannelOptions.Unbounded (equivalent to default)
   Factory	Channel<T>.Create(options: ChannelOptions = default)

   Consequences

   Documentation must warn about memory growth on unbounded channels. Bounded queues park senders when full.

   Verification anchors

   Corelib concurrency tests; runtime channel builtins.

   Open full ADR page

2. 0002-fiber-cancellation Fiber cancellation via Cancel and OnCancelled Accepted

   Cancellation signalling, event ordering, and join/channel error paths.

   Context

   Fibers need cooperative cancellation without panics on join or parked channel ops.

   Decision

   Rule	Detail
   Signal	Fiber.Cancel() sets runtime cancellation flag
   Event	Each Fiber<T> declares event OnCancelled(); runtime raises on child before unblocking parked ops
   Join	Join → Result<T, FiberError::Cancelled> after cancellation observed
   Channels	Parked Send / Receive → ChannelError::Cancelled
   Ordering	OnCancelled runs before Join / channel errors; handlers must not block on Join of self

   Consequences

   Unhandled panic in OnCancelled aborts process in v1 (same as other unhandled event paths).

   Verification anchors

   Corelib + runtime concurrency tests; cancel/join fixtures.

   Open full ADR page

3. 0003-hub-round-robin-fairness Hub WaitReceive uses round-robin fairness Accepted

   Fair multiplexing across registered channels when multiple receives are ready.

   Context

   FIFO registration order starves late channels when an early channel is always ready.

   Decision

   Rule	Detail
   Algorithm	Round-robin among channels with a ready Receive
   Cursor	Per-Hub index advanced after each successful WaitReceive
   v1 scope	WaitReceive only — no WaitSend

   Consequences

   Console hubs should keep registration count small (under 16 typical).

   Verification anchors

   Hub integration tests in runtime and corelib suites.

   Open full ADR page

4. 0004-main-fiber-shutdown Main fiber and process shutdown Accepted

   main() fiber id, join/detach policy, and process teardown.

   Context

   Process lifetime must be defined when main returns while child fibers still run.

   Decision

   Rule	Detail
   Main	main() runs on fiber 0
   Shutdown	When main returns, runtime Joins spawned fibers that were not Detached
   Detach	Detach waives parent Join; child panic still aborts process
   Leak	Spawn without Join or Detach before main ends → conformance warning in v0.2 tests

   Consequences

   Future recovery policies require a new ADR; v1 aborts on undetached child panic.

   Verification anchors

   Runtime shutdown tests; conformance warnings catalog.

   Open full ADR page

5. 0005-result-not-panic-errors Channel and fiber errors use Result not panic Accepted

   Error surfaces for channel, fiber join, and mutex operations.

   Context

   Panics as control flow for expected failure modes break contracts and LSP stability.

   Decision

   Surface	Rule
   Channel	Send / Receive → Result; TrySend / TryReceive → Option
   Fiber	Join → Result<T, FiberError>; stack overflow → FiberError::StackOverflow at Join
   Mutex	Lock → Result<MutexGuard, MutexError>; TryLock → Option (None = would block)

   Consequences

   v1: Lock may return Cancelled when fiber cancelled—no .NET-style poison.

   Verification anchors

   Corelib API signatures; runtime integration tests.

   Open full ADR page

6. 0006-spawn-keyword-reserved-async spawn keyword; async and await reserved Accepted

   Keyword policy for fiber introduction vs deferred async syntax.

   Context

   Aligns with inception ADR D-INC-0008; avoids dual concurrency models in v1.

   Decision

   Rule	Detail
   Keyword	spawn required for new fibers; no go alias in v1
   Reserved	async and await are parse errors (reserved, not implemented)
   Data transfer	Channel only between fibers for data; Mutex / WaitGroup for coordination
   Handles	Fiber<T> and Channel<T> are move-only

   Consequences

   Parser and semantic tests reject async/await; spawn lowering returns Fiber<T>.

   Verification anchors

   Parser fixtures; Fibers and spawn.

   Open full ADR page

7. 0007-gc-phase-a-single-mutator GC phase A single mutator Accepted

   Ship many fibers with one GC mutator; document phase B parallel mutators.

   Context

   Parallel GC mutators require write barriers not ready for initial ship.

   Decision

   Phase	Rule
   A (ship)	Many fibers, one GC mutator; gc_write_barrier no-op
   B (documented)	Parallel mutators + real barriers; no corelib API break

   Consequences

   Scheduler and memory specs must stay consistent with phase A barriers.

   Verification anchors

   Runtime GC tests; memory-and-gc-runtime-contract feature.

   Open full ADR page

8. 0008-scheduler-defaults Scheduler and stack defaults Accepted

   Processor count, stack sizes, and phase A arena policy.

   Context

   Hosts need predictable defaults without per-program scheduler tuning.

   Decision

   Setting	Default
   ProcessorCount	Host logical CPU count at init
   Stacks	64 KiB initial, 8 MiB max
   Arena	Phase A: one process arena; pool threads run Beskid mutator code under scheduler rules

   Consequences

   Fiber scheduler design model article details syscall parking.

   Verification anchors

   Fiber scheduler and stacks.

   Open full ADR page

9. 0009-channel-runtime-semantics Channel runtime delivery semantics Accepted

   Multi-receiver/sender rules and close behavior.

   Context

   Authors need defined fan-in/fan-out and close idempotence.

   Decision

   Rule	Detail
   Receivers	Multiple allowed; each message delivered to exactly one successful Receive (FIFO)
   Senders	Multiple allowed unless SingleWriter hint (hint only v1)
   Close	Any handle holder may Close; idempotent writer shutdown
   void spawn	Fiber<Unit> when entry returns no value

   Consequences

   Close after drain returns ChannelError::Closed in Result.

   Verification anchors

   Runtime concurrency.rs; corelib channel tests.

   Open full ADR page

10. 0010-hub-homogeneous-v1 Homogeneous Hub in v1 Accepted

    Hub type parameter, limits, and heterogeneous deferral.

    Context

    Heterogeneous select requires tagged unions or multiple hubs in v1.

    Decision

    Rule	Detail
    Fairness	Round-robin (see D-CORE-CONC-0003)
    Max registrations	256 per hub (HubError::Limit possible)
    Element type	Homogeneous — one Hub<T> wraps only Channel<T> with same T
    Heterogeneous	Not v1 — use multiple hubs or Channel<HubMessage>
    Result	HubReceiveResult { index: i64, value: T }

    Consequences

    UI/console hubs should stay well below 256 registrations.

    Verification anchors

    Hub builtin tests; examples article.

    Open full ADR page

11. 0011-fiber-handle-oncancelled OnCancelled on Fiber handle only Accepted

    Spawn entry types vs fiber handle contract surface.

    Context

    Authors should not declare cancellation events on arbitrary spawn closures.

    Decision

    Rule	Detail
    Placement	OnCancelled on Fiber<T> handle from spawn only
    Spawn entry	Ordinary fn(...) -> T; does not declare OnCancelled
    Handle	Fiber<T> struct wrapping runtime builtins

    Consequences

    Lowering wires cancel slot from handle metadata.

    Verification anchors

    Semantic + lowering tests for spawn.

    Open full ADR page

12. 0012-mutex-trylock-v1 Mutex TryLock and Lock cancellation Accepted

    Mutex API for v1 coordination.

    Context

    TryLock supports non-blocking attempts; Lock parks with cancel path.

    Decision

    Rule	Detail
    TryLock	In v1 — returns Option<MutexGuard>
    Lock	Parks until acquired or Cancelled

    Consequences

    No poison semantics in v1.

    Verification anchors

    Mutex corelib tests.

    Open full ADR page

13. 0013-monotonic-clock Concurrency.NowMillis monotonic clock Accepted

    Monotonic time API owned by concurrency package in v0.2.

    Context

    Legacy rt_now_millis and scattered clock builtins confuse package boundaries.

    Decision

    Concurrency.NowMillis() -> i64 in concurrency package replaces legacy rt_now_millis. Wall clock deferred to future System.Time.

    Consequences

    Wall-clock ADR required before exposing civil time in corelib.

    Verification anchors

    Builtin spec table; corelib clock smoke tests.

    Open full ADR page

14. 0014-join-ancestor-forbidden Forbidden child Join of ancestor Accepted

    Compile-time rule preventing join cycles on fiber stacks.

    Context

    Parent/child Join cycles deadlock the scheduler.

    Decision

    Child Join parent → compile-time diagnostic JoinWouldDeadlock. Parent Join child and sibling Join remain allowed.

    Consequences

    Diagnostic registry documents JoinWouldDeadlock.

    Verification anchors

    Semantic analyzer tests for join graph.

    Open full ADR page

Articles

• Concurrency package - Contracts and edge cases Send, Receive, Join, Cancel, and Hub normative contracts. article Standard Reviewed Wed May 20
• Concurrency package - Decisions record (legacy index) Migration index pointing to per-decision ADR files under adr/—normative text lives in ADRs, not this page. article Standard Reviewed Fri May 22
• Concurrency package - Design model Package layout, module map, and thin-wrapper rule for Fiber and Channel structs. article Standard Reviewed Wed May 20
• Concurrency package - Examples Illustrative spawn, Channel, and Hub usage (informative). 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 · 14 SpecSection(s) · 0 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
  Concurrency package

  Parent feature hub

Package layout

Workspace package corelib_concurrency (directory compiler/corelib/packages/concurrency/) with one primary module file per public type (match existing corelib style: System/Syscall/ split).

Module path	Responsibility
Concurrency.Fiber	Fiber<T> struct; event OnCancelled() on handle; Join, Detach, Cancel
Concurrency.Channel	Channel<T>; Send, Receive, TrySend, TryReceive, Close
Concurrency.ChannelOptions	Bounded(capacity), Unbounded, optional SingleReader / SingleWriter flags
Concurrency.Hub	Hub<T> homogeneous; Register, WaitReceive (round-robin)
Concurrency.HubReceiveResult	index + value: T
Concurrency.Mutex	Lock, TryLock, Unlock
Concurrency.WaitGroup	Add, Done, Wait
Concurrency	Yield, NowMillis, ProcessorCount, SetProcessorCount

Prelude re-exports (optional, versioned): only what most apps need—avoid dumping the whole package into Prelude.bd until stable.

Status code layout

Runtime status values are split by namespace. Concurrency.Status is only for channel, hub, mutex, and wait-group paths: Ok = 0, Closed = 1, Cancelled = 2, WouldBlock = 3, HubEmpty = 4, HubLimit = 5, HubNotFound = 6, and MutexBusy = 1 for try-lock. Concurrency.FiberJoinStatus is a separate join namespace: Ok = 0, Cancelled = 1, Panicked = 2, StackOverflow = 3, and NotDone = 4.

Fiber Join mappings must never compare join results against channel/hub status constants. Hub Register and WaitReceive map only hub-specific statuses to HubError.

Thin-wrapper rule

Each public method maps 1:1 to a runtime builtin or a small inline sequence documented in Channels and synchronization. No intermediate “scheduler interface” trait hierarchy in Beskid source.

Reference implementation note

Runtime fiber switching may follow a stack-switching coroutine design (see Building lightweight coroutines in Rust (fibers) for engineering patterns). The normative contract remains this platform spec and ABI symbols, not the article.

Anti-patterns (forbidden)

• Parallel .NET-style stacks (Task, ValueTask, ChannelReader/ChannelWriter split types in user API)
• Hidden async/await lowering
• Second channel abstraction in System.* outside this package