Concurrency package

Platform spec feature

Concurrency package

Back to Concurrency ◎ Open 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

• Area
  Concurrency

  Parent area

• Feature
  Fiber scheduler and stacks

  Runtime implementation contract

• Feature
  Channels and synchronization

  Send, Receive, Hub, and memory ordering

• Feature
  Fibers and spawn

  spawn keyword requires Fiber contract

Layer diagram

flowchart TB
  author[Beskid source spawn / Channel / Hub]
  corelib[corelib_concurrency structs]
  builtins[runtime builtins fiber_* channel_* hub_*]
  scheduler[fiber scheduler + GC safepoints]
  author --> corelib --> builtins --> scheduler

The package is a thin wrapper layer only — no duplicate channel abstractions or async state machines.

What this feature specifies

Normative corelib shapes for cooperative concurrency: Fiber<T>, Channel<T>, homogeneous Hub<T>, Mutex, and WaitGroup as thin wrappers over stable runtime builtins. spawn lowering returns a move-only fiber handle with OnCancelled on the handle; channel and join failures use Result / Option, not panic.

Implementation anchors

• Workspace package compiler/corelib/packages/concurrency/ (corelib_concurrency)
• Runtime symbols: compiler/crates/beskid_abi/src/symbols.rs, BUILTIN_SPECS
• Corelib tests: compiler/corelib/beskid_corelib/tests/corelib_tests/src/concurrency/
• Runtime integration: compiler/crates/beskid_runtime/tests/concurrency.rs plus compiler/crates/beskid_tests/src/runtime/jit.rs spawn smoke coverage

Contract statement

The corelib_concurrency workspace package provides the only supported user-facing API for cooperative fibers and channel communication. Public types are structs whose methods call stable runtime builtins (fiber_*, channel_*, hub_*, mutex_*, wait_group_*). The package must not introduce secondary abstraction layers (no builder stacks, no implicit async state machines, no duplicated channel interfaces).

All fiber operations that can fail must return Core.Results.Result (or Option where absence is ordinary). Panics are not the error path for channel or join failures.

Inputs and outputs

Surface	Role
Fiber<T>	Opaque handle wrapping fiber_* builtins; T is the spawn entry return type
Channel<T>	Unbounded by default; ChannelOptions.Bounded(n) for bounded queues
Hub<T>	Homogeneous multichannel WaitReceive (round-robin); unlike types use Channel<HubMessage> or multiple hubs
Mutex	Mutual exclusion between fibers on shared state
WaitGroup	Fork–join counter for batches of fibers
Concurrency.Yield()	Cooperative reschedule (fiber_yield)
Concurrency.NowMillis()	Monotonic milliseconds (fiber_now_millis / clock builtin)
Concurrency.Spawn	Used by lowering of spawn; returns Fiber<T> with OnCancelled on handle
Fiber.Join	Result<T, FiberError>
Fiber.Detach	Fire-and-forget; unjoined panic still aborts process unless recovered at runtime policy
Fiber.Cancel	Sets cancel flag; runs child event OnCancelled(); Join → FiberError::Cancelled

State model

• Fiber<T> — runtime handle + metadata (id, cancellation flag). Not copyable unless spec later allows handle duplication; move-only preferred.
• Channel<T> — holds runtime queue id; Close marks writer end closed; Receive after drain returns ChannelError::Closed in Result.
• Hub — registered set of channel endpoints with cached readiness index updated by runtime on send/receive.
• Phase A (see scheduler spec): many fibers, single GC mutator thread documented; Phase B adds parallel mutators without API break.

Algorithms and flow

1. spawn entry lowers to fiber_spawn_with_cancel_slot(entry, env, onCancelledSlot); parent gets a Fiber<T> backed by the runtime i64 fiber id.
2. Send — if queue full, park current fiber (not OS thread); on success establishes happens-before edge to receiver.
3. Receive — if empty and open, park; if closed and empty, return Result::Err(Closed).
4. TrySend / TryReceive — non-blocking; Option for empty/full.
5. Hub.WaitReceive — runtime waits until any registered channel can satisfy Receive; returns which member completed.
6. Blocking syscall paths in System.Syscall should park the calling fiber and delegate blocking work to the thread pool (runtime), not stall the whole scheduler.

Edge cases and errors

• Send after Close → Result::Err(ChannelError::Closed) (no panic).
• Cancel on joined fiber → FiberError::Cancelled on Join.
• Detach child panic → process abort after diagnostic unless runtime policy adds domain recovery later.
• Fibers must not share pointers to another fiber’s stack; Channel is the only approved cross-fiber communication (language + memory model).

Compatibility and versioning

New builtins require beskid_runtime_abi_version bump and entries in BUILTIN_SPECS / define_builtins!. Deprecated v0.1 rt_yield / rt_now_millis (sched feature) are superseded by fiber_yield and monotonic clock builtins—remove legacy doc references to async/await.

Security and performance notes

• Default fiber stack: 64 KiB, growable cap 8 MiB (runtime).
• Unbounded channels are opt-in; documentation must warn about memory growth.
• Hub registration count should be bounded in UI scenarios (console) to avoid linear scans on hot paths.

Examples

See examples article: spawn + Join, bounded Channel, Hub for stdin/resize multiplexing sketch.

Verification and traceability

• Corelib compile tests under compiler/corelib/beskid_corelib/tests/corelib_tests/src/concurrency/
• Runtime integration: canonical primitive coverage in compiler/crates/beskid_runtime/tests/concurrency.rs; JIT smoke in compiler/crates/beskid_tests/src/runtime/jit.rs
• Conformance: bounded/closed Channel, Cancel, Hub readiness ordering, Mutex, WaitGroup, and syscall parking

Decisions

No open decisions. Closed choices are normative ADRs under adr/ (D-CORE-CONC-0001 … D-CORE-CONC-0014); use the reader ADRs tab for expandable detail. Legacy decisions record is a migration index only.

Related features

• System.Threading — OS threads (preemptive), not fibers
• Console terminal events — delivers via Channel

Articles

• Channel default capacity is unboundedFactory defaults and explicit bounded/unbounded options for Channel construction.
• Concurrency package - Contracts and edge casesSend, Receive, Join, Cancel, and Hub normative contracts.
• Concurrency package - Decisions record (legacy index)Migration index pointing to per-decision ADR files under adr/—normative text lives in ADRs, not this page.
• Concurrency package - Design modelPackage layout, module map, and thin-wrapper rule for Fiber and Channel structs.
• Concurrency package - ExamplesIllustrative spawn, Channel, and Hub usage (informative).