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 2.7.5 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.7.5', 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> <script type="text/javascript" src="../_static/sidebar.js"></script> <link rel="search" type="application/opensearchdescription+xml" title="Search within Python 2.7.5 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 2.7.5 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" /> <script type="text/javascript" src="../_static/copybutton.js"></script> </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="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="http://www.python.org/">Python</a> »</li> <li> <a href="../index.html">Python 2.7.5 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="function"> <dt id="Py_INCREF"> void <tt class="descname">Py_INCREF</tt><big>(</big><a class="reference internal" href="structures.html#PyObject" title="PyObject">PyObject</a><em> *o</em><big>)</big><a class="headerlink" href="#Py_INCREF" title="Permalink to this definition">¶</a></dt> <dd><p>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 class="reference internal" href="#Py_XINCREF" title="Py_XINCREF"><tt class="xref c c-func docutils literal"><span class="pre">Py_XINCREF()</span></tt></a>.</p> </dd></dl> <dl class="function"> <dt id="Py_XINCREF"> void <tt class="descname">Py_XINCREF</tt><big>(</big><a class="reference internal" href="structures.html#PyObject" title="PyObject">PyObject</a><em> *o</em><big>)</big><a class="headerlink" href="#Py_XINCREF" title="Permalink to this definition">¶</a></dt> <dd><p>Increment the reference count for object <em>o</em>. The object may be <em>NULL</em>, in which case the macro has no effect.</p> </dd></dl> <dl class="function"> <dt id="Py_DECREF"> void <tt class="descname">Py_DECREF</tt><big>(</big><a class="reference internal" href="structures.html#PyObject" title="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 class="reference internal" href="#Py_XDECREF" title="Py_XDECREF"><tt class="xref c c-func 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 class="reference internal" href="../reference/datamodel.html#object.__del__" title="object.__del__"><tt class="xref py py-meth 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 class="reference internal" href="#Py_DECREF" title="Py_DECREF"><tt class="xref c c-func 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 class="reference internal" href="#Py_DECREF" title="Py_DECREF"><tt class="xref c c-func docutils literal"><span class="pre">Py_DECREF()</span></tt></a> for the temporary variable.</p> </div> </dd></dl> <dl class="function"> <dt id="Py_XDECREF"> void <tt class="descname">Py_XDECREF</tt><big>(</big><a class="reference internal" href="structures.html#PyObject" title="PyObject">PyObject</a><em> *o</em><big>)</big><a class="headerlink" href="#Py_XDECREF" 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 class="reference internal" href="#Py_DECREF" title="Py_DECREF"><tt class="xref c c-func docutils literal"><span class="pre">Py_DECREF()</span></tt></a>, and the same warning applies.</p> </dd></dl> <dl class="function"> <dt id="Py_CLEAR"> void <tt class="descname">Py_CLEAR</tt><big>(</big><a class="reference internal" href="structures.html#PyObject" title="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 class="reference internal" href="#Py_DECREF" title="Py_DECREF"><tt class="xref c c-func 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 class="reference internal" href="#Py_DECREF" title="Py_DECREF"><tt class="xref c c-func 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 class="reference internal" href="#Py_XINCREF" title="Py_XINCREF"><tt class="xref c c-func docutils literal"><span class="pre">Py_XINCREF()</span></tt></a> and <a class="reference internal" href="#Py_XDECREF" title="Py_XDECREF"><tt class="xref c c-func 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 c c-func docutils literal"><span class="pre">_Py_Dealloc()</span></tt>, <tt class="xref c c-func docutils literal"><span class="pre">_Py_ForgetReference()</span></tt>, <tt class="xref c c-func docutils literal"><span class="pre">_Py_NewReference()</span></tt>, as well as the global variable <tt class="xref c c-data 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" /> <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="../py-modindex.html" title="Python 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="http://www.python.org/">Python</a> »</li> <li> <a href="../index.html">Python 2.7.5 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-2020, 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 Oct 13, 2020. <a href="../bugs.html">Found a bug</a>? <br /> Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3. </div> </body> </html>