# module ObjectSpace

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.

The `ObjectSpace` module contains a number of routines that interact with the garbage collection facility and allow you to traverse all living objects with an iterator.

`ObjectSpace` also provides support for object finalizers, procs that will be called after a specific object was destroyed by garbage collection. See the documentation for `ObjectSpace.define_finalizer` for important information on how to use this method correctly.

    a = "A"
    b = "B"

    ObjectSpace.define_finalizer(a, proc {|id| puts "Finalizer one on #{id}" })
    ObjectSpace.define_finalizer(b, proc {|id| puts "Finalizer two on #{id}" })

    a = nil
    b = nil

produces:

    Finalizer two on 537763470
    Finalizer one on 537763480

### Public Class Methods

allocation_class_path(object) → string
Source

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

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.

allocation_generation(object) → integer or nil
Source

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

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.

allocation_method_id(object) → string
Source

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

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.

allocation_sourcefile(object) → string
Source

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

Returns the source file origin from the given `object`.

See `::trace_object_allocations` for more information and examples.

allocation_sourceline(object) → integer
Source

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

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

See `::trace_object_allocations` for more information and examples.

count_imemo_objects([result_hash]) → hash
Source

    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_ast);
            INIT_IMEMO_TYPE_ID(imemo_parser_strterm);
            INIT_IMEMO_TYPE_ID(imemo_callinfo);
            INIT_IMEMO_TYPE_ID(imemo_callcache);
            INIT_IMEMO_TYPE_ID(imemo_constcache);
    #undef INIT_IMEMO_TYPE_ID
        }

        each_object_with_flags(count_imemo_objects_i, (void *)hash);

        return hash;
    }

Counts objects for each `T_IMEMO` type.

This method is only for MRI developers interested in performance and memory usage of Ruby programs.

It returns a hash as:

    {:imemo_ifunc=>8,
     :imemo_svar=>7,
     :imemo_cref=>509,
     :imemo_memo=>1,
     :imemo_throw_data=>1}

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 specific and may change in the future.

In this version, keys are symbol objects.

This method is only expected to work with C Ruby.

count_nodes([result_hash]) → hash
Source

    static VALUE
    count_nodes(int argc, VALUE *argv, VALUE os)
    {
        return setup_hash(argc, argv);
    }

Counts nodes for each node type.

This method is only for MRI developers interested in performance and memory usage of Ruby programs.

It returns a hash as:

    {:NODE_METHOD=>2027, :NODE_FBODY=>1927, :NODE_CFUNC=>1798, ...}

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

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

count_objects([result_hash]) → hash
Source

    static VALUE
    count_objects(int argc, VALUE *argv, VALUE os)
    {
        struct count_objects_data data = { 0 };
        VALUE hash = Qnil;

        if (rb_check_arity(argc, 0, 1) == 1) {
            hash = argv[0];
            if (!RB_TYPE_P(hash, T_HASH))
                rb_raise(rb_eTypeError, "non-hash given");
        }

        rb_gc_impl_each_object(rb_gc_get_objspace(), count_objects_i, &data);

        if (NIL_P(hash)) {
            hash = rb_hash_new();
        }
        else if (!RHASH_EMPTY_P(hash)) {
            rb_hash_stlike_foreach(hash, set_zero, hash);
        }
        rb_hash_aset(hash, ID2SYM(rb_intern("TOTAL")), SIZET2NUM(data.total));
        rb_hash_aset(hash, ID2SYM(rb_intern("FREE")), SIZET2NUM(data.freed));

        for (size_t i = 0; i <= T_MASK; i++) {
            VALUE type = type_sym(i);
            if (data.counts[i])
                rb_hash_aset(hash, type, SIZET2NUM(data.counts[i]));
        }

        return hash;
    }

Counts all objects grouped by type.

It returns a hash, such as:

    {
      :TOTAL=>10000,
      :FREE=>3011,
      :T_OBJECT=>6,
      :T_CLASS=>404,
      # ...
    }

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

