Module: GC

Relationships & Source Files
Defined in:	gc.rb, gc.c

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 manually disabled.
.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

#garbage_collect(full_mark: true, immediate_mark: true, immediate_sweep: true)

Alias of .start

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.

[ GitHub ]

# File 'gc.rb', line 359


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.

[ GitHub ]

# File 'gc.rb', line 347


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.

[ GitHub ]

# File 'gc.rb', line 74


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

[ GitHub ]

# File 'gc.rb', line 92


def self.stress=(flag)
  Primitive.gc_stress_set_m flag
end

Class Method Details

.config ⇒ Hash .config(hash) ⇒ Hash

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.

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.

Valid config 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(:needs_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 to false.

[ GitHub ]

# File 'gc.rb', line 301


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.

[ GitHub ]

# File 'gc.rb', line 100


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

[ GitHub ]

# File 'gc.rb', line 66


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

[ GitHub ]

# File 'gc.rb', line 54


def self.enable
  Primitive.gc_enable
end

.latest_gc_info ⇒ Hash .latest_gc_info(hash) ⇒ Hash .latest_gc_info(key) ⇒ `value`

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

[ GitHub ]

# File 'gc.rb', line 329


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 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 run, meaning all objects are marked. When set to false, a minor garbage collection cycle is run, 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 are 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 immediate_sweep keyword argument determines whether or not to defer sweeping (using lazy sweep). When set to false, sweeping is performed in steps that are interleaved with future Ruby code execution, so sweeping might not be completed during this method call. When set to true, 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.

[ GitHub ]

# File 'gc.rb', line 35


def self.start full_mark: true, immediate_mark: true, immediate_sweep: true
  Primitive.gc_start_internal full_mark, immediate_mark, immediate_sweep, false
end

.stat ⇒ Hash .stat(hash) ⇒ Hash .stat(:key) ⇒ Numeric

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.

[ GitHub ]

# File 'gc.rb', line 184


def self.stat hash_or_key = nil
  Primitive.gc_stat hash_or_key
end

.stat_heap ⇒ Hash .stat_heap(nil, hash) ⇒ Hash .stat_heap(heap_name) ⇒ Hash .stat_heap(heap_name, hash) ⇒ Hash .stat_heap(heap_name, :key) ⇒ Numeric

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.

[ GitHub ]

# File 'gc.rb', line 247


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.

[ GitHub ]

# File 'gc.rb', line 369


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

[ GitHub ]

# File 'gc.rb', line 40


def garbage_collect full_mark: true, immediate_mark: true, immediate_sweep: true
  Primitive.gc_start_internal full_mark, immediate_mark, immediate_sweep, false
end

Module: GC

Overview

Class Attribute Summary

Class Method Summary

Instance Method Summary

Class Attribute Details

.measure_total_time ⇒ Boolean (rw)

.measure_total_time=(true/false) (rw)

.stress ⇒ Integer, ... (rw)

.stress=(flag) ⇒ flag (rw)

Class Method Details

.config ⇒ Hash .config(hash) ⇒ Hash

.count ⇒ Integer

.disable ⇒ Boolean

.enable ⇒ Boolean

.latest_gc_info ⇒ Hash .latest_gc_info(hash) ⇒ Hash .latest_gc_info(key) ⇒ value

.start(full_mark: true, immediate_mark: true, immediate_sweep: true)

.stat ⇒ Hash .stat(hash) ⇒ Hash .stat(:key) ⇒ Numeric

.stat_heap ⇒ Hash .stat_heap(nil, hash) ⇒ Hash .stat_heap(heap_name) ⇒ Hash .stat_heap(heap_name, hash) ⇒ Hash .stat_heap(heap_name, :key) ⇒ Numeric

.total_time ⇒ Integer

Instance Method Details

#garbage_collect(full_mark: true, immediate_mark: true, immediate_sweep: true)

.measure_total_time ⇒ `Boolean` (rw)

.stress=(flag) ⇒ `flag` (rw)

.disable ⇒ `Boolean`

.enable ⇒ `Boolean`

.latest_gc_info ⇒ Hash .latest_gc_info(hash) ⇒ Hash .latest_gc_info(key) ⇒ `value`