# 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

OPTS

  GC build options

### Public Class Methods

add_stress_to_class(class[, ...]) click to toggle source

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) {
            stress_to_class = rb_ary_hidden_new(argc);
        }
        rb_ary_cat(stress_to_class, argv, argc);
        return self;
    }

auto_compact → true or false click to toggle source

Returns whether or not automatic compaction has been enabled.

    static VALUE
    gc_get_auto_compact(VALUE _)
    {
        return RBOOL(ruby_enable_autocompact);
    }

auto_compact = flag click to toggle source

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);
        return v;
    }

compact click to toggle source

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);
    }

count → Integer click to toggle source

The number of times GC occurred.

It returns the number of times GC occurred since the process started.

    # File gc.rb, line 99
    def self.count
      Primitive.gc_count
    end

disable → true or false click to toggle source

Disables garbage collection, returning `true` if garbage collection was already disabled.

    GC.disable   #=> false
    GC.disable   #=> true

    # File gc.rb, line 63
    def self.disable
      Primitive.gc_disable
    end

enable → true or false click to toggle source

Enables garbage collection, returning `true` if garbage collection was previously disabled.

    GC.disable   #=> false
    GC.enable    #=> true
    GC.enable    #=> false

    # File gc.rb, line 51
    def self.enable
      Primitive.gc_enable
    end

latest_compact_info → hash click to toggle source

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;
    }

latest_gc_info → hash click to toggle source
latest_gc_info(hash) → hash
latest_gc_info(:major_by) → :malloc

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 gc.rb, line 231
    def self.latest_gc_info hash_or_key = nil
      Primitive.gc_latest_gc_info hash_or_key
    end

malloc_allocated_size → Integer click to toggle source

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);
    }

malloc_allocations → Integer click to toggle source

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);
    }

measure_total_time → true/false click to toggle source

Return `measure_total_time` flag (default: `true`). Note that measurement can affect the application performance.

    # File gc.rb, line 273
    def self.measure_total_time
      Primitive.cexpr! %{
        RBOOL(rb_objspace.flags.measure_gc)
      }
    end

measure_total_time = true/false click to toggle source

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 gc.rb, line 261
    def self.measure_total_time=(flag)
      Primitive.cstmt! %{
        rb_objspace.flags.measure_gc = RTEST(flag) ? TRUE : FALSE;
        return flag;
      }
    end

remove_stress_to_class(class[, ...]) click to toggle source

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) {
                stress_to_class = 0;
            }
        }
        return Qnil;
    }

start → nil click to toggle source
garbage_collect → nil
include GC; garbage_collect → nil
start(full_mark: true, immediate_sweep: true) → nil
garbage_collect(full_mark: true, immediate_sweep: true) → nil
include GC; garbage_collect(full_mark: true, immediate_sweep: true) → nil

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

stat → Hash click to toggle source
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 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 gc.rb, line 183
    def self.stat hash_or_key = nil
      Primitive.gc_stat hash_or_key
    end

stat_heap → Hash click to toggle source
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 memory pools 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 memory pool. Otherwise, it will return a `Hash` with memory pool names as keys and a `Hash` containing information about the memory pool 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 memory pool.

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.

    # File gc.rb, line 217
    def self.stat_heap heap_name = nil, hash_or_key = nil
      Primitive.gc_stat_heap heap_name, hash_or_key
    end

stress → integer, true or false click to toggle source

Returns current status of GC stress mode.

    # File gc.rb, line 71
    def self.stress
      Primitive.gc_stress_get
    end

stress = flag → flag click to toggle source

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 gc.rb, line 89
    def self.stress=(flag)
      Primitive.gc_stress_set_m flag
    end

total_time → int click to toggle source

Return measured GC total time in nano seconds.

    # File gc.rb, line 283
    def self.total_time
      Primitive.cexpr! %{
        ULL2NUM(rb_objspace.profile.total_time_ns)
      }
    end

using_rvargc? → true or false click to toggle source

Returns true if using experimental feature Variable Width Allocation, false otherwise.

    static VALUE
    gc_using_rvargc_p(VALUE mod)
    {
    #if USE_RVARGC
        return Qtrue;
    #else
        return Qfalse;
    #endif
    }

verify_compaction_references(toward: nil, double_heap: false) → hash click to toggle source

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 gc.rb, line 250
    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 → nil click to toggle source

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;
    }

verify_transient_heap_internal_consistency() click to toggle source

    static VALUE
    gc_verify_transient_heap_internal_consistency(VALUE dmy)
    {
        rb_transient_heap_verify();
        return Qnil;
    }

### Public Instance Methods

garbage_collect(full_mark: true, immediate_mark: true, immediate_sweep: true) click to toggle source

    # File 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