Concurrency package - Contracts and edge cases

Platform spec article

Concurrency package - Contracts and edge cases

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

Channel<T>

Construction

• Channel<T>.Create(options: ChannelOptions = default) — default is unbounded.
• ChannelOptions.Bounded(n) — n > 0; Send parks when full (Wait mode).
• ChannelOptions.Unbounded — equivalent to default; queue grows until OOM (documented risk).
• ChannelOptions.SingleReader() / SingleWriter() — unbounded factories that set optimization hints without changing queue semantics.
• Optional capacity field inside options must not contradict Bounded / Unbounded variant; bounded wins when Bounded(n) is chosen.

Send and Receive (full names required)

Method	Contract
Send	Result<(), ChannelError>; blocks/parks fiber when full (bounded + Wait mode)
Receive	Result<T, ChannelError>; parks when empty and open
TrySend	Option<()> — None if would block
TryReceive	Option<T> — None if would block
Close	Idempotent writer close; no panic

ChannelError (closed set)

• Closed — endpoint closed
• Cancelled — owning fiber cancelled (Cancel / OnCancelled path)

TrySend / TryReceive use Option only (None = would block); no ChannelError::Full.

ChannelOptions (.NET-inspired, sync-only)

• SingleReader / SingleWriter — optimization hints; behavior unchanged if violated but may enable faster paths
• BoundedChannelFullMode::Wait — default; sender parks
• No AllowSynchronousContinuations (async-only .NET concept)

Fiber<T>

Fiber<T> is a corelib struct (runtime handle) that must declare:

event OnCancelled();

The spawn entry function does not declare OnCancelled — only the handle type does.

Method	Contract
Join	Result<T, FiberError> — Ok(value), Cancelled, StackOverflow, Panicked
Detach	void; parent waives Join; child panic aborts process
Cancel	void; raises OnCancelled on child fiber, then unblocks parked ops with Cancelled

OnCancelled runs on the child fiber. Unhandled failure in a handler aborts the process. Handlers must not Join self, Join an ancestor, or block indefinitely.

Join from a child fiber to a parent (or ancestor) handle is a compile error (JoinWouldDeadlock).

M3 completion requires generated code to import the ABI symbol fiber_spawn_with_cancel_slot, pass the handle’s OnCancelled event slot, and treat the returned handle as an i64 fiber id rather than a pointer.

FiberError (closed set)

• Cancelled
• StackOverflow
• Panicked — carries diagnostic handle / message policy per runtime

Hub<T>

• Homogeneous only in v1 — Hub<T> registers only Channel<T> instances
• Register(index, channel) / Unregister(index) — index is user-chosen i64 key in WaitReceive result
• WaitReceive → Result<HubReceiveResult, HubError> where HubReceiveResult carries member index and received value
• Round-robin fairness among ready channels (see decisions record)
• Multiplexing unlike types: use Channel<HubMessage> (enum/union) or multiple hubs — not mixed-type Hub in v1
• WaitSend — not in v1
• Replaces language-level select for v1

Mutex and WaitGroup

• Mutex.Lock → Result<MutexGuard, MutexError>
• Mutex.TryLock → Option<MutexGuard> (None if would block)
• Mutex.Unlock — explicit in v1 (no defer required for spec)
• WaitGroup.Wait parks until counter zero; Add/Done follow Go semantics

Console integration

Console.OnResize and control onTick paths must publish into a Channel<T> (or Hub member) so UI fibers Receive events without multicast event invocation across fibers. Language event syntax may remain for single-fiber use; cross-fiber UI must use Channel (see console-terminal-events).