123456789_123456789_123456789_123456789_123456789_

Module: ObjectSpace

Overview

The objspace library extends the ObjectSpace module and adds several methods to get internal statistic information about object/memory management.

You need to require 'objspace' to use this extension module.

Generally, you SHOULD NOT use this library if you do not know about the MRI implementation. Mainly, this library is for (memory) profiler developers and MRI developers who need to know about MRI memory usage.

Class Method Summary

Class Method Details

._dump(obj, output) (mod_func)

This method is for internal use only.
[ GitHub ]

  
# File 'ext/objspace/objspace_dump.c', line 792

static VALUE
objspace_dump(VALUE os, VALUE obj, VALUE output)
{
    VALUE args[2];
    args[0] = obj;
    args[1] = output;
    return rb_vm_lock_with_barrier(dump_locked, (void*)args);
}

._dump_all(output, full, since, shapes) (mod_func)

This method is for internal use only.
[ GitHub ]

  
# File 'ext/objspace/objspace_dump.c', line 877

static VALUE
objspace_dump_all(VALUE os, VALUE output, VALUE full, VALUE since, VALUE shapes)
{
    VALUE args[4];
    args[0] = output;
    args[1] = full;
    args[2] = since;
    args[3] = shapes;
    return rb_vm_lock_with_barrier(dump_all_locked, (void*)args);
}

._dump_shapes(output, shapes) (mod_func)

This method is for internal use only.
[ GitHub ]

  
# File 'ext/objspace/objspace_dump.c', line 904

static VALUE
objspace_dump_shapes(VALUE os, VALUE output, VALUE shapes)
{
    VALUE args[2];
    args[0] = output;
    args[1] = shapes;
    return rb_vm_lock_with_barrier(dump_shapes_locked, (void*)args);
}

.allocation_class_path(object) ⇒ String (mod_func)

Returns the class for the given object.

class A
  def foo
    ObjectSpace::trace_object_allocations do
      obj = Object.new
      p "#{ObjectSpace::allocation_class_path(obj)}"
    end
  end
end

A.new.foo #=> "Class"

See .trace_object_allocations for more information and examples.

[ GitHub ]

  
# File 'ext/objspace/object_tracing.c', line 511

static VALUE
allocation_class_path(VALUE self, VALUE obj)
{
    struct allocation_info *info = lookup_allocation_info(obj);

    if (info && info->class_path) {
        return rb_str_new2(info->class_path);
    }
    else {
        return Qnil;
    }
}

.allocation_generation(object) ⇒ Integer? (mod_func)

Returns garbage collector generation for the given object.

class B
  include ObjectSpace

  def foo
    trace_object_allocations do
      obj = Object.new
      p "Generation is #{allocation_generation(obj)}"
    end
  end
end

B.new.foo #=> "Generation is 3"

See .trace_object_allocations for more information and examples.

[ GitHub ]

  
# File 'ext/objspace/object_tracing.c', line 576

static VALUE
allocation_generation(VALUE self, VALUE obj)
{
    struct allocation_info *info = lookup_allocation_info(obj);
    if (info) {
        return SIZET2NUM(info->generation);
    }
    else {
        return Qnil;
    }
}

.allocation_method_id(object) ⇒ String (mod_func)

Returns the method identifier for the given object.

class A
  include ObjectSpace

  def foo
    trace_object_allocations do
      obj = Object.new
      p "#{allocation_class_path(obj)}##{allocation_method_id(obj)}"
    end
  end
end

A.new.foo #=> "Class#new"

See .trace_object_allocations for more information and examples.

[ GitHub ]

  
# File 'ext/objspace/object_tracing.c', line 544

static VALUE
allocation_method_id(VALUE self, VALUE obj)
{
    struct allocation_info *info = lookup_allocation_info(obj);
    if (info) {
        return info->mid;
    }
    else {
        return Qnil;
    }
}

.allocation_sourcefile(object) ⇒ String (mod_func)

Returns the source file origin from the given object.

See .trace_object_allocations for more information and examples.

[ GitHub ]

  
# File 'ext/objspace/object_tracing.c', line 460

