123456789_123456789_123456789_123456789_123456789_

Module: GC

Relationships & Source Files
Namespace Children
Modules:
Profiler
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.

Constant Summary

Class Attribute Summary

Class Method Summary

Instance Method Summary

Class Attribute Details

.auto_compact ⇒ Boolean (rw)

Returns whether or not automatic compaction has been enabled.

[ GitHub ] 

  


# File 'gc.c', line 11653



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


  








  

    .auto_compact=(flag)   (rw)  



  

    

Updates automatic compaction mode.



When enabled, the compactor will execute on every major collection.



Enabling compaction will degrade performance on major collections.


  



  [ GitHub ]


  

  


# File 'gc.c', line 11634



static VALUE
gc_set_auto_compact(VALUE _, VALUE v)
{
    GC_ASSERT(GC_COMPACTION_SUPPORTED);

    ruby_enable_autocompact = RTEST(v);
    return v;
}


  








  

    .measure_total_time  ⇒ Boolean  (rw)  



  

    

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


  



  [ GitHub ]


  

  


# File 'gc.rb', line 273



def self.measure_total_time
  Primitive.cexpr! %{
    RBOOL(rb_objspace.flags.measure_gc)
  }
end


  








  

    .measure_total_time=(true/false)   (rw)  



  

    

Enable to measure 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 261



def self.measure_total_time=(flag)
  Primitive.cstmt! %{
    rb_objspace.flags.measure_gc = RTEST(flag) ? TRUE : FALSE;
    return flag;
  }
end


  








  

    .stress  ⇒ Boolean  (rw)  



  

    

Returns current status of GC stress mode.


  



  [ GitHub ]


  

  


# File 'gc.rb', line 71



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.



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


  



  [ GitHub ]


  

  


# File 'gc.rb', line 89



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


  








  

    .using_rvargc?  ⇒ Boolean  (readonly)  



  

    

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


  



  [ GitHub ]


  

  


# File 'gc.c', line 14607



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


  







Class Method Details



  

    .add_stress_to_class(class[, ...])    



  

    

Raises NoMemoryError when allocating an instance of the given classes.


  



  [ GitHub ]


  

  


# File 'gc.c', line 14505



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


  








  

    .compact    



  

    

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


  



  [ GitHub ]


  

  


# File 'gc.c', line 10956



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   



  

    

The number of times GC occurred.



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


  



  [ GitHub ]


  

  


# File 'gc.rb', line 99



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 63



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 51



def self.enable
  Primitive.gc_enable
end


  








  

    .latest_compact_info  ⇒ Hash   



  

    

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.


  



  [ GitHub ]


  

  


# File 'gc.c', line 10850



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


  





  


  [ GitHub ]


  

  


# 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   



  

    

Returns the size of memory allocated by malloc().



Only available if ruby was built with CALC_EXACT_MALLOC_SIZE.


  



  [ GitHub ]


  

  


# File 'gc.c', line 12802



static VALUE
gc_malloc_allocated_size(VALUE self)
{
    return UINT2NUM(rb_objspace.malloc_params.allocated_size);
}


  








  

    .malloc_allocations  ⇒ Integer   



  

    

Returns the number of malloc() allocations.



Only available if ruby was built with CALC_EXACT_MALLOC_SIZE.


  



  [ GitHub ]


  

  


# File 'gc.c', line 12817



static VALUE
gc_malloc_allocations(VALUE self)
{
    return UINT2NUM(rb_objspace.malloc_params.allocations);
}


  








  

    .remove_stress_to_class(class[, ...])    



  

    

No longer raises ::NoMemoryError when allocating an instance of the given classes.


  



  [ GitHub ]


  

  


# File 'gc.c', line 14525



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 
      ObjectSpace.garbage_collect  ⇒ nil 
      .include(GC; garbage_collect)  ⇒ nil 
      .start(full_mark: true, immediate_sweep: true)  ⇒ nil 
      ObjectSpace.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.


  





  


  [ GitHub ]


  

  


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


  





  


  [ GitHub ]


  

  


# File 'gc.rb', line 183



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


  





  


  [ GitHub ]


  

  


# 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


  








  

    .total_time  ⇒ Integer   



  

    

Return measured GC total time in nano seconds.


  



  [ GitHub ]


  

  


# File 'gc.rb', line 283



def self.total_time
  Primitive.cexpr! %{
    ULL2NUM(rb_objspace.profile.total_time_ns)
  }
end


  








  

    .verify_compaction_references(toward: nil, double_heap: false)  ⇒ Hash   



  

    

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.


  



  [ GitHub ]






  

    .verify_internal_consistency  ⇒ nil   



  

    

Verify internal consistency.



This method is implementation specific. Now this method checks generational consistency if RGenGC is supported.


  



  [ GitHub ]


  

  


# File 'gc.c', line 8070



static VALUE
gc_verify_internal_consistency_m(VALUE dummy)
{
    gc_verify_internal_consistency(&rb_objspace);
    return Qnil;
}


  








  

    .verify_transient_heap_internal_consistency  
  

  [ GitHub ]


  

  


# File 'gc.c', line 8183



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


  







Instance Method Details



  

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

  [ GitHub ]


  

  


# 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