Module: ObjectSpace

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.

Adds a new finalizer for obj that is called when obj is destroyed by the garbage collector or when ::Ruby shuts down (which ever comes first).

With a block given, uses the block as the callback. Without a block given, uses a callable object finalizer as the callback. The callback is called when obj is destroyed with a single argument id which is the object ID of obj (see Object#object_id).

The return value is an array [0, callback], where callback is a ::Proc created from the block if one was given or finalizer otherwise.

Note that defining a finalizer in an instance method of the object may prevent the object from being garbage collected since if the block or finalizer refers to obj then obj will never be reclaimed by the garbage collector. For example, the following script demonstrates the issue:

class Foo
  def define_final
    ObjectSpace.define_finalizer(self) do |id|
      puts "Running finalizer for #{id}!"
    end
  end
end

obj = Foo.new
obj.define_final

There are two patterns to solve this issue:

• Create the finalizer in a non-instance method so it can safely capture the needed state:

  class Foo
    def define_final
      ObjectSpace.define_finalizer(self, self.class.create_finalizer)
    end
  
    def self.create_finalizer
      proc do |id|
        puts "Running finalizer for #{id}!"
      end
    end
  end

• Use a callable object:

  class Foo
    class Finalizer
      def call(id)
        puts "Running finalizer for #{id}!"
      end
    end
  
    def define_final
      ObjectSpace.define_finalizer(self, Finalizer.new)
    end
  end

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

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 (such as Fixnums, static ::Symbols true, false and nil) are never returned.

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

Job = Class.new
jobs = [Job.new, Job.new]
count = ObjectSpace.each_object(Job) {|x| p x }
puts "Total count: #{count}"

produces:

#<Job:0x000000011d6cbbf0>
#<Job:0x000000011d6cbc68>
 Total count: 2

Due to a current ::Ractor implementation issue, this method does not yield Ractor-unshareable objects when the process is in multi-Ractor mode. Multi-ractor mode is enabled when Ractor.new has been called for the first time. See bugs.ruby-lang.org/issues/19387 for more information.

a = 12345678987654321 # shareable
b = [].freeze # shareable
c = {} # not shareable
ObjectSpace.each_object {|x| x } # yields a, b, and c
Ractor.new {} # enter multi-Ractor mode
ObjectSpace.each_object {|x| x } # does not yield c

Alias of GC.start

Removes all finalizers for obj.