static VALUE
allocation_sourcefile(VALUE self, VALUE obj)
{
    struct allocation_info *info = lookup_allocation_info(obj);

    if (info && info->path) {
        return rb_str_new2(info->path);
    }
    else {
        return Qnil;
    }
}

.allocation_sourceline(object) ⇒ Integer (mod_func)

Returns the original line from source for from the given object.

See .trace_object_allocations for more information and examples.

[ GitHub ]

  
# File 'ext/objspace/object_tracing.c', line 480

static VALUE
allocation_sourceline(VALUE self, VALUE obj)
{
    struct allocation_info *info = lookup_allocation_info(obj);

    if (info) {
        return INT2FIX(info->line);
    }
    else {
        return Qnil;
    }
}

.count_imemo_objects(result_hash = nil) ⇒ Hash (mod_func)

Returns a hash containing the number of objects for each T_IMEMO type. The keys are Symbol objects of the T_IMEMO type name. T_IMEMO objects are Ruby internal objects that are not visible to Ruby programs.

ObjectSpace.count_imemo_objects
# => {imemo_callcache: 5482, imemo_constcache: 1258, imemo_ment: 13906, ... }

If the optional argument result_hash is given, it is overwritten and returned. This is intended to avoid the probe effect.

This method is intended for developers interested in performance and memory usage of Ruby programs. The contents of the returned hash is implementation specific and may change in the future.

This method is only expected to work with C Ruby.

[ GitHub ]

  
# File 'ext/objspace/objspace.c', line 438

static VALUE
count_imemo_objects(int argc, VALUE *argv, VALUE self)
{
    VALUE hash = setup_hash(argc, argv);

    if (imemo_type_ids[0] == 0) {
#define INIT_IMEMO_TYPE_ID(n) (imemo_type_ids[n] = rb_intern_const(#n))
        INIT_IMEMO_TYPE_ID(imemo_env);
        INIT_IMEMO_TYPE_ID(imemo_cref);
        INIT_IMEMO_TYPE_ID(imemo_svar);
        INIT_IMEMO_TYPE_ID(imemo_throw_data);
        INIT_IMEMO_TYPE_ID(imemo_ifunc);
        INIT_IMEMO_TYPE_ID(imemo_memo);
        INIT_IMEMO_TYPE_ID(imemo_ment);
        INIT_IMEMO_TYPE_ID(imemo_iseq);
        INIT_IMEMO_TYPE_ID(imemo_tmpbuf);
        INIT_IMEMO_TYPE_ID(imemo_callinfo);
        INIT_IMEMO_TYPE_ID(imemo_callcache);
        INIT_IMEMO_TYPE_ID(imemo_constcache);
        INIT_IMEMO_TYPE_ID(imemo_fields);
#undef INIT_IMEMO_TYPE_ID
    }

    each_object_with_flags(count_imemo_objects_i, (void *)hash);

    return hash;
}

.count_objects_size([result_hash]) ⇒ Hash (mod_func)

Counts objects size (in bytes) for each type.

Note that this information is incomplete. You need to deal with this information as only a HINT. Especially, total size of T_DATA may be wrong.

It returns a hash as:

{:TOTAL=>1461154, :T_CLASS=>158280, :T_MODULE=>20672, :T_STRING=>527249, ...}

If the optional argument, result_hash, is given, it is overwritten and returned. This is intended to avoid probe effect.

The contents of the returned hash is implementation defined. It may be changed in future.

This method is only expected to work with C Ruby.

[ GitHub ]

  
# File 'ext/objspace/objspace.c', line 245

static VALUE
count_objects_size(int argc, VALUE *argv, VALUE os)
{
    size_t counts[T_MASK+1];
    size_t total = 0;
    enum ruby_value_type i;
    VALUE hash = setup_hash(argc, argv);

    for (i = 0; i <= T_MASK; i++) {
        counts[i] = 0;
    }

    each_object_with_flags(cos_i, &counts[0]);

    for (i = 0; i <= T_MASK; i++) {
        if (counts[i]) {
            VALUE type = type2sym(i);
            total += counts[i];
            rb_hash_aset(hash, type, SIZET2NUM(counts[i]));
        }
    }
    rb_hash_aset(hash, ID2SYM(rb_intern("TOTAL")), SIZET2NUM(total));
    return hash;
}

