|
1 .. highlightlang:: c |
|
2 |
|
3 |
|
4 .. _countingrefs: |
|
5 |
|
6 ****************** |
|
7 Reference Counting |
|
8 ****************** |
|
9 |
|
10 The macros in this section are used for managing reference counts of Python |
|
11 objects. |
|
12 |
|
13 |
|
14 .. cfunction:: void Py_INCREF(PyObject *o) |
|
15 |
|
16 Increment the reference count for object *o*. The object must not be *NULL*; if |
|
17 you aren't sure that it isn't *NULL*, use :cfunc:`Py_XINCREF`. |
|
18 |
|
19 |
|
20 .. cfunction:: void Py_XINCREF(PyObject *o) |
|
21 |
|
22 Increment the reference count for object *o*. The object may be *NULL*, in |
|
23 which case the macro has no effect. |
|
24 |
|
25 |
|
26 .. cfunction:: void Py_DECREF(PyObject *o) |
|
27 |
|
28 Decrement the reference count for object *o*. The object must not be *NULL*; if |
|
29 you aren't sure that it isn't *NULL*, use :cfunc:`Py_XDECREF`. If the reference |
|
30 count reaches zero, the object's type's deallocation function (which must not be |
|
31 *NULL*) is invoked. |
|
32 |
|
33 .. warning:: |
|
34 |
|
35 The deallocation function can cause arbitrary Python code to be invoked (e.g. |
|
36 when a class instance with a :meth:`__del__` method is deallocated). While |
|
37 exceptions in such code are not propagated, the executed code has free access to |
|
38 all Python global variables. This means that any object that is reachable from |
|
39 a global variable should be in a consistent state before :cfunc:`Py_DECREF` is |
|
40 invoked. For example, code to delete an object from a list should copy a |
|
41 reference to the deleted object in a temporary variable, update the list data |
|
42 structure, and then call :cfunc:`Py_DECREF` for the temporary variable. |
|
43 |
|
44 |
|
45 .. cfunction:: void Py_XDECREF(PyObject *o) |
|
46 |
|
47 Decrement the reference count for object *o*. The object may be *NULL*, in |
|
48 which case the macro has no effect; otherwise the effect is the same as for |
|
49 :cfunc:`Py_DECREF`, and the same warning applies. |
|
50 |
|
51 |
|
52 .. cfunction:: void Py_CLEAR(PyObject *o) |
|
53 |
|
54 Decrement the reference count for object *o*. The object may be *NULL*, in |
|
55 which case the macro has no effect; otherwise the effect is the same as for |
|
56 :cfunc:`Py_DECREF`, except that the argument is also set to *NULL*. The warning |
|
57 for :cfunc:`Py_DECREF` does not apply with respect to the object passed because |
|
58 the macro carefully uses a temporary variable and sets the argument to *NULL* |
|
59 before decrementing its reference count. |
|
60 |
|
61 It is a good idea to use this macro whenever decrementing the value of a |
|
62 variable that might be traversed during garbage collection. |
|
63 |
|
64 .. versionadded:: 2.4 |
|
65 |
|
66 The following functions are for runtime dynamic embedding of Python: |
|
67 ``Py_IncRef(PyObject *o)``, ``Py_DecRef(PyObject *o)``. They are |
|
68 simply exported function versions of :cfunc:`Py_XINCREF` and |
|
69 :cfunc:`Py_XDECREF`, respectively. |
|
70 |
|
71 The following functions or macros are only for use within the interpreter core: |
|
72 :cfunc:`_Py_Dealloc`, :cfunc:`_Py_ForgetReference`, :cfunc:`_Py_NewReference`, |
|
73 as well as the global variable :cdata:`_Py_RefTotal`. |
|
74 |