Module: GC

Defined in:
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 GC::Profiler.

Defined Under Namespace

Modules: Profiler

Constant Summary collapse

INTERNAL_CONSTANTS = 
gc_constants
OPTS = 
opts = rb_ary_new()

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.count ⇒ Integer

The number of times GC occurred.

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

Returns:



5234
5235
5236
5237
5238
 
# File 'gc.c', line 5234

static VALUE
gc_count(VALUE self)
{
    return SIZET2NUM(rb_gc_count());
}

.disable ⇒ Boolean

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

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

Returns:

  • (Boolean) 


5637
5638
5639
5640
5641
5642
5643
5644
5645
5646
5647
 
# File 'gc.c', line 5637

VALUE
rb_gc_disable(void)
{
    rb_objspace_t *objspace = &rb_objspace;
    int old = dont_gc;

    gc_rest_sweep(objspace);

    dont_gc = TRUE;
    return old ? Qtrue : Qfalse;
}

.enable ⇒ Boolean

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

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

Returns:

  • (Boolean) 


5615
5616
5617
5618
5619
5620
5621
5622
5623
 
# File 'gc.c', line 5615

VALUE
rb_gc_enable(void)
{
    rb_objspace_t *objspace = &rb_objspace;
    int old = dont_gc;

    dont_gc = FALSE;
    return old ? Qtrue : Qfalse;
}

.latest_gc_info ⇒ Object .latest_gc_info(hash) ⇒ Hash .latest_gc_info(:major_by) ⇒ Object

Returns information about the most recent garbage collection.

Overloads:

  • .latest_gc_info(hash) ⇒ Hash

    Returns:



5333
5334
5335
5336
5337
5338
5339
5340
5341
5342
5343
5344
5345
5346
5347
5348
5349
 
# File 'gc.c', line 5333

static VALUE
gc_latest_gc_info(int argc, VALUE *argv, VALUE self)
{
    rb_objspace_t *objspace = &rb_objspace;
    VALUE arg = Qnil;

    if (rb_scan_args(argc, argv, "01", &arg) == 1) {
	if (!SYMBOL_P(arg) && !RB_TYPE_P(arg, T_HASH)) {
	    rb_raise(rb_eTypeError, "non-hash or symbol given");
	}
    }

    if (arg == Qnil)
        arg = rb_hash_new();

    return gc_info_decode(objspace->profile.latest_gc_info, arg);
}

.malloc_allocated_size ⇒ Integer

Returns the size of memory allocated by malloc().

Only available if ruby was built with CALC_EXACT_MALLOC_SIZE.

Returns:



6286
6287
6288
6289
6290
 
# File 'gc.c', line 6286

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.

Returns:



6301
6302
6303
6304
6305
 
# File 'gc.c', line 6301

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

.start ⇒ nil .garbage_collect ⇒ nil .garbage_collect ⇒ nil .start(full_mark:false) ⇒ nil

Initiates garbage collection, unless 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.

Overloads:

  • .start ⇒ nil

    Returns:

    • (nil)
  • .garbage_collect ⇒ nil

    Returns:

    • (nil)
  • .garbage_collect ⇒ nil

    Returns:

    • (nil)
  • .start(full_mark:false) ⇒ nil

    Returns:

    • (nil) 


5150
5151
5152
5153
5154
5155
5156
5157
5158
5159
5160
5161
5162
5163
5164
5165
5166
5167
5168
5169
5170
5171
5172
5173
5174
5175
5176
5177
5178
5179
5180
 
# File 'gc.c', line 5150

static VALUE
gc_start_internal(int argc, VALUE *argv, VALUE self)
{
    rb_objspace_t *objspace = &rb_objspace;
    int full_mark = TRUE, immediate_sweep = TRUE;
    VALUE opt = Qnil;
    static ID keyword_ids[2];

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

    if (!NIL_P(opt)) {
	VALUE kwvals[2];

	if (!keyword_ids[0]) {
	    keyword_ids[0] = rb_intern("full_mark");
	    keyword_ids[1] = rb_intern("immediate_sweep");
	}

	rb_get_kwargs(opt, keyword_ids, 0, 2, kwvals);

	if (kwvals[0] != Qundef)
	    full_mark = RTEST(kwvals[0]);
	if (kwvals[1] != Qundef)
	    immediate_sweep = RTEST(kwvals[1]);
    }

    garbage_collect(objspace, full_mark, immediate_sweep, GPR_FLAG_METHOD);
    if (!finalizing) finalize_deferred(objspace);

    return Qnil;
}