.count_symbols(result_hash = nil) ⇒ Hash (mod_func)

Returns a hash containing the number of objects for each Symbol type.

The types of Symbols are the following:

  • mortal_dynamic_symbol: Symbols that are garbage collectable.

  • immortal_dynamic_symbol: Symbols that are objects allocated from the garbage collector, but are not garbage collectable.

  • immortal_static_symbol: Symbols that are not allocated from the garbage collector, and are thus not garbage collectable.

  • immortal_symbol: the sum of immortal_dynamic_symbol and immortal_static_symbol.

If the optional argument result_hash is given, it is overwritten and returned. This is intended to avoid the probe effect.

This method is intended for developers interested in performance and memory usage of Ruby programs. The contents of the returned hash is implementation specific and may change in the future.

This method is only expected to work with C Ruby.

[ GitHub ]

  
# File 'ext/objspace/objspace.c', line 318

static VALUE
count_symbols(int argc, VALUE *argv, VALUE os)
{
    struct dynamic_symbol_counts dynamic_counts = {0, 0};
    VALUE hash = setup_hash(argc, argv);

    size_t immortal_symbols = rb_sym_immortal_count();
    each_object_with_flags(cs_i, &dynamic_counts);

    rb_hash_aset(hash, ID2SYM(rb_intern("mortal_dynamic_symbol")),   SIZET2NUM(dynamic_counts.mortal));
    rb_hash_aset(hash, ID2SYM(rb_intern("immortal_dynamic_symbol")), SIZET2NUM(dynamic_counts.immortal));
    rb_hash_aset(hash, ID2SYM(rb_intern("immortal_static_symbol")),  SIZET2NUM(immortal_symbols - dynamic_counts.immortal));
    rb_hash_aset(hash, ID2SYM(rb_intern("immortal_symbol")),         SIZET2NUM(immortal_symbols));

    return hash;
}

.count_tdata_objects(result_hash = nil) ⇒ Hash (mod_func)

Returns a hash containing the number of objects for each T_DATA type. The keys are Class objects when the T_DATA object has an associated class, or Symbol objects of the name defined in the rb_data_type_struct for internal T_DATA objects.

ObjectSpace.count_tdata_objects
# => {RBS::Location => 39255, marshal_compat_table: 1, Encoding => 103, mutex: 1, ... }

If the optional argument result_hash is given, it is overwritten and returned. This is intended to avoid the probe effect.

This method is intended for developers interested in performance and memory usage of Ruby programs. The contents of the returned hash is implementation specific and may change in the future.

This method is only expected to work with C Ruby.

[ GitHub ]

  
# File 'ext/objspace/objspace.c', line 384

static VALUE
count_tdata_objects(int argc, VALUE *argv, VALUE self)
{
    VALUE hash = setup_hash(argc, argv);
    each_object_with_flags(cto_i, (void *)hash);
    return hash;
}

.dump(obj, output: :string) (mod_func)

Dump the contents of a ruby object as JSON.

output can be one of: :stdout, :file, :string, or IO object.

  • :file means dumping to a tempfile and returning corresponding File object;

  • :stdout means printing the dump and returning nil;

  • :string means returning a string with the dump;

  • if an instance of IO object is provided, the output goes there, and the object is returned.

This method is only expected to work with C Ruby. This is an experimental method and is subject to change. In particular, the function signature and output format are not guaranteed to be compatible in future versions of ruby.

[ GitHub ]

  
# File 'ext/objspace/lib/objspace.rb', line 28

def dump(obj, output: :string)
  out = case output
  when :file, nil
    require 'tempfile'
    Tempfile.create(%w(rubyobj .json))
  when :stdout
    STDOUT
  when :string
    +''
  when IO
    output
  else
    raise ArgumentError, "wrong output option: #{output.inspect}"
  end

  ret = _dump(obj, out)
  return nil if output == :stdout
  ret
end

.dump_all(output: :file, full: false, since: nil, shapes: true) (mod_func)

