1 2 :mod:`gc` --- Garbage Collector interface 3 ========================================= 4 5 .. module:: gc 6 :synopsis: Interface to the cycle-detecting garbage collector. 7 .. moduleauthor:: Neil Schemenauer <nas (a] arctrix.com> 8 .. sectionauthor:: Neil Schemenauer <nas (a] arctrix.com> 9 10 11 This module provides an interface to the optional garbage collector. It 12 provides the ability to disable the collector, tune the collection frequency, 13 and set debugging options. It also provides access to unreachable objects that 14 the collector found but cannot free. Since the collector supplements the 15 reference counting already used in Python, you can disable the collector if you 16 are sure your program does not create reference cycles. Automatic collection 17 can be disabled by calling ``gc.disable()``. To debug a leaking program call 18 ``gc.set_debug(gc.DEBUG_LEAK)``. Notice that this includes 19 ``gc.DEBUG_SAVEALL``, causing garbage-collected objects to be saved in 20 gc.garbage for inspection. 21 22 The :mod:`gc` module provides the following functions: 23 24 25 .. function:: enable() 26 27 Enable automatic garbage collection. 28 29 30 .. function:: disable() 31 32 Disable automatic garbage collection. 33 34 35 .. function:: isenabled() 36 37 Returns true if automatic collection is enabled. 38 39 40 .. function:: collect([generation]) 41 42 With no arguments, run a full collection. The optional argument *generation* 43 may be an integer specifying which generation to collect (from 0 to 2). A 44 :exc:`ValueError` is raised if the generation number is invalid. The number of 45 unreachable objects found is returned. 46 47 .. versionchanged:: 2.5 48 The optional *generation* argument was added. 49 50 .. versionchanged:: 2.6 51 The free lists maintained for a number of built-in types are cleared 52 whenever a full collection or collection of the highest generation (2) 53 is run. Not all items in some free lists may be freed due to the 54 particular implementation, in particular :class:`int` and :class:`float`. 55 56 57 .. function:: set_debug(flags) 58 59 Set the garbage collection debugging flags. Debugging information will be 60 written to ``sys.stderr``. See below for a list of debugging flags which can be 61 combined using bit operations to control debugging. 62 63 64 .. function:: get_debug() 65 66 Return the debugging flags currently set. 67 68 69 .. function:: get_objects() 70 71 Returns a list of all objects tracked by the collector, excluding the list 72 returned. 73 74 .. versionadded:: 2.2 75 76 77 .. function:: set_threshold(threshold0[, threshold1[, threshold2]]) 78 79 Set the garbage collection thresholds (the collection frequency). Setting 80 *threshold0* to zero disables collection. 81 82 The GC classifies objects into three generations depending on how many 83 collection sweeps they have survived. New objects are placed in the youngest 84 generation (generation ``0``). If an object survives a collection it is moved 85 into the next older generation. Since generation ``2`` is the oldest 86 generation, objects in that generation remain there after a collection. In 87 order to decide when to run, the collector keeps track of the number object 88 allocations and deallocations since the last collection. When the number of 89 allocations minus the number of deallocations exceeds *threshold0*, collection 90 starts. Initially only generation ``0`` is examined. If generation ``0`` has 91 been examined more than *threshold1* times since generation ``1`` has been 92 examined, then generation ``1`` is examined as well. Similarly, *threshold2* 93 controls the number of collections of generation ``1`` before collecting 94 generation ``2``. 95 96 97 .. function:: get_count() 98 99 Return the current collection counts as a tuple of ``(count0, count1, 100 count2)``. 101 102 .. versionadded:: 2.5 103 104 105 .. function:: get_threshold() 106 107 Return the current collection thresholds as a tuple of ``(threshold0, 108 threshold1, threshold2)``. 109 110 111 .. function:: get_referrers(*objs) 112 113 Return the list of objects that directly refer to any of objs. This function 114 will only locate those containers which support garbage collection; extension 115 types which do refer to other objects but do not support garbage collection will 116 not be found. 117 118 Note that objects which have already been dereferenced, but which live in cycles 119 and have not yet been collected by the garbage collector can be listed among the 120 resulting referrers. To get only currently live objects, call :func:`collect` 121 before calling :func:`get_referrers`. 122 123 Care must be taken when using objects returned by :func:`get_referrers` because 124 some of them could still be under construction and hence in a temporarily 125 invalid state. Avoid using :func:`get_referrers` for any purpose other than 126 debugging. 127 128 .. versionadded:: 2.2 129 130 131 .. function:: get_referents(*objs) 132 133 Return a list of objects directly referred to by any of the arguments. The 134 referents returned are those objects visited by the arguments' C-level 135 :c:member:`~PyTypeObject.tp_traverse` methods (if any), and may not be all objects actually 136 directly reachable. :c:member:`~PyTypeObject.tp_traverse` methods are supported only by objects 137 that support garbage collection, and are only required to visit objects that may 138 be involved in a cycle. So, for example, if an integer is directly reachable 139 from an argument, that integer object may or may not appear in the result list. 140 141 .. versionadded:: 2.3 142 143 .. function:: is_tracked(obj) 144 145 Returns ``True`` if the object is currently tracked by the garbage collector, 146 ``False`` otherwise. As a general rule, instances of atomic types aren't 147 tracked and instances of non-atomic types (containers, user-defined 148 objects...) are. However, some type-specific optimizations can be present 149 in order to suppress the garbage collector footprint of simple instances 150 (e.g. dicts containing only atomic keys and values):: 151 152 >>> gc.is_tracked(0) 153 False 154 >>> gc.is_tracked("a") 155 False 156 >>> gc.is_tracked([]) 157 True 158 >>> gc.is_tracked({}) 159 False 160 >>> gc.is_tracked({"a": 1}) 161 False 162 >>> gc.is_tracked({"a": []}) 163 True 164 165 .. versionadded:: 2.7 166 167 168 The following variable is provided for read-only access (you can mutate its 169 value but should not rebind it): 170 171 172 .. data:: garbage 173 174 A list of objects which the collector found to be unreachable but could not be 175 freed (uncollectable objects). By default, this list contains only objects with 176 :meth:`__del__` methods. [#]_ Objects that have :meth:`__del__` methods and are 177 part of a reference cycle cause the entire reference cycle to be uncollectable, 178 including objects not necessarily in the cycle but reachable only from it. 179 Python doesn't collect such cycles automatically because, in general, it isn't 180 possible for Python to guess a safe order in which to run the :meth:`__del__` 181 methods. If you know a safe order, you can force the issue by examining the 182 *garbage* list, and explicitly breaking cycles due to your objects within the 183 list. Note that these objects are kept alive even so by virtue of being in the 184 *garbage* list, so they should be removed from *garbage* too. For example, 185 after breaking cycles, do ``del gc.garbage[:]`` to empty the list. It's 186 generally better to avoid the issue by not creating cycles containing objects 187 with :meth:`__del__` methods, and *garbage* can be examined in that case to 188 verify that no such cycles are being created. 189 190 If :const:`DEBUG_SAVEALL` is set, then all unreachable objects will be added to 191 this list rather than freed. 192 193 The following constants are provided for use with :func:`set_debug`: 194 195 196 .. data:: DEBUG_STATS 197 198 Print statistics during collection. This information can be useful when tuning 199 the collection frequency. 200 201 202 .. data:: DEBUG_COLLECTABLE 203 204 Print information on collectable objects found. 205 206 207 .. data:: DEBUG_UNCOLLECTABLE 208 209 Print information of uncollectable objects found (objects which are not 210 reachable but cannot be freed by the collector). These objects will be added to 211 the ``garbage`` list. 212 213 214 .. data:: DEBUG_INSTANCES 215 216 When :const:`DEBUG_COLLECTABLE` or :const:`DEBUG_UNCOLLECTABLE` is set, print 217 information about instance objects found. 218 219 220 .. data:: DEBUG_OBJECTS 221 222 When :const:`DEBUG_COLLECTABLE` or :const:`DEBUG_UNCOLLECTABLE` is set, print 223 information about objects other than instance objects found. 224 225 226 .. data:: DEBUG_SAVEALL 227 228 When set, all unreachable objects found will be appended to *garbage* rather 229 than being freed. This can be useful for debugging a leaking program. 230 231 232 .. data:: DEBUG_LEAK 233 234 The debugging flags necessary for the collector to print information about a 235 leaking program (equal to ``DEBUG_COLLECTABLE | DEBUG_UNCOLLECTABLE | 236 DEBUG_INSTANCES | DEBUG_OBJECTS | DEBUG_SAVEALL``). 237 238 .. rubric:: Footnotes 239 240 .. [#] Prior to Python 2.2, the list contained all instance objects in unreachable 241 cycles, not only those with :meth:`__del__` methods. 242 243
