Module: GC
Overview
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 Profiler
.
Class Attribute Summary
-
.measure_total_time ⇒ Boolean
rw
Returns the measure_total_time flag (default:
true
). -
.measure_total_time=(true/false)
rw
Enables measuring GC time.
-
.stress ⇒ Integer, ...
rw
Returns the current status of GC stress mode.
-
.stress=(flag) ⇒ flag
rw
Updates the GC stress mode.
Class Method Summary
-
.config ⇒ Hash
Sets or gets information about the current GC config.
-
.count ⇒ Integer
Returns the number of times GC has occurred since the process started.
-
.disable ⇒ Boolean
Disables garbage collection, returning
true
if garbage collection was already disabled. -
.enable ⇒ Boolean
Enables garbage collection, returning
true
if garbage collection was previously disabled. -
.latest_gc_info ⇒ Hash
Returns information about the most recent garbage collection.
-
.start(full_mark: true, immediate_mark: true, immediate_sweep: true)
Initiates garbage collection, even if explicitly disabled by .disable.
-
.stat ⇒ Hash
Returns a
::Hash
containing information about the GC. -
.stat_heap ⇒ Hash
Returns information for heaps in the GC.
-
.total_time ⇒ Integer
Returns the measured GC total time in nanoseconds.
Instance Method Summary
Class Attribute Details
.measure_total_time ⇒ Boolean
(rw)
Returns the measure_total_time flag (default: true
). Note that measurement can affect the application’s performance.
# File 'gc.rb', line 384
def self.measure_total_time Primitive.cexpr! %{ RBOOL(rb_gc_impl_get_measure_total_time(rb_gc_get_objspace())) } end
.measure_total_time=(true/false) (rw)
Enables measuring GC time. You can get the result with GC.stat(:time)
. Note that GC time measurement can cause some performance overhead.
# File 'gc.rb', line 372
def self.measure_total_time=(flag) Primitive.cstmt! %{ rb_gc_impl_set_measure_total_time(rb_gc_get_objspace(), flag); return flag; } end
.stress ⇒ Integer, ... (rw)
Returns the current status of GC stress mode.
# File 'gc.rb', line 82
def self.stress Primitive.gc_stress_get end
.stress=(flag) ⇒ flag
(rw)
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.
The flag can be true, false, or an integer bitwise-ORed with the following flags:
0x01:: no major GC
0x02:: no immediate sweep
0x04:: full mark after malloc/calloc/realloc
# File 'gc.rb', line 100
def self.stress=(flag) Primitive.gc_stress_set_m flag end
Class Method Details
Sets or gets information about the current GC config.
Configuration parameters are GC implementation-specific and may change without notice.
This method can be called without parameters to retrieve the current config as a ::Hash
with ::Symbol
keys.
This method can also be called with a ::Hash
argument to assign values to valid config keys. Config keys missing from the passed ::Hash
will be left unmodified.
If a key/value pair is passed to this function that does not correspond to a valid config key for the GC implementation being used, no config will be updated, the key will be present in the returned ::Hash
, and its value will be nil
. This is to facilitate easy migration between GC implementations.
In both call-seqs, the return value of config
will be a ::Hash
containing the most recent full configuration, i.e., all keys and values defined by the specific GC implementation being used. In the case of a config update, the return value will include the new values being updated.
This method is only expected to work on CRuby.
GC Implementation independent values
The config
hash can also contain keys that are global and read-only. These keys are not specific to any one GC library implementation and attempting to write to them will raise ::ArgumentError
.
There is currently only one global, read-only key:
- implementation
-
Returns a
::String
containing the name of the currently loaded GC library, if one has been loaded usingRUBY_GC_LIBRARY
, and “default” in all other cases
GC Implementation specific values
GC libraries are expected to document their own configuration. Valid keys for Ruby’s default GC implementation are:
- rgengc_allow_full_mark
-
Controls whether the GC is allowed to run a full mark (young & old objects).
When
true
, GC interleaves major and minor collections. This is the default. GC will function as intended.When
false
, the GC will never trigger a full marking cycle unless explicitly requested by user code. Instead, only a minor mark will run—only young objects will be marked. When the heap space is exhausted, new pages will be allocated immediately instead of running a full mark.A flag will be set to notify that a full mark has been requested. This flag is accessible using
GC.latest_gc_info(:need_major_by)
The user can trigger a major collection at any time using
GC.start(full_mark: true)
When
false
, Young to Old object promotion is disabled. For performance reasons, it is recommended to warm up an application using Process.warmup before setting this parameter tofalse
.
# File 'gc.rb', line 326
def self.config hash = nil return Primitive.gc_config_get unless hash if(Primitive.cexpr!("RBOOL(RB_TYPE_P(hash, T_HASH))")) if hash.include?(:implementation) raise ArgumentError, 'Attempting to set read-only key "Implementation"' end Primitive.gc_config_set hash else raise ArgumentError end end
.count ⇒ Integer
Returns the number of times GC has occurred since the process started.
# File 'gc.rb', line 108
def self.count Primitive.gc_count end
.disable ⇒ Boolean
Disables garbage collection, returning true
if garbage collection was already disabled.
GC.disable #=> false
GC.disable #=> true
# File 'gc.rb', line 74
def self.disable Primitive.gc_disable end
.enable ⇒ Boolean
Enables garbage collection, returning true
if garbage collection was previously disabled.
GC.disable #=> false
GC.enable #=> true
GC.enable #=> false
# File 'gc.rb', line 62
def self.enable Primitive.gc_enable end
Returns information about the most recent garbage collection.
If the argument hash
is given and is a ::Hash
object, it is overwritten and returned. This is intended to avoid the probe effect.
If the argument key
is given and is a ::Symbol
object, it returns the value associated with the key. This is equivalent to GC.latest_gc_info[key]
.
# File 'gc.rb', line 354
def self.latest_gc_info hash_or_key = nil if hash_or_key == nil hash_or_key = {} elsif Primitive.cexpr!("RBOOL(!SYMBOL_P(hash_or_key) && !RB_TYPE_P(hash_or_key, T_HASH))") raise TypeError, "non-hash or symbol given" end Primitive.cstmt! %{ return rb_gc_latest_gc_info(hash_or_key); } end
.start(full_mark: true, immediate_mark: true, immediate_sweep: true)
Initiates garbage collection, even if explicitly disabled by .disable.
Keyword arguments:
-
full_mark
: its boolean value determines whether to perform a major garbage collection cycle:-
true
: initiates a major garbage collection cycle, meaning all objects (old and new) are marked. -
false
: initiates a minor garbage collection cycle, meaning only young objects are marked.
-
-
immediate_mark
: its boolean value determines whether to perform incremental marking:-
true
: marking is completed before the method returns. -
false
: marking is performed by parts, interleaved with program execution both before the method returns and afterward; therefore marking may not be completed before the return. Note that iffull_mark
isfalse
, marking will always be immediate, regardless of the value ofimmediate_mark
.
-
-
immediate_sweep
: its boolean value determines whether to defer sweeping (using lazy sweep):-
true
: sweeping is completed before the method returns. -
false
: sweeping is performed by parts, interleaved with program execution both before the method returns and afterward; therefore sweeping may not be completed before the return.
-
Note that these keword arguments are implementation- and version-dependent, are not guaranteed to be future-compatible, and may be ignored in some implementations.
# File 'gc.rb', line 43
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 internal statistics about GC such as:
- count
-
The total number of garbage collections run 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
:oldmalloc_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 the probe effect.
This method is only expected to work on CRuby.
# File 'gc.rb', line 192
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 a ::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
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 this heap has forced major garbage collection cycles 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 'gc.rb', line 255
def self.stat_heap heap_name = nil, hash_or_key = nil Primitive.gc_stat_heap heap_name, hash_or_key end
.total_time ⇒ Integer
Returns the measured GC total time in nanoseconds.
# File 'gc.rb', line 394
def self.total_time Primitive.cexpr! %{ ULL2NUM(rb_gc_impl_get_total_time(rb_gc_get_objspace())) } end
Instance Method Details
#garbage_collect(full_mark: true, immediate_mark: true, immediate_sweep: true)
Alias of .start
# File 'gc.rb', line 48
def garbage_collect full_mark: true, immediate_mark: true, immediate_sweep: true Primitive.gc_start_internal full_mark, immediate_mark, immediate_sweep, false end