Dump the contents of the ruby heap as JSON.

output argument is the same as for #dump.

full must be a boolean. If true, all heap slots are dumped including the empty ones (T_NONE).

since must be a non-negative integer or nil.

If since is a positive integer, only objects of that generation and newer generations are dumped. The current generation can be accessed using GC.count. Objects that were allocated without object allocation tracing enabled are ignored. See .trace_object_allocations for more information and examples.

If since is omitted or is nil, all objects are dumped.

shapes must be a boolean or a non-negative integer.

If shapes is a positive integer, only shapes newer than the provided shape id are dumped. The current shape_id can be accessed using RubyVM.stat(:next_shape_id).

If shapes is false, no shapes are dumped.

To only dump objects allocated past a certain point you can combine since and shapes:

ObjectSpace.trace_object_allocations
GC.start
gc_generation = GC.count
shape_generation = RubyVM.stat(:next_shape_id)
call_method_to_instrument
ObjectSpace.dump_all(since: gc_generation, shapes: shape_generation)

This method is only expected to work with C Ruby. This is an experimental method and is subject to change. In particular, the function signature and output format are not guaranteed to be compatible in future versions of ruby.

[ GitHub ]

  
# File 'ext/objspace/lib/objspace.rb', line 84

def dump_all(output: :file, full: false, since: nil, shapes: true)
  out = case output
  when :file, nil
    require 'tempfile'
    Tempfile.create(%w(rubyheap .json))
  when :stdout
    STDOUT
  when :string
    +''
  when IO
    output
  else
    raise ArgumentError, "wrong output option: #{output.inspect}"
  end

  shapes = 0 if shapes == true
  ret = _dump_all(out, full, since, shapes)
  return nil if output == :stdout
  ret
end

.dump_shapes(output: :file, since: 0) (mod_func)

Dump the contents of the ruby shape tree as JSON.

output argument is the same as for #dump.

If since is a positive integer, only shapes newer than the provided shape id are dumped. The current shape_id can be accessed using RubyVM.stat(:next_shape_id).

This method is only expected to work with C Ruby. This is an experimental method and is subject to change. In particular, the function signature and output format are not guaranteed to be compatible in future versions of ruby.

[ GitHub ]

  
# File 'ext/objspace/lib/objspace.rb', line 116

def dump_shapes(output: :file, since: 0)
  out = case output
  when :file, nil
    require 'tempfile'
    Tempfile.create(%w(rubyshapes .json))
  when :stdout
    STDOUT
  when :string
    +''
  when IO
    output
  else
    raise ArgumentError, "wrong output option: #{output.inspect}"
  end

  ret = _dump_shapes(out, since)
  return nil if output == :stdout
  ret
end

.internal_class_of(obj) ⇒ Class, Module (mod_func)

MRI specific feature

Return internal class of obj.

obj can be an instance of ::ObjectSpace::InternalObjectWrapper.

Note that you should not use this method in your application.

[ GitHub ]

  
# File 'ext/objspace/objspace.c', line 706

static VALUE
objspace_internal_class_of(VALUE self, VALUE obj)
{
    VALUE klass;

    if (rb_typeddata_is_kind_of(obj, &iow_data_type)) {
        obj = (VALUE)DATA_PTR(obj);
    }

    if (RB_TYPE_P(obj, T_IMEMO)) {
        return Qnil;
    }
    else {
        klass = CLASS_OF(obj);
        return wrap_klass_iow(klass);
    }
}

.internal_super_of(cls) ⇒ Class, Module (mod_func)

MRI specific feature

Return internal super class of cls (Class or Module).

obj can be an instance of ::ObjectSpace::InternalObjectWrapper.

Note that you should not use this method in your application.

[ GitHub ]

  
# File 'ext/objspace/objspace.c', line 733

static VALUE
objspace_internal_super_of(VALUE self, VALUE obj)
{
    VALUE super;

    if (rb_typeddata_is_kind_of(obj, &iow_data_type)) {
        obj = (VALUE)DATA_PTR(obj);
    }

    switch (OBJ_BUILTIN_TYPE(obj)) {
      case T_MODULE:
      case T_CLASS:
      case T_ICLASS:
        super = rb_class_super_of(obj);
        break;
      default:
        rb_raise(rb_eArgError, "class or module is expected");
    }

    return wrap_klass_iow(super);
}

