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

.stress ⇒ Boolean (rw)

Returns current status of GC stress mode.

[ GitHub ] 

  


# File 'gc.rb', line 71



def self.stress
  __builtin_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)
  __builtin_gc_stress_set_m flag
end


  







Class Method Details



  

    .add_stress_to_class(class[, ...])    



  

    

Raises NoMemoryError when allocating an instance of the given classes.


  



  [ GitHub ]


  

  


# File 'gc.c', line 11796



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


  








  

    .compact  
  

  [ GitHub ]


  

  


# File 'gc.rb', line 158



def self.compact
  __builtin_rb_gc_compact
end


  








  

    .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
  __builtin_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
  __builtin_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
  __builtin_gc_enable
end


  








  

    

      .latest_gc_info  ⇒ GC 
      .latest_gc_info(hash)  ⇒ Hash 
      .latest_gc_info(:major_by)  ⇒ :malloc 
    

  



  

    

Returns information about the most recent garbage collection.


  





  


  [ GitHub ]


  

  


# File 'gc.rb', line 154



def self.latest_gc_info hash_or_key = nil
  __builtin_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 10310



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 10325



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 11816



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
  __builtin_gc_start_internal full_mark, immediate_mark, immediate_sweep
end


  








  

    

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

  



  

    

Returns a ::Hash containing information about the GC.



The hash includes information about internal statistics about GC such as:



{
    :count=>0,
    :heap_allocated_pages=>24,
    :heap_sorted_length=>24,
    :heap_allocatable_pages=>0,
    :heap_available_slots=>9783,
    :heap_live_slots=>7713,
    :heap_free_slots=>2070,
    :heap_final_slots=>0,
    :heap_marked_slots=>0,
    :heap_eden_pages=>24,
    :heap_tomb_pages=>0,
    :total_allocated_pages=>24,
    :total_freed_pages=>0,
    :total_allocated_objects=>7796,
    :total_freed_objects=>83,
    :malloc_increase_bytes=>2389312,
    :malloc_increase_bytes_limit=>16777216,
    :minor_gc_count=>0,
    :major_gc_count=>0,
    :remembered_wb_unprotected_objects=>0,
    :remembered_wb_unprotected_objects_limit=>0,
    :old_objects=>0,
    :old_objects_limit=>0,
    :oldmalloc_increase_bytes=>2389760,
    :oldmalloc_increase_bytes_limit=>16777216
}



The contents of the hash are implementation specific and may be changed in the future.



This method is only expected to work on C Ruby.


  





  


  [ GitHub ]


  

  


# File 'gc.rb', line 144



def self.stat hash_or_key = nil
  __builtin_gc_stat hash_or_key
end


  








  

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



  

    

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.


  



  [ GitHub ]


  

  


# File 'gc.c', line 8651



static VALUE
gc_verify_compaction_references(int argc, VALUE *argv, VALUE mod)
{
    rb_objspace_t *objspace = &rb_objspace;
    int use_toward_empty = FALSE;
    int use_double_pages = FALSE;

    if (dont_gc) return Qnil;

    VALUE opt = Qnil;
    static ID keyword_ids[2];
    VALUE kwvals[2];

    kwvals[1] = Qtrue;

    rb_scan_args(argc, argv, "0:", &opt);

    if (!NIL_P(opt)) {
        if (!keyword_ids[0]) {
            keyword_ids[0] = rb_intern("toward");
            keyword_ids[1] = rb_intern("double_heap");
        }

        rb_get_kwargs(opt, keyword_ids, 0, 2, kwvals);
        if (kwvals[0] != Qundef && rb_intern("empty") == rb_sym2id(kwvals[0])) {
            use_toward_empty = TRUE;
        }
        if (kwvals[1] != Qundef && RTEST(kwvals[1])) {
            use_double_pages = TRUE;
        }
    }

    gc_compact(objspace, use_toward_empty, use_double_pages, TRUE);
    return gc_compact_stats(objspace);
}


  








  

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



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 6223



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
  __builtin_gc_start_internal full_mark, immediate_mark, immediate_sweep
end