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.
internal constants
static VALUE
rb_gcdebug_add_stress_to_class(int argc, VALUE *argv, VALUE self)
{
rb_objspace_t *objspace = &rb_objspace;
if (!stress_to_class) {
stress_to_class = rb_ary_tmp_new(argc);
}
rb_ary_cat(stress_to_class, argv, argc);
return self;
}
Raises NoMemoryError when allocating an instance of the given classes.
# File tmp/rubies/ruby-3.1.3/gc.rb, line 46
def self.auto_compact
Primitive.gc_get_auto_compact
end
Returns whether or not automatic compaction has been enabled.
# File tmp/rubies/ruby-3.1.3/gc.rb, line 58
def self.auto_compact=(flag)
Primitive.gc_set_auto_compact(flag)
end
Updates automatic compaction mode.
When enabled, the compactor will execute on every major collection.
Enabling compaction will degrade performance on major collections.
# File tmp/rubies/ruby-3.1.3/gc.rb, line 238
def self.compact
Primitive.gc_compact
end
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.
# File tmp/rubies/ruby-3.1.3/gc.rb, line 120
def self.count
Primitive.gc_count
end
# File tmp/rubies/ruby-3.1.3/gc.rb, line 84
def self.disable
Primitive.gc_disable
end
Disables garbage collection, returning true if garbage collection was already disabled.
GC.disable #=> false GC.disable #=> true
# File tmp/rubies/ruby-3.1.3/gc.rb, line 72
def self.enable
Primitive.gc_enable
end
Enables garbage collection, returning true if garbage collection was previously disabled.
GC.disable #=> false GC.enable #=> true GC.enable #=> false
# File tmp/rubies/ruby-3.1.3/gc.rb, line 223
def self.latest_compact_info
Primitive.gc_compact_stats
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.
# File tmp/rubies/ruby-3.1.3/gc.rb, line 209
def self.latest_gc_info hash_or_key = nil
Primitive.gc_latest_gc_info hash_or_key
end
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.
static VALUE
gc_malloc_allocated_size(VALUE self)
{
return UINT2NUM(rb_objspace.malloc_params.allocated_size);
}
Returns the size of memory allocated by malloc().
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);
}
Returns the number of malloc() allocations.
Only available if ruby was built with CALC_EXACT_MALLOC_SIZE.
# File tmp/rubies/ruby-3.1.3/gc.rb, line 288
def self.measure_total_time
Primitive.cexpr! %{
RBOOL(rb_objspace.flags.measure_gc)
}
end
Return measure_total_time flag (default: true). Note that measurement can affect the application performance.
# File tmp/rubies/ruby-3.1.3/gc.rb, line 276
def self.measure_total_time=(flag)
Primitive.cstmt! %{
rb_objspace.flags.measure_gc = RTEST(flag) ? TRUE : FALSE;
return flag;
}
end
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) {
stress_to_class = 0;
}
}
return Qnil;
}
No longer raises NoMemoryError when allocating an instance of the given classes.
# File tmp/rubies/ruby-3.1.3/gc.rb, line 33
def self.start full_mark: true, immediate_mark: true, immediate_sweep: true
Primitive.gc_start_internal full_mark, immediate_mark, immediate_sweep, false
end
Initiates garbage collection, even if manually disabled.
This method is defined with keyword arguments that default to true:
def GC.start(full_mark: true, immediate_sweep: true); end
Use full_mark: false to perform a minor GC. Use immediate_sweep: false to defer sweeping (use lazy sweep).
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 tmp/rubies/ruby-3.1.3/gc.rb, line 195
def self.stat hash_or_key = nil
Primitive.gc_stat hash_or_key
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)
- 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,
GCis 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
- 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
GCis 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
GCis 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
GCis 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 tmp/rubies/ruby-3.1.3/gc.rb, line 92
def self.stress
Primitive.gc_stress_get
end
Returns current status of GC stress mode.
# File tmp/rubies/ruby-3.1.3/gc.rb, line 110
def self.stress=(flag)
Primitive.gc_stress_set_m flag
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 tmp/rubies/ruby-3.1.3/gc.rb, line 298
def self.total_time
Primitive.cexpr! %{
ULL2NUM(rb_objspace.profile.total_time_ns)
}
end
Return measured GC total time in nano seconds.
# File tmp/rubies/ruby-3.1.3/gc.rb, line 256
def self.verify_compaction_references(toward: nil, double_heap: false)
Primitive.gc_verify_compaction_references(double_heap, toward == :empty)
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 doubles 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.
static VALUE
gc_verify_internal_consistency_m(VALUE dummy)
{
gc_verify_internal_consistency(&rb_objspace);
return Qnil;
}
Verify internal consistency.
This method is implementation specific. Now this method checks generational consistency if RGenGC is supported.
static VALUE
gc_verify_transient_heap_internal_consistency(VALUE dmy)
{
rb_transient_heap_verify();
return Qnil;
}
# File tmp/rubies/ruby-3.1.3/gc.rb, line 37
def garbage_collect full_mark: true, immediate_mark: true, immediate_sweep: true
Primitive.gc_start_internal full_mark, immediate_mark, immediate_sweep, false
end