.memsize_of(obj) ⇒ Integer (mod_func)

Return consuming memory size of obj in bytes.

Note that the return size is incomplete. You need to deal with this information as only a HINT. Especially, the size of T_DATA may not be correct.

This method is only expected to work with CRuby.

From Ruby 3.2 with Variable Width Allocation, it returns the actual slot size used plus any additional memory allocated outside the slot (such as external strings, arrays, or hash tables).

[ GitHub ]

  
# File 'ext/objspace/objspace.c', line 48

static VALUE
memsize_of_m(VALUE self, VALUE obj)
{
    return SIZET2NUM(rb_obj_memsize_of(obj));
}

.memsize_of_all(klass = nil) ⇒ Integer (mod_func)

Returns the total memory size of all living objects in bytes.

ObjectSpace.memsize_of_all # => 12502001

If klass is given (which must be a Class or Module), returns the total memory size of objects whose class is, or is a subclass, of klass.

class MyClass; end
ObjectSpace.memsize_of_all(MyClass) # => 0
o = MyClass.new
ObjectSpace.memsize_of_all(MyClass) # => 40

Note that the value returned may be an underestimate of the actual amount of memory used. Therefore, the value returned should only be used as a hint, rather than a source of truth. In particular, the size of T_DATA objects may not be correct.

This method is only expected to work with C Ruby.

[ GitHub ]

  
# File 'ext/objspace/objspace.c', line 133

static VALUE
memsize_of_all_m(int argc, VALUE *argv, VALUE self)
{
    struct total_data data = {0, 0};

    if (argc > 0) {
        rb_scan_args(argc, argv, "01", &data.klass);
        if (!NIL_P(data.klass)) rb_obj_is_kind_of(Qnil, data.klass);
    }

    each_object_with_flags(total_i, &data);
    return SIZET2NUM(data.total);
}

.reachable_objects_from(obj) ⇒ Array? (mod_func)

MRI specific feature

Return all reachable objects from ‘obj’.

This method returns all reachable objects from ‘obj’.

If ‘obj’ has two or more references to the same object ‘x’, then returned array only includes one ‘x’ object.

If ‘obj’ is a non-markable (non-heap management) object such as true, false, nil, symbols and Fixnums (and Flonum) then it simply returns nil.

If ‘obj’ has references to an internal object, then it returns instances of ::ObjectSpace::InternalObjectWrapper class. This object contains a reference to an internal object and you can check the type of internal object with ‘type’ method.

If ‘obj’ is instance of ::ObjectSpace::InternalObjectWrapper class, then this method returns all reachable object from an internal object, which is pointed by ‘obj’.

With this method, you can find memory leaks.

This method is only expected to work with C Ruby.

Example:

ObjectSpace.reachable_objects_from(['a', 'b', 'c'])
#=> [Array, 'a', 'b', 'c']

ObjectSpace.reachable_objects_from(['a', 'a', 'a'])
#=> [Array, 'a', 'a', 'a'] # all 'a' strings have different object id

ObjectSpace.reachable_objects_from([v = 'a', v, v])
#=> [Array, 'a']

ObjectSpace.reachable_objects_from(1)
#=> nil # 1 is not markable (heap managed) object
[ GitHub ]

  
# File 'ext/objspace/objspace.c', line 594

static VALUE
reachable_objects_from(VALUE self, VALUE obj)
{
    if (!RB_SPECIAL_CONST_P(obj)) {
        struct rof_data data;

        if (rb_typeddata_is_kind_of(obj, &iow_data_type)) {
            obj = (VALUE)DATA_PTR(obj);
        }

        data.refs = rb_obj_hide(rb_ident_hash_new());
        data.values = rb_ary_new();

        rb_objspace_reachable_objects_from(obj, reachable_object_from_i, &data);

        return data.values;
    }
    else {
        return Qnil;
    }
}

.reachable_objects_from_rootHash (mod_func)

MRI specific feature

Return all reachable objects from root.