The keys starting with `:T_` means live objects. For example, `:T_ARRAY` is the number of arrays. `:FREE` means object slots which is not used now. `:TOTAL` means sum of above.

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

    h = {}
    ObjectSpace.count_objects(h)
    puts h
    # => { :TOTAL=>10000, :T_CLASS=>158280, :T_MODULE=>20672, :T_STRING=>527249 }

This method is only expected to work on C Ruby.

count_objects_size([result_hash]) → hash
Source

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

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.

count_symbols([result_hash]) → hash
Source

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

Counts symbols for each `Symbol` type.

This method is only for MRI developers interested in performance and memory usage of Ruby programs.

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

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

On this version of MRI, they have 3 types of Symbols (and 1 total counts).

    * mortal_dynamic_symbol: GC target symbols (collected by GC)
    * immortal_dynamic_symbol: Immortal symbols promoted from dynamic symbols (do not collected by GC)
    * immortal_static_symbol: Immortal symbols (do not collected by GC)
    * immortal_symbol: total immortal symbols (immortal_dynamic_symbol+immortal_static_symbol)

count_tdata_objects([result_hash]) → hash
Source

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

Counts objects for each `T_DATA` type.

This method is only for MRI developers interested in performance and memory usage of Ruby programs.

It returns a hash as:

    {RubyVM::InstructionSequence=>504, :parser=>5, :barrier=>6,
     :mutex=>6, Proc=>60, RubyVM::Env=>57, Mutex=>1, Encoding=>99,
     ThreadGroup=>1, Binding=>1, Thread=>1, RubyVM=>1, :iseq=>1,
     Random=>1, ARGF.class=>1, Data=>1, :autoload=>3, Time=>2}
    # T_DATA objects existing at startup on r32276.

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 specific and may change in the future.

In this version, keys are `Class` object or `Symbol` object.

If object is kind of normal (accessible) object, the key is `Class` object. If object is not a kind of normal (internal) object, the key is symbol name, registered by rb_data_type_struct.

This method is only expected to work with C Ruby.

define_finalizer(obj, aProc=proc())
Source

    static VALUE
    define_final(int argc, VALUE *argv, VALUE os)
    {
        VALUE obj, block;

        rb_scan_args(argc, argv, "11", &obj, &block);
        if (argc == 1) {
            block = rb_block_proc();
        }

        if (rb_callable_receiver(block) == obj) {
            rb_warn("finalizer references object to be finalized");
        }

        return rb_define_finalizer(obj, block);
    }

Adds aProc as a finalizer, to be called after obj was destroyed. The object ID of the obj will be passed as an argument to aProc. If aProc is a lambda or method, make sure it can be called with a single argument.

The return value is an array `[0, aProc]`.

The two recommended patterns are to either create the finaliser proc in a non-instance method where it can safely capture the needed state, or to use a custom callable object that stores the needed state explicitly as instance variables.

    class Foo
      def initialize(data_needed_for_finalization)
        ObjectSpace.define_finalizer(self, self.class.create_finalizer(data_needed_for_finalization))
      end

      def self.create_finalizer(data_needed_for_finalization)
        proc {
          puts "finalizing #{data_needed_for_finalization}"
        }
      end
    end

    class Bar
     class Remover
        def initialize(data_needed_for_finalization)
          @data_needed_for_finalization = data_needed_for_finalization
        end

        def call(id)
          puts "finalizing #{@data_needed_for_finalization}"
        end
      end

      def initialize(data_needed_for_finalization)
        ObjectSpace.define_finalizer(self, Remover.new(data_needed_for_finalization))
      end
    end

Note that if your finalizer references the object to be finalized it will never be run on `GC`, although it will still be run at exit. You will get a warning if you capture the object to be finalized as the receiver of the finalizer.

    class CapturesSelf
      def initialize(name)
        ObjectSpace.define_finalizer(self, proc {
          # this finalizer will only be run on exit
          puts "finalizing #{name}"
        })
      end
    end

