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:



5227
5228
5229
5230
5231
 
# File 'gc.c', line 5227

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) 


5630
5631
5632
5633
5634
5635
5636
5637
5638
5639
5640
 
# File 'gc.c', line 5630

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) 


5608
5609
5610
5611
5612
5613
5614
5615
5616
 
# File 'gc.c', line 5608

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:



5326
5327
5328
5329
5330
5331
5332
5333
5334
5335
5336
5337
5338
5339
5340
5341
5342
 
# File 'gc.c', line 5326

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:



6269
6270
6271
6272
6273
 
# File 'gc.c', line 6269

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:



6284
6285
6286
6287
6288
 
# File 'gc.c', line 6284

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) 


5143
5144
5145
5146
5147
5148
5149
5150
5151
5152
5153
5154
5155
5156
5157
5158
5159
5160
5161
5162
5163
5164
5165
5166
5167
5168
5169
5170
5171
5172
5173
 
# File 'gc.c', line 5143

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:



5525
5526
5527
5528
5529
5530
5531
5532
5533
5534
5535
5536
5537
5538
5539
5540
5541
5542
5543
5544
5545
 
# File 'gc.c', line 5525

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) 


5567
5568
5569
5570
5571
5572
 
# File 'gc.c', line 5567

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) 


5586
5587
5588
5589
5590
5591
5592
5593
 
# File 'gc.c', line 5586

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) 


4207
4208
4209
4210
4211
4212
4213
4214
4215
4216
4217
4218
4219
4220
4221
4222
4223
4224
4225
4226
 
# File 'gc.c', line 4207

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) 


5143
5144
5145
5146
5147
5148
5149
5150
5151
5152
5153
5154
5155
5156
5157
5158
5159
5160
5161
5162
5163
5164
5165
5166
5167
5168
5169
5170
5171
5172
5173
 
# File 'gc.c', line 5143

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