static VALUEallocation_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 givenobject.

classAdeffooObjectSpace::trace_object_allocationsdoobj =Object.newp"#{ObjectSpace::allocation_class_path(obj)}"endendendA.new.foo#=> "Class"

See::trace_object_allocations for more information and examples.

static VALUEallocation_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 givenobject.

classBincludeObjectSpacedeffootrace_object_allocationsdoobj =Object.newp"Generation is #{allocation_generation(obj)}"endendendB.new.foo#=> "Generation is 3"

See::trace_object_allocations for more information and examples.

static VALUEallocation_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 givenobject.

classAincludeObjectSpacedeffootrace_object_allocationsdoobj =Object.newp"#{allocation_class_path(obj)}##{allocation_method_id(obj)}"endendendA.new.foo#=> "Class#new"

See::trace_object_allocations for more information and examples.

static VALUEallocation_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 givenobject.

See::trace_object_allocations for more information and examples.

static VALUEallocation_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 givenobject.

See::trace_object_allocations for more information and examples.

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

Counts objects for eachT_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.

static VALUEcount_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.

static VALUEcount_objects(int argc, VALUE *argv, VALUE os){    struct count_objects_data data = { 0 };    VALUE hash = Qnil;    VALUE types[T_MASK + 1];    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");    }    for (size_t i = 0; i <= T_MASK; i++) {        // type_sym can allocate an object,        // so we need to create all key symbols in advance        // not to disturb the result        types[i] = type_sym(i);    }    // Same as type_sym, we need to create all key symbols in advance    VALUE total = ID2SYM(rb_intern("TOTAL"));    VALUE free = ID2SYM(rb_intern("FREE"));    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, total, SIZET2NUM(data.total));    rb_hash_aset(hash, free, SIZET2NUM(data.freed));    for (size_t i = 0; i <= T_MASK; i++) {        if (data.counts[i]) {            rb_hash_aset(hash, types[i], 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 argumentresult_hash is given, it is overwritten and returned. This is intended to avoid probe effect.

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

This method is only expected to work on C Ruby.

static VALUEcount_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 aHINT. 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.

static VALUEcount_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 eachSymbol 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)

static VALUEcount_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 eachT_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 orSymbol 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.

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

AddsaProc as a finalizer, to be called afterobj was destroyed. The object ID of theobj will be passed as an argument toaProc. IfaProc 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.

classFoodefinitialize(data_needed_for_finalization)ObjectSpace.define_finalizer(self,self.class.create_finalizer(data_needed_for_finalization))enddefself.create_finalizer(data_needed_for_finalization)proc {puts"finalizing #{data_needed_for_finalization}"    }endendclassBarclassRemoverdefinitialize(data_needed_for_finalization)@data_needed_for_finalization =data_needed_for_finalizationenddefcall(id)puts"finalizing #{@data_needed_for_finalization}"endenddefinitialize(data_needed_for_finalization)ObjectSpace.define_finalizer(self,Remover.new(data_needed_for_finalization))endend

Note that if your finalizer references the object to be finalized it will never be run onGC, 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.

