140f6969d5213fd0ece03148e62e461e

Edit file

File name : refcounting.html

Content :

<!DOCTYPE html>

<title>Reference Counting &#8212; Python 3.10.12 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
 
 <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
 <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?2022.1" />
 
 <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
 <script src="../_static/jquery.js"></script>
 <script src="../_static/underscore.js"></script>
 <script src="../_static/doctools.js"></script>
 
 <script src="../_static/sidebar.js"></script>
 
 <link rel="search" type="application/opensearchdescription+xml"
 title="Search within Python 3.10.12 documentation"
 href="../_static/opensearch.xml"/>
 <link rel="author" title="About these documents" href="../about.html" />
 <link rel="index" title="Index" href="../genindex.html" />
 <link rel="search" title="Search" href="../search.html" />
 <link rel="copyright" title="Copyright" href="../copyright.html" />
 <link rel="next" title="Exception Handling" href="exceptions.html" />
 <link rel="prev" title="The Very High Level Layer" href="veryhigh.html" />
 <link rel="canonical" href="file:///usr/share/doc/python3.10/html/c-api/refcounting.html" />

</head>
<body>
<div class="mobile-nav">
 <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"
 aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu" />
 <label for="menuToggler" class="toggler__label">
 
 </label>
 <nav class="nav-content" role="navigation">
 <a href="https://www.python.org/" class="nav-logo">
 <img src="../_static/py.svg" alt="Logo"/>
 </a>
 <div class="version_switcher_placeholder"></div>
 <form role="search" class="search" action="../search.html" method="get">
 <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">
 <path fill-rule="nonzero"
 d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z" fill="#444"></path>
 </svg>
 <input type="text" name="q" aria-label="Quick search"/>
 <input type="submit" value="Go"/>
 </form>
 </nav>
 <div class="menu-wrapper">
 <nav class="menu" role="navigation" aria-label="main navigation">
 <div class="language_switcher_placeholder"></div>
 <h4>Previous topic</h4>
 <a href="veryhigh.html"
 title="previous chapter">The Very High Level Layer</a>
 <h4>Next topic</h4>
 <a href="exceptions.html"
 title="next chapter">Exception Handling</a>
 <div role="note" aria-label="source link">
 <h3>This Page</h3>
 <ul class="this-page-menu">
 <li><a href="../bugs.html">Report a Bug</a></li>
 <li>
 <a href="https://github.com/python/cpython/blob/3.10/Doc/c-api/refcounting.rst"
 rel="nofollow">Show Source
 </a>
 </li>
 </ul>
 </div>
 </nav>
 </div>
</div>

<div class="related" role="navigation" aria-label="related navigation">
 <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.svg" alt="python logo" style="vertical-align: middle; margin-top: -1px"/></li>
 <li><a href="https://www.python.org/">Python</a> &#187;</li>
 <li class="switchers">
 <div class="language_switcher_placeholder"></div>
 <div class="version_switcher_placeholder"></div>
 </li>
 <li>
 
 </li>
 <li id="cpython-language-and-version">
 <a href="../index.html">3.10.12 Documentation</a> &#187;
 </li>

<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Python/C API Reference Manual</a> &#187;</li>
 <li class="nav-item nav-item-this"><a href="">Reference Counting</a></li>
 <li class="right">

<div class="document">
 <div class="documentwrapper">
 <div class="bodywrapper">
 <div class="body" role="main">
 
 <section id="reference-counting">
<h1>Reference Counting<a class="headerlink" href="#reference-counting" title="Permalink to this headline">¶</a></h1>
The macros in this section are used for managing reference counts of Python
objects.
<dl class="c function">
<dt class="sig sig-object c" id="c.Py_INCREF">
void Py_INCREF(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *o)<a class="headerlink" href="#c.Py_INCREF" title="Permalink to this definition">¶</a> </dt>
<dd>Increment the reference count for object o.
This function is usually used to convert a <a class="reference internal" href="../glossary.html#term-borrowed-reference">borrowed reference</a> to a
<a class="reference internal" href="../glossary.html#term-strong-reference">strong reference</a> in-place. The <a class="reference internal" href="#c.Py_NewRef" title="Py_NewRef"><code class="xref c c-func docutils literal notranslate">Py_NewRef()</code></a> function can be
used to create a new <a class="reference internal" href="../glossary.html#term-strong-reference">strong reference</a>.
The object must not be <code class="docutils literal notranslate">NULL</code>; if you aren’t sure that it isn’t
<code class="docutils literal notranslate">NULL</code>, use <a class="reference internal" href="#c.Py_XINCREF" title="Py_XINCREF"><code class="xref c c-func docutils literal notranslate">Py_XINCREF()</code></a>.
</dd></dl>