[ GitHub ]

  
# File 'ext/objspace/objspace.c', line 669

static VALUE
reachable_objects_from_root(VALUE self)
{
    struct rofr_data data;
    VALUE hash = data.categories = rb_ident_hash_new();
    data.last_category = 0;

    rb_objspace_reachable_objects_from_root(reachable_object_from_root_i, &data);
    rb_hash_foreach(hash, collect_values_of_values, hash);

    return hash;
}

.trace_object_allocations (mod_func)

Starts tracing object allocations from the ObjectSpace extension module.

For example:

require 'objspace'

class C
  include ObjectSpace

  def foo
    trace_object_allocations do
      obj = Object.new
      p "#{allocation_sourcefile(obj)}:#{allocation_sourceline(obj)}"
    end
  end
end

C.new.foo #=> "objtrace.rb:8"

This example has included the ObjectSpace module to make it easier to read, but you can also use the .trace_object_allocations notation (recommended).

Note that this feature introduces a huge performance decrease and huge memory consumption.

[ GitHub ]

  
# File 'ext/objspace/object_tracing.c', line 376

static VALUE
trace_object_allocations(VALUE self)
{
    trace_object_allocations_start(self);
    return rb_ensure(rb_yield, Qnil, trace_object_allocations_stop, self);
}

.trace_object_allocations_clear (mod_func)

Clear recorded tracing information.

[ GitHub ]

  
# File 'ext/objspace/object_tracing.c', line 332

static VALUE
trace_object_allocations_clear(VALUE self)
{
    struct traceobj_arg *arg = get_traceobj_arg();

    /* clear tables */
    st_foreach(arg->object_table, free_values_i, 0);
    st_clear(arg->object_table);
    st_foreach(arg->str_table, free_keys_i, 0);
    st_clear(arg->str_table);

    /* do not touch TracePoints */

    return Qnil;
}

.trace_object_allocations_debug_start (mod_func)

Starts tracing object allocations for GC debugging. If you encounter the BUG “… is T_NONE” (and so on) on your application, please try this method at the beginning of your app.

[ GitHub ]

  
# File 'ext/objspace/object_tracing.c', line 423

static VALUE
trace_object_allocations_debug_start(VALUE self)
{
    tmp_keep_remains = 1;
    if (object_allocations_reporter_registered == 0) {
        object_allocations_reporter_registered = 1;
        rb_bug_reporter_add(object_allocations_reporter, 0);
    }

    return trace_object_allocations_start(self);
}

.trace_object_allocations_start (mod_func)

Starts tracing object allocations.

[ GitHub ]

  
# File 'ext/objspace/object_tracing.c', line 276

static VALUE
trace_object_allocations_start(VALUE self)
{
    struct traceobj_arg *arg = get_traceobj_arg();

    if (arg->running++ > 0) {
        /* do nothing */
    }
    else {
        if (arg->newobj_trace == 0) {
            arg->newobj_trace = rb_tracepoint_new(0, RUBY_INTERNAL_EVENT_NEWOBJ, newobj_i, arg);
            arg->freeobj_trace = rb_tracepoint_new(0, RUBY_INTERNAL_EVENT_FREEOBJ, freeobj_i, arg);
        }
        rb_tracepoint_enable(arg->newobj_trace);
        rb_tracepoint_enable(arg->freeobj_trace);
    }

    return Qnil;
}

.trace_object_allocations_stop (mod_func)

Stop tracing object allocations.

Note that if .trace_object_allocations_start is called n-times, then tracing will stop after calling .trace_object_allocations_stop n-times.

[ GitHub ]

  
# File 'ext/objspace/object_tracing.c', line 305

static VALUE
trace_object_allocations_stop(VALUE self)
{
    struct traceobj_arg *arg = get_traceobj_arg();

    if (arg->running > 0) {
        arg->running--;
    }

    if (arg->running == 0) {
        if (arg->newobj_trace != 0) {
            rb_tracepoint_disable(arg->newobj_trace);
        }
        if (arg->freeobj_trace != 0) {
            rb_tracepoint_disable(arg->freeobj_trace);
        }
    }

    return Qnil;
}