[前][次][番号順一覧][スレッド一覧]

ruby-changes:67718

From: =E5=8D=9C=E9=83=A8=E6=98=8C=E5=B9=B3 <ko1@a...>
Date: Fri, 10 Sep 2021 20:00:52 +0900 (JST)
Subject: [ruby-changes:67718] c3c0bf6823 (master): include/ruby/internal/rgengc.h: add dosygen

https://git.ruby-lang.org/ruby.git/commit/?id=c3c0bf6823

From c3c0bf6823ed86981235b71b83cb420d272532cb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=8D=9C=E9=83=A8=E6=98=8C=E5=B9=B3?=
 <shyouhei@r...>
Date: Thu, 7 Jan 2021 10:27:53 +0900
Subject: include/ruby/internal/rgengc.h: add dosygen

Must not be a bad idea to improve documents. [ci skip]
---
 include/ruby/internal/rgengc.h | 284 ++++++++++++++++++++++++++++++++++++++---
 template/Doxyfile.tmpl         |   1 +
 2 files changed, 265 insertions(+), 20 deletions(-)

diff --git a/include/ruby/internal/rgengc.h b/include/ruby/internal/rgengc.h
index a41e75c..7ea0444 100644
--- a/include/ruby/internal/rgengc.h
+++ b/include/ruby/internal/rgengc.h
@@ -22,106 +22,250 @@ https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/rgengc.h#L22
  * @see        Sasada,  K.,  "Gradual  write-barrier   insertion  into  a  Ruby
  *             interpreter",   in  proceedings   of   the   2019  ACM   SIGPLAN
  *             International  Symposium on  Memory Management  (ISMM 2019),  pp
- *             115-121, 2019. https://doi.org/10.1145/3315573.3329986
+ *             115-121, 2019.  https://doi.org/10.1145/3315573.3329986
  */
 #include "ruby/internal/attr/artificial.h"
+#include "ruby/internal/attr/maybe_unused.h"
 #include "ruby/internal/attr/pure.h"
 #include "ruby/internal/dllexport.h"
 #include "ruby/internal/special_consts.h"
 #include "ruby/internal/stdbool.h"
 #include "ruby/internal/value.h"
 #include "ruby/assert.h"
-#include "ruby/backward/2/attributes.h"
 
+/**
+ * @private
+ *
+ * @deprecated  This macro once was a thing in the old days, but makes no sense
+ *              any  longer today.   Exists  here  for backwards  compatibility
+ *              only.  You can safely forget about it.
+ */
 #undef USE_RGENGC
 #define USE_RGENGC 1
 
+/**
+ * @private
+ *
+ * This is  a compile-time flag  to enable/disable incremental GC  feature.  It
+ * has to  be set at  the time  ruby itself compiles.   Makes no sense  for 3rd
+ * parties.  It is safe  for them to set this though;  that just doesn't change
+ * anything.
+ */
 #ifndef USE_RINCGC
 # define USE_RINCGC 1
 #endif
 
+/**
+ * @deprecated  This macro seems  broken.  Setting this to  anything other than
+ *              zero just doesn't compile.  We need to KonMari.
+ */
 #ifndef USE_RGENGC_LOGGING_WB_UNPROTECT
 # define USE_RGENGC_LOGGING_WB_UNPROTECT 0
 #endif
 
+/**
+ * @private
+ *
+ * This  is   a  compile-time   flag  to   enable/disable  write   barrier  for
+ * struct ::RArray.  It has to be set  at the time ruby itself compiles.  Makes
+ * no sense for 3rd parties.
+ */
 #ifndef RGENGC_WB_PROTECTED_ARRAY
 # define RGENGC_WB_PROTECTED_ARRAY 1
 #endif
 
+/**
+ * @private
+ *
+ * This  is   a  compile-time   flag  to   enable/disable  write   barrier  for
+ * struct ::RHash.  It has  to be set at the time  ruby itself compiles.  Makes
+ * no sense for 3rd parties.
+ */
 #ifndef RGENGC_WB_PROTECTED_HASH
 # define RGENGC_WB_PROTECTED_HASH 1
 #endif
 
+/**
+ * @private
+ *
+ * This  is   a  compile-time   flag  to   enable/disable  write   barrier  for
+ * struct ::RStruct.  It has to be set at the time ruby itself compiles.  Makes
+ * no sense for 3rd parties.
+ */
 #ifndef RGENGC_WB_PROTECTED_STRUCT
 # define RGENGC_WB_PROTECTED_STRUCT 1
 #endif
 
