Ruby  3.4.0dev (2024-11-05 revision 348a53415339076afc4a02fcd09f3ae36e9c4c61)
Macros | Functions
gc.h File Reference

(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"
Include dependency graph for gc.h:
This graph shows which files directly or indirectly include this file:

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)
 

Detailed Description

Registering values to the GC.

Author
Ruby developers ruby-.nosp@m.core.nosp@m.@ruby.nosp@m.-lan.nosp@m.g.org
Warning
Symbols prefixed with either 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.
Note
To ruby-core: remember that this header can be possibly recursively included from extension libraries written in C++. Do not expect for instance __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.

Macro Definition Documentation

◆ RB_OBJ_WB_UNPROTECT

#define RB_OBJ_WB_UNPROTECT (   x)    rb_obj_wb_unprotect(x, __FILE__, __LINE__)

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.

Parameters
[out]xAn object that would not be protected by the barrier.

Definition at line 630 of file gc.h.

◆ RB_OBJ_WB_UNPROTECT_FOR

#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.

Parameters
[in]typeOne of ARRAY, STRING, etc.
[out]objAn object of type that would not be protected.

Definition at line 643 of file gc.h.

◆ RGENGC_LOGGING_WB_UNPROTECT

#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.

Definition at line 652 of file gc.h.

◆ RGENGC_WB_PROTECTED_ARRAY

#define RGENGC_WB_PROTECTED_ARRAY   1

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.

Definition at line 446 of file gc.h.

◆ RGENGC_WB_PROTECTED_BIGNUM

#define RGENGC_WB_PROTECTED_BIGNUM   1

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.

Definition at line 567 of file gc.h.

◆ RGENGC_WB_PROTECTED_CLASS

#define RGENGC_WB_PROTECTED_CLASS   1

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.

Definition at line 523 of file gc.h.

◆ RGENGC_WB_PROTECTED_COMPLEX

#define RGENGC_WB_PROTECTED_COMPLEX   1

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.

Definition at line 545 of file gc.h.

◆ RGENGC_WB_PROTECTED_FLOAT

#define RGENGC_WB_PROTECTED_FLOAT   1

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.

Definition at line 534 of file gc.h.

◆ RGENGC_WB_PROTECTED_HASH

#define RGENGC_WB_PROTECTED_HASH   1

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.

Definition at line 457 of file gc.h.

◆ RGENGC_WB_PROTECTED_MATCH

#define RGENGC_WB_PROTECTED_MATCH   1

This is a compile-time flag to enable/disable write barrier for struct RMatch.

It has to be set at the time ruby itself compiles. Makes no sense for 3rd parties.

Definition at line 512 of file gc.h.

◆ RGENGC_WB_PROTECTED_NODE_CREF

#define RGENGC_WB_PROTECTED_NODE_CREF   1
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.

Definition at line 582 of file gc.h.

◆ RGENGC_WB_PROTECTED_OBJECT

#define RGENGC_WB_PROTECTED_OBJECT   1

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.

Definition at line 490 of file gc.h.

◆ RGENGC_WB_PROTECTED_RATIONAL

#define RGENGC_WB_PROTECTED_RATIONAL   1

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.

Definition at line 556 of file gc.h.

◆ RGENGC_WB_PROTECTED_REGEXP

#define RGENGC_WB_PROTECTED_REGEXP   1

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.

Definition at line 501 of file gc.h.

◆ RGENGC_WB_PROTECTED_STRING

#define RGENGC_WB_PROTECTED_STRING   1

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.

Definition at line 479 of file gc.h.

◆ RGENGC_WB_PROTECTED_STRUCT

#define RGENGC_WB_PROTECTED_STRUCT   1

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.

Definition at line 468 of file gc.h.

◆ USE_RGENGC

#define USE_RGENGC   1
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.

Definition at line 428 of file gc.h.

◆ USE_RGENGC_LOGGING_WB_UNPROTECT

#define USE_RGENGC_LOGGING_WB_UNPROTECT   0
Deprecated:
This macro seems broken.

Setting this to anything other than zero just doesn't compile. We need to KonMari.

Definition at line 435 of file gc.h.

Function Documentation

◆ rb_define_finalizer()

VALUE rb_define_finalizer ( VALUE  obj,
VALUE  block 
)

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.

