Flow and algorithm

Platform spec article

Flow and algorithm

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

Purpose

Step-by-step algorithms for panic and syscall builtins. Layering diagram: design model.

Panic path

1. Lowering or runtime detects unrecoverable condition (bounds check, failed alloc message).
2. Build BeskidStr message pointer or call panic_str with empty/default handle.
3. panic / panic_str formats diagnostic output when possible, then traps.
4. No return to generated Beskid code (AbiReturnKind::Never).

syscall_write algorithm

1. Validate fd range (non-negative, fits platform i32 where required).
2. Read { ptr, len } from BeskidStr; null handle returns -1.
3. On Linux x86_64, loop write syscall until buffer drained or error.
4. Return total bytes written as i64, or -1 on hard failure.

syscall_read algorithm

1. Accept fd and max byte count (i64 parameters per BUILTIN_SPECS).
2. Allocate or fill buffer via runtime string helpers; return BeskidStr pointer.
3. Map EOF to empty string handle per corelib contract (IO-005 in console streams).

Blocking and fibers

1. When a fiber triggers blocking syscall work, runtime may use scheduler::run_blocking to avoid blocking the scheduler thread’s mutator role incorrectly.
2. Pool threads must not run arbitrary Beskid mutator allocations (memory contract GC-003).

Corelib write failure

1. System.Output.Write calls WriteWith.
2. On syscall error, corelib must panic with stable message — not Option — per console IO spec.

Related topics

• Contracts and edge cases
• Builtins and symbols