1berry/ruby
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Clarify C API documentation about pinned classes

Browse Source 
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.
This commit is contained in:
Jean Boussier 2024-02-29 17:15:06 +01:00 committed by Jean Boussier
parent e626da82ea
commit c09e5ad17d
3 changed files with 20 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
include/ruby/internal/intern/class.h
View File

@ -88,8 +88,8 @@ VALUE rb_define_class_id(ID id, VALUE super);
* @post `outer::id` refers the returned class. * @post `outer::id` refers the returned class.
* @note If a class named `id` is already defined and its superclass is * @note If a class named `id` is already defined and its superclass is
* `super`, the function just returns the defined class. * `super`, the function just returns the defined class.
* @note The compaction GC does not move classes returned by this * @note The GC does not collect nor move classes returned by this
* function. * function. They are immortal.
*/ */
VALUE rb_define_class_id_under(VALUE outer, ID id, VALUE super); 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. * constant is not a module.
* @return The created module. * @return The created module.
* @post `outer::id` refers the returned module. * @post `outer::id` refers the returned module.
* @note The compaction GC does not move classes returned by this * @note The GC does not collect nor move classes returned by this
* function. * function. They are immortal.
*/ */
VALUE rb_define_module_id_under(VALUE outer, ID id); VALUE rb_define_module_id_under(VALUE outer, ID id);

8
include/ruby/internal/intern/struct.h
View File

@ -54,6 +54,8 @@ VALUE rb_struct_new(VALUE klass, ...);
* @post Global toplevel constant `name` is defined. * @post Global toplevel constant `name` is defined.
* @note `name` is allowed to be a null pointer. This function creates * @note `name` is allowed to be a null pointer. This function creates
* an anonymous struct class then. * an anonymous struct class then.
* @note The GC does not collect nor move classes returned by this
* function. They are immortal.
* *
* @internal * @internal
* *
@ -78,6 +80,8 @@ RBIMPL_ATTR_NONNULL((2))
* @post `name` is a constant under `space`. * @post `name` is a constant under `space`.
* @note In contrast to rb_struct_define(), it doesn't make any sense to * @note In contrast to rb_struct_define(), it doesn't make any sense to
* pass a null pointer to this function. * 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, ...); 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`. * @post `class_name` is a constant under `outer`.
* @note In contrast to rb_struct_define_without_accessor(), it doesn't * @note In contrast to rb_struct_define_without_accessor(), it doesn't
* make any sense to pass a null name. * 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, ...); 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. * NULL. Each of which are the name of fields.
* @exception rb_eArgError Duplicated field name. * @exception rb_eArgError Duplicated field name.
* @return The defined class. * @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, ...); VALUE rb_data_define(VALUE super, ...);

16
include/ruby/internal/module.h
View File

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