Note
Note that finalisers run after the object they finalise dies. You cannot for instance call its methods.
If your finaliser references the object it finalises that object loses any chance to become a garbage; effectively leaks memory until the end of the process.
Parameters
[in]objTarget to finalise.
[in]blockSomething callable.
Exceptions
rb_eRuntimeErrorSomehow obj cannot have finalisers.
rb_eFrozenErrorobj is frozen.
rb_eArgErrorblock doesn't respond to call.
Returns
The passed block.
Postcondition
block runs after obj dies.

Definition at line 1571 of file gc.c.

◆ rb_during_gc()

int rb_during_gc ( void  )

Queries if the GC is busy.

Return values
0It isn't.
1It is.

Definition at line 3378 of file gc.c.

◆ rb_gc()

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 immediately scans the entire object space to sort the dead.
  • It immediately reclaims any single dead bodies to reuse later.

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().

◆ rb_gc_adjust_memory_usage()

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.

Parameters
[in]diffAmount of memory increased(+)/decreased(-).

Definition at line 4368 of file gc.c.

◆ rb_gc_copy_finalizer()

void rb_gc_copy_finalizer ( VALUE  dst,
VALUE  src 
)

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.

Parameters
[out]dstDestination object.
[in]srcSource object.
Postcondition
dst and src share the same finaliser.

Definition at line 1486 of file gc.c.

◆ rb_gc_count()

size_t rb_gc_count ( void  )

Identical to rb_gc_stat(), with "count" parameter.

Returns
Lifetime total number of runs of GC.

Definition at line 3386 of file gc.c.

◆ rb_gc_disable()

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.

Return values
RUBY_QtrueGC was disabled before.
RUBY_QfalseGC was enabled before.
Postcondition
GC is disabled.

Definition at line 3566 of file gc.c.

◆ rb_gc_enable()

VALUE rb_gc_enable ( void  )

(Re-) enables GC.

This makes sense only after you called rb_gc_disable().

Return values
RUBY_QtrueGC was disabled before.
RUBY_QfalseGC was enabled before.
Postcondition
GC is enabled.

Definition at line 3532 of file gc.c.

◆ rb_gc_latest_gc_info()

VALUE rb_gc_latest_gc_info ( VALUE  key_or_buf)

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.

Parameters
[in,out]key_or_bufA Symbol, or a Hash.
Exceptions
rb_eTypeErrorNeither Symbol nor Hash.
rb_eFrozenErrorFrozen hash is passed.
Returns
In case a Hash is passed it returns that hash. Otherwise the profile value associated with the given key is returned.
Postcondition
In case a Hash is passed it is filled with values.

Definition at line 3398 of file gc.c.

◆ rb_gc_location()

VALUE rb_gc_location ( VALUE  obj)

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.

Parameters
[in]objAn object, possibly already moved to somewhere else.
Returns
An object, which holds the current contents of former obj.

Definition at line 3004 of file gc.c.

◆ rb_gc_mark()

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.

Parameters
[out]objArbitrary Ruby object.
Postcondition
obj is marked.

Definition at line 2094 of file gc.c.

◆ rb_gc_mark_locations()

void rb_gc_mark_locations ( const VALUE start,
const VALUE end 
)

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.

Precondition
Continuous memory region from start to end shall be fully addressable.
Parameters
[out]startPointer to an array of objects.
[out]endPointer that terminates the array of objects.
Postcondition
Objects from start (included) to end (excluded) are marked.

Definition at line 2160 of file gc.c.

◆ rb_gc_mark_maybe()

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.

Parameters
[out]objA possible object.
Postcondition
obj is marked, if possible.

Definition at line 2106 of file gc.c.

◆ rb_gc_mark_movable()

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().

See also
Bartlett, Joel F., "Compacting Garbage Collection with Ambiguous Roots", ACM SIGPLAN Lisp Pointers Volume 1 Issue 6 pp. 3-12, April-May-June, 1988. https://doi.org/10.1145/1317224.1317225
Parameters
[in]objObject that is movable.
Postcondition
Values stored in tbl are marked.

Definition at line 2076 of file gc.c.

◆ rb_gc_register_address()

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().

◆ rb_gc_register_mark_object()

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()

Definition at line 2786 of file gc.c.

◆ rb_gc_start()

VALUE rb_gc_start ( void  )

Identical to rb_gc(), except the return value.

Returns
Always returns RUBY_Qnil.

Definition at line 3363 of file gc.c.

◆ rb_gc_stat()

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.

