kotovalexarian-likes-github/ruby--ruby
1
0
Fork 0
mirror of https://github.com/ruby/ruby.git synced 2022-11-09 12:17:21 -05:00
Code Releases Activity

include/ruby/internal/error.h: add doxygen

Browse source 
Must not be a bad idea to improve documents.
This commit is contained in:
卜部昌平 2020-12-21 11:15:08 +09:00
parent 4881a3ed38
commit 1b6245ccdc
Notes: git 2021-09-10 20:01:48 +09:00
3 changed files with 528 additions and 45 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
error.c
View file

@ -45,7 +45,7 @@
#include "builtin.h"
/*!
* \defgroup exception Exception handlings
* \addtogroup exception
* \{
*/

14
eval.c
View file

@ -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)
{

557
include/ruby/internal/error.h
View file

@ -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()