.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=>2,
:heap_used=>9,
:heap_length=>11,
:heap_increment=>2,
:heap_live_slot=>6836,
:heap_free_slot=>519,
:heap_final_slot=>0,
:heap_swept_slot=>818,
:total_allocated_object=>7674,
:total_freed_object=>838,
:malloc_increase=>181034,
:malloc_limit=>16777216,
:minor_gc_count=>2,
:major_gc_count=>0,
:remembered_shady_object=>55,
:remembered_shady_object_limit=>0,
:old_object=>2422,
:old_object_limit=>0,
:oldmalloc_increase=>277386,
:oldmalloc_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.

Overloads:



5532
5533
5534
5535
5536
5537
5538
5539
5540
5541
5542
5543
5544
5545
5546
5547
5548
5549
5550
5551
5552
 
# File 'gc.c', line 5532

static VALUE
gc_stat(int argc, VALUE *argv, VALUE self)
{
    VALUE arg = Qnil;

    if (rb_scan_args(argc, argv, "01", &arg) == 1) {
	if (SYMBOL_P(arg)) {
	    size_t value = 0;
	    gc_stat_internal(arg, &value);
	    return SIZET2NUM(value);
	} else if (!RB_TYPE_P(arg, T_HASH)) {
	    rb_raise(rb_eTypeError, "non-hash or symbol given");
	}
    }

    if (arg == Qnil) {
        arg = rb_hash_new();
    }
    gc_stat_internal(arg, 0);
    return arg;
}

.stress ⇒ Boolean

Returns current status of GC stress mode.

Returns:

  • (Boolean) 


5574
5575
5576
5577
5578
5579
 
# File 'gc.c', line 5574

static VALUE
gc_stress_get(VALUE self)
{
    rb_objspace_t *objspace = &rb_objspace;
    return ruby_gc_stress;
}

.stress=(bool) ⇒ Boolean

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.

Returns:

  • (Boolean) 


5593
5594
5595
5596
5597
5598
5599
5600
 
# File 'gc.c', line 5593

static VALUE
gc_stress_set(VALUE self, VALUE flag)
{
    rb_objspace_t *objspace = &rb_objspace;
    rb_secure(2);
    ruby_gc_stress = FIXNUM_P(flag) ? flag : (RTEST(flag) ? Qtrue : Qfalse);
    return flag;
}

.verify_internal_consistency ⇒ nil

Verify internal consistency.

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

Returns:

  • (nil) 


4223
4224
4225
4226
4227
4228
4229
4230
4231
4232
4233
4234
4235
4236
4237
4238
4239
4240
4241
4242
 
# File 'gc.c', line 4223

static VALUE
gc_verify_internal_consistency(VALUE self)
{
    struct verify_internal_consistency_struct data;
    data.objspace = &rb_objspace;
    data.err_count = 0;

#if USE_RGENGC
    {
	struct each_obj_args eo_args;
	eo_args.callback = verify_internal_consistency_i;
	eo_args.data = (void *)&data;
	objspace_each_objects((VALUE)&eo_args);
    }
#endif
    if (data.err_count != 0) {
	rb_bug("gc_verify_internal_consistency: found internal consistency.\n");
    }
    return Qnil;
}

Instance Method Details

#start ⇒ nil #garbage_collect ⇒ nil #garbage_collect ⇒ nil #start(full_mark:false) ⇒ nil

Initiates garbage collection, unless 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.

Overloads:

  • #start ⇒ nil

    Returns:

    • (nil)
  • #garbage_collect ⇒ nil

    Returns:

    • (nil)
  • #garbage_collect ⇒ nil

    Returns:

    • (nil)
  • #start(full_mark:false) ⇒ nil

    Returns:

    • (nil) 


5150
5151
5152
5153
5154
5155
5156
5157
5158
5159
5160
5161
5162
5163
5164
5165
5166
5167
5168
5169
5170
5171
5172
5173
5174
5175
5176
5177
5178
5179
5180
 
# File 'gc.c', line 5150

static VALUE
gc_start_internal(int argc, VALUE *argv, VALUE self)
{
    rb_objspace_t *objspace = &rb_objspace;
    int full_mark = TRUE, immediate_sweep = TRUE;
    VALUE opt = Qnil;
    static ID keyword_ids[2];

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

    if (!NIL_P(opt)) {
	VALUE kwvals[2];

	if (!keyword_ids[0]) {
	    keyword_ids[0] = rb_intern("full_mark");
	    keyword_ids[1] = rb_intern("immediate_sweep");
	}

	rb_get_kwargs(opt, keyword_ids, 0, 2, kwvals);

	if (kwvals[0] != Qundef)
	    full_mark = RTEST(kwvals[0]);
	if (kwvals[1] != Qundef)
	    immediate_sweep = RTEST(kwvals[1]);
    }

    garbage_collect(objspace, full_mark, immediate_sweep, GPR_FLAG_METHOD);
    if (!finalizing) finalize_deferred(objspace);

    return Qnil;
}