FAQ and troubleshooting

Platform spec article

FAQ and troubleshooting

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

FAQ

Why panic instead of exceptions?

Beskid explicitly rejects hidden control flow. Option covers expected errors; panic is the runtime trap for faults (error model legacy).

Can I catch panic in Beskid?

No. There is no try/catch for runtime panics in v0.2. Hosts may only intercept before returning to generated code.

Why do writes panic but reads return Result?

v1 CLI policy treats broken stdout as fatal while stdin EOF is normal control flow—see Console I/O streams.

Do syscalls run on fiber scheduler threads?

Blocking operations should use scheduler blocking helpers so mutator rules stay intact; see Flow and algorithm.

Troubleshooting

Symptom	Check
Immediate exit, no message	panic_str null handle path; enable stderr logging in host
syscall_write always -1	Invalid fd or null BeskidStr
Garbled UTF-8 on console	Caller passed non-UTF-8 bytes in string
Hang on stdin read	Fiber parked correctly; deadlock if mutator blocked on same thread

Related topics

• Examples
• Extern dispatch — foreign code panics are not translated