System.Threading

Platform spec feature

System.Threading

Back to Concurrency ◎ Open in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (4)

1. 0001-os-thread-surface-only System.Threading is the OS-thread surface Accepted

   Preemptive threads use System.Threading exclusively in corelib.

   Context

   Cooperative and preemptive concurrency need distinct entry points.

   Decision

   Rule	Detail
   API	System.Threading is the only supported preemptive OS-thread module
   Fibers	Cooperative APIs stay in the concurrency package

   Consequences

   User code must not implement fibers atop Thread.Spawn.

   Verification anchors

   packages/concurrency System.Threading sources; runtime syscall docs.

   Open full ADR page

2. 0002-no-fibers-on-threading Do not build fibers on OS threads Accepted

   Fibers must use Fiber/Channel builtins, not Thread wrappers.

   Context

   Mixing models breaks GC safepoints and scheduler invariants.

   Decision

   Rule	Detail
   Forbidden	Fiber scheduler emulation via System.Threading in corelib
   Required	Use Concurrency package

   Consequences

   Documentation and examples steer authors to spawn/fiber APIs.

   Verification anchors

   Concurrency integration tests; system-threading module docs.

   Open full ADR page

3. 0003-distinct-yield-entry-points Distinct Thread.Yield and Concurrency.Yield Accepted

   OS yield and fiber yield are separate APIs.

   Context

   Kernel scheduling differs from cooperative fiber reschedule.

   Decision

   Rule	Detail
   Thread.Yield	OS-level yield
   Concurrency.Yield	fiber_yield cooperative reschedule

   Consequences

   Names and docs must not alias the two yields.

   Verification anchors

   Runtime tests distinguishing syscall vs fiber_yield.

   Open full ADR page

4. 0004-per-thread-gc-session Per-thread GC session on entry Accepted

   OS thread entry must attach heap session and GC roots.

   Context

   Parallel OS threads require independent GC attachment rules in Phase A.

   Decision

   Rule	Detail
   Entry	Thread start must establish runtime heap session
   FFI	extern "C" stays pinned to calling OS thread for call duration

   Consequences

   Violations risk root loss or cross-thread heap corruption.

   Verification anchors

   Extern dispatch and policy; GC phase ADRs.

   Open full ADR page

Articles

• No directly attached article pages for this node.

History

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

Open full history on GitHub

No commits recorded for this path.

Completeness

OKfeature · 6 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

• Area
  Concurrency

  Parent area

• Feature
  Concurrency package

  Cooperative fibers and channels

• Feature
  Panic, IO, and syscalls

  Syscall surface for thread creation

What this feature specifies

System.Threading is the only supported preemptive OS-thread surface in corelib_concurrency. It wraps syscall-backed Spawn, Join, and Yield for kernel-scheduled threads. Cooperative fibers (Fiber<T>, Channel) must use the Concurrency package, not threads built in user code on top of this module.

Implementation anchors

• Module prefix System.Threading under compiler/corelib/packages/concurrency/
• Syscall and extern targets documented in Panic, IO, and syscalls
• Per-thread GC session rules: Extern dispatch and policy

Contract statement

System.Threading lives in the corelib_concurrency package under module prefix System.Threading. It wraps OS threads (preemptive, kernel-scheduled) using syscalls and/or documented extern targets—not fiber stack switching.

Cooperative concurrency must use Concurrency package (Fiber<T>, Channel). Do not implement fibers on top of System.Threading in corelib.

Responsibilities

API (illustrative)	Role
Thread.Spawn	Start OS thread with entry function; returns Result<Thread, ThreadError>
Thread.Join	Wait for OS thread completion
Thread.Yield	OS-level yield (distinct from Concurrency.Yield)

Fiber scheduler worker pool may use OS threads internally; user code should not confuse the two Yield entry points.

FFI and GC

OS thread entry points must establish a runtime heap session and GC root attachment per thread before calling Beskid code. extern “C” from any fiber or thread must stay pinned to the calling OS thread for the call duration (see Extern dispatch and policy).

Phase alignment

Phase A: fiber scheduler may use a fixed pool of OS threads with one GC mutator; System.Threading documents raw thread creation for libraries that truly need preemptive threads. Phase B: parallel GC mutators—thread module and fiber pool coordination updated in scheduler spec without renaming public Thread APIs.

Decisions

No open decisions. Closed choices are normative ADRs under adr/ (D-CORE-SYST-0001 … D-CORE-SYST-0004); use the reader ADRs tab for expandable detail.