path: root/devdocs/python~3.12/c-api%2Frefcounting.html

 <span id="countingrefs"></span><h1>Reference Counting</h1> <p>The functions and macros in this section are used for managing reference counts of Python objects.</p> <dl class="c function"> <dt class="sig sig-object c" id="c.Py_REFCNT">
<code>Py_ssize_t Py_REFCNT(PyObject *o)</code> </dt> <dd>
<p>Get the reference count of the Python object <em>o</em>.</p> <p>Note that the returned value may not actually reflect how many references to the object are actually held. For example, some objects are “immortal” and have a very high refcount that does not reflect the actual number of references. Consequently, do not rely on the returned value to be accurate, other than a value of 0 or 1.</p> <p>Use the <a class="reference internal" href="#c.Py_SET_REFCNT" title="Py_SET_REFCNT"><code>Py_SET_REFCNT()</code></a> function to set an object reference count.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.11: </span>The parameter type is no longer <span class="c-expr sig sig-inline c"><span class="k">const</span><span class="w"> </span><a class="reference internal" href="structures#c.PyObject" title="PyObject"><span class="n">PyObject</span></a><span class="p">*</span></span>.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.10: </span><a class="reference internal" href="#c.Py_REFCNT" title="Py_REFCNT"><code>Py_REFCNT()</code></a> is changed to the inline static function.</p> </div> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.Py_SET_REFCNT">
<code>void Py_SET_REFCNT(PyObject *o, Py_ssize_t refcnt)</code> </dt> <dd>
<p>Set the object <em>o</em> reference counter to <em>refcnt</em>.</p> <p>Note that this function has no effect on <a class="reference external" href="https://peps.python.org/pep-0683/">immortal</a> objects.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.9.</span></p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.12: </span>Immortal objects are not modified.</p> </div> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.Py_INCREF">
<code>void Py_INCREF(PyObject *o)</code> </dt> <dd>
<p>Indicate taking a new <a class="reference internal" href="../glossary#term-strong-reference"><span class="xref std std-term">strong reference</span></a> to object <em>o</em>, indicating it is in use and should not be destroyed.</p> <p>This function is usually used to convert a <a class="reference internal" href="../glossary#term-borrowed-reference"><span class="xref std std-term">borrowed reference</span></a> to a <a class="reference internal" href="../glossary#term-strong-reference"><span class="xref std std-term">strong reference</span></a> in-place. The <a class="reference internal" href="#c.Py_NewRef" title="Py_NewRef"><code>Py_NewRef()</code></a> function can be used to create a new <a class="reference internal" href="../glossary#term-strong-reference"><span class="xref std std-term">strong reference</span></a>.</p> <p>When done using the object, release it by calling <a class="reference internal" href="#c.Py_DECREF" title="Py_DECREF"><code>Py_DECREF()</code></a>.</p> <p>The object must not be <code>NULL</code>; if you aren’t sure that it isn’t <code>NULL</code>, use <a class="reference internal" href="#c.Py_XINCREF" title="Py_XINCREF"><code>Py_XINCREF()</code></a>.</p> <p>Do not expect this function to actually modify <em>o</em> in any way. For at least <a class="reference external" href="https://peps.python.org/pep-0683/">some objects</a>, this function has no effect.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.12: </span>Immortal objects are not modified.</p> </div> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.Py_XINCREF">
<code>void Py_XINCREF(PyObject *o)</code> </dt> <dd>
<p>Similar to <a class="reference internal" href="#c.Py_INCREF" title="Py_INCREF"><code>Py_INCREF()</code></a>, but the object <em>o</em> can be <code>NULL</code>, in which case this has no effect.</p> <p>See also <a class="reference internal" href="#c.Py_XNewRef" title="Py_XNewRef"><code>Py_XNewRef()</code></a>.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.Py_NewRef">
<code>PyObject *Py_NewRef(PyObject *o)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.10.</em><p>Create a new <a class="reference internal" href="../glossary#term-strong-reference"><span class="xref std std-term">strong reference</span></a> to an object: call <a class="reference internal" href="#c.Py_INCREF" title="Py_INCREF"><code>Py_INCREF()</code></a> on <em>o</em> and return the object <em>o</em>.</p> <p>When the <a class="reference internal" href="../glossary#term-strong-reference"><span class="xref std std-term">strong reference</span></a> is no longer needed, <a class="reference internal" href="#c.Py_DECREF" title="Py_DECREF"><code>Py_DECREF()</code></a> should be called on it to release the reference.</p> <p>The object <em>o</em> must not be <code>NULL</code>; use <a class="reference internal" href="#c.Py_XNewRef" title="Py_XNewRef"><code>Py_XNewRef()</code></a> if <em>o</em> can be <code>NULL</code>.</p> <p>For example:</p> <pre data-language="c">Py_INCREF(obj);
self-&gt;attr = obj;
</pre> <p>can be written as:</p> <pre data-language="c">self-&gt;attr = Py_NewRef(obj);
</pre> <p>See also <a class="reference internal" href="#c.Py_INCREF" title="Py_INCREF"><code>Py_INCREF()</code></a>.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.10.</span></p> </div> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.Py_XNewRef">
<code>PyObject *Py_XNewRef(PyObject *o)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.10.</em><p>Similar to <a class="reference internal" href="#c.Py_NewRef" title="Py_NewRef"><code>Py_NewRef()</code></a>, but the object <em>o</em> can be NULL.</p> <p>If the object <em>o</em> is <code>NULL</code>, the function just returns <code>NULL</code>.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.10.</span></p> </div> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.Py_DECREF">
<code>void Py_DECREF(PyObject *o)</code> </dt> <dd>
<p>Release a <a class="reference internal" href="../glossary#term-strong-reference"><span class="xref std std-term">strong reference</span></a> to object <em>o</em>, indicating the reference is no longer used.</p> <p>Once the last <a class="reference internal" href="../glossary#term-strong-reference"><span class="xref std std-term">strong reference</span></a> is released (i.e. the object’s reference count reaches 0), the object’s type’s deallocation function (which must not be <code>NULL</code>) is invoked.</p> <p>This function is usually used to delete a <a class="reference internal" href="../glossary#term-strong-reference"><span class="xref std std-term">strong reference</span></a> before exiting its scope.</p> <p>The object must not be <code>NULL</code>; if you aren’t sure that it isn’t <code>NULL</code>, use <a class="reference internal" href="#c.Py_XDECREF" title="Py_XDECREF"><code>Py_XDECREF()</code></a>.</p> <p>Do not expect this function to actually modify <em>o</em> in any way. For at least <a class="reference external" href="https://peps.python.org/pep-0683/">some objects</a>, this function has no effect.</p> <div class="admonition warning"> <p class="admonition-title">Warning</p> <p>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#object.__del__" title="object.__del__"><code>__del__()</code></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="#c.Py_DECREF" title="Py_DECREF"><code>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>Py_DECREF()</code></a> for the temporary variable.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.12: </span>Immortal objects are not modified.</p> </div> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.Py_XDECREF">
<code>void Py_XDECREF(PyObject *o)</code> </dt> <dd>
<p>Similar to <a class="reference internal" href="#c.Py_DECREF" title="Py_DECREF"><code>Py_DECREF()</code></a>, but the object <em>o</em> can be <code>NULL</code>, in which case this has no effect. The same warning from <a class="reference internal" href="#c.Py_DECREF" title="Py_DECREF"><code>Py_DECREF()</code></a> applies here as well.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.Py_CLEAR">
<code>void Py_CLEAR(PyObject *o)</code> </dt> <dd>
<p>Release a <a class="reference internal" href="../glossary#term-strong-reference"><span class="xref std std-term">strong reference</span></a> for object <em>o</em>. The object may be <code>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>Py_DECREF()</code></a>, except that the argument is also set to <code>NULL</code>. The warning for <a class="reference internal" href="#c.Py_DECREF" title="Py_DECREF"><code>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>NULL</code> before releasing the reference.</p> <p>It is a good idea to use this macro whenever releasing a reference to an object that might be traversed during garbage collection.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.12: </span>The macro argument is now only evaluated once. If the argument has side effects, these are no longer duplicated.</p> </div> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.Py_IncRef">
<code>void Py_IncRef(PyObject *o)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Indicate taking a new <a class="reference internal" href="../glossary#term-strong-reference"><span class="xref std std-term">strong reference</span></a> to object <em>o</em>. A function version of <a class="reference internal" href="#c.Py_XINCREF" title="Py_XINCREF"><code>Py_XINCREF()</code></a>. It can be used for runtime dynamic embedding of Python.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.Py_DecRef">
<code>void Py_DecRef(PyObject *o)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Release a <a class="reference internal" href="../glossary#term-strong-reference"><span class="xref std std-term">strong reference</span></a> to object <em>o</em>. A function version of <a class="reference internal" href="#c.Py_XDECREF" title="Py_XDECREF"><code>Py_XDECREF()</code></a>. It can be used for runtime dynamic embedding of Python.</p> </dd>
</dl> <dl class="c macro"> <dt class="sig sig-object c" id="c.Py_SETREF">
<code>Py_SETREF(dst, src)</code> </dt> <dd>
<p>Macro safely releasing a <a class="reference internal" href="../glossary#term-strong-reference"><span class="xref std std-term">strong reference</span></a> to object <em>dst</em> and setting <em>dst</em> to <em>src</em>.</p> <p>As in case of <a class="reference internal" href="#c.Py_CLEAR" title="Py_CLEAR"><code>Py_CLEAR()</code></a>, “the obvious” code can be deadly:</p> <pre data-language="c">Py_DECREF(dst);
dst = src;
</pre> <p>The safe way is:</p> <pre data-language="c">Py_SETREF(dst, src);
</pre> <p>That arranges to set <em>dst</em> to <em>src</em> _before_ releasing the reference to the old value of <em>dst</em>, so that any code triggered as a side-effect of <em>dst</em> getting torn down no longer believes <em>dst</em> points to a valid object.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.6.</span></p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.12: </span>The macro arguments are now only evaluated once. If an argument has side effects, these are no longer duplicated.</p> </div> </dd>
</dl> <dl class="c macro"> <dt class="sig sig-object c" id="c.Py_XSETREF">
<code>Py_XSETREF(dst, src)</code> </dt> <dd>
<p>Variant of <a class="reference internal" href="#c.Py_SETREF" title="Py_SETREF"><code>Py_SETREF</code></a> macro that uses <a class="reference internal" href="#c.Py_XDECREF" title="Py_XDECREF"><code>Py_XDECREF()</code></a> instead of <a class="reference internal" href="#c.Py_DECREF" title="Py_DECREF"><code>Py_DECREF()</code></a>.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.6.</span></p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.12: </span>The macro arguments are now only evaluated once. If an argument has side effects, these are no longer duplicated.</p> </div> </dd>
</dl> <div class="_attribution">
  <p class="_attribution-p">
    &copy; 2001&ndash;2023 Python Software Foundation<br>Licensed under the PSF License.<br>
    <a href="https://docs.python.org/3.12/c-api/refcounting.html" class="_attribution-link">https://docs.python.org/3.12/c-api/refcounting.html</a>
  </p>
</div>