Parameters
[in,out]key_or_bufA Symbol, or a Hash.
Exceptions
rb_eTypeErrorNeither Symbol nor Hash.
rb_eFrozenErrorFrozen hash is passed.
Returns
In case a Hash is passed it returns 0. Otherwise the profile value associated with the given key is returned.
Postcondition
In case a Hash is passed it is filled with values.

Definition at line 3435 of file gc.c.

◆ rb_gc_unregister_address()

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.

Definition at line 2819 of file gc.c.

◆ rb_gc_update_tbl_refs()

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.

Parameters
[out]ptrA table that potentially includes moved references.
Postcondition
Moved references, if any, are corrected.

Definition at line 2966 of file gc.c.

◆ rb_gc_writebarrier()

void rb_gc_writebarrier ( VALUE  old,
VALUE  young 
)

This is the implementation of RB_OBJ_WRITE().

People don't use it directly.

Parameters
[in]oldAn object that points to young.
[out]youngAn object that is referenced from old.

Definition at line 2738 of file gc.c.

◆ rb_gc_writebarrier_unprotect()

void rb_gc_writebarrier_unprotect ( VALUE  obj)

This is the implementation of RB_OBJ_WB_UNPROTECT().

People don't use it directly.

Parameters
[out]objAn object that does not participate in WB.

Definition at line 2744 of file gc.c.

Referenced by rb_obj_wb_unprotect().

◆ rb_global_variable()

void rb_global_variable ( VALUE var)

An alias for rb_gc_register_address().

Definition at line 2842 of file gc.c.

◆ rb_mark_hash()

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.

Parameters
[in]tblA table to mark.
Postcondition
Objects stored in tbl are marked.

Definition at line 2238 of file gc.c.

◆ rb_mark_set()

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.

Warning
Of course it can break GC. Leave it unused if unsure.
Parameters
[in]tblA table to mark.
Postcondition
Keys stored in tbl are marked.

Definition at line 2190 of file gc.c.

◆ rb_mark_tbl()

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.

Warning
Of course it can break GC. Leave it unused if unsure.
Parameters
[in]tblA table to mark.
Postcondition
Values stored in tbl are marked.

Definition at line 2394 of file gc.c.

◆ rb_mark_tbl_no_pin()

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.

Warning
Of course it can break GC. Leave it unused if unsure.
Parameters
[in]tblA table to mark.
Postcondition
Values stored in tbl are marked.

Definition at line 2410 of file gc.c.

◆ rb_memerror()

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.

Exceptions
rb_eNoMemErrorRaises it if possible.

Definition at line 4153 of file gc.c.

◆ RB_OBJ_PROMOTED()

static bool RB_OBJ_PROMOTED ( VALUE  obj)
inlinestatic

Tests if the object is "promoted" – that is, whether the object experienced one or more GC marks.

Parameters
[in]objAn object to query.
Return values
trueThe object is "promoted".
falseThe object is young. Have not experienced GC at all.
Note
Hello, is anyone actively calling this function? @shyouhei have never seen any actual usages outside of the GC implementation itself.

Definition at line 726 of file gc.h.

◆ RB_OBJ_PROMOTED_RAW()

static bool RB_OBJ_PROMOTED_RAW ( VALUE  obj)
inlinestatic

This is the implementation of RB_OBJ_PROMOTED().

People don't use it directly.

Parameters
[in]objAn object to query.
Return values
trueThe object is "promoted".
falseThe object is young. Have not experienced GC at all.

Definition at line 706 of file gc.h.

Referenced by RB_OBJ_PROMOTED().

◆ rb_obj_wb_unprotect()

static VALUE rb_obj_wb_unprotect ( VALUE  x,
const char *  filename,
int  line 
)
inlinestatic

This is the implementation of RB_OBJ_WB_UNPROTECT().

People don't use it directly.

Parameters
[out]xAn object that does not participate in WB.
[in]filenameC's __FILE__ of the caller function.
[in]lineC's __LINE__ of the caller function.
Returns
x

Definition at line 746 of file gc.h.

◆ rb_undefine_finalizer()

VALUE rb_undefine_finalizer ( VALUE  obj)

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.

Parameters
[out]objObject to clear its finalisers.
Exceptions
rb_eFrozenErrorobj is frozen.
Returns
The passed obj.
Postcondition
obj has no finalisers.
Note
There is no way to undefine a specific part of many finalisers that obj could have. All you can do is to clear them all.