From 02fc509555af9fe9a0fa4a1bf49fe60b6f37fcc4 Mon Sep 17 00:00:00 2001 From: "Yukihiro \"Matz\" Matsumoto" Date: Mon, 21 Jul 2025 14:01:07 +0900 Subject: [PATCH] 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 --- mrbgems/mruby-error/src/exception.c | 66 ++++++++++++++++++++++++++++- 1 file changed, 64 insertions(+), 2 deletions(-) diff --git a/mrbgems/mruby-error/src/exception.c b/mrbgems/mruby-error/src/exception.c index b43a3ef05..b2b280356 100644 --- a/mrbgems/mruby-error/src/exception.c +++ b/mrbgems/mruby-error/src/exception.c @@ -1,11 +1,15 @@ #include #include +/* Helper structure to pass function and data to protection wrapper */ struct protect_data { - mrb_func_t body; - mrb_value data; + mrb_func_t body; /* Function to be executed under protection */ + mrb_value data; /* Data to be passed to the function */ }; +/* Helper function that wraps user function calls for exception protection. + * Extracts function and data from protect_data structure and calls the + * user function with proper parameters. Used internally by mrb_protect. */ static mrb_value protect_body(mrb_state *mrb, void *p) { @@ -13,6 +17,19 @@ protect_body(mrb_state *mrb, void *p) return dp->body(mrb, dp->data); } +/* + * Executes a function under exception protection. + * + * @param mrb mruby state + * @param body Function to execute under protection + * @param data Data to pass to the function + * @param state Pointer to store exception state (true if exception occurred) + * @return Return value from body function, or exception object if error occurred + * + * This function provides a C API equivalent to Ruby's begin/rescue blocks. + * If an exception occurs during execution of body, it will be caught and + * the exception object returned, with *state set to true. + */ MRB_API mrb_value mrb_protect(mrb_state *mrb, mrb_func_t body, mrb_value data, mrb_bool *state) { @@ -20,6 +37,21 @@ mrb_protect(mrb_state *mrb, mrb_func_t body, mrb_value data, mrb_bool *state) return mrb_protect_error(mrb, protect_body, &protect_data, state); } +/* + * Executes a function with guaranteed cleanup (ensure block). + * + * @param mrb mruby state + * @param body Main function to execute + * @param b_data Data to pass to body function + * @param ensure Cleanup function that always executes + * @param e_data Data to pass to ensure function + * @return Return value from body function + * + * This function provides a C API equivalent to Ruby's begin/ensure blocks. + * The ensure function is guaranteed to execute regardless of whether the + * body function completes normally or raises an exception. If an exception + * occurs in the body, it will be re-raised after the ensure block executes. + */ MRB_API mrb_value mrb_ensure(mrb_state *mrb, mrb_func_t body, mrb_value b_data, mrb_func_t ensure, mrb_value e_data) { @@ -36,6 +68,20 @@ mrb_ensure(mrb_state *mrb, mrb_func_t body, mrb_value b_data, mrb_func_t ensure, return result; } +/* + * Executes a function with exception handling for StandardError and its subclasses. + * + * @param mrb mruby state + * @param body Main function to execute + * @param b_data Data to pass to body function + * @param rescue Exception handler function + * @param r_data Data to pass to rescue function + * @return Return value from body function, or rescue function if StandardError occurred + * + * This function provides a C API equivalent to Ruby's begin/rescue blocks that + * catch StandardError. It's a convenience wrapper around mrb_rescue_exceptions + * that automatically handles StandardError and its subclasses. + */ MRB_API mrb_value mrb_rescue(mrb_state *mrb, mrb_func_t body, mrb_value b_data, mrb_func_t rescue, mrb_value r_data) @@ -43,6 +89,22 @@ mrb_rescue(mrb_state *mrb, mrb_func_t body, mrb_value b_data, return mrb_rescue_exceptions(mrb, body, b_data, rescue, r_data, 1, &mrb->eStandardError_class); } +/* + * Executes a function with exception handling for specific exception classes. + * + * @param mrb mruby state + * @param body Main function to execute + * @param b_data Data to pass to body function + * @param rescue Exception handler function + * @param r_data Data to pass to rescue function + * @param len Number of exception classes to handle + * @param classes Array of exception classes to catch + * @return Return value from body function, or rescue function if matching exception occurred + * + * This function provides a C API equivalent to Ruby's begin/rescue blocks with + * specific exception class handling. Only exceptions that are instances of the + * specified classes will be caught; others will be re-raised. + */ MRB_API mrb_value mrb_rescue_exceptions(mrb_state *mrb, mrb_func_t body, mrb_value b_data, mrb_func_t rescue, mrb_value r_data, mrb_int len, struct RClass **classes)