<dl class="c function">
<dt class="sig sig-object c" id="c.Py_XINCREF">
void Py_XINCREF(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *o)<a class="headerlink" href="#c.Py_XINCREF" title="Permalink to this definition">¶</a> </dt>
<dd>Increment the reference count for object o. The object may be <code class="docutils literal notranslate">NULL</code>, in
which case the macro has no effect.
See also <a class="reference internal" href="#c.Py_XNewRef" title="Py_XNewRef"><code class="xref c c-func docutils literal notranslate">Py_XNewRef()</code></a>.
</dd></dl>

<dl class="c function">
<dt class="sig sig-object c" id="c.Py_NewRef">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *Py_NewRef(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *o)<a class="headerlink" href="#c.Py_NewRef" title="Permalink to this definition">¶</a> </dt>
<dd> Part of the <a class="reference internal" href="stable.html#stable">Stable ABI</a> since version 3.10.Create a new <a class="reference internal" href="../glossary.html#term-strong-reference">strong reference</a> to an object: increment the reference
count of the object o and return the object o.
When the <a class="reference internal" href="../glossary.html#term-strong-reference">strong reference</a> is no longer needed, <a class="reference internal" href="#c.Py_DECREF" title="Py_DECREF"><code class="xref c c-func docutils literal notranslate">Py_DECREF()</code></a>
should be called on it to decrement the object reference count.
The object o must not be <code class="docutils literal notranslate">NULL</code>; use <a class="reference internal" href="#c.Py_XNewRef" title="Py_XNewRef"><code class="xref c c-func docutils literal notranslate">Py_XNewRef()</code></a> if o can be
<code class="docutils literal notranslate">NULL</code>.
For example:
<div class="highlight-c notranslate"><div class="highlight"><pre>Py_INCREF(obj);
self-&gt;attr = obj;
</pre></div>
</div>
can be written as:
<div class="highlight-c notranslate"><div class="highlight"><pre>self-&gt;attr = Py_NewRef(obj);
</pre></div>
</div>
See also <a class="reference internal" href="#c.Py_INCREF" title="Py_INCREF"><code class="xref c c-func docutils literal notranslate">Py_INCREF()</code></a>.
<div class="versionadded">
New in version 3.10.
</div>
</dd></dl>

<dl class="c function">
<dt class="sig sig-object c" id="c.Py_XNewRef">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *Py_XNewRef(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *o)<a class="headerlink" href="#c.Py_XNewRef" title="Permalink to this definition">¶</a> </dt>
<dd> Part of the <a class="reference internal" href="stable.html#stable">Stable ABI</a> since version 3.10.Similar to <a class="reference internal" href="#c.Py_NewRef" title="Py_NewRef"><code class="xref c c-func docutils literal notranslate">Py_NewRef()</code></a>, but the object o can be NULL.
If the object o is <code class="docutils literal notranslate">NULL</code>, the function just returns <code class="docutils literal notranslate">NULL</code>.
<div class="versionadded">
New in version 3.10.
</div>
</dd></dl>