Also note that finalization can be unpredictable and is never guaranteed to be run except on exit.

each_object([module]) {|obj| ... } → integer
each_object([module]) → an_enumerator
Source

    static VALUE
    os_each_obj(int argc, VALUE *argv, VALUE os)
    {
        VALUE of;

        of = (!rb_check_arity(argc, 0, 1) ? 0 : argv[0]);
        RETURN_ENUMERATOR(os, 1, &of);
        return os_obj_of(of);
    }

Calls the block once for each living, nonimmediate object in this Ruby process. If module is specified, calls the block for only those classes or modules that match (or are a subclass of) module. Returns the number of objects found. Immediate objects (`Fixnum`s, `Symbol`s `true`, `false`, and `nil`) are never returned. In the example below, each_object returns both the numbers we defined and several constants defined in the `Math` module.

If no block is given, an enumerator is returned instead.

    a = 102.7
    b = 95       # Won't be returned
    c = 12345678987654321
    count = ObjectSpace.each_object(Numeric) {|x| p x }
    puts "Total count: #{count}"

produces:

    12345678987654321
    102.7
    2.71828182845905
    3.14159265358979
    2.22044604925031e-16
    1.7976931348623157e+308
    2.2250738585072e-308
    Total count: 7

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

    # File gc.rb, line 395
    def garbage_collect full_mark: true, immediate_mark: true, immediate_sweep: true
      Primitive.gc_start_internal full_mark, immediate_mark, immediate_sweep, false
    end

Alias of `GC.start`

internal_class_of(obj) → Class or Module
Source

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

MRI specific feature

  Return internal class of obj.

obj can be an instance of `InternalObjectWrapper`.

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

internal_super_of(cls) → Class or Module
Source

    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 = RCLASS_SUPER(obj);
            break;
          default:
            rb_raise(rb_eArgError, "class or module is expected");
        }

        return wrap_klass_iow(super);
    }

MRI specific feature

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

obj can be an instance of `InternalObjectWrapper`.

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

memsize_of(obj) → Integer
Source

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

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

From Ruby 2.2, `memsize_of`(obj) returns a memory size includes sizeof(RVALUE).

memsize_of_all([klass]) → Integer
Source

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

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

Return consuming memory size of all living objects in bytes.

If `klass` (should be `Class` object) is given, return the total memory size of instances of the given class.

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

Note that this method does NOT return total malloc’ed memory size.

This method can be defined by the following Ruby code:

    def memsize_of_all klass = false
      total = 0
      ObjectSpace.each_object{|e|
        total += ObjectSpace.memsize_of(e) if klass == false || e.kind_of?(klass)
      }
      total
    end

This method is only expected to work with C Ruby.

reachable_objects_from(obj) → array or nil
Source

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

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

reachable_objects_from_root → hash
Source

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

MRI specific feature

  Return all reachable objects from root.

trace_object_allocations { block }
Source

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

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.

trace_object_allocations_clear
Source

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

Clear recorded tracing information.

trace_object_allocations_debug_start ()
Source

    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
Source

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

Starts tracing object allocations.

trace_object_allocations_stop
Source

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

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.

undefine_finalizer(obj)
Source

    static VALUE
    undefine_final(VALUE os, VALUE obj)
    {
        rb_check_frozen(obj);

        rb_gc_impl_undefine_finalizer(rb_gc_get_objspace(), obj);

        return obj;
    }

Removes all finalizers for obj.

### Public Instance Methods

dump (obj, output: :string)
Source

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

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

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

dump_shapes (output: :file, since: 0)
Source

    # 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

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.

### Private Instance Methods

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

    # File gc.rb, line 395
    def garbage_collect full_mark: true, immediate_mark: true, immediate_sweep: true
      Primitive.gc_start_internal full_mark, immediate_mark, immediate_sweep, false
    end

Alias of `GC.start`