<ppdoc>
<copyright>
Copyright (c) 2001 by Addison Wesley Longman, Inc. This material may
be distributed only subject to the terms and conditions set forth in
the Open Publication License, v1.0 or later (the latest version is
presently available at http://www.opencontent.org/openpub/).
<p/>
Distribution of substantively modified versions of this document is
prohibited without the explicit permission of the copyright holder.
<p/>
Distribution of the work or derivative of the work in any standard
(paper) book form is prohibited unless prior permission is obtained
from the copyright holder.
</copyright>

<class name="ObjectSpace" type="module" ref="xref-000001">
<p/>
  The <modulename>ObjectSpace</modulename> module contains a number of routines that
  interact with the garbage collection facility and allow you to
  traverse all living objects with an iterator.    
<p/>
  <modulename>ObjectSpace</modulename> also provides support for  object
  finalizers, procs that will be called when a specific object is
  about to be destroyed by garbage collection.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[    include ObjectSpace
      
    a = "A"
    b = "B"
    c = "C"
  
    define_finalizer(a, proc {|id| puts "Finalizer one on #{id}" })
    define_finalizer(a, proc {|id| puts "Finalizer two on #{id}" })
    define_finalizer(b, proc {|id| puts "Finalizer three on #{id}" })
]]></fullcode>
include<nbsp/>ObjectSpace
<p/>
a<nbsp/>=<nbsp/>"A"
b<nbsp/>=<nbsp/>"B"
c<nbsp/>=<nbsp/>"C"
<p/>
define_finalizer(a,<nbsp/>proc<nbsp/>{|id|<nbsp/>puts<nbsp/>"Finalizer<nbsp/>one<nbsp/>on<nbsp/>#{id}"<nbsp/>})
define_finalizer(a,<nbsp/>proc<nbsp/>{|id|<nbsp/>puts<nbsp/>"Finalizer<nbsp/>two<nbsp/>on<nbsp/>#{id}"<nbsp/>})
define_finalizer(b,<nbsp/>proc<nbsp/>{|id|<nbsp/>puts<nbsp/>"Finalizer<nbsp/>three<nbsp/>on<nbsp/>#{id}"<nbsp/>})
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
Finalizer<nbsp/>three<nbsp/>on<nbsp/>537767360
Finalizer<nbsp/>one<nbsp/>on<nbsp/>537767510
Finalizer<nbsp/>two<nbsp/>on<nbsp/>537767510
</alltt>
</codefragment>
<p/>
  <methods type="class">
<p/>
        <method name="_id2ref" ref="_id2ref">
      <callseq>
        ObjectSpace._id2ref( <obj>anId</obj> )
        <returns><obj>anObject</obj></returns>
      </callseq>
      <desc>
<p/>
      Converts an object id to a reference to the object.      
      May not be
      called on an object id passed as a parameter to a finalizer.
<p/>
<codefragment>
<fullcode><![CDATA[        s = "I am a string"
        r = ObjectSpace._id2ref(s.id)
        r == s
]]></fullcode><rubycode>
<tr>
  <td><tt>s<nbsp/>=<nbsp/>"I<nbsp/>am<nbsp/>a<nbsp/>string"</tt></td>
  <td>&#187;</td>
  <td><tt>"I<nbsp/>am<nbsp/>a<nbsp/>string"</tt></td>
</tr>
<tr>
  <td><tt>r<nbsp/>=<nbsp/>ObjectSpace._id2ref(s.id)</tt></td>
  <td>&#187;</td>
  <td><tt>"I<nbsp/>am<nbsp/>a<nbsp/>string"</tt></td>
</tr>
<tr>
  <td><tt>r<nbsp/>==<nbsp/>s</tt></td>
  <td>&#187;</td>
  <td><tt>true</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="define_finalizer" ref="define_finalizer">
      <callseq>
        ObjectSpace.define_finalizer(
        <obj>anObject</obj>, <obj>aProc</obj>=proc()
        )
      </callseq>
      <desc>
<p/>
      Adds <obj>aProc</obj> as a finalizer, to be called when <obj>anObject</obj> 
      is about to be destroyed.
<p/>
      </desc>
    </method>
<p/>
        <method name="each_object" ref="each_object">
      <callseq>
        ObjectSpace.each_object( <opt>
          <obj>aClassOrMod</obj></opt> )
        <block>{| anObj | <blockbody>block</blockbody> }</block>
<returns><obj>aFixnum</obj></returns>
      </callseq>
      <desc>
<p/>
      Calls the block once for each living, nonimmediate
      object in this Ruby process.
      If <obj>aClassOrMod</obj> is specified, calls the block for only those
      classes or modules that match (or are a subclass of)
      <obj>aClassOrMod</obj>.
      Returns the number of objects found.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[        a = 102.7
        b = 95
        ObjectSpace.each_object(Numeric) {|x| p x }
        print "Total count: ", ObjectSpace.each_object {} ,"\n"
]]></fullcode>
a<nbsp/>=<nbsp/>102.7
b<nbsp/>=<nbsp/>95
ObjectSpace.each_object(Numeric)<nbsp/>{|x|<nbsp/>p<nbsp/>x<nbsp/>}
print<nbsp/>"Total<nbsp/>count:<nbsp/>",<nbsp/>ObjectSpace.each_object<nbsp/>{}<nbsp/>,"\n"
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
102.7
2.718281828
3.141592654
Total<nbsp/>count:<nbsp/>372
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="garbage_collect" ref="garbage_collect">
      <callseq>
        ObjectSpace.garbage_collect 
        <returns><tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      Initiates garbage collection (see module <modulename>GC</modulename> on page 410).      
<p/>
      </desc>
    </method>
<p/>
        <method name="undefine_finalizer" ref="undefine_finalizer">
      <callseq>
        ObjectSpace.undefine_finalizer(
        <obj>anObject</obj> )
      </callseq>
      <desc>
<p/>
      Removes all finalizers for <obj>anObject</obj>.
<p/>
      </desc>
    </method>
<p/>
  </methods>
<p/>
</class>
</ppdoc>
