Yukihiro "Matz" Matsumoto 02fc509555 mruby-error: add comprehensive documentation for C API exception handling functions ...

Added complete documentation for all C API functions providing exception
handling capabilities in src/exception.c:

## Core C API Functions:

### Exception Protection:
- mrb_protect: executes function under exception protection, equivalent to
  Ruby's begin/rescue blocks, catches exceptions and returns them as objects
  with error state flag for C code exception handling

### Guaranteed Cleanup:
- mrb_ensure: executes function with guaranteed cleanup, equivalent to Ruby's
  begin/ensure blocks, ensures cleanup function always runs regardless of
  exceptions, re-raises caught exceptions after cleanup

### Exception Handling:
- mrb_rescue: executes function with StandardError exception handling,
  convenience wrapper for common rescue patterns, automatically catches
  StandardError and its subclasses

- mrb_rescue_exceptions: executes function with specific exception class
  handling, allows selective exception catching based on class hierarchy,
  re-raises unmatched exceptions for precise error control

## Helper Components:

### Internal Structures:
- protect_data: helper structure to pass function and data to protection
  wrapper, encapsulates function pointer and argument data for safe execution

### Internal Functions:
- protect_body: helper function that wraps user function calls for exception
  protection, extracts function and data from protect_data structure and
  calls user function with proper parameters

Key features documented:
- Exception protection and propagation control
- Guaranteed cleanup execution (ensure semantics)
- Selective exception class handling with inheritance support
- Integration with mruby's exception system and GC
- C API patterns for robust error handling in extensions

Provides complete coverage of exception handling C API for robust error
management in mruby C extensions and embedded applications, essential
for building reliable C code that integrates with mruby's exception system.

Co-authored-by: Atlassian Rovo Dev

2025-08-14 10:52:47 +09:00

..

exception.c

mruby-error: add comprehensive documentation for C API exception handling functions

2025-08-14 10:52:47 +09:00