<dl class="c function">
<dt class="sig sig-object c" id="c.Py_DECREF">
void Py_DECREF(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *o)<a class="headerlink" href="#c.Py_DECREF" title="Permalink to this definition">¶</a> </dt>
<dd>Decrement the reference count for object o.
If the reference count reaches zero, the object’s type’s deallocation
function (which must not be <code class="docutils literal notranslate">NULL</code>) is invoked.
This function is usually used to delete a <a class="reference internal" href="../glossary.html#term-strong-reference">strong reference</a> before
exiting its scope.
The object must not be <code class="docutils literal notranslate">NULL</code>; if you aren’t sure that it isn’t <code class="docutils literal notranslate">NULL</code>,
use <a class="reference internal" href="#c.Py_XDECREF" title="Py_XDECREF"><code class="xref c c-func docutils literal notranslate">Py_XDECREF()</code></a>.
<div class="admonition warning">
Warning
The deallocation function can cause arbitrary Python code to be invoked (e.g.
when a class instance with a <code class="xref py py-meth docutils literal notranslate">__del__()</code> 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="#c.Py_DECREF" title="Py_DECREF"><code class="xref c c-func docutils literal notranslate">Py_DECREF()</code></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="#c.Py_DECREF" title="Py_DECREF"><code class="xref c c-func docutils literal notranslate">Py_DECREF()</code></a> for the temporary variable.
</div>
</dd></dl>

<dl class="c function">
<dt class="sig sig-object c" id="c.Py_XDECREF">
void Py_XDECREF(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *o)<a class="headerlink" href="#c.Py_XDECREF" title="Permalink to this definition">¶</a> </dt>
<dd>Decrement the reference count for object o. The object may be <code class="docutils literal notranslate">NULL</code>, in
which case the macro has no effect; otherwise the effect is the same as for
<a class="reference internal" href="#c.Py_DECREF" title="Py_DECREF"><code class="xref c c-func docutils literal notranslate">Py_DECREF()</code></a>, and the same warning applies.
</dd></dl>

<dl class="c function">
<dt class="sig sig-object c" id="c.Py_CLEAR">
void Py_CLEAR(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *o)<a class="headerlink" href="#c.Py_CLEAR" title="Permalink to this definition">¶</a> </dt>
<dd>Decrement the reference count for object o. The object may be <code class="docutils literal notranslate">NULL</code>, in
which case the macro has no effect; otherwise the effect is the same as for
<a class="reference internal" href="#c.Py_DECREF" title="Py_DECREF"><code class="xref c c-func docutils literal notranslate">Py_DECREF()</code></a>, except that the argument is also set to <code class="docutils literal notranslate">NULL</code>. The warning
for <a class="reference internal" href="#c.Py_DECREF" title="Py_DECREF"><code class="xref c c-func docutils literal notranslate">Py_DECREF()</code></a> does not apply with respect to the object passed because
the macro carefully uses a temporary variable and sets the argument to <code class="docutils literal notranslate">NULL</code>
before decrementing its reference count.
It is a good idea to use this macro whenever decrementing the reference
count of an object that might be traversed during garbage collection.
</dd></dl>

<dl class="c function">
<dt class="sig sig-object c" id="c.Py_IncRef">
void Py_IncRef(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *o)<a class="headerlink" href="#c.Py_IncRef" title="Permalink to this definition">¶</a> </dt>
<dd> Part of the <a class="reference internal" href="stable.html#stable">Stable ABI</a>.Increment the reference count for object o. A function version of <a class="reference internal" href="#c.Py_XINCREF" title="Py_XINCREF"><code class="xref c c-func docutils literal notranslate">Py_XINCREF()</code></a>.
It can be used for runtime dynamic embedding of Python.
</dd></dl>

<dl class="c function">
<dt class="sig sig-object c" id="c.Py_DecRef">
void Py_DecRef(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *o)<a class="headerlink" href="#c.Py_DecRef" title="Permalink to this definition">¶</a> </dt>
<dd> Part of the <a class="reference internal" href="stable.html#stable">Stable ABI</a>.Decrement the reference count for object o. A function version of <a class="reference internal" href="#c.Py_XDECREF" title="Py_XDECREF"><code class="xref c c-func docutils literal notranslate">Py_XDECREF()</code></a>.
It can be used for runtime dynamic embedding of Python.
</dd></dl>

The following functions or macros are only for use within the interpreter core:
<code class="xref c c-func docutils literal notranslate">_Py_Dealloc()</code>, <code class="xref c c-func docutils literal notranslate">_Py_ForgetReference()</code>, <code class="xref c c-func docutils literal notranslate">_Py_NewReference()</code>,
as well as the global variable <code class="xref c c-data docutils literal notranslate">_Py_RefTotal</code>.
</section>

<div class="clearer"></div>
 </div>
 </div>
 </div>
 <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
 <div class="sphinxsidebarwrapper">
 <h4>Previous topic</h4>
 <a href="veryhigh.html"
 title="previous chapter">The Very High Level Layer</a>
 <h4>Next topic</h4>
 <a href="exceptions.html"
 title="next chapter">Exception Handling</a>
 <div role="note" aria-label="source link">
 <h3>This Page</h3>
 <ul class="this-page-menu">
 <li><a href="../bugs.html">Report a Bug</a></li>
 <li>
 <a href="https://github.com/python/cpython/blob/3.10/Doc/c-api/refcounting.rst"
 rel="nofollow">Show Source
 </a>
 </li>
 </ul>
 </div>
 </div>
 </div>
 <div class="clearer"></div>
 </div> 
 <div class="related" role="navigation" aria-label="related navigation">
 <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 class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> &#187;</li>
 <li class="nav-item nav-item-this"><a href="">Reference Counting</a></li>
 <li class="right">

<div class="inline-search" role="search">
 <form class="inline-search" action="../search.html" method="get">
 <input placeholder="Quick search" aria-label="Quick search" 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>
 </div>
 |
 </li>
 
 </ul>
 </div> 
 <div class="footer">
 &copy; <a href="../copyright.html">Copyright</a> 2001-2025, Python Software Foundation.
 
 This page is licensed under the Python Software Foundation License Version 2.
 
 Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
 
 See <a href="/license.html">History and License</a> for more information.

The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>

Last updated on February 04, 2025.
 <a href="/bugs.html">Found a bug</a>?

Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.3.2.
 </div>

</body>
</html>