<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <title>weakref – Garbage-collectable references to objects — Python Module of the Week</title> <link rel="stylesheet" href="../_static/sphinxdoc.css" type="text/css" /> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" /> <script type="text/javascript"> var DOCUMENTATION_OPTIONS = { URL_ROOT: '../', VERSION: '1.132', COLLAPSE_INDEX: false, FILE_SUFFIX: '.html', HAS_SOURCE: true }; </script> <script type="text/javascript" src="../_static/jquery.js"></script> <script type="text/javascript" src="../_static/underscore.js"></script> <script type="text/javascript" src="../_static/doctools.js"></script> <link rel="author" title="About these documents" href="../about.html" /> <link rel="top" title="Python Module of the Week" href="../index.html" /> <link rel="up" title="Data Types" href="../data_types.html" /> <link rel="next" title="copy – Duplicate objects" href="../copy/index.html" /> <link rel="prev" title="Queue – A thread-safe FIFO implementation" href="../Queue/index.html" /> </head> <body> <div class="related"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="../genindex.html" title="General Index" accesskey="I">index</a></li> <li class="right" > <a href="../py-modindex.html" title="Python Module Index" >modules</a> |</li> <li class="right" > <a href="../copy/index.html" title="copy – Duplicate objects" accesskey="N">next</a> |</li> <li class="right" > <a href="../Queue/index.html" title="Queue – A thread-safe FIFO implementation" accesskey="P">previous</a> |</li> <li><a href="../contents.html">PyMOTW</a> »</li> <li><a href="../data_types.html" accesskey="U">Data Types</a> »</li> </ul> </div> <div class="sphinxsidebar"> <div class="sphinxsidebarwrapper"> <h3><a href="../contents.html">Table Of Contents</a></h3> <ul> <li><a class="reference internal" href="#">weakref – Garbage-collectable references to objects</a><ul> <li><a class="reference internal" href="#references">References</a></li> <li><a class="reference internal" href="#reference-callbacks">Reference Callbacks</a></li> <li><a class="reference internal" href="#proxies">Proxies</a></li> <li><a class="reference internal" href="#cyclic-references">Cyclic References</a></li> <li><a class="reference internal" href="#caching-objects">Caching Objects</a></li> </ul> </li> </ul> <h4>Previous topic</h4> <p class="topless"><a href="../Queue/index.html" title="previous chapter">Queue – A thread-safe FIFO implementation</a></p> <h4>Next topic</h4> <p class="topless"><a href="../copy/index.html" title="next chapter">copy – Duplicate objects</a></p> <h3>This Page</h3> <ul class="this-page-menu"> <li><a href="../_sources/weakref/index.txt" rel="nofollow">Show Source</a></li> </ul> <div id="searchbox" style="display: none"> <h3>Quick search</h3> <form class="search" action="../search.html" method="get"> <input type="text" name="q" size="18" /> <input type="submit" value="Go" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> <p class="searchtip" style="font-size: 90%"> Enter search terms or a module, class or function name. </p> </div> <script type="text/javascript">$('#searchbox').show(0);</script> </div> </div> <div class="document"> <div class="documentwrapper"> <div class="bodywrapper"> <div class="body"> <div class="section" id="module-weakref"> <span id="weakref-garbage-collectable-references-to-objects"></span><h1>weakref – Garbage-collectable references to objects<a class="headerlink" href="#module-weakref" title="Permalink to this headline">¶</a></h1> <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field"><th class="field-name">Purpose:</th><td class="field-body">Refer to an “expensive” object, but allow it to be garbage collected if there are no other non-weak references.</td> </tr> <tr class="field"><th class="field-name">Python Version:</th><td class="field-body">Since 2.1</td> </tr> </tbody> </table> <p>The <a class="reference internal" href="#module-weakref" title="weakref: Refer to an "expensive" object, but allow it to be garbage collected if there are no other non-weak references."><tt class="xref py py-mod docutils literal"><span class="pre">weakref</span></tt></a> module supports weak references to objects. A normal reference increments the reference count on the object and prevents it from being garbage collected. This is not always desirable, either when a circular reference might be present or when building a cache of objects that should be deleted when memory is needed.</p> <div class="section" id="references"> <h2>References<a class="headerlink" href="#references" title="Permalink to this headline">¶</a></h2> <p>Weak references to your objects are managed through the <tt class="xref py py-class docutils literal"><span class="pre">ref</span></tt> class. To retrieve the original object, call the reference object.</p> <div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">weakref</span> <span class="k">class</span> <span class="nc">ExpensiveObject</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span> <span class="k">def</span> <span class="nf">__del__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="k">print</span> <span class="s">'(Deleting </span><span class="si">%s</span><span class="s">)'</span> <span class="o">%</span> <span class="bp">self</span> <span class="n">obj</span> <span class="o">=</span> <span class="n">ExpensiveObject</span><span class="p">()</span> <span class="n">r</span> <span class="o">=</span> <span class="n">weakref</span><span class="o">.</span><span class="n">ref</span><span class="p">(</span><span class="n">obj</span><span class="p">)</span> <span class="k">print</span> <span class="s">'obj:'</span><span class="p">,</span> <span class="n">obj</span> <span class="k">print</span> <span class="s">'ref:'</span><span class="p">,</span> <span class="n">r</span> <span class="k">print</span> <span class="s">'r():'</span><span class="p">,</span> <span class="n">r</span><span class="p">()</span> <span class="k">print</span> <span class="s">'deleting obj'</span> <span class="k">del</span> <span class="n">obj</span> <span class="k">print</span> <span class="s">'r():'</span><span class="p">,</span> <span class="n">r</span><span class="p">()</span> </pre></div> </div> <p>In this case, since <tt class="docutils literal"><span class="pre">obj</span></tt> is deleted before the second call to the reference, the <tt class="xref py py-class docutils literal"><span class="pre">ref</span></tt> returns <tt class="xref docutils literal"><span class="pre">None</span></tt>.</p> <div class="highlight-python"><pre>$ python weakref_ref.py obj: <__main__.ExpensiveObject object at 0x100464790> ref: <weakref at 0x100458ba8; to 'ExpensiveObject' at 0x100464790> r(): <__main__.ExpensiveObject object at 0x100464790> deleting obj (Deleting <__main__.ExpensiveObject object at 0x100464790>) r(): None</pre> </div> </div> <div class="section" id="reference-callbacks"> <h2>Reference Callbacks<a class="headerlink" href="#reference-callbacks" title="Permalink to this headline">¶</a></h2> <p>The <tt class="xref py py-class docutils literal"><span class="pre">ref</span></tt> constructor takes an optional second argument that should be a callback function to invoke when the referenced object is deleted.</p> <div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">weakref</span> <span class="k">class</span> <span class="nc">ExpensiveObject</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span> <span class="k">def</span> <span class="nf">__del__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="k">print</span> <span class="s">'(Deleting </span><span class="si">%s</span><span class="s">)'</span> <span class="o">%</span> <span class="bp">self</span> <span class="k">def</span> <span class="nf">callback</span><span class="p">(</span><span class="n">reference</span><span class="p">):</span> <span class="sd">"""Invoked when referenced object is deleted"""</span> <span class="k">print</span> <span class="s">'callback('</span><span class="p">,</span> <span class="n">reference</span><span class="p">,</span> <span class="s">')'</span> <span class="n">obj</span> <span class="o">=</span> <span class="n">ExpensiveObject</span><span class="p">()</span> <span class="n">r</span> <span class="o">=</span> <span class="n">weakref</span><span class="o">.</span><span class="n">ref</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="n">callback</span><span class="p">)</span> <span class="k">print</span> <span class="s">'obj:'</span><span class="p">,</span> <span class="n">obj</span> <span class="k">print</span> <span class="s">'ref:'</span><span class="p">,</span> <span class="n">r</span> <span class="k">print</span> <span class="s">'r():'</span><span class="p">,</span> <span class="n">r</span><span class="p">()</span> <span class="k">print</span> <span class="s">'deleting obj'</span> <span class="k">del</span> <span class="n">obj</span> <span class="k">print</span> <span class="s">'r():'</span><span class="p">,</span> <span class="n">r</span><span class="p">()</span> </pre></div> </div> <p>The callback receives the reference object as an argument, after the reference is “dead” and no longer refers to the original object. This lets you remove the weak reference object from a cache, for example.</p> <div class="highlight-python"><pre>$ python weakref_ref_callback.py obj: <__main__.ExpensiveObject object at 0x100462990> ref: <weakref at 0x100458c00; to 'ExpensiveObject' at 0x100462990> r(): <__main__.ExpensiveObject object at 0x100462990> deleting obj callback( <weakref at 0x100458c00; dead> ) (Deleting <__main__.ExpensiveObject object at 0x100462990>) r(): None</pre> </div> </div> <div class="section" id="proxies"> <h2>Proxies<a class="headerlink" href="#proxies" title="Permalink to this headline">¶</a></h2> <p>Instead of using <tt class="xref py py-class docutils literal"><span class="pre">ref</span></tt> directly, it can be more convenient to use a proxy. Proxies can be used as though they were the original object, so you do not need to call the <tt class="xref py py-class docutils literal"><span class="pre">ref</span></tt> first to access the object.</p> <div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">weakref</span> <span class="k">class</span> <span class="nc">ExpensiveObject</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span> <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span> <span class="bp">self</span><span class="o">.</span><span class="n">name</span> <span class="o">=</span> <span class="n">name</span> <span class="k">def</span> <span class="nf">__del__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="k">print</span> <span class="s">'(Deleting </span><span class="si">%s</span><span class="s">)'</span> <span class="o">%</span> <span class="bp">self</span> <span class="n">obj</span> <span class="o">=</span> <span class="n">ExpensiveObject</span><span class="p">(</span><span class="s">'My Object'</span><span class="p">)</span> <span class="n">r</span> <span class="o">=</span> <span class="n">weakref</span><span class="o">.</span><span class="n">ref</span><span class="p">(</span><span class="n">obj</span><span class="p">)</span> <span class="n">p</span> <span class="o">=</span> <span class="n">weakref</span><span class="o">.</span><span class="n">proxy</span><span class="p">(</span><span class="n">obj</span><span class="p">)</span> <span class="k">print</span> <span class="s">'via obj:'</span><span class="p">,</span> <span class="n">obj</span><span class="o">.</span><span class="n">name</span> <span class="k">print</span> <span class="s">'via ref:'</span><span class="p">,</span> <span class="n">r</span><span class="p">()</span><span class="o">.</span><span class="n">name</span> <span class="k">print</span> <span class="s">'via proxy:'</span><span class="p">,</span> <span class="n">p</span><span class="o">.</span><span class="n">name</span> <span class="k">del</span> <span class="n">obj</span> <span class="k">print</span> <span class="s">'via proxy:'</span><span class="p">,</span> <span class="n">p</span><span class="o">.</span><span class="n">name</span> </pre></div> </div> <p>If the proxy is access after the referent object is removed, a <tt class="xref py py-class docutils literal"><span class="pre">ReferenceError</span></tt> exception is raised.</p> <div class="highlight-python"><pre>$ python weakref_proxy.py via obj: My Object via ref: My Object via proxy: My Object (Deleting <__main__.ExpensiveObject object at 0x100462810>) via proxy: Traceback (most recent call last): File "weakref_proxy.py", line 26, in <module> print 'via proxy:', p.name ReferenceError: weakly-referenced object no longer exists</pre> </div> </div> <div class="section" id="cyclic-references"> <h2>Cyclic References<a class="headerlink" href="#cyclic-references" title="Permalink to this headline">¶</a></h2> <p>One use for weak references is to allow cyclic references without preventing garbage collection. This example illustrates the difference between using regular objects and proxies when a graph includes a cycle.</p> <p>First, we need a <tt class="xref py py-class docutils literal"><span class="pre">Graph</span></tt> class that accepts any object given to it as the “next” node in the sequence. For the sake of brevity, this <tt class="xref py py-class docutils literal"><span class="pre">Graph</span></tt> supports a single outgoing reference from each node, which results in boring graphs but makes it easy to create cycles. The function <tt class="xref py py-func docutils literal"><span class="pre">demo()</span></tt> is a utility function to exercise the graph class by creating a cycle and then removing various references.</p> <div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">gc</span> <span class="kn">from</span> <span class="nn">pprint</span> <span class="kn">import</span> <span class="n">pprint</span> <span class="kn">import</span> <span class="nn">weakref</span> <span class="k">class</span> <span class="nc">Graph</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span> <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span> <span class="bp">self</span><span class="o">.</span><span class="n">name</span> <span class="o">=</span> <span class="n">name</span> <span class="bp">self</span><span class="o">.</span><span class="n">other</span> <span class="o">=</span> <span class="bp">None</span> <span class="k">def</span> <span class="nf">set_next</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span> <span class="k">print</span> <span class="s">'</span><span class="si">%s</span><span class="s">.set_next(</span><span class="si">%s</span><span class="s"> (</span><span class="si">%s</span><span class="s">))'</span> <span class="o">%</span> <span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">name</span><span class="p">,</span> <span class="n">other</span><span class="p">,</span> <span class="nb">type</span><span class="p">(</span><span class="n">other</span><span class="p">))</span> <span class="bp">self</span><span class="o">.</span><span class="n">other</span> <span class="o">=</span> <span class="n">other</span> <span class="k">def</span> <span class="nf">all_nodes</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="s">"Generate the nodes in the graph sequence."</span> <span class="k">yield</span> <span class="bp">self</span> <span class="n">n</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">other</span> <span class="k">while</span> <span class="n">n</span> <span class="ow">and</span> <span class="n">n</span><span class="o">.</span><span class="n">name</span> <span class="o">!=</span> <span class="bp">self</span><span class="o">.</span><span class="n">name</span><span class="p">:</span> <span class="k">yield</span> <span class="n">n</span> <span class="n">n</span> <span class="o">=</span> <span class="n">n</span><span class="o">.</span><span class="n">other</span> <span class="k">if</span> <span class="n">n</span> <span class="ow">is</span> <span class="bp">self</span><span class="p">:</span> <span class="k">yield</span> <span class="n">n</span> <span class="k">return</span> <span class="k">def</span> <span class="nf">__str__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="k">return</span> <span class="s">'->'</span><span class="o">.</span><span class="n">join</span><span class="p">([</span><span class="n">n</span><span class="o">.</span><span class="n">name</span> <span class="k">for</span> <span class="n">n</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">all_nodes</span><span class="p">()])</span> <span class="k">def</span> <span class="nf">__repr__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="k">return</span> <span class="s">'</span><span class="si">%s</span><span class="s">(</span><span class="si">%s</span><span class="s">)'</span> <span class="o">%</span> <span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">__class__</span><span class="o">.</span><span class="n">__name__</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">name</span><span class="p">)</span> <span class="k">def</span> <span class="nf">__del__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="k">print</span> <span class="s">'(Deleting </span><span class="si">%s</span><span class="s">)'</span> <span class="o">%</span> <span class="bp">self</span><span class="o">.</span><span class="n">name</span> <span class="bp">self</span><span class="o">.</span><span class="n">set_next</span><span class="p">(</span><span class="bp">None</span><span class="p">)</span> <span class="k">class</span> <span class="nc">WeakGraph</span><span class="p">(</span><span class="n">Graph</span><span class="p">):</span> <span class="k">def</span> <span class="nf">set_next</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span> <span class="k">if</span> <span class="n">other</span> <span class="ow">is</span> <span class="ow">not</span> <span class="bp">None</span><span class="p">:</span> <span class="c"># See if we should replace the reference</span> <span class="c"># to other with a weakref.</span> <span class="k">if</span> <span class="bp">self</span> <span class="ow">in</span> <span class="n">other</span><span class="o">.</span><span class="n">all_nodes</span><span class="p">():</span> <span class="n">other</span> <span class="o">=</span> <span class="n">weakref</span><span class="o">.</span><span class="n">proxy</span><span class="p">(</span><span class="n">other</span><span class="p">)</span> <span class="nb">super</span><span class="p">(</span><span class="n">WeakGraph</span><span class="p">,</span> <span class="bp">self</span><span class="p">)</span><span class="o">.</span><span class="n">set_next</span><span class="p">(</span><span class="n">other</span><span class="p">)</span> <span class="k">return</span> <span class="k">def</span> <span class="nf">collect_and_show_garbage</span><span class="p">():</span> <span class="s">"Show what garbage is present."</span> <span class="k">print</span> <span class="s">'Collecting...'</span> <span class="n">n</span> <span class="o">=</span> <span class="n">gc</span><span class="o">.</span><span class="n">collect</span><span class="p">()</span> <span class="k">print</span> <span class="s">'Unreachable objects:'</span><span class="p">,</span> <span class="n">n</span> <span class="k">print</span> <span class="s">'Garbage:'</span><span class="p">,</span> <span class="n">pprint</span><span class="p">(</span><span class="n">gc</span><span class="o">.</span><span class="n">garbage</span><span class="p">)</span> <span class="k">def</span> <span class="nf">demo</span><span class="p">(</span><span class="n">graph_factory</span><span class="p">):</span> <span class="k">print</span> <span class="s">'Set up graph:'</span> <span class="n">one</span> <span class="o">=</span> <span class="n">graph_factory</span><span class="p">(</span><span class="s">'one'</span><span class="p">)</span> <span class="n">two</span> <span class="o">=</span> <span class="n">graph_factory</span><span class="p">(</span><span class="s">'two'</span><span class="p">)</span> <span class="n">three</span> <span class="o">=</span> <span class="n">graph_factory</span><span class="p">(</span><span class="s">'three'</span><span class="p">)</span> <span class="n">one</span><span class="o">.</span><span class="n">set_next</span><span class="p">(</span><span class="n">two</span><span class="p">)</span> <span class="n">two</span><span class="o">.</span><span class="n">set_next</span><span class="p">(</span><span class="n">three</span><span class="p">)</span> <span class="n">three</span><span class="o">.</span><span class="n">set_next</span><span class="p">(</span><span class="n">one</span><span class="p">)</span> <span class="k">print</span> <span class="k">print</span> <span class="s">'Graphs:'</span> <span class="k">print</span> <span class="nb">str</span><span class="p">(</span><span class="n">one</span><span class="p">)</span> <span class="k">print</span> <span class="nb">str</span><span class="p">(</span><span class="n">two</span><span class="p">)</span> <span class="k">print</span> <span class="nb">str</span><span class="p">(</span><span class="n">three</span><span class="p">)</span> <span class="n">collect_and_show_garbage</span><span class="p">()</span> <span class="k">print</span> <span class="n">three</span> <span class="o">=</span> <span class="bp">None</span> <span class="n">two</span> <span class="o">=</span> <span class="bp">None</span> <span class="k">print</span> <span class="s">'After 2 references removed:'</span> <span class="k">print</span> <span class="nb">str</span><span class="p">(</span><span class="n">one</span><span class="p">)</span> <span class="n">collect_and_show_garbage</span><span class="p">()</span> <span class="k">print</span> <span class="k">print</span> <span class="s">'Removing last reference:'</span> <span class="n">one</span> <span class="o">=</span> <span class="bp">None</span> <span class="n">collect_and_show_garbage</span><span class="p">()</span> </pre></div> </div> <p>Now we can set up a test program using the <a class="reference internal" href="../gc/index.html#module-gc" title="gc: Garbage Collector"><tt class="xref py py-mod docutils literal"><span class="pre">gc</span></tt></a> module to help us debug the leak. The <tt class="docutils literal"><span class="pre">DEBUG_LEAK</span></tt> flag causes <a class="reference internal" href="../gc/index.html#module-gc" title="gc: Garbage Collector"><tt class="xref py py-mod docutils literal"><span class="pre">gc</span></tt></a> to print information about objects that cannot be seen other than through the reference the garbage collector has to them.</p> <div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">gc</span> <span class="kn">from</span> <span class="nn">pprint</span> <span class="kn">import</span> <span class="n">pprint</span> <span class="kn">import</span> <span class="nn">weakref</span> <span class="kn">from</span> <span class="nn">weakref_graph</span> <span class="kn">import</span> <span class="n">Graph</span><span class="p">,</span> <span class="n">demo</span><span class="p">,</span> <span class="n">collect_and_show_garbage</span> <span class="n">gc</span><span class="o">.</span><span class="n">set_debug</span><span class="p">(</span><span class="n">gc</span><span class="o">.</span><span class="n">DEBUG_LEAK</span><span class="p">)</span> <span class="k">print</span> <span class="s">'Setting up the cycle'</span> <span class="k">print</span> <span class="n">demo</span><span class="p">(</span><span class="n">Graph</span><span class="p">)</span> <span class="k">print</span> <span class="k">print</span> <span class="s">'Breaking the cycle and cleaning up garbage'</span> <span class="k">print</span> <span class="n">gc</span><span class="o">.</span><span class="n">garbage</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">set_next</span><span class="p">(</span><span class="bp">None</span><span class="p">)</span> <span class="k">while</span> <span class="n">gc</span><span class="o">.</span><span class="n">garbage</span><span class="p">:</span> <span class="k">del</span> <span class="n">gc</span><span class="o">.</span><span class="n">garbage</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="k">print</span> <span class="n">collect_and_show_garbage</span><span class="p">()</span> </pre></div> </div> <p>Even after deleting the local references to the <tt class="xref py py-class docutils literal"><span class="pre">Graph</span></tt> instances in <tt class="xref py py-func docutils literal"><span class="pre">demo()</span></tt>, the graphs all show up in the garbage list and cannot be collected. The dictionaries in the garbage list hold the attributes of the <tt class="xref py py-class docutils literal"><span class="pre">Graph</span></tt> instances. We can forcibly delete the graphs, since we know what they are:</p> <div class="highlight-python"><pre>$ python -u weakref_cycle.py Setting up the cycle Set up graph: one.set_next(two (<class 'weakref_graph.Graph'>)) two.set_next(three (<class 'weakref_graph.Graph'>)) three.set_next(one->two->three (<class 'weakref_graph.Graph'>)) Graphs: one->two->three->one two->three->one->two three->one->two->three Collecting... Unreachable objects: 0 Garbage:[] After 2 references removed: one->two->three->one Collecting... Unreachable objects: 0 Garbage:[] Removing last reference: Collecting... gc: uncollectable <Graph 0x100477590> gc: uncollectable <Graph 0x1004775d0> gc: uncollectable <Graph 0x100477610> gc: uncollectable <dict 0x10035fb00> gc: uncollectable <dict 0x1003612e0> gc: uncollectable <dict 0x10035c210> Unreachable objects: 6 Garbage:[Graph(one), Graph(two), Graph(three), {'name': 'one', 'other': Graph(two)}, {'name': 'two', 'other': Graph(three)}, {'name': 'three', 'other': Graph(one)}] Breaking the cycle and cleaning up garbage one.set_next(None (<type 'NoneType'>)) (Deleting two) two.set_next(None (<type 'NoneType'>)) (Deleting three) three.set_next(None (<type 'NoneType'>)) (Deleting one) one.set_next(None (<type 'NoneType'>)) Collecting... Unreachable objects: 0 Garbage:[]</pre> </div> <p>And now let’s define a more intelligent <tt class="xref py py-class docutils literal"><span class="pre">WeakGraph</span></tt> class that knows not to create cycles using regular references, but to use a <tt class="xref py py-class docutils literal"><span class="pre">ref</span></tt> when a cycle is detected.</p> <div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">gc</span> <span class="kn">from</span> <span class="nn">pprint</span> <span class="kn">import</span> <span class="n">pprint</span> <span class="kn">import</span> <span class="nn">weakref</span> <span class="kn">from</span> <span class="nn">weakref_graph</span> <span class="kn">import</span> <span class="n">Graph</span><span class="p">,</span> <span class="n">demo</span> <span class="k">class</span> <span class="nc">WeakGraph</span><span class="p">(</span><span class="n">Graph</span><span class="p">):</span> <span class="k">def</span> <span class="nf">set_next</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span> <span class="k">if</span> <span class="n">other</span> <span class="ow">is</span> <span class="ow">not</span> <span class="bp">None</span><span class="p">:</span> <span class="c"># See if we should replace the reference</span> <span class="c"># to other with a weakref.</span> <span class="k">if</span> <span class="bp">self</span> <span class="ow">in</span> <span class="n">other</span><span class="o">.</span><span class="n">all_nodes</span><span class="p">():</span> <span class="n">other</span> <span class="o">=</span> <span class="n">weakref</span><span class="o">.</span><span class="n">proxy</span><span class="p">(</span><span class="n">other</span><span class="p">)</span> <span class="nb">super</span><span class="p">(</span><span class="n">WeakGraph</span><span class="p">,</span> <span class="bp">self</span><span class="p">)</span><span class="o">.</span><span class="n">set_next</span><span class="p">(</span><span class="n">other</span><span class="p">)</span> <span class="k">return</span> <span class="n">demo</span><span class="p">(</span><span class="n">WeakGraph</span><span class="p">)</span> </pre></div> </div> <p>Since the <tt class="xref py py-class docutils literal"><span class="pre">WeakGraph</span></tt> instances use proxies to refer to objects that have already been seen, as <tt class="xref py py-func docutils literal"><span class="pre">demo()</span></tt> removes all local references to the objects, the cycle is broken and the garbage collector can delete the objects for us.</p> <div class="highlight-python"><pre>$ python weakref_weakgraph.py Set up graph: one.set_next(two (<class '__main__.WeakGraph'>)) two.set_next(three (<class '__main__.WeakGraph'>)) three.set_next(one->two->three (<type 'weakproxy'>)) Graphs: one->two->three two->three->one->two three->one->two->three Collecting... Unreachable objects: 0 Garbage:[] After 2 references removed: one->two->three Collecting... Unreachable objects: 0 Garbage:[] Removing last reference: (Deleting one) one.set_next(None (<type 'NoneType'>)) (Deleting two) two.set_next(None (<type 'NoneType'>)) (Deleting three) three.set_next(None (<type 'NoneType'>)) Collecting... Unreachable objects: 0 Garbage:[]</pre> </div> </div> <div class="section" id="caching-objects"> <h2>Caching Objects<a class="headerlink" href="#caching-objects" title="Permalink to this headline">¶</a></h2> <p>The <tt class="xref py py-class docutils literal"><span class="pre">ref</span></tt> and <tt class="xref py py-class docutils literal"><span class="pre">proxy</span></tt> classes are considered “low level”. While they are useful for maintaining weak references to individual objects and allowing cycles to be garbage collected, if you need to create a cache of several objects the <tt class="xref py py-class docutils literal"><span class="pre">WeakKeyDictionary</span></tt> and <tt class="xref py py-class docutils literal"><span class="pre">WeakValueDictionary</span></tt> provide a more appropriate API.</p> <p>As you might expect, the <tt class="xref py py-class docutils literal"><span class="pre">WeakValueDictionary</span></tt> uses weak references to the values it holds, allowing them to be garbage collected when other code is not actually using them.</p> <p>To illustrate the difference between memory handling with a regular dictionary and <tt class="xref py py-class docutils literal"><span class="pre">WeakValueDictionary</span></tt>, let’s go experiment with explicitly calling the garbage collector again:</p> <div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">gc</span> <span class="kn">from</span> <span class="nn">pprint</span> <span class="kn">import</span> <span class="n">pprint</span> <span class="kn">import</span> <span class="nn">weakref</span> <span class="n">gc</span><span class="o">.</span><span class="n">set_debug</span><span class="p">(</span><span class="n">gc</span><span class="o">.</span><span class="n">DEBUG_LEAK</span><span class="p">)</span> <span class="k">class</span> <span class="nc">ExpensiveObject</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span> <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span> <span class="bp">self</span><span class="o">.</span><span class="n">name</span> <span class="o">=</span> <span class="n">name</span> <span class="k">def</span> <span class="nf">__repr__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="k">return</span> <span class="s">'ExpensiveObject(</span><span class="si">%s</span><span class="s">)'</span> <span class="o">%</span> <span class="bp">self</span><span class="o">.</span><span class="n">name</span> <span class="k">def</span> <span class="nf">__del__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> <span class="k">print</span> <span class="s">'(Deleting </span><span class="si">%s</span><span class="s">)'</span> <span class="o">%</span> <span class="bp">self</span> <span class="k">def</span> <span class="nf">demo</span><span class="p">(</span><span class="n">cache_factory</span><span class="p">):</span> <span class="c"># hold objects so any weak references </span> <span class="c"># are not removed immediately</span> <span class="n">all_refs</span> <span class="o">=</span> <span class="p">{}</span> <span class="c"># the cache using the factory we're given</span> <span class="k">print</span> <span class="s">'CACHE TYPE:'</span><span class="p">,</span> <span class="n">cache_factory</span> <span class="n">cache</span> <span class="o">=</span> <span class="n">cache_factory</span><span class="p">()</span> <span class="k">for</span> <span class="n">name</span> <span class="ow">in</span> <span class="p">[</span> <span class="s">'one'</span><span class="p">,</span> <span class="s">'two'</span><span class="p">,</span> <span class="s">'three'</span> <span class="p">]:</span> <span class="n">o</span> <span class="o">=</span> <span class="n">ExpensiveObject</span><span class="p">(</span><span class="n">name</span><span class="p">)</span> <span class="n">cache</span><span class="p">[</span><span class="n">name</span><span class="p">]</span> <span class="o">=</span> <span class="n">o</span> <span class="n">all_refs</span><span class="p">[</span><span class="n">name</span><span class="p">]</span> <span class="o">=</span> <span class="n">o</span> <span class="k">del</span> <span class="n">o</span> <span class="c"># decref</span> <span class="k">print</span> <span class="s">'all_refs ='</span><span class="p">,</span> <span class="n">pprint</span><span class="p">(</span><span class="n">all_refs</span><span class="p">)</span> <span class="k">print</span> <span class="s">'Before, cache contains:'</span><span class="p">,</span> <span class="n">cache</span><span class="o">.</span><span class="n">keys</span><span class="p">()</span> <span class="k">for</span> <span class="n">name</span><span class="p">,</span> <span class="n">value</span> <span class="ow">in</span> <span class="n">cache</span><span class="o">.</span><span class="n">items</span><span class="p">():</span> <span class="k">print</span> <span class="s">' </span><span class="si">%s</span><span class="s"> = </span><span class="si">%s</span><span class="s">'</span> <span class="o">%</span> <span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="n">value</span><span class="p">)</span> <span class="k">del</span> <span class="n">value</span> <span class="c"># decref</span> <span class="c"># Remove all references to our objects except the cache</span> <span class="k">print</span> <span class="s">'Cleanup:'</span> <span class="k">del</span> <span class="n">all_refs</span> <span class="n">gc</span><span class="o">.</span><span class="n">collect</span><span class="p">()</span> <span class="k">print</span> <span class="s">'After, cache contains:'</span><span class="p">,</span> <span class="n">cache</span><span class="o">.</span><span class="n">keys</span><span class="p">()</span> <span class="k">for</span> <span class="n">name</span><span class="p">,</span> <span class="n">value</span> <span class="ow">in</span> <span class="n">cache</span><span class="o">.</span><span class="n">items</span><span class="p">():</span> <span class="k">print</span> <span class="s">' </span><span class="si">%s</span><span class="s"> = </span><span class="si">%s</span><span class="s">'</span> <span class="o">%</span> <span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="n">value</span><span class="p">)</span> <span class="k">print</span> <span class="s">'demo returning'</span> <span class="k">return</span> <span class="n">demo</span><span class="p">(</span><span class="nb">dict</span><span class="p">)</span> <span class="k">print</span> <span class="n">demo</span><span class="p">(</span><span class="n">weakref</span><span class="o">.</span><span class="n">WeakValueDictionary</span><span class="p">)</span> </pre></div> </div> <p>Notice that any loop variables that refer to the values we are caching must be cleared explicitly to decrement the reference count on the object. Otherwise the garbage collector would not remove the objects and they would remain in the cache. Similarly, the all_refs variable is used to hold references to prevent them from being garbage collected prematurely.</p> <div class="highlight-python"><pre>$ python weakref_valuedict.py CACHE TYPE: <type 'dict'> all_refs ={'one': ExpensiveObject(one), 'three': ExpensiveObject(three), 'two': ExpensiveObject(two)} Before, cache contains: ['three', 'two', 'one'] three = ExpensiveObject(three) two = ExpensiveObject(two) one = ExpensiveObject(one) Cleanup: After, cache contains: ['three', 'two', 'one'] three = ExpensiveObject(three) two = ExpensiveObject(two) one = ExpensiveObject(one) demo returning (Deleting ExpensiveObject(three)) (Deleting ExpensiveObject(two)) (Deleting ExpensiveObject(one)) CACHE TYPE: weakref.WeakValueDictionary all_refs ={'one': ExpensiveObject(one), 'three': ExpensiveObject(three), 'two': ExpensiveObject(two)} Before, cache contains: ['three', 'two', 'one'] three = ExpensiveObject(three) two = ExpensiveObject(two) one = ExpensiveObject(one) Cleanup: (Deleting ExpensiveObject(three)) (Deleting ExpensiveObject(two)) (Deleting ExpensiveObject(one)) After, cache contains: [] demo returning</pre> </div> <p>The WeakKeyDictionary works similarly but uses weak references for the keys instead of the values in the dictionary.</p> <p>The library documentation for weakref contains this warning:</p> <div class="admonition warning"> <p class="first admonition-title">Warning</p> <p class="last">Caution: Because a WeakValueDictionary is built on top of a Python dictionary, it must not change size when iterating over it. This can be difficult to ensure for a WeakValueDictionary because actions performed by the program during iteration may cause items in the dictionary to vanish “by magic” (as a side effect of garbage collection).</p> </div> <div class="admonition-see-also admonition seealso"> <p class="first admonition-title">See also</p> <dl class="last docutils"> <dt><a class="reference external" href="http://docs.python.org/lib/module-weakref.html">weakref</a></dt> <dd>Standard library documentation for this module.</dd> <dt><a class="reference internal" href="../gc/index.html#module-gc" title="gc: Garbage Collector"><tt class="xref py py-mod docutils literal"><span class="pre">gc</span></tt></a></dt> <dd>The gc module is the interface to the interpreter’s garbage collector.</dd> </dl> </div> </div> </div> </div> </div> </div> <div class="clearer"></div> </div> <div class="related"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="../genindex.html" title="General Index" >index</a></li> <li class="right" > <a href="../py-modindex.html" title="Python Module Index" >modules</a> |</li> <li class="right" > <a href="../copy/index.html" title="copy – Duplicate objects" >next</a> |</li> <li class="right" > <a href="../Queue/index.html" title="Queue – A thread-safe FIFO implementation" >previous</a> |</li> <li><a href="../contents.html">PyMOTW</a> »</li> <li><a href="../data_types.html" >Data Types</a> »</li> </ul> </div> <div class="footer"> © Copyright Doug Hellmann. Last updated on Oct 24, 2010. Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>. <br/><a href="http://creativecommons.org/licenses/by-nc-sa/3.0/us/" rel="license"><img alt="Creative Commons License" style="border-width:0" src="http://i.creativecommons.org/l/by-nc-sa/3.0/us/88x31.png"/></a> </div> </body> </html>