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 | |
Antoine Pitrou | d4156c1 | 2012-10-30 22:43:19 +0100 | [diff] [blame] | 70 | .. function:: get_stats() |
| 71 | |
R David Murray | 0e81463 | 2013-12-26 15:11:28 -0500 | [diff] [blame] | 72 | Return a list of three per-generation dictionaries containing collection |
| 73 | statistics since interpreter start. The number of keys may change |
| 74 | in the future, but currently each dictionary will contain the following |
| 75 | items: |
Antoine Pitrou | d4156c1 | 2012-10-30 22:43:19 +0100 | [diff] [blame] | 76 | |
| 77 | * ``collections`` is the number of times this generation was collected; |
| 78 | |
| 79 | * ``collected`` is the total number of objects collected inside this |
| 80 | generation; |
| 81 | |
| 82 | * ``uncollectable`` is the total number of objects which were found |
| 83 | to be uncollectable (and were therefore moved to the :data:`garbage` |
| 84 | list) inside this generation. |
| 85 | |
| 86 | .. versionadded:: 3.4 |
| 87 | |
| 88 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 89 | .. function:: set_threshold(threshold0[, threshold1[, threshold2]]) |
| 90 | |
| 91 | Set the garbage collection thresholds (the collection frequency). Setting |
| 92 | *threshold0* to zero disables collection. |
| 93 | |
| 94 | The GC classifies objects into three generations depending on how many |
| 95 | collection sweeps they have survived. New objects are placed in the youngest |
| 96 | generation (generation ``0``). If an object survives a collection it is moved |
| 97 | into the next older generation. Since generation ``2`` is the oldest |
| 98 | generation, objects in that generation remain there after a collection. In |
| 99 | order to decide when to run, the collector keeps track of the number object |
| 100 | allocations and deallocations since the last collection. When the number of |
| 101 | allocations minus the number of deallocations exceeds *threshold0*, collection |
| 102 | starts. Initially only generation ``0`` is examined. If generation ``0`` has |
| 103 | been examined more than *threshold1* times since generation ``1`` has been |
| 104 | examined, then generation ``1`` is examined as well. Similarly, *threshold2* |
| 105 | controls the number of collections of generation ``1`` before collecting |
| 106 | generation ``2``. |
| 107 | |
| 108 | |
| 109 | .. function:: get_count() |
| 110 | |
| 111 | Return the current collection counts as a tuple of ``(count0, count1, |
| 112 | count2)``. |
| 113 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 114 | |
| 115 | .. function:: get_threshold() |
| 116 | |
| 117 | Return the current collection thresholds as a tuple of ``(threshold0, |
| 118 | threshold1, threshold2)``. |
| 119 | |
| 120 | |
| 121 | .. function:: get_referrers(*objs) |
| 122 | |
| 123 | Return the list of objects that directly refer to any of objs. This function |
| 124 | will only locate those containers which support garbage collection; extension |
| 125 | types which do refer to other objects but do not support garbage collection will |
| 126 | not be found. |
| 127 | |
| 128 | Note that objects which have already been dereferenced, but which live in cycles |
| 129 | and have not yet been collected by the garbage collector can be listed among the |
| 130 | resulting referrers. To get only currently live objects, call :func:`collect` |
| 131 | before calling :func:`get_referrers`. |
| 132 | |
| 133 | Care must be taken when using objects returned by :func:`get_referrers` because |
| 134 | some of them could still be under construction and hence in a temporarily |
| 135 | invalid state. Avoid using :func:`get_referrers` for any purpose other than |
| 136 | debugging. |
| 137 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 138 | |
| 139 | .. function:: get_referents(*objs) |
| 140 | |
| 141 | Return a list of objects directly referred to by any of the arguments. The |
| 142 | referents returned are those objects visited by the arguments' C-level |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 143 | :c:member:`~PyTypeObject.tp_traverse` methods (if any), and may not be all objects actually |
| 144 | directly reachable. :c:member:`~PyTypeObject.tp_traverse` methods are supported only by objects |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 145 | that support garbage collection, and are only required to visit objects that may |
| 146 | be involved in a cycle. So, for example, if an integer is directly reachable |
| 147 | from an argument, that integer object may or may not appear in the result list. |
| 148 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 149 | |
Antoine Pitrou | 3a652b1 | 2009-03-23 18:52:06 +0000 | [diff] [blame] | 150 | .. function:: is_tracked(obj) |
| 151 | |
Serhiy Storchaka | fbc1c26 | 2013-11-29 12:17:13 +0200 | [diff] [blame] | 152 | Returns ``True`` if the object is currently tracked by the garbage collector, |
| 153 | ``False`` otherwise. As a general rule, instances of atomic types aren't |
Antoine Pitrou | 3a652b1 | 2009-03-23 18:52:06 +0000 | [diff] [blame] | 154 | tracked and instances of non-atomic types (containers, user-defined |
| 155 | objects...) are. However, some type-specific optimizations can be present |
| 156 | in order to suppress the garbage collector footprint of simple instances |
| 157 | (e.g. dicts containing only atomic keys and values):: |
| 158 | |
| 159 | >>> gc.is_tracked(0) |
| 160 | False |
| 161 | >>> gc.is_tracked("a") |
| 162 | False |
| 163 | >>> gc.is_tracked([]) |
| 164 | True |
| 165 | >>> gc.is_tracked({}) |
| 166 | False |
| 167 | >>> gc.is_tracked({"a": 1}) |
| 168 | False |
| 169 | >>> gc.is_tracked({"a": []}) |
| 170 | True |
| 171 | |
Georg Brandl | 705d9d5 | 2009-05-05 09:29:50 +0000 | [diff] [blame] | 172 | .. versionadded:: 3.1 |
Antoine Pitrou | 3a652b1 | 2009-03-23 18:52:06 +0000 | [diff] [blame] | 173 | |
| 174 | |
Kristján Valur Jónsson | 69c6352 | 2012-04-15 11:41:32 +0000 | [diff] [blame] | 175 | The following variables are provided for read-only access (you can mutate the |
| 176 | values but should not rebind them): |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 177 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 178 | .. data:: garbage |
| 179 | |
Antoine Pitrou | 796564c | 2013-07-30 19:59:21 +0200 | [diff] [blame] | 180 | A list of objects which the collector found to be unreachable but could |
| 181 | not be freed (uncollectable objects). Starting with Python 3.4, this |
| 182 | list should be empty most of the time, except when using instances of |
| 183 | C extension types with a non-NULL ``tp_del`` slot. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 184 | |
Antoine Pitrou | 796564c | 2013-07-30 19:59:21 +0200 | [diff] [blame] | 185 | If :const:`DEBUG_SAVEALL` is set, then all unreachable objects will be |
| 186 | added to this list rather than freed. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 187 | |
Antoine Pitrou | 696e035 | 2010-08-08 22:18:46 +0000 | [diff] [blame] | 188 | .. versionchanged:: 3.2 |
Antoine Pitrou | 5db1bb8 | 2014-12-07 01:28:27 +0100 | [diff] [blame^] | 189 | If this list is non-empty at :term:`interpreter shutdown`, a |
Georg Brandl | 08be72d | 2010-10-24 15:11:22 +0000 | [diff] [blame] | 190 | :exc:`ResourceWarning` is emitted, which is silent by default. If |
| 191 | :const:`DEBUG_UNCOLLECTABLE` is set, in addition all uncollectable objects |
| 192 | are printed. |
Antoine Pitrou | 696e035 | 2010-08-08 22:18:46 +0000 | [diff] [blame] | 193 | |
Antoine Pitrou | 796564c | 2013-07-30 19:59:21 +0200 | [diff] [blame] | 194 | .. versionchanged:: 3.4 |
| 195 | Following :pep:`442`, objects with a :meth:`__del__` method don't end |
| 196 | up in :attr:`gc.garbage` anymore. |
| 197 | |
Kristján Valur Jónsson | 69c6352 | 2012-04-15 11:41:32 +0000 | [diff] [blame] | 198 | .. data:: callbacks |
| 199 | |
| 200 | A list of callbacks that will be invoked by the garbage collector before and |
| 201 | after collection. The callbacks will be called with two arguments, |
Brian Curtin | c07bda0 | 2012-04-16 15:24:02 -0500 | [diff] [blame] | 202 | *phase* and *info*. |
Kristján Valur Jónsson | 69c6352 | 2012-04-15 11:41:32 +0000 | [diff] [blame] | 203 | |
Gregory P. Smith | 89bbe68 | 2012-09-30 10:36:07 -0700 | [diff] [blame] | 204 | *phase* can be one of two values: |
Kristján Valur Jónsson | 69c6352 | 2012-04-15 11:41:32 +0000 | [diff] [blame] | 205 | |
| 206 | "start": The garbage collection is about to start. |
| 207 | |
| 208 | "stop": The garbage collection has finished. |
| 209 | |
Gregory P. Smith | 89bbe68 | 2012-09-30 10:36:07 -0700 | [diff] [blame] | 210 | *info* is a dict providing more information for the callback. The following |
Kristján Valur Jónsson | 69c6352 | 2012-04-15 11:41:32 +0000 | [diff] [blame] | 211 | keys are currently defined: |
| 212 | |
| 213 | "generation": The oldest generation being collected. |
| 214 | |
Brian Curtin | c07bda0 | 2012-04-16 15:24:02 -0500 | [diff] [blame] | 215 | "collected": When *phase* is "stop", the number of objects |
Kristján Valur Jónsson | 69c6352 | 2012-04-15 11:41:32 +0000 | [diff] [blame] | 216 | successfully collected. |
| 217 | |
Gregory P. Smith | 89bbe68 | 2012-09-30 10:36:07 -0700 | [diff] [blame] | 218 | "uncollectable": When *phase* is "stop", the number of objects |
Kristján Valur Jónsson | 69c6352 | 2012-04-15 11:41:32 +0000 | [diff] [blame] | 219 | that could not be collected and were put in :data:`garbage`. |
| 220 | |
| 221 | Applications can add their own callbacks to this list. The primary |
| 222 | use cases are: |
| 223 | |
| 224 | Gathering statistics about garbage collection, such as how often |
| 225 | various generations are collected, and how long the collection |
| 226 | takes. |
| 227 | |
| 228 | Allowing applications to identify and clear their own uncollectable |
| 229 | types when they appear in :data:`garbage`. |
| 230 | |
| 231 | .. versionadded:: 3.3 |
| 232 | |
Antoine Pitrou | 696e035 | 2010-08-08 22:18:46 +0000 | [diff] [blame] | 233 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 234 | The following constants are provided for use with :func:`set_debug`: |
| 235 | |
| 236 | |
| 237 | .. data:: DEBUG_STATS |
| 238 | |
| 239 | Print statistics during collection. This information can be useful when tuning |
| 240 | the collection frequency. |
| 241 | |
| 242 | |
| 243 | .. data:: DEBUG_COLLECTABLE |
| 244 | |
| 245 | Print information on collectable objects found. |
| 246 | |
| 247 | |
| 248 | .. data:: DEBUG_UNCOLLECTABLE |
| 249 | |
| 250 | Print information of uncollectable objects found (objects which are not |
Georg Brandl | 08be72d | 2010-10-24 15:11:22 +0000 | [diff] [blame] | 251 | reachable but cannot be freed by the collector). These objects will be added |
| 252 | to the ``garbage`` list. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 253 | |
Antoine Pitrou | 696e035 | 2010-08-08 22:18:46 +0000 | [diff] [blame] | 254 | .. versionchanged:: 3.2 |
Antoine Pitrou | 5db1bb8 | 2014-12-07 01:28:27 +0100 | [diff] [blame^] | 255 | Also print the contents of the :data:`garbage` list at |
| 256 | :term:`interpreter shutdown`, if it isn't empty. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 257 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 258 | .. data:: DEBUG_SAVEALL |
| 259 | |
| 260 | When set, all unreachable objects found will be appended to *garbage* rather |
| 261 | than being freed. This can be useful for debugging a leaking program. |
| 262 | |
| 263 | |
| 264 | .. data:: DEBUG_LEAK |
| 265 | |
| 266 | The debugging flags necessary for the collector to print information about a |
| 267 | leaking program (equal to ``DEBUG_COLLECTABLE | DEBUG_UNCOLLECTABLE | |
Amaury Forgeot d'Arc | ad8dcd5 | 2007-12-10 23:58:35 +0000 | [diff] [blame] | 268 | DEBUG_SAVEALL``). |