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