+/**
+ * @private
+ *
+ * This  is   a  compile-time   flag  to   enable/disable  write   barrier  for
+ * struct ::RString.  It has to be set at the time ruby itself compiles.  Makes
+ * no sense for 3rd parties.
+ */
 #ifndef RGENGC_WB_PROTECTED_STRING
 # define RGENGC_WB_PROTECTED_STRING 1
 #endif
 
+/**
+ * @private
+ *
+ * This  is   a  compile-time   flag  to   enable/disable  write   barrier  for
+ * struct ::RObject.  It has to be set at the time ruby itself compiles.  Makes
+ * no sense for 3rd parties.
+ */
 #ifndef RGENGC_WB_PROTECTED_OBJECT
 # define RGENGC_WB_PROTECTED_OBJECT 1
 #endif
 
+/**
+ * @private
+ *
+ * This  is   a  compile-time   flag  to   enable/disable  write   barrier  for
+ * struct ::RRegexp.  It has to be set at the time ruby itself compiles.  Makes
+ * no sense for 3rd parties.
+ */
 #ifndef RGENGC_WB_PROTECTED_REGEXP
 # define RGENGC_WB_PROTECTED_REGEXP 1
 #endif
 
+/**
+ * @private
+ *
+ * This  is   a  compile-time   flag  to   enable/disable  write   barrier  for
+ * struct ::RClass.  It has to be set  at the time ruby itself compiles.  Makes
+ * no sense for 3rd parties.
+ */
 #ifndef RGENGC_WB_PROTECTED_CLASS
 # define RGENGC_WB_PROTECTED_CLASS 1
 #endif
 
+/**
+ * @private
+ *
+ * This  is   a  compile-time   flag  to   enable/disable  write   barrier  for
+ * struct ::RFloat.  It has to be set  at the time ruby itself compiles.  Makes
+ * no sense for 3rd parties.
+ */
 #ifndef RGENGC_WB_PROTECTED_FLOAT
 # define RGENGC_WB_PROTECTED_FLOAT 1
 #endif
 
+/**
+ * @private
+ *
+ * This  is   a  compile-time   flag  to   enable/disable  write   barrier  for
+ * struct ::RComplex.   It has  to be  set at  the time  ruby itself  compiles.
+ * Makes no sense for 3rd parties.
+ */
 #ifndef RGENGC_WB_PROTECTED_COMPLEX
 # define RGENGC_WB_PROTECTED_COMPLEX 1
 #endif
 
+/**
+ * @private
+ *
+ * This  is   a  compile-time   flag  to   enable/disable  write   barrier  for
+ * struct ::RRational.  It  has to  be set  at the  time ruby  itself compiles.
+ * Makes no sense for 3rd parties.
+ */
 #ifndef RGENGC_WB_PROTECTED_RATIONAL
 # define RGENGC_WB_PROTECTED_RATIONAL 1
 #endif
 
+/**
+ * @private
+ *
+ * This  is   a  compile-time   flag  to   enable/disable  write   barrier  for
+ * struct ::RBignum.  It has to be set at the time ruby itself compiles.  Makes
+ * no sense for 3rd parties.
+ */
 #ifndef RGENGC_WB_PROTECTED_BIGNUM
 # define RGENGC_WB_PROTECTED_BIGNUM 1
 #endif
 
+/**
+ * @private
+ *
+ * @deprecated  This macro once was a thing in the old days, but makes no sense
+ *              any  longer today.   Exists  here  for backwards  compatibility
+ *              only.  You can safely forget about it.
+ *
+ * @internal
+ *
+ * @shyouhei doesn't think anybody uses this right now.
+ */
 #ifndef RGENGC_WB_PROTECTED_NODE_CREF
 # define RGENGC_WB_PROTECTED_NODE_CREF 1
 #endif
 
 /**
- * @name Write barrier (WB) interfaces:
- * @{
+ * @defgroup rgengc Write barrier (WB) interfaces:
  *
  * @note The following  core interfaces can  be changed in the  future.  Please
  *       catch up if you want to insert WB into C-extensions correctly.
+ *
+ * @{
  */
 
 /**
- * WB for new  reference from `a' to  `b'. Write `b' into `*slot'.  `slot' is a
- * pointer in `a'.
+ * Declaration of a "back" pointer.  This  is a write barrier for new reference
+ * from  "old"  generation  to  "young" generation.   It  writes  `young`  into
+ * `*slot`, which is a pointer inside of `old`.
+ *
+ * @param[in]   old    An old object.
+ * @param[in]   slot   A pointer inside of `old`.
+ * @param[out]  young  A young object.
  */