classCapturesSelfdefinitialize(name)ObjectSpace.define_finalizer(self,proc {# this finalizer will only be run on exitputs"finalizing #{name}"    })endend

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

static VALUEos_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. Ifmodule 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 (Fixnums,Symbolstrue,false, andnil) are never returned. In the example below, each_object returns both the numbers we defined and several constants defined in theMath module.

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

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

produces:

12345678987654321102.72.718281828459053.141592653589792.22044604925031e-161.7976931348623157e+3082.2250738585072e-308Totalcount:7

Due to a current knownRactor implementation issue, this method will not yield Ractor-unshareable objects in multi-Ractor mode (whenRactor.new has been called within the process at least once). Seebugs.ruby-lang.org/issues/19387 for more information.

a =12345678987654321# shareableb = [].freeze# shareablec = {}# not shareableObjectSpace.each_object {|x|x }# yields a, b, and cRactor.new {}# enter multi-Ractor modeObjectSpace.each_object {|x|x }# does not yield c

# File gc.rb, line 599defgarbage_collectfull_mark:true,immediate_mark:true,immediate_sweep:truePrimitive.gc_start_internalfull_mark,immediate_mark,immediate_sweep,falseend

Alias ofGC.start

static VALUEobjspace_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 ofInternalObjectWrapper.

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

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

MRI specific feature

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

obj can be an instance ofInternalObjectWrapper.

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

static VALUEmemsize_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 aHINT. Especially, the size ofT_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).

static VALUEmemsize_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.

Ifklass (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 aHINT. Especially, the size ofT_DATA may not be correct.

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

This method can be defined by the following Ruby code:

defmemsize_of_allklass =falsetotal =0ObjectSpace.each_object{|e|total+=ObjectSpace.memsize_of(e)ifklass==false||e.kind_of?(klass)  }totalend

This method is only expected to work with C Ruby.

static VALUEreachable_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 ofObjectSpace::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 ofObjectSpace::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 idObjectSpace.reachable_objects_from([v ='a',v,v])#=> [Array, 'a']ObjectSpace.reachable_objects_from(1)#=> nil # 1 is not markable (heap managed) object

static VALUEreachable_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.

static VALUEtrace_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 theObjectSpace extension module.

For example:

require'objspace'classCincludeObjectSpacedeffootrace_object_allocationsdoobj =Object.newp"#{allocation_sourcefile(obj)}:#{allocation_sourceline(obj)}"endendendC.new.foo#=> "objtrace.rb:8"

This example has included theObjectSpace 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.

static VALUEtrace_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.

static VALUEtrace_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.

static VALUEtrace_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.

static VALUEundefine_final(VALUE os, VALUE obj){    return rb_undefine_finalizer(obj);}

Removes all finalizers forobj.

# File ext/objspace/lib/objspace.rb, line 28defdump(obj,output::string)out =caseoutputwhen:file,nilrequire'tempfile'Tempfile.create(%w(rubyobj .json))when:stdoutSTDOUTwhen:string+''whenIOoutputelseraiseArgumentError,"wrong output option: #{output.inspect}"endret =_dump(obj,out)returnnilifoutput==:stdoutretend

Dump the contents of a ruby object asJSON.

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

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

• :stdout means printing the dump and returningnil;

• :string means returning a string with the dump;

• if an instance ofIO 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.

# File ext/objspace/lib/objspace.rb, line 84defdump_all(output::file,full:false,since:nil,shapes:true)out =caseoutputwhen:file,nilrequire'tempfile'Tempfile.create(%w(rubyheap .json))when:stdoutSTDOUTwhen:string+''whenIOoutputelseraiseArgumentError,"wrong output option: #{output.inspect}"endshapes =0ifshapes==trueret =_dump_all(out,full,since,shapes)returnnilifoutput==:stdoutretend

Dump the contents of the ruby heap asJSON.

output argument is the same as fordump.

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

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

Ifsince is omitted or isnil, all objects are dumped.

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

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

Ifshapes isfalse, no shapes are dumped.

To only dump objects allocated past a certain point you can combinesince andshapes:

ObjectSpace.trace_object_allocationsGC.startgc_generation =GC.countshape_generation =RubyVM.stat(:next_shape_id)call_method_to_instrumentObjectSpace.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.

# File ext/objspace/lib/objspace.rb, line 116defdump_shapes(output::file,since:0)out =caseoutputwhen:file,nilrequire'tempfile'Tempfile.create(%w(rubyshapes .json))when:stdoutSTDOUTwhen:string+''whenIOoutputelseraiseArgumentError,"wrong output option: #{output.inspect}"endret =_dump_shapes(out,since)returnnilifoutput==:stdoutretend

Dump the contents of the ruby shape tree asJSON.

output argument is the same as fordump.

Ifsince is a positive integer, only shapes newer than the provided shape id are dumped. The current shape_id can be accessed usingRubyVM.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.

# File gc.rb, line 599defgarbage_collectfull_mark:true,immediate_mark:true,immediate_sweep:truePrimitive.gc_start_internalfull_mark,immediate_mark,immediate_sweep,falseend

Alias ofGC.start