module GC
The GC module provides an interface to Ruby’s mark and sweep garbage collection mechanism.
Some of the underlying methods are also available via the ObjectSpace
module.
You may obtain information about the operation of the GC through GC::Profiler
.
Constants
- INTERNAL_CONSTANTS
Internal constants in the garbage collector.
- OPTS
GC build options
Public Class Methods
Raises NoMemoryError
when allocating an instance of the given classes.
static VALUE rb_gcdebug_add_stress_to_class(int argc, VALUE *argv, VALUE self) { rb_objspace_t *objspace = &rb_objspace; if (!stress_to_class) { set_stress_to_class(rb_ary_hidden_new(argc)); } rb_ary_cat(stress_to_class, argv, argc); return self; }
Returns whether or not automatic compaction has been enabled.
static VALUE gc_get_auto_compact(VALUE _) { return RBOOL(ruby_enable_autocompact); }
Updates automatic compaction mode.
When enabled, the compactor will execute on every major collection.
Enabling compaction will degrade performance on major collections.
static VALUE gc_set_auto_compact(VALUE _, VALUE v) { GC_ASSERT(GC_COMPACTION_SUPPORTED); ruby_enable_autocompact = RTEST(v); #if RGENGC_CHECK_MODE ruby_autocompact_compare_func = NULL; if (SYMBOL_P(v)) { ID id = RB_SYM2ID(v); if (id == rb_intern("empty")) { ruby_autocompact_compare_func = compare_free_slots; } } #endif return v; }
This function compacts objects together in Ruby’s heap. It eliminates unused space (or fragmentation) in the heap by moving objects in to that unused space. This function returns a hash which contains statistics about which objects were moved. See GC.latest_gc_info
for details about compaction statistics.
This method is implementation specific and not expected to be implemented in any implementation besides MRI.
To test whether GC compaction is supported, use the idiom:
GC.respond_to?(:compact)
static VALUE gc_compact(VALUE self) { /* Run GC with compaction enabled */ gc_start_internal(NULL, self, Qtrue, Qtrue, Qtrue, Qtrue); return gc_compact_stats(self); }
The number of times GC occurred.
It returns the number of times GC occurred since the process started.
# File ruby_3_3_3/gc.rb, line 105 def self.count Primitive.gc_count end
Disables garbage collection, returning true
if garbage collection was already disabled.
GC.disable #=> false GC.disable #=> true
# File ruby_3_3_3/gc.rb, line 69 def self.disable Primitive.gc_disable end
Enables garbage collection, returning true
if garbage collection was previously disabled.
GC.disable #=> false GC.enable #=> true GC.enable #=> false
# File ruby_3_3_3/gc.rb, line 57 def self.enable Primitive.gc_enable end
Returns information about object moved in the most recent GC compaction.
The returned hash has two keys :considered and :moved. The hash for :considered lists the number of objects that were considered for movement by the compactor, and the :moved hash lists the number of objects that were actually moved. Some objects can’t be moved (maybe they were pinned) so these numbers can be used to calculate compaction efficiency.
static VALUE gc_compact_stats(VALUE self) { size_t i; rb_objspace_t *objspace = &rb_objspace; VALUE h = rb_hash_new(); VALUE considered = rb_hash_new(); VALUE moved = rb_hash_new(); VALUE moved_up = rb_hash_new(); VALUE moved_down = rb_hash_new(); for (i=0; i<T_MASK; i++) { if (objspace->rcompactor.considered_count_table[i]) { rb_hash_aset(considered, type_sym(i), SIZET2NUM(objspace->rcompactor.considered_count_table[i])); } if (objspace->rcompactor.moved_count_table[i]) { rb_hash_aset(moved, type_sym(i), SIZET2NUM(objspace->rcompactor.moved_count_table[i])); } if (objspace->rcompactor.moved_up_count_table[i]) { rb_hash_aset(moved_up, type_sym(i), SIZET2NUM(objspace->rcompactor.moved_up_count_table[i])); } if (objspace->rcompactor.moved_down_count_table[i]) { rb_hash_aset(moved_down, type_sym(i), SIZET2NUM(objspace->rcompactor.moved_down_count_table[i])); } } rb_hash_aset(h, ID2SYM(rb_intern("considered")), considered); rb_hash_aset(h, ID2SYM(rb_intern("moved")), moved); rb_hash_aset(h, ID2SYM(rb_intern("moved_up")), moved_up); rb_hash_aset(h, ID2SYM(rb_intern("moved_down")), moved_down); return h; }
Returns information about the most recent garbage collection.
If the optional argument, hash, is given, it is overwritten and returned. This is intended to avoid probe effect.
# File ruby_3_3_3/gc.rb, line 266 def self.latest_gc_info hash_or_key = nil Primitive.gc_latest_gc_info hash_or_key end
Returns the size of memory allocated by malloc().
Only available if ruby was built with CALC_EXACT_MALLOC_SIZE
.
static VALUE gc_malloc_allocated_size(VALUE self) { return UINT2NUM(rb_objspace.malloc_params.allocated_size); }
Returns the number of malloc() allocations.
Only available if ruby was built with CALC_EXACT_MALLOC_SIZE
.
static VALUE gc_malloc_allocations(VALUE self) { return UINT2NUM(rb_objspace.malloc_params.allocations); }
Return measure_total_time
flag (default: true
). Note that measurement can affect the application performance.
# File ruby_3_3_3/gc.rb, line 308 def self.measure_total_time Primitive.cexpr! %{ RBOOL(rb_objspace.flags.measure_gc) } end
Enable to measure GC time. You can get the result with GC.stat(:time)
. Note that GC time measurement can cause some performance overhead.
# File ruby_3_3_3/gc.rb, line 296 def self.measure_total_time=(flag) Primitive.cstmt! %{ rb_objspace.flags.measure_gc = RTEST(flag) ? TRUE : FALSE; return flag; } end
No longer raises NoMemoryError
when allocating an instance of the given classes.
static VALUE rb_gcdebug_remove_stress_to_class(int argc, VALUE *argv, VALUE self) { rb_objspace_t *objspace = &rb_objspace; int i; if (stress_to_class) { for (i = 0; i < argc; ++i) { rb_ary_delete_same(stress_to_class, argv[i]); } if (RARRAY_LEN(stress_to_class) == 0) { set_stress_to_class(0); } } return Qnil; }
Initiates garbage collection, even if manually disabled.
The full_mark
keyword argument determines whether or not to perform a major garbage collection cycle. When set to true
, a major garbage collection cycle is ran, meaning all objects are marked. When set to false
, a minor garbage collection cycle is ran, meaning only young objects are marked.
The immediate_mark
keyword argument determines whether or not to perform incremental marking. When set to true
, marking is completed during the call to this method. When set to false
, marking is performed in steps that is interleaved with future Ruby code execution, so marking might not be completed during this method call. Note that if full_mark
is false
then marking will always be immediate, regardless of the value of immediate_mark
.
The immedate_sweep
keyword argument determines whether or not to defer sweeping (using lazy sweep). When set to true
, sweeping is performed in steps that is interleaved with future Ruby code execution, so sweeping might not be completed during this method call. When set to false
, sweeping is completed during the call to this method.
Note: These keyword arguments are implementation and version dependent. They are not guaranteed to be future-compatible, and may be ignored if the underlying implementation does not support them.
# File ruby_3_3_3/gc.rb, line 38 def self.start full_mark: true, immediate_mark: true, immediate_sweep: true Primitive.gc_start_internal full_mark, immediate_mark, immediate_sweep, false end
Returns a Hash
containing information about the GC.
The contents of the hash are implementation specific and may change in the future without notice.
The hash includes information about internal statistics about GC such as:
- count
-
The total number of garbage collections ran since application start (count includes both minor and major garbage collections)
- time
-
The total time spent in garbage collections (in milliseconds)
- heap_allocated_pages
-
The total number of
:heap_eden_pages
+:heap_tomb_pages
- heap_sorted_length
-
The number of pages that can fit into the buffer that holds references to all pages
- heap_allocatable_pages
-
The total number of pages the application could allocate without additional GC
- heap_available_slots
-
The total number of slots in all
:heap_allocated_pages
- heap_live_slots
-
The total number of slots which contain live objects
- heap_free_slots
-
The total number of slots which do not contain live objects
- heap_final_slots
-
The total number of slots with pending finalizers to be run
- heap_marked_slots
-
The total number of objects marked in the last GC
- heap_eden_pages
-
The total number of pages which contain at least one live slot
- heap_tomb_pages
-
The total number of pages which do not contain any live slots
- total_allocated_pages
-
The cumulative number of pages allocated since application start
- total_freed_pages
-
The cumulative number of pages freed since application start
- total_allocated_objects
-
The cumulative number of objects allocated since application start
- total_freed_objects
-
The cumulative number of objects freed since application start
- malloc_increase_bytes
-
Amount of memory allocated on the heap for objects. Decreased by any GC
- malloc_increase_bytes_limit
-
When
:malloc_increase_bytes
crosses this limit, GC is triggered - minor_gc_count
-
The total number of minor garbage collections run since process start
- major_gc_count
-
The total number of major garbage collections run since process start
- compact_count
-
The total number of compactions run since process start
- read_barrier_faults
-
The total number of times the read barrier was triggered during compaction
- total_moved_objects
-
The total number of objects compaction has moved
- remembered_wb_unprotected_objects
-
The total number of objects without write barriers
- remembered_wb_unprotected_objects_limit
-
When
:remembered_wb_unprotected_objects
crosses this limit, major GC is triggered - old_objects
-
Number of live, old objects which have survived at least 3 garbage collections
- old_objects_limit
-
When
:old_objects
crosses this limit, major GC is triggered - oldmalloc_increase_bytes
-
Amount of memory allocated on the heap for objects. Decreased by major GC
- oldmalloc_increase_bytes_limit
-
When
:old_malloc_increase_bytes
crosses this limit, major GC is triggered
If the optional argument, hash, is given, it is overwritten and returned. This is intended to avoid probe effect.
This method is only expected to work on CRuby.
# File ruby_3_3_3/gc.rb, line 189 def self.stat hash_or_key = nil Primitive.gc_stat hash_or_key end
Returns information for heaps in the GC.
If the first optional argument, heap_name
, is passed in and not nil
, it returns a Hash
containing information about the particular heap. Otherwise, it will return a Hash
with heap names as keys and a Hash
containing information about the heap as values.
If the second optional argument, hash_or_key
, is given as Hash
, it will be overwritten and returned. This is intended to avoid the probe effect.
If both optional arguments are passed in and the second optional argument is a symbol, it will return a Numeric
of the value for the particular heap.
On CRuby, heap_name
is of the type Integer
but may be of type String
on other implementations.
The contents of the hash are implementation specific and may change in the future without notice.
If the optional argument, hash, is given, it is overwritten and returned.
This method is only expected to work on CRuby.
The hash includes the following keys about the internal information in the GC:
- slot_size
-
The slot size of the heap in bytes.
- heap_allocatable_pages
-
The number of pages that can be allocated without triggering a new garbage collection cycle.
- heap_eden_pages
-
The number of pages in the eden heap.
- heap_eden_slots
-
The total number of slots in all of the pages in the eden heap.
- heap_tomb_pages
-
The number of pages in the tomb heap. The tomb heap only contains pages that do not have any live objects.
- heap_tomb_slots
-
The total number of slots in all of the pages in the tomb heap.
- total_allocated_pages
-
The total number of pages that have been allocated in the heap.
- total_freed_pages
-
The total number of pages that have been freed and released back to the system in the heap.
- force_major_gc_count
-
The number of times major garbage collection cycles this heap has forced to start due to running out of free slots.
- force_incremental_marking_finish_count
-
The number of times this heap has forced incremental marking to complete due to running out of pooled slots.
# File ruby_3_3_3/gc.rb, line 252 def self.stat_heap heap_name = nil, hash_or_key = nil Primitive.gc_stat_heap heap_name, hash_or_key end
Returns current status of GC stress mode.
# File ruby_3_3_3/gc.rb, line 77 def self.stress Primitive.gc_stress_get end
Updates the GC stress mode.
When stress mode is enabled, the GC is invoked at every GC opportunity: all memory and object allocations.
Enabling stress mode will degrade performance, it is only for debugging.
flag can be true, false, or an integer bit-ORed following flags.
0x01:: no major GC 0x02:: no immediate sweep 0x04:: full mark after malloc/calloc/realloc
# File ruby_3_3_3/gc.rb, line 95 def self.stress=(flag) Primitive.gc_stress_set_m flag end
Return measured GC total time in nano seconds.
# File ruby_3_3_3/gc.rb, line 318 def self.total_time Primitive.cexpr! %{ ULL2NUM(rb_objspace.profile.marking_time_ns + rb_objspace.profile.sweeping_time_ns) } end
Verify compaction reference consistency.
This method is implementation specific. During compaction, objects that were moved are replaced with T_MOVED objects. No object should have a reference to a T_MOVED object after compaction.
This function expands the heap to ensure room to move all objects, compacts the heap to make sure everything moves, updates all references, then performs a full GC. If any object contains a reference to a T_MOVED object, that object should be pushed on the mark stack, and will make a SEGV.
# File ruby_3_3_3/gc.rb, line 285 def self.verify_compaction_references(toward: nil, double_heap: false, expand_heap: false) Primitive.gc_verify_compaction_references(double_heap, expand_heap, toward == :empty) end
Verify internal consistency.
This method is implementation specific. Now this method checks generational consistency if RGenGC is supported.
static VALUE gc_verify_internal_consistency_m(VALUE dummy) { gc_verify_internal_consistency(&rb_objspace); return Qnil; }
Public Instance Methods
Alias of GC.start
# File ruby_3_3_3/gc.rb, line 43 def garbage_collect full_mark: true, immediate_mark: true, immediate_sweep: true Primitive.gc_start_internal full_mark, immediate_mark, immediate_sweep, false end