-#define RB_OBJ_WRITE(a, slot, b) \
-    RBIMPL_CAST(rb_obj_write((VALUE)(a), (VALUE *)(slot), (VALUE)(b), __FILE__, __LINE__))
+#define RB_OBJ_WRITE(old, slot, young) \
+    RBIMPL_CAST(rb_obj_write((VALUE)(old), (VALUE *)(slot), (VALUE)(young), __FILE__, __LINE__))
+
 /**
- * WB for new  reference from `a' to  `b'.  This doesn't write  any values, but
- * only  a WB  declaration.  `oldv'  is replaced  value with  `b' (not  used in
- * current Ruby).
+ * Identical to #RB_OBJ_WRITE(), except it doesn't write any values, but only a
+ * WB declaration.   `oldv` is  replaced value  with `b`  (not used  in current
+ * Ruby).
+ *
+ * @param[in]   old    An old object.
+ * @param[in]   oldv   An object previously stored inside of `old`.
+ * @param[out]  young  A young object.
  */
-#define RB_OBJ_WRITTEN(a, oldv, b) \
-    RBIMPL_CAST(rb_obj_written((VALUE)(a), (VALUE)(oldv), (VALUE)(b), __FILE__, __LINE__))
+#define RB_OBJ_WRITTEN(old, oldv, young) \
+    RBIMPL_CAST(rb_obj_written((VALUE)(old), (VALUE)(oldv), (VALUE)(young), __FILE__, __LINE__))
 /** @} */
 
-#define OBJ_PROMOTED_RAW RB_OBJ_PROMOTED_RAW
-#define OBJ_PROMOTED     RB_OBJ_PROMOTED
-#define OBJ_WB_UNPROTECT RB_OBJ_WB_UNPROTECT
+#define OBJ_PROMOTED_RAW RB_OBJ_PROMOTED_RAW /**< @old{RB_OBJ_PROMOTED_RAW} */
+#define OBJ_PROMOTED     RB_OBJ_PROMOTED     /**< @old{RB_OBJ_PROMOTED} */
+#define OBJ_WB_UNPROTECT RB_OBJ_WB_UNPROTECT /**< @old{RB_OBJ_WB_UNPROTECT} */
 
+/**
+ * Asserts that the passed object is  not fenced by write barriers.  Objects of
+ * such  property do  not contribute  to  generational GCs.   They are  scanned
+ * always.
+ *
+ * @param[out]  x  An object that would not be protected by the barrier.
+ */
 #define RB_OBJ_WB_UNPROTECT(x) rb_obj_wb_unprotect(x, __FILE__, __LINE__)
+
+/**
+ * Identical  to #RB_OBJ_WB_UNPROTECT(),  except it  can also  assert that  the
+ * given object is of given type.
+ *
+ * @param[in]   type  One of `ARRAY`, `STRING`, etc.
+ * @param[out]  obj   An object of `type` that would not be protected.
+ *
+ * @internal
+ *
+ * @shyouhei doesn't understand why this has to be visible from extensions.
+ */
 #define RB_OBJ_WB_UNPROTECT_FOR(type, obj) \
     (RGENGC_WB_PROTECTED_##type ? OBJ_WB_UNPROTECT(obj) : obj)
+
+/**
+ * @private
+ *
+ * This is an implementation detail of rb_obj_wb_unprotect().  People don't use
+ * it directly.
+ */
 #define RGENGC_LOGGING_WB_UNPROTECT rb_gc_unprotect_logging
 
 /** @cond INTERNAL_MACRO */
@@ -130,15 +274,51 @@ https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/rgengc.h#L274
 /** @endcond */
 
 RBIMPL_SYMBOL_EXPORT_BEGIN()
-void rb_gc_writebarrier(VALUE a, VALUE b);
+/**
+ * This  is  the  implementation  of  #RB_OBJ_WRITE().   People  don't  use  it
+ * directly.
+ *
+ * @param[in]   old    An object that points to `young`.
+ * @param[out]  young  An object that is referenced from `old`.
+ */
+void rb_gc_writebarrier(VALUE old, VALUE young);
+
+/**
+ * This is the  implementation of #RB_OBJ_WB_UNPROTECT().  People  don't use it
+ * directly.
+ *
+ * @param[out] obj  An object that does not participate in WB.
+ */
 void rb_gc_w (... truncated)

--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/

[前][次][番号順一覧][スレッド一覧]