Debian Codegraph @

Doc/c-api/refcounting.rst

raw
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.