diff options
author | 卜部昌平 <shyouhei@ruby-lang.org> | 2021-02-01 14:51:15 +0900 |
---|---|---|
committer | 卜部昌平 <shyouhei@ruby-lang.org> | 2021-09-10 20:00:06 +0900 |
commit | 549e9383e46d9fb9074cef483caaf9b5af908199 (patch) | |
tree | d3cf4277b0a2a383eed94bf6243fc68526f82c00 /include/ruby | |
parent | ada4a0fdd231cce24407ad4a89f6e5fd56940b31 (diff) |
include/ruby/internal/core/robject.h: add doxygen
Must not be a bad idea to improve documents. [ci skip]
Notes
Notes:
Merged: https://github.com/ruby/ruby/pull/4815
Diffstat (limited to 'include/ruby')
-rw-r--r-- | include/ruby/internal/core/robject.h | 97 |
1 files changed, 93 insertions, 4 deletions
diff --git a/include/ruby/internal/core/robject.h b/include/ruby/internal/core/robject.h index 0d0436dad0..f2028063a6 100644 --- a/include/ruby/internal/core/robject.h +++ b/include/ruby/internal/core/robject.h @@ -34,35 +34,113 @@ #include "ruby/internal/value.h" #include "ruby/internal/value_type.h" +/** + * Convenient casting macro. + * + * @param obj An object, which is in fact an ::RRegexp. + * @return The passed object casted to ::RRegexp. + */ #define ROBJECT(obj) RBIMPL_CAST((struct RObject *)(obj)) +/** @cond INTERNAL_MACRO */ #define ROBJECT_EMBED_LEN_MAX ROBJECT_EMBED_LEN_MAX #define ROBJECT_EMBED ROBJECT_EMBED -/** @cond INTERNAL_MACRO */ #define ROBJECT_NUMIV ROBJECT_NUMIV #define ROBJECT_IVPTR ROBJECT_IVPTR #define ROBJECT_IV_INDEX_TBL ROBJECT_IV_INDEX_TBL /** @endcond */ -enum ruby_robject_flags { ROBJECT_EMBED = RUBY_FL_USER1 }; +/** + * @private + * + * Bits that you can set to ::RBasic::flags. + */ +enum ruby_robject_flags { + /** + * This flag has something to do with memory footprint. If the object is + * "small" enough, ruby tries to be creative to abuse padding bits of + * struct ::RObject for storing instance variables. This flag denotes that + * situation. + * + * @warning This bit has to be considered read-only. Setting/clearing + * this bit without corresponding fix up must cause immediate + * SEGV. Also, internal structures of an object change + * dynamically and transparently throughout of its lifetime. + * Don't assume it being persistent. + * + * @internal + * + * 3rd parties must not be aware that there even is more than one way to + * store instance variables. Might better be hidden. + */ + ROBJECT_EMBED = RUBY_FL_USER1 +}; -enum ruby_robject_consts { ROBJECT_EMBED_LEN_MAX = RBIMPL_EMBED_LEN_MAX_OF(VALUE) }; +/** + * This is an enum because GDB wants it (rather than a macro). People need not + * bother. + */ +enum ruby_robject_consts { + /** Max possible number of instance variables that can be embedded. */ + ROBJECT_EMBED_LEN_MAX = RBIMPL_EMBED_LEN_MAX_OF(VALUE) +}; struct st_table; +/** + * Ruby's ordinal objects. Unless otherwise special cased, all predefined and + * user-defined classes share this struct to hold their instances. + */ struct RObject { + + /** Basic part, including flags and class. */ struct RBasic basic; + + /** Object's specific fields. */ union { + + /** + * Object that use separated memory region for instance variables use + * this pattern. + */ struct { + + /** + * Number of instance variables. This is per object; objects might + * differ in this field even if they have the identical classes. + */ uint32_t numiv; + + /** Pointer to a C array that holds instance variables. */ VALUE *ivptr; - struct st_table *iv_index_tbl; /* shortcut for RCLASS_IV_INDEX_TBL(rb_obj_class(obj)) */ + + /** + * This is a table that holds instance variable name to index + * mapping. Used when accessing instance variables using names. + * + * @internal + * + * This is a shortcut for `RCLASS_IV_INDEX_TBL(rb_obj_class(obj))`. + */ + struct st_table *iv_index_tbl; } heap; + + /** + * Embedded instance variables. When an object is small enough, it + * uses this area to store the instance variables. + */ VALUE ary[ROBJECT_EMBED_LEN_MAX]; } as; }; RBIMPL_ATTR_PURE_UNLESS_DEBUG() RBIMPL_ATTR_ARTIFICIAL() +/** + * Queries the number of instance variables. + * + * @param[in] obj Object in question. + * @return Its number of instance variables. + * @pre `obj` must be an instance of ::RObject. + */ static inline uint32_t ROBJECT_NUMIV(VALUE obj) { @@ -78,6 +156,17 @@ ROBJECT_NUMIV(VALUE obj) RBIMPL_ATTR_PURE_UNLESS_DEBUG() RBIMPL_ATTR_ARTIFICIAL() +/** + * Queries the instance variables. + * + * @param[in] obj Object in question. + * @return Its instance variables, in C array. + * @pre `obj` must be an instance of ::RObject. + * + * @internal + * + * @shyouhei finds no reason for this to be visible from extension libraries. + */ static inline VALUE * ROBJECT_IVPTR(VALUE obj) { |