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