1.. highlight:: c 2 3.. _supporting-cycle-detection: 4 5Supporting Cyclic Garbage Collection 6==================================== 7 8Python's support for detecting and collecting garbage which involves circular 9references requires support from object types which are "containers" for other 10objects which may also be containers. Types which do not store references to 11other objects, or which only store references to atomic types (such as numbers 12or strings), do not need to provide any explicit support for garbage 13collection. 14 15To create a container type, the :c:member:`~PyTypeObject.tp_flags` field of the type object must 16include the :const:`Py_TPFLAGS_HAVE_GC` and provide an implementation of the 17:c:member:`~PyTypeObject.tp_traverse` handler. If instances of the type are mutable, a 18:c:member:`~PyTypeObject.tp_clear` implementation must also be provided. 19 20 21.. data:: Py_TPFLAGS_HAVE_GC 22 :noindex: 23 24 Objects with a type with this flag set must conform with the rules 25 documented here. For convenience these objects will be referred to as 26 container objects. 27 28Constructors for container types must conform to two rules: 29 30#. The memory for the object must be allocated using :c:func:`PyObject_GC_New` 31 or :c:func:`PyObject_GC_NewVar`. 32 33#. Once all the fields which may contain references to other containers are 34 initialized, it must call :c:func:`PyObject_GC_Track`. 35 36Similarly, the deallocator for the object must conform to a similar pair of 37rules: 38 39#. Before fields which refer to other containers are invalidated, 40 :c:func:`PyObject_GC_UnTrack` must be called. 41 42#. The object's memory must be deallocated using :c:func:`PyObject_GC_Del`. 43 44 .. warning:: 45 If a type adds the Py_TPFLAGS_HAVE_GC, then it *must* implement at least 46 a :c:member:`~PyTypeObject.tp_traverse` handler or explicitly use one 47 from its subclass or subclasses. 48 49 When calling :c:func:`PyType_Ready` or some of the APIs that indirectly 50 call it like :c:func:`PyType_FromSpecWithBases` or 51 :c:func:`PyType_FromSpec` the interpreter will automatically populate the 52 :c:member:`~PyTypeObject.tp_flags`, :c:member:`~PyTypeObject.tp_traverse` 53 and :c:member:`~PyTypeObject.tp_clear` fields if the type inherits from a 54 class that implements the garbage collector protocol and the child class 55 does *not* include the :const:`Py_TPFLAGS_HAVE_GC` flag. 56 57.. c:function:: TYPE* PyObject_GC_New(TYPE, PyTypeObject *type) 58 59 Analogous to :c:func:`PyObject_New` but for container objects with the 60 :const:`Py_TPFLAGS_HAVE_GC` flag set. 61 62 63.. c:function:: TYPE* PyObject_GC_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size) 64 65 Analogous to :c:func:`PyObject_NewVar` but for container objects with the 66 :const:`Py_TPFLAGS_HAVE_GC` flag set. 67 68 69.. c:function:: TYPE* PyObject_GC_Resize(TYPE, PyVarObject *op, Py_ssize_t newsize) 70 71 Resize an object allocated by :c:func:`PyObject_NewVar`. Returns the 72 resized object or ``NULL`` on failure. *op* must not be tracked by the collector yet. 73 74 75.. c:function:: void PyObject_GC_Track(PyObject *op) 76 77 Adds the object *op* to the set of container objects tracked by the 78 collector. The collector can run at unexpected times so objects must be 79 valid while being tracked. This should be called once all the fields 80 followed by the :c:member:`~PyTypeObject.tp_traverse` handler become valid, usually near the 81 end of the constructor. 82 83 84.. c:function:: int PyObject_IS_GC(PyObject *obj) 85 86 Returns non-zero if the object implements the garbage collector protocol, 87 otherwise returns 0. 88 89 The object cannot be tracked by the garbage collector if this function returns 0. 90 91 92.. c:function:: int PyObject_GC_IsTracked(PyObject *op) 93 94 Returns 1 if the object type of *op* implements the GC protocol and *op* is being 95 currently tracked by the garbage collector and 0 otherwise. 96 97 This is analogous to the Python function :func:`gc.is_tracked`. 98 99 .. versionadded:: 3.9 100 101 102.. c:function:: int PyObject_GC_IsFinalized(PyObject *op) 103 104 Returns 1 if the object type of *op* implements the GC protocol and *op* has been 105 already finalized by the garbage collector and 0 otherwise. 106 107 This is analogous to the Python function :func:`gc.is_finalized`. 108 109 .. versionadded:: 3.9 110 111 112.. c:function:: void PyObject_GC_Del(void *op) 113 114 Releases memory allocated to an object using :c:func:`PyObject_GC_New` or 115 :c:func:`PyObject_GC_NewVar`. 116 117 118.. c:function:: void PyObject_GC_UnTrack(void *op) 119 120 Remove the object *op* from the set of container objects tracked by the 121 collector. Note that :c:func:`PyObject_GC_Track` can be called again on 122 this object to add it back to the set of tracked objects. The deallocator 123 (:c:member:`~PyTypeObject.tp_dealloc` handler) should call this for the object before any of 124 the fields used by the :c:member:`~PyTypeObject.tp_traverse` handler become invalid. 125 126 127.. versionchanged:: 3.8 128 129 The :c:func:`_PyObject_GC_TRACK` and :c:func:`_PyObject_GC_UNTRACK` macros 130 have been removed from the public C API. 131 132The :c:member:`~PyTypeObject.tp_traverse` handler accepts a function parameter of this type: 133 134 135.. c:type:: int (*visitproc)(PyObject *object, void *arg) 136 137 Type of the visitor function passed to the :c:member:`~PyTypeObject.tp_traverse` handler. 138 The function should be called with an object to traverse as *object* and 139 the third parameter to the :c:member:`~PyTypeObject.tp_traverse` handler as *arg*. The 140 Python core uses several visitor functions to implement cyclic garbage 141 detection; it's not expected that users will need to write their own 142 visitor functions. 143 144The :c:member:`~PyTypeObject.tp_traverse` handler must have the following type: 145 146 147.. c:type:: int (*traverseproc)(PyObject *self, visitproc visit, void *arg) 148 149 Traversal function for a container object. Implementations must call the 150 *visit* function for each object directly contained by *self*, with the 151 parameters to *visit* being the contained object and the *arg* value passed 152 to the handler. The *visit* function must not be called with a ``NULL`` 153 object argument. If *visit* returns a non-zero value that value should be 154 returned immediately. 155 156To simplify writing :c:member:`~PyTypeObject.tp_traverse` handlers, a :c:func:`Py_VISIT` macro is 157provided. In order to use this macro, the :c:member:`~PyTypeObject.tp_traverse` implementation 158must name its arguments exactly *visit* and *arg*: 159 160 161.. c:function:: void Py_VISIT(PyObject *o) 162 163 If *o* is not ``NULL``, call the *visit* callback, with arguments *o* 164 and *arg*. If *visit* returns a non-zero value, then return it. 165 Using this macro, :c:member:`~PyTypeObject.tp_traverse` handlers 166 look like:: 167 168 static int 169 my_traverse(Noddy *self, visitproc visit, void *arg) 170 { 171 Py_VISIT(self->foo); 172 Py_VISIT(self->bar); 173 return 0; 174 } 175 176The :c:member:`~PyTypeObject.tp_clear` handler must be of the :c:type:`inquiry` type, or ``NULL`` 177if the object is immutable. 178 179 180.. c:type:: int (*inquiry)(PyObject *self) 181 182 Drop references that may have created reference cycles. Immutable objects 183 do not have to define this method since they can never directly create 184 reference cycles. Note that the object must still be valid after calling 185 this method (don't just call :c:func:`Py_DECREF` on a reference). The 186 collector will call this method if it detects that this object is involved 187 in a reference cycle. 188 189 190Controlling the Garbage Collector State 191--------------------------------------- 192 193The C-API provides the following functions for controlling 194garbage collection runs. 195 196.. c:function:: Py_ssize_t PyGC_Collect(void) 197 198 Perform a full garbage collection, if the garbage collector is enabled. 199 (Note that :func:`gc.collect` runs it unconditionally.) 200 201 Returns the number of collected + unreachable objects which cannot 202 be collected. 203 If the garbage collector is disabled or already collecting, 204 returns ``0`` immediately. 205 Errors during garbage collection are passed to :data:`sys.unraisablehook`. 206 This function does not raise exceptions. 207 208 209.. c:function:: int PyGC_Enable(void) 210 211 Enable the garbage collector: similar to :func:`gc.enable`. 212 Returns the previous state, 0 for disabled and 1 for enabled. 213 214 .. versionadded:: 3.10 215 216 217.. c:function:: int PyGC_Disable(void) 218 219 Disable the garbage collector: similar to :func:`gc.disable`. 220 Returns the previous state, 0 for disabled and 1 for enabled. 221 222 .. versionadded:: 3.10 223 224 225.. c:function:: int PyGC_IsEnabled(void) 226 227 Query the state of the garbage collector: similar to :func:`gc.isenabled`. 228 Returns the current state, 0 for disabled and 1 for enabled. 229 230 .. versionadded:: 3.10 231