Module: ObjectSpace
Relationships & Source Files | |
Namespace Children | |
Classes:
| |
Defined in: | ext/objspace/objspace.c, ext/objspace/object_tracing.c, ext/objspace/objspace_dump.c |
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
-
.allocation_class_path(object) ⇒ String
mod_func
Returns the class for the given
object
. -
.allocation_generation(object) ⇒ Fixnum
mod_func
Returns garbage collector generation for the given
object
. -
.allocation_method_id(object) ⇒ String
mod_func
Returns the method identifier for the given
object
. -
.allocation_sourcefile(object) ⇒ String
mod_func
Returns the source file origin from the given
object
. -
.allocation_sourceline(object) ⇒ String
mod_func
Returns the original line from source for from the given
object
. -
.count_imemo_objects([result_hash]) ⇒ Hash
mod_func
Counts objects for each
T_IMEMO
type. -
.count_nodes([result_hash]) ⇒ Hash
mod_func
Counts nodes for each node type.
-
.count_objects_size([result_hash]) ⇒ Hash
mod_func
Counts objects size (in bytes) for each type.
-
.count_symbols([result_hash]) ⇒ Hash
mod_func
Counts symbols for each Symbol type.
-
.count_tdata_objects([result_hash]) ⇒ Hash
mod_func
Counts objects for each
T_DATA
type. -
.dump(obj[, output: :string]) #) ⇒ "{ ... }"
mod_func
Dump the contents of a ruby object as JSON.
-
.dump_all([output: :file]) #)) ⇒ 1
mod_func
Dump the contents of the ruby heap as JSON.
-
.internal_class_of(obj) ⇒ Class, Module
mod_func
- MRI specific feature
Return internal class of obj.
-
.internal_super_of(cls) ⇒ Class, Module
mod_func
- MRI specific feature
Return internal super class of cls (Class or Module).
-
.memsize_of(obj) ⇒ Integer
mod_func
Return consuming memory size of obj.
-
.memsize_of_all([klass]) ⇒ Integer
mod_func
Return consuming memory size of all living objects.
-
.reachable_objects_from(obj) ⇒ Array?
mod_func
- MRI specific feature
Return all reachable objects from `obj'.
-
.reachable_objects_from_root ⇒ Hash
mod_func
- MRI specific feature
Return all reachable objects from root.
-
.trace_object_allocations
mod_func
Starts tracing object allocations from the
ObjectSpace
extension module. -
.trace_object_allocations_clear
mod_func
Clear recorded tracing information.
- .trace_object_allocations_debug_start mod_func
-
.trace_object_allocations_start
mod_func
Starts tracing object allocations.
-
.trace_object_allocations_stop
mod_func
Stop tracing object allocations.
Class Method Details
.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.
.allocation_generation(object) ⇒ Fixnum
(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.
.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.
.allocation_sourcefile(object) ⇒ String
(mod_func)
Returns the source file origin from the given object
.
See .trace_object_allocations for more information and examples.
.allocation_sourceline(object) ⇒ String
(mod_func)
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
(mod_func)
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
(mod_func)
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_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 not right size.
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
(mod_func)
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
(mod_func)
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, :=>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.
.dump(obj[, output: :string]) #) ⇒ "{ ... }" (mod_func)
.dump(obj, output: :file) #)) ⇒ 1
.dump(obj, output: :stdout) #)) ⇒ nil
1
.dump(obj, output: :stdout) #)) ⇒ nil
Dump the contents of a ruby object as JSON.
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]) #)) ⇒ 1
(mod_func)
.dump_all(output: :stdout) #)) ⇒ nil
.dump_all(output: :string) #)) ⇒ "{...}\n
{...}\n
..."
.dump_all(output:)
File.open('heap.json','w')) #) ⇒ #<File:heap
.json
1
(mod_func)
.dump_all(output: :stdout) #)) ⇒ nil
.dump_all(output: :string) #)) ⇒ "{...}\n
{...}\n
..."
.dump_all(output:)
File.open('heap.json','w')) #) ⇒ #<File:heap
.json
Dump the contents of the ruby heap as JSON.
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.
.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.
.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.
.memsize_of(obj) ⇒ Integer
(mod_func)
Return consuming memory size of obj.
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
(mod_func)
Return consuming memory size of all living objects.
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
? (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 except 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
(mod_func)
- MRI specific feature
-
Return all reachable objects from root.
.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.
.trace_object_allocations_clear (mod_func)
Clear recorded tracing information.
.trace_object_allocations_debug_start (mod_func)
.trace_object_allocations_start (mod_func)
Starts tracing object allocations.
.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.