Design model

Platform spec article

Design model

Back to Panic, IO, and syscalls ◎ Open feature in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (3)

1. 0008-panic-terminates-process Runtime panic terminates the process Accepted

   No Beskid stack unwinding across panic; traps end execution.

   Context

   Language Option covers expected errors. Unrecoverable faults and some IO failures need a distinct path that does not conflate with Result channel semantics.

   Decision

   Mechanism	Use
   Option / Result	Expected failures (language-meta + corelib)
   panic / panic_str	Unrecoverable faults, hard IO faults in v1 streams, allocation failures
   Unwind	No Beskid stack unwinding across panics
   Outcome	Runtime panics terminate the process (trap / abort)
   Builtin kind	AbiReturnKind::Never in BUILTIN_SPECS

   Consequences

   Corelib must not catch panics for ordinary control flow. Fiber Detach panics still abort unless future domain recovery is specified.

   Verification anchors

   beskid_runtime::builtins::panic_io; e2e runtime cases.

   Open full ADR page

2. 0009-runtime-owned-syscalls Syscalls centralized in runtime builtins Accepted

   Lowering and corelib route IO through syscall_read/write, not embedded OS code.

   Context

   Scattering platform syscall sequences through codegen duplicates policy and breaks GC mutator rules at IO sites.

   Decision

   Rule	Detail
   Builtins	syscall_read, syscall_write accept fd + buffer (BeskidStr for write)
   Implementation	beskid_runtime::builtins::panic_io — Linux x86_64 direct syscalls in reference tree
   Other targets	May use std::io for fds 1/2 while preserving signatures
   Front-end	Must not embed OS-specific syscall sequences in lowering
   Corelib	System.Input / Output / Error wrap builtins with descriptors

   Git anchor: 12ee673 (split System I/O surfaces).

   Consequences

   New platforms document stub vs native behavior without renaming symbols.

   Verification anchors

   panic_io.rs; console stream corelib tests.

   Open full ADR page

3. 0010-blocking-syscalls-park-fiber Blocking syscalls park the calling fiber Accepted

   Scheduler run_blocking offloads host work without stalling other fibers.

   Context

   Blocking read/write on a fiber must not freeze the entire M:N scheduler or violate Phase A mutator rules on pool threads.

   Decision

   Rule	Detail
   Blocking path	Enqueue host blocking work on syscall pool; park current fiber only
   Wake	Resume fiber on scheduler thread when worker completes
   Pool workers	Must not execute generated Beskid mutator code or allocate as mutators
   Pool worker tagging	Each pool thread calls set_syscall_pool_worker() so the runtime can assert this rule (assert_mutator_allowed) and panic on accidental allocation
   Allocation	Runtime object creation for results happens after resume on scheduler thread
   Console	Producers Send bytes/events; consumers Receive on fibers

   Consequences

   M6+ syscall integration is required for conformance on blocking builtins.

   Verification anchors

   Scheduler run_blocking; fiber scheduler verification article.

   Open full ADR page

Articles

• Contracts and edge cases MUST rules for panic divergence, syscall parameters, and backend neutrality. article Standard Reviewed Fri May 22
• Design model Panic termination, syscall ownership, and runtime-mediated IO boundaries. article Standard Reviewed Fri May 22
• Examples Panic from lowering, syscall_write status codes, and corelib IO scenarios. article Standard Reviewed Fri May 22
• FAQ and troubleshooting Panic vs Option, syscall return codes, and fiber/blocking IO issues. article Standard Reviewed Fri May 22
• Flow and algorithm Panic emission, syscall_write chunking, and blocking IO on fibers. article Standard Reviewed Fri May 22
• Verification and traceability panic_io implementation paths, e2e runtime cases, and IO contract cross-tests. article Standard Reviewed Fri May 22

History

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

Open full history on GitHub

No commits recorded for this path.

Completeness

OKfeature · 2 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
  Panic, IO, and syscalls

  Parent feature hub

• Feature
  Console I/O streams

  Corelib facades over syscall builtins

Purpose

Define runtime ownership of unrecoverable faults (panic) and platform IO (syscall_read, syscall_write). Front-end and corelib must not embed OS-specific syscall sequences in lowering.

Primary actors

Actor	Role
Lowering	Emits panic for unrecoverable checks; routes corelib IO to builtins
beskid_runtime::builtins::panic_io	Linux x86_64 syscall asm; stdio fallback elsewhere
Scheduler	run_blocking for syscall work without violating GC mutator rules
Corelib System.Syscall	Wraps builtins with descriptors (Console I/O streams)

Failure model split

Mechanism	Use
Option<T> (language)	Expected errors — canonical in language-meta
panic / panic_str	Unrecoverable faults, failed writes in v1 streams, allocation failures

Runtime panics terminate the process (trap). There is no Beskid stack unwinding across panics.

IO boundary

flowchart TB
  core[System.Input / Output / Error]
  wrap[Syscall ReadWith / WriteWith]
  builtin[syscall_read / syscall_write]
  os[OS read/write]
  core --> wrap --> builtin --> os
  trap[panic on hard fault] --> builtin

Syscall builtins accept file descriptor + buffer (syscall_write uses BeskidStr). They return integer status codes; corelib maps EOF/errors to Result.

Platform scope

Reference implementation: Linux x86_64 direct syscalls for performance. Other targets may delegate to std::io for fds 1/2 while preserving signatures (IO-ABI-003).

Related topics

• Flow and algorithm
• Legacy: Error model, Syscalls and ABI boundary