Edit File: refcounting.html
<!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>Reference Counting — Python v2.6.6 documentation</title> <link rel="stylesheet" href="../_static/default.css" type="text/css" /> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" /> <script type="text/javascript"> var DOCUMENTATION_OPTIONS = { URL_ROOT: '../', VERSION: '2.6.6', COLLAPSE_MODINDEX: false, FILE_SUFFIX: '.html', HAS_SOURCE: true }; </script> <script type="text/javascript" src="../_static/jquery.js"></script> <script type="text/javascript" src="../_static/doctools.js"></script> <link rel="search" type="application/opensearchdescription+xml" title="Search within Python v2.6.6 documentation" href="../_static/opensearch.xml"/> <link rel="author" title="About these documents" href="../about.html" /> <link rel="copyright" title="Copyright" href="../copyright.html" /> <link rel="top" title="Python v2.6.6 documentation" href="../index.html" /> <link rel="up" title="Python/C API Reference Manual" href="index.html" /> <link rel="next" title="Exception Handling" href="exceptions.html" /> <link rel="prev" title="The Very High Level Layer" href="veryhigh.html" /> <link rel="shortcut icon" type="image/png" href="../_static/py.png" /> </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="../modindex.html" title="Global Module Index" accesskey="M">modules</a> |</li> <li class="right" > <a href="exceptions.html" title="Exception Handling" accesskey="N">next</a> |</li> <li class="right" > <a href="veryhigh.html" title="The Very High Level Layer" accesskey="P">previous</a> |</li> <li><img src="../_static/py.png" alt="" style="vertical-align: middle; margin-top: -1px"/></li> <li><a href="../index.html">Python v2.6.6 documentation</a> »</li> <li><a href="index.html" accesskey="U">Python/C API Reference Manual</a> »</li> </ul> </div> <div class="document"> <div class="documentwrapper"> <div class="bodywrapper"> <div class="body"> <div class="section" id="reference-counting"> <span id="countingrefs"></span><h1>Reference Counting<a class="headerlink" href="#reference-counting" title="Permalink to this headline">¶</a></h1> <p>The macros in this section are used for managing reference counts of Python objects.</p> <dl class="cfunction"> <dt id="Py_INCREF"> void <tt class="descname">Py_INCREF</tt><big>(</big><a title="PyObject" class="reference external" href="structures.html#PyObject">PyObject</a><em> *o</em><big>)</big><a class="headerlink" href="#Py_INCREF" title="Permalink to this definition">¶</a></dt> <dd>Increment the reference count for object <em>o</em>. The object must not be <em>NULL</em>; if you aren’t sure that it isn’t <em>NULL</em>, use <a title="Py_XINCREF" class="reference internal" href="#Py_XINCREF"><tt class="xref docutils literal"><span class="pre">Py_XINCREF()</span></tt></a>.</dd></dl> <dl class="cfunction"> <dt id="Py_XINCREF"> void <tt class="descname">Py_XINCREF</tt><big>(</big><a title="PyObject" class="reference external" href="structures.html#PyObject">PyObject</a><em> *o</em><big>)</big><a class="headerlink" href="#Py_XINCREF" title="Permalink to this definition">¶</a></dt> <dd>Increment the reference count for object <em>o</em>. The object may be <em>NULL</em>, in which case the macro has no effect.</dd></dl> <dl class="cfunction"> <dt id="Py_DECREF"> void <tt class="descname">Py_DECREF</tt><big>(</big><a title="PyObject" class="reference external" href="structures.html#PyObject">PyObject</a><em> *o</em><big>)</big><a class="headerlink" href="#Py_DECREF" title="Permalink to this definition">¶</a></dt> <dd><p>Decrement the reference count for object <em>o</em>. The object must not be <em>NULL</em>; if you aren’t sure that it isn’t <em>NULL</em>, use <a title="Py_XDECREF" class="reference internal" href="#Py_XDECREF"><tt class="xref docutils literal"><span class="pre">Py_XDECREF()</span></tt></a>. If the reference count reaches zero, the object’s type’s deallocation function (which must not be <em>NULL</em>) is invoked.</p> <div class="admonition warning"> <p class="first admonition-title">Warning</p> <p class="last">The deallocation function can cause arbitrary Python code to be invoked (e.g. when a class instance with a <a title="object.__del__" class="reference external" href="../reference/datamodel.html#object.__del__"><tt class="xref docutils literal"><span class="pre">__del__()</span></tt></a> method is deallocated). While exceptions in such code are not propagated, the executed code has free access to all Python global variables. This means that any object that is reachable from a global variable should be in a consistent state before <a title="Py_DECREF" class="reference internal" href="#Py_DECREF"><tt class="xref docutils literal"><span class="pre">Py_DECREF()</span></tt></a> is invoked. For example, code to delete an object from a list should copy a reference to the deleted object in a temporary variable, update the list data structure, and then call <a title="Py_DECREF" class="reference internal" href="#Py_DECREF"><tt class="xref docutils literal"><span class="pre">Py_DECREF()</span></tt></a> for the temporary variable.</p> </div> </dd></dl> <dl class="cfunction"> <dt id="Py_XDECREF"> void <tt class="descname">Py_XDECREF</tt><big>(</big><a title="PyObject" class="reference external" href="structures.html#PyObject">PyObject</a><em> *o</em><big>)</big><a class="headerlink" href="#Py_XDECREF" title="Permalink to this definition">¶</a></dt> <dd>Decrement the reference count for object <em>o</em>. The object may be <em>NULL</em>, in which case the macro has no effect; otherwise the effect is the same as for <a title="Py_DECREF" class="reference internal" href="#Py_DECREF"><tt class="xref docutils literal"><span class="pre">Py_DECREF()</span></tt></a>, and the same warning applies.</dd></dl> <dl class="cfunction"> <dt id="Py_CLEAR"> void <tt class="descname">Py_CLEAR</tt><big>(</big><a title="PyObject" class="reference external" href="structures.html#PyObject">PyObject</a><em> *o</em><big>)</big><a class="headerlink" href="#Py_CLEAR" title="Permalink to this definition">¶</a></dt> <dd><p>Decrement the reference count for object <em>o</em>. The object may be <em>NULL</em>, in which case the macro has no effect; otherwise the effect is the same as for <a title="Py_DECREF" class="reference internal" href="#Py_DECREF"><tt class="xref docutils literal"><span class="pre">Py_DECREF()</span></tt></a>, except that the argument is also set to <em>NULL</em>. The warning for <a title="Py_DECREF" class="reference internal" href="#Py_DECREF"><tt class="xref docutils literal"><span class="pre">Py_DECREF()</span></tt></a> does not apply with respect to the object passed because the macro carefully uses a temporary variable and sets the argument to <em>NULL</em> before decrementing its reference count.</p> <p>It is a good idea to use this macro whenever decrementing the value of a variable that might be traversed during garbage collection.</p> <p class="versionadded"> <span class="versionmodified">New in version 2.4.</span></p> </dd></dl> <p>The following functions are for runtime dynamic embedding of Python: <tt class="docutils literal"><span class="pre">Py_IncRef(PyObject</span> <span class="pre">*o)</span></tt>, <tt class="docutils literal"><span class="pre">Py_DecRef(PyObject</span> <span class="pre">*o)</span></tt>. They are simply exported function versions of <a title="Py_XINCREF" class="reference internal" href="#Py_XINCREF"><tt class="xref docutils literal"><span class="pre">Py_XINCREF()</span></tt></a> and <a title="Py_XDECREF" class="reference internal" href="#Py_XDECREF"><tt class="xref docutils literal"><span class="pre">Py_XDECREF()</span></tt></a>, respectively.</p> <p>The following functions or macros are only for use within the interpreter core: <tt class="xref docutils literal"><span class="pre">_Py_Dealloc()</span></tt>, <tt class="xref docutils literal"><span class="pre">_Py_ForgetReference()</span></tt>, <tt class="xref docutils literal"><span class="pre">_Py_NewReference()</span></tt>, as well as the global variable <tt class="xref docutils literal"><span class="pre">_Py_RefTotal</span></tt>.</p> </div> </div> </div> </div> <div class="sphinxsidebar"> <div class="sphinxsidebarwrapper"> <h4>Previous topic</h4> <p class="topless"><a href="veryhigh.html" title="previous chapter">The Very High Level Layer</a></p> <h4>Next topic</h4> <p class="topless"><a href="exceptions.html" title="next chapter">Exception Handling</a></p> <h3>This Page</h3> <ul class="this-page-menu"> <li><a href="../bugs.html">Report a Bug</a></li> <li><a href="../_sources/c-api/refcounting.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="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="../modindex.html" title="Global Module Index" >modules</a> |</li> <li class="right" > <a href="exceptions.html" title="Exception Handling" >next</a> |</li> <li class="right" > <a href="veryhigh.html" title="The Very High Level Layer" >previous</a> |</li> <li><img src="../_static/py.png" alt="" style="vertical-align: middle; margin-top: -1px"/></li> <li><a href="../index.html">Python v2.6.6 documentation</a> »</li> <li><a href="index.html" >Python/C API Reference Manual</a> »</li> </ul> </div> <div class="footer"> © <a href="../copyright.html">Copyright</a> 1990-2011, Python Software Foundation. <br /> The Python Software Foundation is a non-profit corporation. <a href="http://www.python.org/psf/donations/">Please donate.</a> <br /> Last updated on Jul 20, 2011. <a href="../bugs.html">Found a bug</a>? <br /> Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.6. </div> </body> </html>
Back to File Manager