(526111290b2e01e798f436dfe4acc3bf10c6bbd1)

Public APIs related to rb_mGC. More...

#include "ruby/internal/config.h"
#include "ruby/internal/attr/cold.h"
#include "ruby/internal/attr/noreturn.h"
#include "ruby/internal/attr/nonnull.h"
#include "ruby/internal/attr/pure.h"
#include "ruby/internal/dllexport.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.

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_force_recycle (VALUE obj)
	Asserts that the passed object is no longer needed. 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...

Detailed Description

Public APIs related to rb_mGC.

Author: Ruby developers ruby-.nosp@m.core.nosp@m.@ruby.nosp@m.-lan.nosp@m.g.org

Copyright: This file is a part of the programming language Ruby. Permission is hereby granted, to either redistribute and/or modify this file, provided that the conditions mentioned in the file COPYING are met. Consult the file for details.

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.

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]	obj	Target to finalise.
[in]	block	Something `call`able.

Exceptions

rb_eRuntimeError	Somehow `obj` cannot have finalisers.
rb_eFrozenError	`obj` is frozen.
rb_eArgError	`block` doesn't respond to `call`.

Returns: The passed block.

Postcondition: block runs after obj dies.

Definition at line 4346 of file gc.c.

◆ rb_during_gc()

int rb_during_gc ( void )

Queries if the GC is busy.

Return values

0	It isn't.
1	It is.

Definition at line 11043 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 11035 of file gc.c.

Referenced by rb_fdopen(), 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] diff Amount of memory increased(+)/decreased(-).

Definition at line 12853 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]	dst	Destination object.
[in]	src	Source object.

Postcondition: dst and src share the same finaliser.

Definition at line 4354 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 11067 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_Qtrue	GC was disabled before.
RUBY_Qfalse	GC was enabled before.

Postcondition: GC is disabled.

Definition at line 11624 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_Qtrue	GC was disabled before.
RUBY_Qfalse	GC was enabled before.

Postcondition: GC is enabled.

Definition at line 11587 of file gc.c.

◆ rb_gc_force_recycle()

void rb_gc_force_recycle ( VALUE obj )

Asserts that the passed object is no longer needed.

Such objects are reclaimed sooner or later so this function is not mandatory. But sometimes you can know from your application knowledge that an object is surely dead at some point. Calling this as a hint can be a polite way.

Parameters

[out] obj Object, dead.

Precondition: obj have never been passed to this function before.

Postcondition: obj could be invalidated.

Warning: It is a failure to pass an object multiple times to this function.

Deprecated:: This is now a no-op function.

Definition at line 9272 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_buf A Symbol, or a Hash.

Exceptions

rb_eTypeError	Neither Symbol nor Hash.
rb_eFrozenError	Frozen 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 11187 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] obj An object, possibly already moved to somewhere else.

Returns: An object, which holds the current contents of former obj.

Definition at line 10420 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] obj Arbitrary Ruby object.

Postcondition: obj is marked.

Definition at line 7149 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]	start	Pointer to an array of objects.
[out]	end	Pointer that terminates the array of objects.

Postcondition: Objects from start (included) to end (excluded) are marked.

Definition at line 6564 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] obj A possible object.

Postcondition: obj is marked, if possible.

Definition at line 6968 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] obj Object that is movable.

Postcondition: Values stored in tbl are marked.

Definition at line 7143 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 11028 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_buf A Symbol, or a Hash.

Exceptions

rb_eTypeError	Neither Symbol nor Hash.
rb_eFrozenError	Frozen 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 11421 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] ptr A table that potentially includes moved references.

Postcondition: Moved references, if any, are corrected.

Definition at line 10264 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] tbl A table to mark.

Postcondition: Objects stored in tbl are marked.

Definition at line 6734 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] tbl A table to mark.

Postcondition: Keys stored in tbl are marked.

Definition at line 6670 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] tbl A table to mark.

Postcondition: Values stored in tbl are marked.

Definition at line 6931 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] tbl A table to mark.

Postcondition: Values stored in tbl are marked.

Definition at line 6937 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_eNoMemError Raises it if possible.

Definition at line 12056 of file gc.c.

◆ 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] obj Object to clear its finalisers.

Exceptions

rb_eFrozenError obj 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.

Definition at line 4194 of file gc.c.

(526111290b2e01e798f436dfe4acc3bf10c6bbd1)

Functions

Detailed Description

Function Documentation

◆ rb_define_finalizer()

◆ rb_during_gc()

◆ rb_gc()

◆ rb_gc_adjust_memory_usage()

◆ rb_gc_copy_finalizer()

◆ rb_gc_count()

◆ rb_gc_disable()

◆ rb_gc_enable()

◆ rb_gc_force_recycle()

◆ rb_gc_latest_gc_info()

◆ rb_gc_location()

◆ rb_gc_mark()

◆ rb_gc_mark_locations()

◆ rb_gc_mark_maybe()

◆ rb_gc_mark_movable()

◆ rb_gc_start()

◆ rb_gc_stat()

◆ rb_gc_update_tbl_refs()

◆ rb_mark_hash()

◆ rb_mark_set()

◆ rb_mark_tbl()

◆ rb_mark_tbl_no_pin()

◆ rb_memerror()

◆ rb_undefine_finalizer()