Clarify C API documentation about pinned classes

They are not only pinned, but also immortal. Even if the constant referencing them is removed, they will remain alive. It's a precision worth noting.
ruby · Mar 1, 2024 · c09e5ad · c09e5ad
1 parent e626da8
commit c09e5ad
Show file tree

Hide file tree

Showing 3 changed files with 20 additions and 12 deletions.
diff --git a/include/ruby/internal/intern/class.h b/include/ruby/internal/intern/class.h
@@ -88,8 +88,8 @@ VALUE rb_define_class_id(ID id, VALUE super);
  * @post        `outer::id` refers the returned class.
  * @note        If a class named `id` is  already defined and its superclass is
  *              `super`, the function just returns the defined class.
- * @note        The  compaction  GC does  not  move  classes returned  by  this
- *              function.
+ * @note        The GC does not collect nor move classes returned by this
+ *              function. They are immortal.
  */
 VALUE rb_define_class_id_under(VALUE outer, ID id, VALUE super);
 
@@ -127,8 +127,8 @@ VALUE rb_define_module_id(ID id);
  *                             constant is not a module.
  * @return      The created module.
  * @post        `outer::id` refers the returned module.
- * @note        The  compaction  GC does  not  move  classes returned  by  this
- *              function.
+ * @note        The GC does not collect nor move classes returned by this
+ *              function. They are immortal.
  */
 VALUE rb_define_module_id_under(VALUE outer, ID id);
 

diff --git a/include/ruby/internal/intern/struct.h b/include/ruby/internal/intern/struct.h
@@ -54,6 +54,8 @@ VALUE rb_struct_new(VALUE klass, ...);
  * @post       Global toplevel constant `name` is defined.
  * @note       `name` is allowed  to be a null pointer.   This function creates
  *             an anonymous struct class then.
+ * @note       The GC does not collect nor move classes returned by this
+ *             function. They are immortal.
  *
  * @internal
  *
@@ -78,6 +80,8 @@ RBIMPL_ATTR_NONNULL((2))
  * @post        `name` is a constant under `space`.
  * @note        In contrast to rb_struct_define(), it doesn't make any sense to
  *              pass  a null pointer to this function.
+ * @note        The GC does not collect nor move classes returned by this
+ *              function. They are immortal.
  */
 VALUE rb_struct_define_under(VALUE space, const char *name, ...);
 
@@ -195,6 +199,8 @@ RBIMPL_ATTR_NONNULL((2))
  * @post        `class_name` is a constant under `outer`.
  * @note        In contrast to  rb_struct_define_without_accessor(), it doesn't
  *              make any sense to pass a null name.
+ * @note        The GC does not collect nor move classes returned by this
+ *              function. They are immortal.
  */
 VALUE rb_struct_define_without_accessor_under(VALUE outer, const char *class_name, VALUE super, rb_alloc_func_t alloc, ...);
 
@@ -209,6 +215,8 @@ VALUE rb_struct_define_without_accessor_under(VALUE outer, const char *class_nam
  *                             NULL.  Each of which are the name of fields.
  * @exception  rb_eArgError    Duplicated field name.
  * @return     The defined class.
+ * @note       The GC does not collect nor move classes returned by this
+ *             function. They are immortal.
  */
 VALUE rb_data_define(VALUE super, ...);
 

diff --git a/include/ruby/internal/module.h b/include/ruby/internal/module.h
@@ -56,8 +56,8 @@ RBIMPL_ATTR_NONNULL(())
  * @post       Top-level constant named `name` refers the returned class.
  * @note       If a class named `name` is already defined and its superclass is
  *             `super`, the function just returns the defined class.
- * @note       The  compaction  GC  does  not move  classes  returned  by  this
- *             function.
+ * @note       The GC does not collect nor move classes returned by this
+ *             function. They are immortal.
  *
  * @internal
  *
@@ -75,8 +75,8 @@ RBIMPL_ATTR_NONNULL(())
  *                            constant is not a module.
  * @return     The created module.
  * @post       Top-level constant named `name` refers the returned module.
- * @note       The  compaction  GC  does  not move  classes  returned  by  this
- *             function.
+ * @note       The GC does not collect nor move modules returned by this
+ *             function. They are immortal.
  *
  * @internal
  *
@@ -103,8 +103,8 @@ RBIMPL_ATTR_NONNULL(())
  * @post        `outer::name` refers the returned class.
  * @note        If a class  named `name` is already defined  and its superclass
  *              is `super`, the function just returns the defined class.
- * @note        The  compaction  GC does  not  move  classes returned  by  this
- *              function.
+ * @note        The GC does not collect nor move classes returned by this
+ *              function. They are immortal.
  */
 VALUE rb_define_class_under(VALUE outer, const char *name, VALUE super);
 
@@ -118,8 +118,8 @@ RBIMPL_ATTR_NONNULL(())
  *                             the constant is not a class.
  * @return      The created module.
  * @post        `outer::name` refers the returned module.
- * @note        The  compaction  GC does  not  move  classes returned  by  this
- *              function.
+ * @note        The GC does not collect nor move modules returned by this
+ *              function. They are immortal.
  */
 VALUE rb_define_module_under(VALUE outer, const char *name);