doc: exception handling mechanism and CRuby contrast#897
Merged
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. 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. 🚀 New features to boost your workflow:
|
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
6db933b to
0a1e6ba
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds
doc/exception_handling.md— a walkthrough of monoruby's exception mechanism contrasted point-by-point with CRuby, capturing the findings from theException#backtracework (#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 smuggledValues.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_erroras the per-frame unwinder, the per-method exception table (get_exception_dest),ensuredeferral (the deferred-unwind stack), and$!restoration.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/backtraceivar, and whyloop's internalStopIterationpays almost nothing (caught at the Rust level below the bytecode-rescuepath).Each section pairs the monoruby behavior with the corresponding CRuby mechanism (eager-at-raise
rb_backtrace_tsnapshot,catch_tableentries,exc_setup_cause, uncatchablefatal).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