| 1 |
.. highlight:: c |
| 2 |
|
| 3 |
|
| 4 |
.. _countingrefs: |
| 5 |
|
| 6 |
****************** |
| 7 |
Reference Counting |
| 8 |
****************** |
| 9 |
|
| 10 |
The functions and macros in this section are used for managing reference counts |
| 11 |
of Python objects. |
| 12 |
|
| 13 |
|
| 14 |
.. c:function:: Py_ssize_t Py_REFCNT(PyObject *o) |
| 15 |
|
| 16 |
Get the reference count of the Python object *o*. |
| 17 |
|
| 18 |
Note that the returned value may not actually reflect how many |
| 19 |
references to the object are actually held. For example, some |
| 20 |
objects are :term:`immortal` and have a very high refcount that does not |
| 21 |
reflect the actual number of references. Consequently, do not rely |
| 22 |
on the returned value to be accurate, other than a value of 0 or 1. |
| 23 |
|
| 24 |
Use the :c:func:`Py_SET_REFCNT()` function to set an object reference count. |
| 25 |
|
| 26 |
.. note:: |
| 27 |
|
| 28 |
On :term:`free-threaded builds <free-threaded build>` of Python, returning 1 |
| 29 |
isn't sufficient to determine if it's safe to treat *o* as having no |
| 30 |
access by other threads. Use :c:func:`PyUnstable_Object_IsUniquelyReferenced` |
| 31 |
for that instead. |
| 32 |
|
| 33 |
See also the function :c:func:`PyUnstable_Object_IsUniqueReferencedTemporary()`. |
| 34 |
|
| 35 |
.. versionchanged:: 3.10 |
| 36 |
:c:func:`Py_REFCNT()` is changed to the inline static function. |
| 37 |
|
| 38 |
.. versionchanged:: 3.11 |
| 39 |
The parameter type is no longer :c:expr:`const PyObject*`. |
| 40 |
|
| 41 |
|
| 42 |
.. c:function:: void Py_SET_REFCNT(PyObject *o, Py_ssize_t refcnt) |
| 43 |
|
| 44 |
Set the object *o* reference counter to *refcnt*. |
| 45 |
|
| 46 |
On :ref:`Python build with Free Threading <free-threading-build>`, if |
| 47 |
*refcnt* is larger than ``UINT32_MAX``, the object is made :term:`immortal`. |
| 48 |
|
| 49 |
This function has no effect on :term:`immortal` objects. |
| 50 |
|
| 51 |
.. versionadded:: 3.9 |
| 52 |
|
| 53 |
.. versionchanged:: 3.12 |
| 54 |
Immortal objects are not modified. |
| 55 |
|
| 56 |
|
| 57 |
.. c:function:: void Py_INCREF(PyObject *o) |
| 58 |
|
| 59 |
Indicate taking a new :term:`strong reference` to object *o*, |
| 60 |
indicating it is in use and should not be destroyed. |
| 61 |
|
| 62 |
This function has no effect on :term:`immortal` objects. |
| 63 |
|
| 64 |
This function is usually used to convert a :term:`borrowed reference` to a |
| 65 |
:term:`strong reference` in-place. The :c:func:`Py_NewRef` function can be |
| 66 |
used to create a new :term:`strong reference`. |
| 67 |
|
| 68 |
When done using the object, release is by calling :c:func:`Py_DECREF`. |
| 69 |
|
| 70 |
The object must not be ``NULL``; if you aren't sure that it isn't |
| 71 |
``NULL``, use :c:func:`Py_XINCREF`. |
| 72 |
|
| 73 |
Do not expect this function to actually modify *o* in any way. |
| 74 |
For at least :pep:`some objects <0683>`, |
| 75 |
this function has no effect. |
| 76 |
|
| 77 |
.. versionchanged:: 3.12 |
| 78 |
Immortal objects are not modified. |
| 79 |
|
| 80 |
|
| 81 |
.. c:function:: void Py_XINCREF(PyObject *o) |
| 82 |
|
| 83 |
Similar to :c:func:`Py_INCREF`, but the object *o* can be ``NULL``, |
| 84 |
in which case this has no effect. |
| 85 |
|
| 86 |
See also :c:func:`Py_XNewRef`. |
| 87 |
|
| 88 |
|
| 89 |
.. c:function:: PyObject* Py_NewRef(PyObject *o) |
| 90 |
|
| 91 |
Create a new :term:`strong reference` to an object: |
| 92 |
call :c:func:`Py_INCREF` on *o* and return the object *o*. |
| 93 |
|
| 94 |
When the :term:`strong reference` is no longer needed, :c:func:`Py_DECREF` |
| 95 |
should be called on it to release the reference. |
| 96 |
|
| 97 |
The object *o* must not be ``NULL``; use :c:func:`Py_XNewRef` if *o* can be |
| 98 |
``NULL``. |
| 99 |
|
| 100 |
For example:: |
| 101 |
|
| 102 |
Py_INCREF(obj); |
| 103 |
self->attr = obj; |
| 104 |
|
| 105 |
can be written as:: |
| 106 |
|
| 107 |
self->attr = Py_NewRef(obj); |
| 108 |
|
| 109 |
See also :c:func:`Py_INCREF`. |
| 110 |
|
| 111 |
.. versionadded:: 3.10 |
| 112 |
|
| 113 |
|
| 114 |
.. c:function:: PyObject* Py_XNewRef(PyObject *o) |
| 115 |
|
| 116 |
Similar to :c:func:`Py_NewRef`, but the object *o* can be NULL. |
| 117 |
|
| 118 |
If the object *o* is ``NULL``, the function just returns ``NULL``. |
| 119 |
|
| 120 |
.. versionadded:: 3.10 |
| 121 |
|
| 122 |
|
| 123 |
.. c:function:: void Py_DECREF(PyObject *o) |
| 124 |
|
| 125 |
Release a :term:`strong reference` to object *o*, indicating the |
| 126 |
reference is no longer used. |
| 127 |
|
| 128 |
This function has no effect on :term:`immortal` objects. |
| 129 |
|
| 130 |
Once the last :term:`strong reference` is released |
| 131 |
(i.e. the object's reference count reaches 0), |
| 132 |
the object's type's deallocation |
| 133 |
function (which must not be ``NULL``) is invoked. |
| 134 |
|
| 135 |
This function is usually used to delete a :term:`strong reference` before |
| 136 |
exiting its scope. |
| 137 |
|
| 138 |
The object must not be ``NULL``; if you aren't sure that it isn't ``NULL``, |
| 139 |
use :c:func:`Py_XDECREF`. |
| 140 |
|
| 141 |
Do not expect this function to actually modify *o* in any way. |
| 142 |
For at least :pep:`some objects <683>`, |
| 143 |
this function has no effect. |
| 144 |
|
| 145 |
.. warning:: |
| 146 |
|
| 147 |
The deallocation function can cause arbitrary Python code to be invoked (e.g. |
| 148 |
when a class instance with a :meth:`~object.__del__` method is deallocated). While |
| 149 |
exceptions in such code are not propagated, the executed code has free access to |
| 150 |
all Python global variables. This means that any object that is reachable from |
| 151 |
a global variable should be in a consistent state before :c:func:`Py_DECREF` is |
| 152 |
invoked. For example, code to delete an object from a list should copy a |
| 153 |
reference to the deleted object in a temporary variable, update the list data |
| 154 |
structure, and then call :c:func:`Py_DECREF` for the temporary variable. |
| 155 |
|
| 156 |
.. versionchanged:: 3.12 |
| 157 |
Immortal objects are not modified. |
| 158 |
|
| 159 |
|
| 160 |
.. c:function:: void Py_XDECREF(PyObject *o) |
| 161 |
|
| 162 |
Similar to :c:func:`Py_DECREF`, but the object *o* can be ``NULL``, |
| 163 |
in which case this has no effect. |
| 164 |
The same warning from :c:func:`Py_DECREF` applies here as well. |
| 165 |
|
| 166 |
|
| 167 |
.. c:function:: void Py_CLEAR(PyObject *o) |
| 168 |
|
| 169 |
Release a :term:`strong reference` for object *o*. |
| 170 |
The object may be ``NULL``, in |
| 171 |
which case the macro has no effect; otherwise the effect is the same as for |
| 172 |
:c:func:`Py_DECREF`, except that the argument is also set to ``NULL``. The warning |
| 173 |
for :c:func:`Py_DECREF` does not apply with respect to the object passed because |
| 174 |
the macro carefully uses a temporary variable and sets the argument to ``NULL`` |
| 175 |
before releasing the reference. |
| 176 |
|
| 177 |
It is a good idea to use this macro whenever releasing a reference |
| 178 |
to an object that might be traversed during garbage collection. |
| 179 |
|
| 180 |
.. versionchanged:: 3.12 |
| 181 |
The macro argument is now only evaluated once. If the argument has side |
| 182 |
effects, these are no longer duplicated. |
| 183 |
|
| 184 |
|
| 185 |
.. c:function:: void Py_IncRef(PyObject *o) |
| 186 |
|
| 187 |
Indicate taking a new :term:`strong reference` to object *o*. |
| 188 |
A function version of :c:func:`Py_XINCREF`. |
| 189 |
It can be used for runtime dynamic embedding of Python. |
| 190 |
|
| 191 |
|
| 192 |
.. c:function:: void Py_DecRef(PyObject *o) |
| 193 |
|
| 194 |
Release a :term:`strong reference` to object *o*. |
| 195 |
A function version of :c:func:`Py_XDECREF`. |
| 196 |
It can be used for runtime dynamic embedding of Python. |
| 197 |
|
| 198 |
|
| 199 |
.. c:macro:: Py_SETREF(dst, src) |
| 200 |
|
| 201 |
Macro safely releasing a :term:`strong reference` to object *dst* |
| 202 |
and setting *dst* to *src*. |
| 203 |
|
| 204 |
As in case of :c:func:`Py_CLEAR`, "the obvious" code can be deadly:: |
| 205 |
|
| 206 |
Py_DECREF(dst); |
| 207 |
dst = src; |
| 208 |
|
| 209 |
The safe way is:: |
| 210 |
|
| 211 |
Py_SETREF(dst, src); |
| 212 |
|
| 213 |
That arranges to set *dst* to *src* *before* releasing the reference |
| 214 |
to the old value of *dst*, so that any code triggered as a side-effect |
| 215 |
of *dst* getting torn down no longer believes *dst* points |
| 216 |
to a valid object. |
| 217 |
|
| 218 |
.. versionadded:: 3.6 |
| 219 |
|
| 220 |
.. versionchanged:: 3.12 |
| 221 |
The macro arguments are now only evaluated once. If an argument has side |
| 222 |
effects, these are no longer duplicated. |
| 223 |
|
| 224 |
|
| 225 |
.. c:macro:: Py_XSETREF(dst, src) |
| 226 |
|
| 227 |
Variant of :c:macro:`Py_SETREF` macro that uses :c:func:`Py_XDECREF` instead |
| 228 |
of :c:func:`Py_DECREF`. |
| 229 |
|
| 230 |
.. versionadded:: 3.6 |
| 231 |
|
| 232 |
.. versionchanged:: 3.12 |
| 233 |
The macro arguments are now only evaluated once. If an argument has side |
| 234 |
effects, these are no longer duplicated. |