Ruby
3.4.0dev (2024-11-05 revision 348a53415339076afc4a02fcd09f3ae36e9c4c61)
|
Registering values to the GC. More...
#include "ruby/internal/config.h"
#include "ruby/assert.h"
#include "ruby/internal/attr/cold.h"
#include "ruby/internal/attr/nonnull.h"
#include "ruby/internal/attr/noreturn.h"
#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"
Go to the source code of this file.
Macros | |
#define | RUBY_REF_EDGE(s, p) offsetof(s, p) |
#define | RUBY_REFS_LIST_PTR(l) (RUBY_DATA_FUNC)(uintptr_t)(l) |
#define | RUBY_REF_END SIZE_MAX |
#define | RUBY_REFERENCES(t) static const size_t t[] |
#define | RUBY_REFERENCES_START(t) RUBY_REFERENCES(t) = { |
#define | RUBY_REFERENCES_END RUBY_REF_END, }; |
#define | USE_RGENGC 1 |
#define | USE_RGENGC_LOGGING_WB_UNPROTECT 0 |
#define | RGENGC_WB_PROTECTED_ARRAY 1 |
This is a compile-time flag to enable/disable write barrier for struct RArray. More... | |
#define | RGENGC_WB_PROTECTED_HASH 1 |
This is a compile-time flag to enable/disable write barrier for struct RHash. More... | |
#define | RGENGC_WB_PROTECTED_STRUCT 1 |
This is a compile-time flag to enable/disable write barrier for struct RStruct. More... | |
#define | RGENGC_WB_PROTECTED_STRING 1 |
This is a compile-time flag to enable/disable write barrier for struct RString. More... | |
#define | RGENGC_WB_PROTECTED_OBJECT 1 |
This is a compile-time flag to enable/disable write barrier for struct RObject. More... | |
#define | RGENGC_WB_PROTECTED_REGEXP 1 |
This is a compile-time flag to enable/disable write barrier for struct RRegexp. More... | |
#define | RGENGC_WB_PROTECTED_MATCH 1 |
This is a compile-time flag to enable/disable write barrier for struct RMatch. More... | |
#define | RGENGC_WB_PROTECTED_CLASS 1 |
This is a compile-time flag to enable/disable write barrier for struct RClass. More... | |
#define | RGENGC_WB_PROTECTED_FLOAT 1 |
This is a compile-time flag to enable/disable write barrier for struct RFloat. More... | |
#define | RGENGC_WB_PROTECTED_COMPLEX 1 |
This is a compile-time flag to enable/disable write barrier for struct RComplex. More... | |
#define | RGENGC_WB_PROTECTED_RATIONAL 1 |
This is a compile-time flag to enable/disable write barrier for struct RRational. More... | |
#define | RGENGC_WB_PROTECTED_BIGNUM 1 |
This is a compile-time flag to enable/disable write barrier for struct RBignum. More... | |
#define | RGENGC_WB_PROTECTED_NODE_CREF 1 |
#define | RB_OBJ_WRITE(old, slot, young) RBIMPL_CAST(rb_obj_write((VALUE)(old), (VALUE *)(slot), (VALUE)(young), __FILE__, __LINE__)) |
Declaration of a "back" pointer. More... | |
#define | RB_OBJ_WRITTEN(old, oldv, young) RBIMPL_CAST(rb_obj_written((VALUE)(old), (VALUE)(oldv), (VALUE)(young), __FILE__, __LINE__)) |
Identical to RB_OBJ_WRITE(), except it doesn't write any values, but only a WB declaration. More... | |
#define | OBJ_PROMOTED_RAW RB_OBJ_PROMOTED_RAW |
Old name of RB_OBJ_PROMOTED_RAW. More... | |
#define | OBJ_PROMOTED RB_OBJ_PROMOTED |
Old name of RB_OBJ_PROMOTED. More... | |
#define | OBJ_WB_UNPROTECT RB_OBJ_WB_UNPROTECT |
Old name of RB_OBJ_WB_UNPROTECT. More... | |
#define | RB_OBJ_WB_UNPROTECT(x) rb_obj_wb_unprotect(x, __FILE__, __LINE__) |
Asserts that the passed object is not fenced by write barriers. More... | |
#define | RB_OBJ_WB_UNPROTECT_FOR(type, obj) (RGENGC_WB_PROTECTED_##type ? OBJ_WB_UNPROTECT(obj) : obj) |
Identical to RB_OBJ_WB_UNPROTECT(), except it can also assert that the given object is of given type. More... | |
#define | RGENGC_LOGGING_WB_UNPROTECT rb_gc_unprotect_logging |
This is an implementation detail of rb_obj_wb_unprotect(). More... | |
Functions | |
void | rb_memerror (void) |
Triggers out-of-memory error. More... | |
int | rb_during_gc (void) |
Queries if the GC is busy. More... | |
void | rb_gc_mark_locations (const VALUE *start, const VALUE *end) |
Marks objects between the two pointers. More... | |
void | rb_mark_tbl (struct st_table *tbl) |
Identical to rb_mark_hash(), except it marks only values of the table and leave their associated keys unmarked. More... | |
void | rb_mark_tbl_no_pin (struct st_table *tbl) |
Identical to rb_mark_tbl(), except it marks objects using rb_gc_mark_movable(). More... | |
void | rb_mark_set (struct st_table *tbl) |
Identical to rb_mark_hash(), except it marks only keys of the table and leave their associated values unmarked. More... | |
void | rb_mark_hash (struct st_table *tbl) |
Marks keys and values associated inside of the given table. More... | |
void | rb_gc_update_tbl_refs (st_table *ptr) |
Updates references inside of tables. More... | |
void | rb_gc_mark_maybe (VALUE obj) |
Identical to rb_gc_mark(), except it allows the passed value be a non-object. More... | |
void | rb_gc_mark (VALUE obj) |
Marks an object. More... | |
void | rb_gc_mark_movable (VALUE obj) |
Maybe this is the only function provided for C extensions to control the pinning of objects, so let us describe it in detail. More... | |
VALUE | rb_gc_location (VALUE obj) |
Finds a new "location" of an object. More... | |
void | rb_gc (void) |
Triggers a GC process. More... | |
void | rb_gc_copy_finalizer (VALUE dst, VALUE src) |
Copy&paste an object's finaliser to another. More... | |
VALUE | rb_gc_enable (void) |
(Re-) enables GC. More... | |
VALUE | rb_gc_disable (void) |
Disables GC. More... | |
VALUE | rb_gc_start (void) |
Identical to rb_gc(), except the return value. More... | |
VALUE | rb_define_finalizer (VALUE obj, VALUE block) |
Assigns a finaliser for an object. More... | |
VALUE | rb_undefine_finalizer (VALUE obj) |
Modifies the object so that it has no finalisers at all. More... | |
size_t | rb_gc_count (void) |
Identical to rb_gc_stat(), with "count" parameter. More... | |
size_t | rb_gc_stat (VALUE key_or_buf) |
Obtains various GC related profiles. More... | |
VALUE | rb_gc_latest_gc_info (VALUE key_or_buf) |
Obtains various info regarding the most recent GC run. More... | |
void | rb_gc_adjust_memory_usage (ssize_t diff) |
Informs that there are external memory usages. More... | |
void | rb_gc_register_address (VALUE *valptr) |
Inform the garbage collector that the global or static variable pointed by valptr stores a live Ruby object that should not be moved. More... | |
void | rb_global_variable (VALUE *) |
An alias for rb_gc_register_address() . More... | |
void | rb_gc_unregister_address (VALUE *valptr) |
Inform the garbage collector that a pointer previously passed to rb_gc_register_address() no longer points to a live Ruby object. More... | |
void | rb_gc_register_mark_object (VALUE object) |
Inform the garbage collector that object is a live Ruby object that should not be moved. More... | |
void | rb_gc_writebarrier (VALUE old, VALUE young) |
This is the implementation of RB_OBJ_WRITE(). More... | |
void | rb_gc_writebarrier_unprotect (VALUE obj) |
This is the implementation of RB_OBJ_WB_UNPROTECT(). More... | |
static bool | RB_OBJ_PROMOTED_RAW (VALUE obj) |
This is the implementation of RB_OBJ_PROMOTED(). More... | |
static bool | RB_OBJ_PROMOTED (VALUE obj) |
Tests if the object is "promoted" – that is, whether the object experienced one or more GC marks. More... | |
static VALUE | rb_obj_wb_unprotect (VALUE x, const char *filename, int line) |
This is the implementation of RB_OBJ_WB_UNPROTECT(). More... | |
static void | rb_gc_force_recycle (VALUE obj) |
Registering values to the GC.
RBIMPL
or rbimpl
are implementation details. Don't take them as canon. They could rapidly appear then vanish. The name (path) of this header file is also an implementation detail. Do not expect it to persist at the place it is now. Developers are free to move it anywhere anytime at will. __VA_ARGS__
is always available. We assume C99 for ruby itself but we don't assume languages of extension libraries. They could be written in C++98. Definition in file gc.h.
#define RB_OBJ_WB_UNPROTECT | ( | x | ) | rb_obj_wb_unprotect(x, __FILE__, __LINE__) |
#define RB_OBJ_WB_UNPROTECT_FOR | ( | type, | |
obj | |||
) | (RGENGC_WB_PROTECTED_##type ? OBJ_WB_UNPROTECT(obj) : obj) |
Identical to RB_OBJ_WB_UNPROTECT(), except it can also assert that the given object is of given type.
[in] | type | One of ARRAY , STRING , etc. |
[out] | obj | An object of type that would not be protected. |
#define RGENGC_LOGGING_WB_UNPROTECT rb_gc_unprotect_logging |
This is an implementation detail of rb_obj_wb_unprotect().
People don't use it directly.
#define RGENGC_WB_PROTECTED_ARRAY 1 |
#define RGENGC_WB_PROTECTED_BIGNUM 1 |
#define RGENGC_WB_PROTECTED_CLASS 1 |
#define RGENGC_WB_PROTECTED_COMPLEX 1 |
#define RGENGC_WB_PROTECTED_FLOAT 1 |
#define RGENGC_WB_PROTECTED_HASH 1 |
#define RGENGC_WB_PROTECTED_MATCH 1 |
#define RGENGC_WB_PROTECTED_NODE_CREF 1 |
Exists here for backwards compatibility only. You can safely forget about it.
#define RGENGC_WB_PROTECTED_OBJECT 1 |
#define RGENGC_WB_PROTECTED_RATIONAL 1 |
#define RGENGC_WB_PROTECTED_REGEXP 1 |
#define RGENGC_WB_PROTECTED_STRING 1 |
#define RGENGC_WB_PROTECTED_STRUCT 1 |
#define USE_RGENGC 1 |
Exists here for backwards compatibility only. You can safely forget about it.
#define USE_RGENGC_LOGGING_WB_UNPROTECT 0 |
Setting this to anything other than zero just doesn't compile. We need to KonMari.
Assigns a finaliser for an object.
Each objects can have objects (typically blocks) that run immediately after that object dies. They are called finalisers of an object. This function associates a finaliser object with a target object.
[in] | obj | Target to finalise. |
[in] | block | Something call able. |
rb_eRuntimeError | Somehow obj cannot have finalisers. |
rb_eFrozenError | obj is frozen. |
rb_eArgError | block doesn't respond to call . |
block
. block
runs after obj
dies. int rb_during_gc | ( | void | ) |
void rb_gc | ( | void | ) |
Triggers a GC process.
This was the only GC entry point that we had at the beginning. Over time our GC evolved. Now what this function does is just a very simplified variation of the entire GC algorithms. A series of procedures kicked by this API is called a "full" GC.
It is worth noting that the procedures above do not include evaluations of finalisers. They run later.
Definition at line 3370 of file gc.c.
Referenced by rb_gc_start(), and rb_reg_region_copy().
void rb_gc_adjust_memory_usage | ( | ssize_t | diff | ) |
Informs that there are external memory usages.
Our GC runs when we are running out of memory. The amount of memory, however, can increase/decrease behind-the-scene. For instance DLLs can allocate memories using mmap(2)
etc, which are opaque to us. Registering such external allocations using this function enables proper detection of how much memories an object used as a whole. That will trigger GCs more often than it would otherwise. You can also pass negative numbers here, to indicate that such external allocations are gone.
[in] | diff | Amount of memory increased(+)/decreased(-). |
Copy&paste an object's finaliser to another.
This is one of the GC utility functions that you can call when you design your own initialize_copy
, initialize_dup
, initialize_clone
.
[out] | dst | Destination object. |
[in] | src | Source object. |
dst
and src
share the same finaliser. size_t rb_gc_count | ( | void | ) |
Identical to rb_gc_stat(), with "count" parameter.
VALUE rb_gc_disable | ( | void | ) |
Disables GC.
This prevents automatic GC runs when the process is running out of memory. Such situations shall result in rb_memerror(). However this does not prevent users from manually invoking rb_gc(). That should work. People abused this by disabling GC at the beginning of an event loop, process events without GC overheads, then manually force reclaiming garbage at the bottom of the loop. However because our GC is now much smarter than just calling rb_gc(), this technique is proven to be sub-optimal these days. It is believed that there is currently practically no needs of this function.
RUBY_Qtrue | GC was disabled before. |
RUBY_Qfalse | GC was enabled before. |
VALUE rb_gc_enable | ( | void | ) |
(Re-) enables GC.
This makes sense only after you called rb_gc_disable().
RUBY_Qtrue | GC was disabled before. |
RUBY_Qfalse | GC was enabled before. |
Obtains various info regarding the most recent GC run.
This includes for instance the reason of the GC. The parameter can be either a Symbol or a Hash. If a Hash is passed, it is filled with everything currently available. If a Symbol is passed just that portion is returned.
Possible variations of keys you can pass here change from version to version. You can get the list of known keys by passing an empty hash and let it be filled.
[in,out] | key_or_buf | A Symbol, or a Hash. |
rb_eTypeError | Neither Symbol nor Hash. |
rb_eFrozenError | Frozen hash is passed. |
Finds a new "location" of an object.
An object can be moved on compaction. This function projects its new abode, or just returns the passed object if not moved. This is one of the GC utility functions that you can call when you design your own rb_data_type_struct::dcompact.
[in] | obj | An object, possibly already moved to somewhere else. |
obj
. void rb_gc_mark | ( | VALUE | obj | ) |
Marks an object.
This is one of the GC utility functions that you can call when you design your own rb_data_type_struct::dmark.
[out] | obj | Arbitrary Ruby object. |
obj
is marked. Marks objects between the two pointers.
This is one of the GC utility functions that you can call when you design your own rb_data_type_struct::dmark.
start
to end
shall be fully addressable. [out] | start | Pointer to an array of objects. |
[out] | end | Pointer that terminates the array of objects. |
start
(included) to end
(excluded) are marked. void rb_gc_mark_maybe | ( | VALUE | obj | ) |
Identical to rb_gc_mark(), except it allows the passed value be a non-object.
For instance pointers to different type of memory regions are allowed here. Such values are silently ignored. This is one of the GC utility functions that you can call when you design your own rb_data_type_struct::dmark.
[out] | obj | A possible object. |
obj
is marked, if possible. void rb_gc_mark_movable | ( | VALUE | obj | ) |
Maybe this is the only function provided for C extensions to control the pinning of objects, so let us describe it in detail.
These days Ruby's GC is copying. As far as an object's physical address is guaranteed unused, it can move around the object space. Our GC engine rearranges these objects after it reclaims unreachable objects from our object space, so that the space is compact (improves memory locality). This is called the "compaction" phase, and works well most of the time... as far as there are no C extensions. C extensions complicate the scenario because Ruby core cannot detect any use of the physical address of an object inside of C functions. In order to prevent memory corruptions, objects observable from C extensions are "pinned"; they stick to where they are born until they die, just in case any C extensions touch their raw pointers. This variant of scheme is called "Mostly-Copying" garbage collector. Authors of C extensions, however, can extremely carefully write them to become compaction-aware. To do so avoid referring to a Ruby object from inside of your struct in the first place. But if that is not possible, use this function from your rb_data_type_struct::dmark then. This way objects marked using it are considered movable. If you chose this way you have to manually fix up locations of such moved pointers using rb_gc_location().
[in] | obj | Object that is movable. |
tbl
are marked. void rb_gc_register_address | ( | VALUE * | valptr | ) |
Inform the garbage collector that the global or static variable pointed by valptr
stores a live Ruby object that should not be moved.
Note that extensions should use this API on global constants instead of assuming constants defined in Ruby are always alive. Ruby code can remove global constants.
Because this registration itself has a possibility to trigger a GC, this function must be called before any GC-able objects is assigned to the address pointed by valptr
.
Definition at line 2795 of file gc.c.
Referenced by rb_global_variable(), and ruby_init_loadpath().
void rb_gc_register_mark_object | ( | VALUE | object | ) |
Inform the garbage collector that object
is a live Ruby object that should not be moved.
See also: rb_gc_register_address()
VALUE rb_gc_start | ( | void | ) |
size_t rb_gc_stat | ( | VALUE | key_or_buf | ) |
Obtains various GC related profiles.
The parameter can be either a Symbol or a Hash. If a Hash is passed, it is filled with everything currently available. If a Symbol is passed just that portion is returned.
Possible variations of keys you can pass here change from version to version. You can get the list of known keys by passing an empty hash and let it be filled.
[in,out] | key_or_buf | A Symbol, or a Hash. |
rb_eTypeError | Neither Symbol nor Hash. |
rb_eFrozenError | Frozen hash is passed. |
void rb_gc_unregister_address | ( | VALUE * | valptr | ) |
Inform the garbage collector that a pointer previously passed to rb_gc_register_address()
no longer points to a live Ruby object.
void rb_gc_update_tbl_refs | ( | st_table * | ptr | ) |
Updates references inside of tables.
After you marked values using rb_mark_tbl_no_pin(), the objects inside of the table could of course be moved. This function is to fixup those references. You can call this from your rb_data_type_struct::dcompact.
[out] | ptr | A table that potentially includes moved references. |
This is the implementation of RB_OBJ_WRITE().
People don't use it directly.
[in] | old | An object that points to young . |
[out] | young | An object that is referenced from old . |
void rb_gc_writebarrier_unprotect | ( | VALUE | obj | ) |
This is the implementation of RB_OBJ_WB_UNPROTECT().
People don't use it directly.
[out] | obj | An object that does not participate in WB. |
Definition at line 2744 of file gc.c.
Referenced by rb_obj_wb_unprotect().
void rb_global_variable | ( | VALUE * | var | ) |
An alias for rb_gc_register_address()
.
void rb_mark_hash | ( | struct st_table * | tbl | ) |
Marks keys and values associated inside of the given table.
This is one of the GC utility functions that you can call when you design your own rb_data_type_struct::dmark.
[in] | tbl | A table to mark. |
tbl
are marked. void rb_mark_set | ( | struct st_table * | tbl | ) |
Identical to rb_mark_hash(), except it marks only keys of the table and leave their associated values unmarked.
This is one of the GC utility functions that you can call when you design your own rb_data_type_struct::dmark.
[in] | tbl | A table to mark. |
tbl
are marked. void rb_mark_tbl | ( | struct st_table * | tbl | ) |
Identical to rb_mark_hash(), except it marks only values of the table and leave their associated keys unmarked.
This is one of the GC utility functions that you can call when you design your own rb_data_type_struct::dmark.
[in] | tbl | A table to mark. |
tbl
are marked. void rb_mark_tbl_no_pin | ( | struct st_table * | tbl | ) |
Identical to rb_mark_tbl(), except it marks objects using rb_gc_mark_movable().
This is one of the GC utility functions that you can call when you design your own rb_data_type_struct::dmark.
[in] | tbl | A table to mark. |
tbl
are marked. void rb_memerror | ( | void | ) |
Triggers out-of-memory error.
If possible it raises rb_eNoMemError. But because we are running out of memory that is not always doable. This function tries hard to show something, but ultimately can die silently.
rb_eNoMemError | Raises it if possible. |
|
inlinestatic |
Tests if the object is "promoted" – that is, whether the object experienced one or more GC marks.
[in] | obj | An object to query. |
true | The object is "promoted". |
false | The object is young. Have not experienced GC at all. |
|
inlinestatic |
This is the implementation of RB_OBJ_PROMOTED().
People don't use it directly.
[in] | obj | An object to query. |
true | The object is "promoted". |
false | The object is young. Have not experienced GC at all. |
Definition at line 706 of file gc.h.
Referenced by RB_OBJ_PROMOTED().
This is the implementation of RB_OBJ_WB_UNPROTECT().
People don't use it directly.
[out] | x | An object that does not participate in WB. |
[in] | filename | C's __FILE__ of the caller function. |
[in] | line | C's __LINE__ of the caller function. |
Modifies the object so that it has no finalisers at all.
This function is mainly provided for symmetry. No practical usages can be thought of.
[out] | obj | Object to clear its finalisers. |
rb_eFrozenError | obj is frozen. |
obj
. obj
has no finalisers. obj
could have. All you can do is to clear them all.