Panic, IO, and syscalls

Platform spec feature

Panic, IO, and syscalls

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

• Area
  Runtime

  Parent area

• Area
  ABI and host boundary

  Builtin symbol contracts define runtime export obligations

• Area
  Interop

  Extern boundaries eventually reach syscall and panic surfaces

• Feature
  Interop.Contracts

  Shared vocabulary for runtime vs user foreign boundaries

• Feature
  Rust ABI profile

  Runtime export surface for builtins and syscall bridges

What this feature specifies

Panic, IO, and syscalls defines one operational contract that a newcomer can follow end-to-end: first the model, then execution flow, then strict guarantees, concrete examples, and verification guidance.

Implementation anchors

• Builtin exports in compiler/crates/beskid_runtime/src/builtins/mod.rs
• Panic and syscall implementation in compiler/crates/beskid_runtime/src/builtins/panic_io.rs
• Runtime symbol registration in compiler/crates/beskid_runtime/src/lib.rs
• E2E coverage in compiler/crates/beskid_e2e_tests/src/tests/runtime_cases.rs

Decisions

No open decisions. Closed choices are normative ADRs under adr/ (D-EXEC-RT-0008 … D-EXEC-RT-0010); use the reader ADRs tab for expandable detail.

Articles

• Runtime panic terminates the processNo Beskid stack unwinding across panic; traps end execution.
• Contracts and edge casesMUST rules for panic divergence, syscall parameters, and backend neutrality.
• Design modelPanic termination, syscall ownership, and runtime-mediated IO boundaries.
• ExamplesPanic from lowering, syscall_write status codes, and corelib IO scenarios.
• FAQ and troubleshootingPanic vs Option, syscall return codes, and fiber/blocking IO issues.
• Flow and algorithmPanic emission, syscall_write chunking, and blocking IO on fibers.
• Verification and traceabilitypanic_io implementation paths, e2e runtime cases, and IO contract cross-tests.