Skip to content

doc: exception handling mechanism and CRuby contrast#897

Merged
sisshiki1969 merged 1 commit into
masterfrom
claude/cruby-4-0-2-specs-olt61c
Jul 13, 2026
Merged

doc: exception handling mechanism and CRuby contrast#897
sisshiki1969 merged 1 commit into
masterfrom
claude/cruby-4-0-2-specs-olt61c

Conversation

@sisshiki1969

Copy link
Copy Markdown
Owner

Summary

Adds doc/exception_handling.md — a walkthrough of monoruby's exception mechanism contrasted point-by-point with CRuby, capturing the findings from the Exception#backtrace work (#896).

The document's through-line is laziness: monoruby stores the minimum at raise time and defers the expensive work (exception-object materialization, backtrace string formatting) until something actually asks for it, which is what keeps the raise path — including the control-flow pseudo-exceptions that reuse the same machinery — cheap.

Sections:

  • MonorubyErr (the in-flight Rust error) vs the lazily-materialized Ruby exception object (take_ex_obj), including GC rooting of smuggled Values.
  • Two families of MonorubyErrKind: real exceptions vs control-flow pseudo-exceptions (return/break/throw/retry/redo/fatal), and why the latter are dispatched before any trace capture, so they pay nothing for backtraces.
  • handle_error as the per-frame unwinder, the per-method exception table (get_exception_dest), ensure deferral (the deferred-unwind stack), and $! restoration.
  • Backtrace construction — the key contrast: incremental tuple capture on unwind, the catch-time caller walk (complete_backtrace_for_rescue) explained as the last coherent snapshot point (why not eager-at-raise, why not lazy-at-#backtrace), lazy string formatting + memoization in the /backtrace ivar, and why loop's internal StopIteration pays almost nothing (caught at the Rust level below the bytecode-rescue path).
  • Fatal errors, top-level reporting, a file map, and a hot-path cost table.

Each section pairs the monoruby behavior with the corresponding CRuby mechanism (eager-at-raise rb_backtrace_t snapshot, catch_table entries, exc_setup_cause, uncatchable fatal).

Test plan

Documentation only — no code changes. File references and cited line numbers were verified against the current tree.

🤖 Generated with Claude Code


Generated by Claude Code

@codecov

codecov Bot commented Jul 13, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.51%. Comparing base (8753ca6) to head (0a1e6ba).

Additional details and impacted files
@@            Coverage Diff             @@
##           master     #897      +/-   ##
==========================================
+ Coverage   90.50%   90.51%   +0.01%     
==========================================
  Files         189      189              
  Lines      123227   123227              
==========================================
+ Hits       111521   111535      +14     
+ Misses      11706    11692      -14     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Document monoruby's raise/unwind/rescue pipeline and how it differs from
CRuby, centered on the laziness that keeps the raise path cheap:

- MonorubyErr (in-flight Rust error) vs the lazily-materialized Ruby
  exception object (take_ex_obj).
- The two families of MonorubyErrKind: real exceptions vs control-flow
  pseudo-exceptions (return/break/throw/retry/redo/fatal), and why the
  latter are dispatched before any trace capture.
- handle_error as the per-frame unwinder, the per-method exception table,
  ensure deferral, and $! restoration.
- Backtrace construction: incremental capture on unwind, the catch-time
  caller walk (complete_backtrace_for_rescue) as the last coherent
  snapshot point, lazy string formatting + memoization, and why loop's
  StopIteration pays almost nothing.
- Point-by-point CRuby contrast (eager-at-raise snapshot vs
  deferred/incremental) and a hot-path cost table.

Captures the findings from the Exception#backtrace work (#896).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XpzdoFu46d2ChJpSzeWsNK
@sisshiki1969 sisshiki1969 force-pushed the claude/cruby-4-0-2-specs-olt61c branch from 6db933b to 0a1e6ba Compare July 13, 2026 00:18
@sisshiki1969 sisshiki1969 merged commit 80c5b3d into master Jul 13, 2026
4 checks passed
@sisshiki1969 sisshiki1969 deleted the claude/cruby-4-0-2-specs-olt61c branch July 13, 2026 01:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants