Gecko [ fernandoquevedodop.com ]

Name	Size	Permission
abstract.html	13.46 KB	-rw-r--r--
allocation.html	21.28 KB	-rw-r--r--
apiabiversion.html	15.83 KB	-rw-r--r--
arg.html	105.47 KB	-rw-r--r--
bool.html	14.58 KB	-rw-r--r--
buffer.html	83.05 KB	-rw-r--r--
bytearray.html	24.02 KB	-rw-r--r--
bytes.html	38.82 KB	-rw-r--r--
call.html	64.15 KB	-rw-r--r--
capsule.html	33.48 KB	-rw-r--r--
cell.html	17.69 KB	-rw-r--r--
code.html	24.99 KB	-rw-r--r--
codec.html	39.51 KB	-rw-r--r--
complex.html	30.48 KB	-rw-r--r--
concrete.html	21.41 KB	-rw-r--r--
contextvars.html	30.26 KB	-rw-r--r--
conversion.html	28.6 KB	-rw-r--r--
coro.html	14.01 KB	-rw-r--r--
datetime.html	53.09 KB	-rw-r--r--
descriptor.html	19.49 KB	-rw-r--r--
dict.html	56.11 KB	-rw-r--r--
exceptions.html	190.81 KB	-rw-r--r--
file.html	24.95 KB	-rw-r--r--
float.html	21.84 KB	-rw-r--r--
function.html	27.12 KB	-rw-r--r--
gcsupport.html	43.43 KB	-rw-r--r--
gen.html	16.21 KB	-rw-r--r--
import.html	61.83 KB	-rw-r--r--
index.html	22.24 KB	-rw-r--r--
init.html	225.02 KB	-rw-r--r--
init_config.html	204.18 KB	-rw-r--r--
intro.html	96.61 KB	-rw-r--r--
iter.html	19.62 KB	-rw-r--r--
iterator.html	16.87 KB	-rw-r--r--
list.html	34.91 KB	-rw-r--r--
long.html	62.14 KB	-rw-r--r--
mapping.html	28.43 KB	-rw-r--r--
marshal.html	23.89 KB	-rw-r--r--
memory.html	95.91 KB	-rw-r--r--
memoryview.html	20 KB	-rw-r--r--
method.html	23.98 KB	-rw-r--r--
module.html	98.3 KB	-rw-r--r--
none.html	12.1 KB	-rw-r--r--
number.html	74.63 KB	-rw-r--r--
objbuffer.html	19.12 KB	-rw-r--r--
object.html	80.93 KB	-rw-r--r--
objimpl.html	13.03 KB	-rw-r--r--
refcounting.html	25.62 KB	-rw-r--r--
reflection.html	20.69 KB	-rw-r--r--
sequence.html	46.94 KB	-rw-r--r--
set.html	41.5 KB	-rw-r--r--
slice.html	30.93 KB	-rw-r--r--
stable.html	195.79 KB	-rw-r--r--
structures.html	73.73 KB	-rw-r--r--
sys.html	69.43 KB	-rw-r--r--
tuple.html	47.5 KB	-rw-r--r--
type.html	55.03 KB	-rw-r--r--
typehints.html	16.62 KB	-rw-r--r--
typeobj.html	428.4 KB	-rw-r--r--
unicode.html	287.18 KB	-rw-r--r--
utilities.html	11.88 KB	-rw-r--r--
veryhigh.html	81.69 KB	-rw-r--r--
weakref.html	21.05 KB	-rw-r--r--

Code Editor : refcounting.html

<!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-2026, 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 January 26, 2026.
 <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>

${this.title}

Code Editor : refcounting.html