From 1b6245ccdcd414698a257847d508603f438578ca Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=8D=9C=E9=83=A8=E6=98=8C=E5=B9=B3?= Date: Mon, 21 Dec 2020 11:15:08 +0900 Subject: [PATCH] include/ruby/internal/error.h: add doxygen Must not be a bad idea to improve documents. --- error.c | 2 +- eval.c | 14 - include/ruby/internal/error.h | 557 ++++++++++++++++++++++++++++++++-- 3 files changed, 528 insertions(+), 45 deletions(-) diff --git a/error.c b/error.c index 79a24a71fd..6cd64bc280 100644 --- a/error.c +++ b/error.c @@ -45,7 +45,7 @@ #include "builtin.h" /*! - * \defgroup exception Exception handlings + * \addtogroup exception * \{ */ diff --git a/eval.c b/eval.c index ff05984bf1..209ad334ee 100644 --- a/eval.c +++ b/eval.c @@ -1769,26 +1769,12 @@ errinfo_getter(ID id, VALUE *_) return get_errinfo(); } -/*! The current exception in the current thread. - * - * Same as \c $! in Ruby. - * \return the current exception or \c Qnil - * \ingroup exception - */ VALUE rb_errinfo(void) { return GET_EC()->errinfo; } -/*! Sets the current exception (\c $!) to the given value - * - * \param[in] err an \c Exception object or \c Qnil. - * \exception TypeError if \a err is neither an exception nor \c nil. - * \note this function does not raise the exception. - * Use \c rb_raise() when you want to raise. - * \ingroup exception - */ void rb_set_errinfo(VALUE err) { diff --git a/include/ruby/internal/error.h b/include/ruby/internal/error.h index 9f4111949d..6b54f567ed 100644 --- a/include/ruby/internal/error.h +++ b/include/ruby/internal/error.h @@ -20,64 +20,561 @@ * extension libraries. They could be written in C++98. * @brief Declares ::rb_raise(). */ +#include "ruby/internal/attr/cold.h" +#include "ruby/internal/attr/format.h" +#include "ruby/internal/attr/noreturn.h" +#include "ruby/internal/attr/nonnull.h" #include "ruby/internal/dllexport.h" #include "ruby/internal/value.h" -#include "ruby/backward/2/attributes.h" + +/** + * @defgroup exception Exception handlings + * @{ + */ RBIMPL_SYMBOL_EXPORT_BEGIN() +/** + * This is the same as `$!` in Ruby. + * + * @retval RUBY_Qnil Not handling exceptions at the moment. + * @retval otherwise The current exception in the current thread. + * @ingroup exception + */ VALUE rb_errinfo(void); + +/** + * Sets the current exception (`$!`) to the given value. + * + * @exception rb_eTypeError What is given was neither ::rb_eException nor + * ::RUBY_Qnil. + * @note Use rb_raise() instead to raise `err`. This function just + * assigns the given object to the global variable. + * @ingroup exception + */ void rb_set_errinfo(VALUE); +/** + * Warning categories. A warning issued using this API can be selectively + * requested / suppressed by the end-users. For instance passing + * `-W:no-deprecated` to the ruby process would suppress those warnings in + * deprecated category. + * + * @warning There is no way to declare a new category (for now). + */ typedef enum { + /** Category unspecified. */ RB_WARN_CATEGORY_NONE, + + /** Warning is for deprecated features. */ RB_WARN_CATEGORY_DEPRECATED, + + /** Warning is for experimental features. */ RB_WARN_CATEGORY_EXPERIMENTAL, + RB_WARN_CATEGORY_ALL_BITS = 0x6 /* no RB_WARN_CATEGORY_NONE bit */ } rb_warning_category_t; -/* for rb_readwrite_sys_fail first argument */ +/** for rb_readwrite_sys_fail first argument */ enum rb_io_wait_readwrite {RB_IO_WAIT_READABLE, RB_IO_WAIT_WRITABLE}; +/** @cond INTERNAL_MACRO */ #define RB_IO_WAIT_READABLE RB_IO_WAIT_READABLE #define RB_IO_WAIT_WRITABLE RB_IO_WAIT_WRITABLE +/** @endcond */ -PRINTF_ARGS(NORETURN(void rb_raise(VALUE, const char*, ...)), 2, 3); -PRINTF_ARGS(NORETURN(void rb_fatal(const char*, ...)), 1, 2); -COLDFUNC PRINTF_ARGS(NORETURN(void rb_bug(const char*, ...)), 1, 2); -NORETURN(void rb_bug_errno(const char*, int)); -NORETURN(void rb_sys_fail(const char*)); -NORETURN(void rb_sys_fail_str(VALUE)); -NORETURN(void rb_mod_sys_fail(VALUE, const char*)); -NORETURN(void rb_mod_sys_fail_str(VALUE, VALUE)); -NORETURN(void rb_readwrite_sys_fail(enum rb_io_wait_readwrite, const char*)); -NORETURN(void rb_iter_break(void)); -NORETURN(void rb_iter_break_value(VALUE)); -NORETURN(void rb_exit(int)); -NORETURN(void rb_notimplement(void)); -VALUE rb_syserr_new(int, const char *); +RBIMPL_ATTR_NORETURN() +RBIMPL_ATTR_NONNULL((2)) +RBIMPL_ATTR_FORMAT(RBIMPL_PRINTF_FORMAT, 2, 3) +/** + * Exception entry point. By calling this function the execution of your + * program gets interrupted to "raise" an exception up to the callee entities. + * Programs could "rescue" that exception, or could "ensure" some part of them. + * If nobody cares about such things, the raised exception reaches at the top + * of execution. This yields abnormal end of the process. + * + * @param[in] exc A subclass of ::rb_eException. + * @param[in] fmt Format specifier string compatible with rb_sprintf(). + * @exception exc The specified exception. + * @note It never returns. + */ +void rb_raise(VALUE exc, const char *fmt, ...); + +RBIMPL_ATTR_NORETURN() +RBIMPL_ATTR_NONNULL((1)) +RBIMPL_ATTR_FORMAT(RBIMPL_PRINTF_FORMAT, 1, 2) +/** + * Raises the unsung "fatal" exception. This is considered severe. Nobody can + * rescue the exception. Once raised, process termination is inevitable. + * However ensure clauses still run, so that resources are properly cleaned up. + * + * @param[in] fmt Format specifier string compatible with rb_sprintf(). + * @exception rb_eFatal An exception that you cannot rescue. + * @note It never returns. + */ +void rb_fatal(const char *fmt, ...); + +RBIMPL_ATTR_COLD() +RBIMPL_ATTR_NORETURN() +RBIMPL_ATTR_NONNULL((1)) +RBIMPL_ATTR_FORMAT(RBIMPL_PRINTF_FORMAT, 1, 2) +/** + * Interpreter panic switch. Immediate process termination without any + * synchronisations shall occur. LOTS of internal states, stack traces, and + * even machine registers are displayed if possible for debugging purposes + * then. + * + * @warning Do not use this API. + * @warning You are not expected to use this API. + * @warning Why not just fix your code instead of calling this API? + * @warning It was a bad idea to expose this API to extension libraries at + * the first place. We just cannot delete it at this point for + * backwards compatibility. That doesn't mean everyone are + * welcomed to call this function at will. + * @param[in] fmt Format specifier string compatible with rb_sprintf(). + * @note It never returns. + */ +void rb_bug(const char *fmt, ...); + +RBIMPL_ATTR_NORETURN() +RBIMPL_ATTR_NONNULL(()) +/** + * This is a wrapper of rb_bug() which automatically constructs appropriate + * message from the passed errno. + * + * @param[in] msg Additional message to display. + * @exception err C level errno. + * @note It never returns. + */ +void rb_bug_errno(const char *msg, int err); + +RBIMPL_ATTR_NORETURN() +/** + * Converts a C errno into a Ruby exception, then raises it. For instance: + * + * ```C + * static VALUE + * foo(VALUE argv) + * { + * const auto cmd = StringValueCStr(argv); + * const auto waitr = system(cmd); + * if (waitr == -1) { + * rb_sys_fail("system(3posix)"); // <-------------- this + * } + * else { + * return INT2FIX(fd); + * } + * } + * ``` + * + * @param[in] msg Additional message to raise. + * @exception rb_eSystemCallError An exception representing errno. + * @note It never returns. + */ +void rb_sys_fail(const char *msg); + +RBIMPL_ATTR_NORETURN() +/** + * Identical to rb_sys_fail(), except it takes the message in Ruby's String + * instead of C's. + * + * @param[in] msg Additional message to raise. + * @exception rb_eSystemCallError An exception representing errno. + * @note It never returns. + */ +void rb_sys_fail_str(VALUE msg); + +RBIMPL_ATTR_NORETURN() +RBIMPL_ATTR_NONNULL((2)) +/** + * Identical to rb_sys_fail(), except it takes additional module to extend the + * exception object before raising. + * + * @param[in] mod A ::rb_cModule instance. + * @param[in] msg Additional message to raise. + * @exception rb_eSystemCallError An exception representing errno. + * @note It never returns. + * + * @internal + * + * Does anybody use it? + */ +void rb_mod_sys_fail(VALUE mod, const char *msg); + +RBIMPL_ATTR_NORETURN() +/** + * Identical to rb_mod_sys_fail(), except it takes the message in Ruby's String + * instead of C's. + * + * @param[in] mod A ::rb_cModule instance. + * @param[in] msg Additional message to raise. + * @exception rb_eSystemCallError An exception representing errno. + * @note It never returns. + */ +void rb_mod_sys_fail_str(VALUE mod, VALUE msg); + +RBIMPL_ATTR_NORETURN() +/** + * Raises appropriate exception using the parameters. + * + * In Ruby level there are rb_eEAGAINWaitReadable etc. This function maps the + * given parameter to an appropriate exception class, then raises it. + * + * @param[in] waiting Reason for the IO to wait. + * @param[in] msg Additional message to raise. + * @exception rb_eEAGAINWaitWritable + * @exception rb_eEWOULDBLOCKWaitWritable + * @exception rb_eEINPROGRESSWaitWritable + * @exception rb_eEAGAINWaitReadable + * @exception rb_eEWOULDBLOCKWaitReadable + * @exception rb_eEINPROGRESSWaitReadable + * @exception rb_eSystemCallError + * @note It never returns. + */ +void rb_readwrite_sys_fail(enum rb_io_wait_readwrite waiting, const char *msg); + +RBIMPL_ATTR_NORETURN() +/** + * Breaks from a block. Because you are using a CAPI this is not as intuitive + * as it sounds. In order for this function to properly work, make a + * ::rb_block_call_func_t function that calls it internally, and pass that + * function to rb_block_call(). + * + * @exception rb_eLocalJumpError Called from outside of a block. + * @note It never returns. + */ +void rb_iter_break(void); + +RBIMPL_ATTR_NORETURN() +/** + * Identical to rb_iter_break(), except it additionally takes the "value" of + * this breakage. It will be the evaluation result of the iterator. This is + * kind of complicated; you cannot see this as a "return from a block" + * behaviour. Take a look at this example: + * + * ```ruby + * def foo(q) + * puts(w = yield(q)) + * puts(e = yield(w)) + * puts(r = yield(e)) + * puts(t = yield(r)) + * puts(y = yield(t)) + * return "howdy!" + * end + * + * x = foo(0) {|i| + * if i > 2 + * break "hello!" + * else + * next i + 1 + * end + * } + * + * puts x + * ``` + * + * This script outputs 1, 2, 3, and hello. Note that the value passed to break + * becomes the return value of foo method, not the value of yield. This is + * confusing, but can be handy on occasions e.g. when you want to bring a + * local variable out of a block. + * + * @param[in] val The value of the iterator. + * @exception rb_eLocalJumpError Called from outside of a block. + * @note It never returns. + */ +void rb_iter_break_value(VALUE val); + +RBIMPL_ATTR_NORETURN() +/** + * Terminates the current execution context. This API is the entry point of a + * "well-mannered" termination sequence. When called from an extension + * library, it raises ::rb_eSystemExit exception. Programs could rescue that + * exception. Can cancel process exit then. Otherwise, that exception results + * in a process termination with the status passed to this function. + * + * @param[in] status Exit status, see also exit(3). + * @exception rb_eSystemExit Exception representing the exit status. + * @note It never returns. + * + * @internal + * + * "When called from an extension library"? You might wonder. In fact there + * are chances for this function to be called from outside of it, for instance + * when dlopen(3) failed. In case it is not possible for this function to + * raise an exception, it does not (silently enters to process cleanup). But + * that is a kind of implementation detail which extension library authors + * should not bother. + */ +void rb_exit(int status); + +RBIMPL_ATTR_NORETURN() +/** + * @exception rb_eNotImpError + * @note It never returns. + */ +void rb_notimplement(void); + +/** + * Creates an exception object that represents the given C errno. + * + * @param[in] err C level errno. + * @param[in] msg Additional message. + * @retval rb_eSystemCallError An exception for the errno. + */ +VALUE rb_syserr_new(int err, const char * msg); + +/** + * Identical to rb_syserr_new(), except it takes the message in Ruby's String + * instead of C's. + * + * @param[in] n C level errno. + * @param[in] arg Additional message. + * @retval rb_eSystemCallError An exception for the errno. + */ VALUE rb_syserr_new_str(int n, VALUE arg); -NORETURN(void rb_syserr_fail(int, const char*)); -NORETURN(void rb_syserr_fail_str(int, VALUE)); -NORETURN(void rb_mod_syserr_fail(VALUE, int, const char*)); -NORETURN(void rb_mod_syserr_fail_str(VALUE, int, VALUE)); -NORETURN(void rb_readwrite_syserr_fail(enum rb_io_wait_readwrite, int, const char*)); -COLDFUNC NORETURN(void rb_unexpected_type(VALUE,int)); +RBIMPL_ATTR_NORETURN() +/** + * Raises appropriate exception that represents a C errno. + * + * @param[in] err C level errno. + * @param[in] msg Additional message to raise. + * @exception rb_eSystemCallError An exception representing `err`. + * @note It never returns. + */ +void rb_syserr_fail(int err, const char *msg); + +RBIMPL_ATTR_NORETURN() +/** + * Identical to rb_syserr_fail(), except it takes the message in Ruby's String + * instead of C's. + * + * @param[in] err C level errno. + * @param[in] msg Additional message to raise. + * @exception rb_eSystemCallError An exception representing `err`. + * @note It never returns. + */ +void rb_syserr_fail_str(int err, VALUE msg); + +RBIMPL_ATTR_NORETURN() +RBIMPL_ATTR_NONNULL(()) +/** + * Identical to rb_mod_sys_fail(), except it does not depend on C global + * variable errno. Pass it explicitly. + * + * @param[in] mod A ::rb_cModule instance. + * @param[in] err C level errno. + * @param[in] msg Additional message to raise. + * @exception rb_eSystemCallError An exception representing `err`. + * @note It never returns. + */ +void rb_mod_syserr_fail(VALUE mod, int err, const char *msg); + +RBIMPL_ATTR_NORETURN() +/** + * Identical to rb_mod_syserr_fail(), except it takes the message in Ruby's + * String instead of C's. + * + * @param[in] mod A ::rb_cModule instance. + * @param[in] err C level errno. + * @param[in] msg Additional message to raise. + * @exception rb_eSystemCallError An exception representing `err`. + * @note It never returns. + */ +void rb_mod_syserr_fail_str(VALUE mod, int err, VALUE msg); + +RBIMPL_ATTR_NORETURN() +/** + * Identical to rb_readwrite_sys_fail(), except it does not depend on C global + * variable errno. Pass it explicitly. + * + * @param[in] waiting Reason for the IO to wait. + * @param[in] err C level errno. + * @param[in] msg Additional message to raise. + * @exception rb_eEAGAINWaitWritable + * @exception rb_eEWOULDBLOCKWaitWritable + * @exception rb_eEINPROGRESSWaitWritable + * @exception rb_eEAGAINWaitReadable + * @exception rb_eEWOULDBLOCKWaitReadable + * @exception rb_eEINPROGRESSWaitReadable + * @exception rb_eSystemCallError + * @note It never returns. + */ +void rb_readwrite_syserr_fail(enum rb_io_wait_readwrite waiting, int err, const char *msg); + +RBIMPL_ATTR_COLD() +RBIMPL_ATTR_NORETURN() +/** + * Fails with the given object's type incompatibility to the type. + * + * It seems this function is visible from extension libraries only because + * RTYPEDDATA_TYPE() uses it on RUBY_DEBUG. So you can basically ignore it; + * use some other fine-grained method instead. + * + * @param[in] self The object in question. + * @param[in] t Expected type of the object. + * @exception rb_eTypeError `self` not in type `t`. + * @note It never returns. + * @note The second argument must have been an enum ::ruby_value_type, + * but for historical reasons it remains to be an int (in other + * words we see no benefits fixing this bug). + */ +void rb_unexpected_type(VALUE self, int t); + +/** + * @private + * + * This is an implementation detail of #ruby_verbose. Please don't use it + * directly. + * + * @retval Qnil Interpreter is quiet. + * @retval Qfalse Interpreter is kind of chatty. + * @retval otherwise Interpreter is very verbose. + */ VALUE *rb_ruby_verbose_ptr(void); + +/** + * @private + * + * This is an implementation detail of #ruby_debug. Please don't use it + * directly. + * + * @retval Qnil Interpreter not in debug mode. + * @retval Qfalse Interpreter not in debug mode. + * @retval otherwise Interpreter is in debug mode. + */ VALUE *rb_ruby_debug_ptr(void); + +/** + * This variable controls whether the interpreter is in debug mode. Setting + * this to some truthy value is equivalent to passing `-W` flag to the + * interpreter. Setting this to ::Qfalse is equivalent to passing `-W1` flag + * to the interpreter. Setting this to ::Qnil is equivalent to passing `-W0` + * flag to the interpreter. + * + * @retval Qnil Interpreter is quiet. + * @retval Qfalse Interpreter is kind of chatty. + * @retval otherwise Interpreter is very verbose. + */ #define ruby_verbose (*rb_ruby_verbose_ptr()) + +/** + * This variable controls whether the interpreter is in debug mode. Setting + * this to some truthy value is equivalent to passing `-d` flag to the + * interpreter. + * + * @retval Qnil Interpreter not in debug mode. + * @retval Qfalse Interpreter not in debug mode. + * @retval otherwise Interpreter is in debug mode. + */ #define ruby_debug (*rb_ruby_debug_ptr()) /* reports if `-W' specified */ -PRINTF_ARGS(void rb_warning(const char*, ...), 1, 2); -PRINTF_ARGS(void rb_category_warning(rb_warning_category_t, const char*, ...), 2, 3); -PRINTF_ARGS(void rb_compile_warning(const char *, int, const char*, ...), 3, 4); -PRINTF_ARGS(void rb_category_compile_warn(rb_warning_category_t, const char *, int, const char*, ...), 4, 5); -PRINTF_ARGS(void rb_sys_warning(const char*, ...), 1, 2); +RBIMPL_ATTR_NONNULL((1)) +RBIMPL_ATTR_FORMAT(RBIMPL_PRINTF_FORMAT, 1, 2) +/** + * Issues a warning. + * + * In ruby, warnings these days are tightly coupled with the rb_mWarning + * constant and its `warn` singleton method. This CAPI is just a thin wrapper + * of it; everything passed are formatted like what rb_sprintf() does, then + * passed through to the method. Programs can have their own `def + * Warning.warn` at will to do whatever they want, from ignoring the warnings + * at all to sinking them to some BigQuery data set via a Fluentd cluster. By + * default, the method just emits its passed contents to ::rb_stderr using + * rb_io_write(). + * + * @note This function is affected by the `-W` flag. + * @param[in] fmt Format specifier string compatible with rb_sprintf(). + * + * @internal + * + * Above description is in fact inaccurate. This API interfaces with Ractors. + */ +void rb_warning(const char *fmt, ...); + +RBIMPL_ATTR_NONNULL((2)) +RBIMPL_ATTR_FORMAT(RBIMPL_PRINTF_FORMAT, 2, 3) +/** + * Identical to rb_warning(), except it takes additional "category" parameter. + * + * @param[in] cat Name of a known category. + * @param[in] fmt Format specifier string compatible with rb_sprintf(). + */ +void rb_category_warning(rb_warning_category_t cat, const char *fmt, ...); + +RBIMPL_ATTR_NONNULL((1, 3)) +RBIMPL_ATTR_FORMAT(RBIMPL_PRINTF_FORMAT, 3, 4) +/** + * Issues a compile-time warning that happens at `__file__:__line__`. Purpose + * of this function being exposed to CAPI is unclear. + * + * @note This function is affected by the `-W` flag. + * @param[in] file The path corresponding to Ruby level `__FILE__`. + * @param[in] line The number corresponding to Ruby level `__LINE__`. + * @param[in] fmt Format specifier string compatible with rb_sprintf(). + */ +void rb_compile_warning(const char *file, int line, const char *fmt, ...); + +RBIMPL_ATTR_NONNULL((1)) +RBIMPL_ATTR_FORMAT(RBIMPL_PRINTF_FORMAT, 1, 2) +/** + * Identical to rb_sys_fail(), except it does not raise an exception to render + * a warning instead. + * + * @note This function is affected by the `-W` flag. + * @param[in] fmt Format specifier string compatible with rb_sprintf(). + */ +void rb_sys_warning(const char *fmt, ...); + /* reports always */ -COLDFUNC PRINTF_ARGS(void rb_warn(const char*, ...), 1, 2); -COLDFUNC PRINTF_ARGS(void rb_category_warn(rb_warning_category_t, const char*, ...), 2, 3); -PRINTF_ARGS(void rb_compile_warn(const char *, int, const char*, ...), 3, 4); +RBIMPL_ATTR_COLD() +RBIMPL_ATTR_NONNULL((1)) +RBIMPL_ATTR_FORMAT(RBIMPL_PRINTF_FORMAT, 1, 2) +/** + * Identical to rb_warning(), except it reports always regardless of runtime + * `-W` flag. + * + * @param[in] fmt Format specifier string compatible with rb_sprintf(). + */ +void rb_warn(const char *fmt, ...); + +RBIMPL_ATTR_COLD() +RBIMPL_ATTR_NONNULL((2)) +RBIMPL_ATTR_FORMAT(RBIMPL_PRINTF_FORMAT, 2, 3) +/** + * Identical to rb_category_warning(), except it reports always regardless of + * runtime `-W` flag. + * + * @param[in] cat Category e.g. deprecated. + * @param[in] fmt Format specifier string compatible with rb_sprintf(). + */ +void rb_category_warn(rb_warning_category_t cat, const char *fmt, ...); + +RBIMPL_ATTR_NONNULL((1, 3)) +RBIMPL_ATTR_FORMAT(RBIMPL_PRINTF_FORMAT, 3, 4) +/** + * Identical to rb_compile_warning(), except it reports always regardless of + * runtime `-W` flag. + * + * @param[in] file The path corresponding to Ruby level `__FILE__`. + * @param[in] line The number corresponding to Ruby level `__LINE__`. + * @param[in] fmt Format specifier string compatible with rb_sprintf(). + */ +void rb_compile_warn(const char *file, int line, const char *fmt, ...); + +RBIMPL_ATTR_NONNULL((2, 4)) +RBIMPL_ATTR_FORMAT(RBIMPL_PRINTF_FORMAT, 4, 5) +/** + * Identical to rb_compile_warn(), except it also accepts category. + * + * @param[in] cat Category e.g. deprecated. + * @param[in] file The path corresponding to Ruby level `__FILE__`. + * @param[in] line The number corresponding to Ruby level `__LINE__`. + * @param[in] fmt Format specifier string compatible with rb_sprintf(). + */ +void rb_category_compile_warn(rb_warning_category_t cat, const char *file, int line, const char *fmt, ...); + +/** @} */ RBIMPL_SYMBOL_EXPORT_END()