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. |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 6 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 7 | .. moduleauthor:: Neil Schemenauer <nas@arctrix.com> |
| 8 | .. sectionauthor:: Neil Schemenauer <nas@arctrix.com> |
| 9 | |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 10 | -------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 11 | |
| 12 | This module provides an interface to the optional garbage collector. It |
| 13 | provides the ability to disable the collector, tune the collection frequency, |
| 14 | and set debugging options. It also provides access to unreachable objects that |
| 15 | the collector found but cannot free. Since the collector supplements the |
| 16 | reference counting already used in Python, you can disable the collector if you |
| 17 | are sure your program does not create reference cycles. Automatic collection |
| 18 | can be disabled by calling ``gc.disable()``. To debug a leaking program call |
| 19 | ``gc.set_debug(gc.DEBUG_LEAK)``. Notice that this includes |
| 20 | ``gc.DEBUG_SAVEALL``, causing garbage-collected objects to be saved in |
| 21 | gc.garbage for inspection. |
| 22 | |
| 23 | The :mod:`gc` module provides the following functions: |
| 24 | |
| 25 | |
| 26 | .. function:: enable() |
| 27 | |
| 28 | Enable automatic garbage collection. |
| 29 | |
| 30 | |
| 31 | .. function:: disable() |
| 32 | |
| 33 | Disable automatic garbage collection. |
| 34 | |
| 35 | |
| 36 | .. function:: isenabled() |
| 37 | |
| 38 | Returns true if automatic collection is enabled. |
| 39 | |
| 40 | |
Benjamin Peterson | bc51a8a | 2016-10-24 23:00:03 -0700 | [diff] [blame] | 41 | .. function:: collect(generation=2) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 42 | |
| 43 | With no arguments, run a full collection. The optional argument *generation* |
| 44 | may be an integer specifying which generation to collect (from 0 to 2). A |
| 45 | :exc:`ValueError` is raised if the generation number is invalid. The number of |
| 46 | unreachable objects found is returned. |
| 47 | |
Georg Brandl | c4a55fc | 2010-02-06 18:46:57 +0000 | [diff] [blame] | 48 | 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] | 49 | whenever a full collection or collection of the highest generation (2) |
| 50 | is run. Not all items in some free lists may be freed due to the |
| 51 | particular implementation, in particular :class:`float`. |
| 52 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 53 | |
| 54 | .. function:: set_debug(flags) |
| 55 | |
| 56 | Set the garbage collection debugging flags. Debugging information will be |
| 57 | written to ``sys.stderr``. See below for a list of debugging flags which can be |
| 58 | combined using bit operations to control debugging. |
| 59 | |
| 60 | |
| 61 | .. function:: get_debug() |
| 62 | |
| 63 | Return the debugging flags currently set. |
| 64 | |
| 65 | |
| 66 | .. function:: get_objects() |
| 67 | |
| 68 | Returns a list of all objects tracked by the collector, excluding the list |
| 69 | returned. |
| 70 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 71 | |
Antoine Pitrou | d4156c1 | 2012-10-30 22:43:19 +0100 | [diff] [blame] | 72 | .. function:: get_stats() |
| 73 | |
R David Murray | 0e81463 | 2013-12-26 15:11:28 -0500 | [diff] [blame] | 74 | Return a list of three per-generation dictionaries containing collection |
| 75 | statistics since interpreter start. The number of keys may change |
| 76 | in the future, but currently each dictionary will contain the following |
| 77 | items: |
Antoine Pitrou | d4156c1 | 2012-10-30 22:43:19 +0100 | [diff] [blame] | 78 | |
| 79 | * ``collections`` is the number of times this generation was collected; |
| 80 | |
| 81 | * ``collected`` is the total number of objects collected inside this |
| 82 | generation; |
| 83 | |
| 84 | * ``uncollectable`` is the total number of objects which were found |
| 85 | to be uncollectable (and were therefore moved to the :data:`garbage` |
| 86 | list) inside this generation. |
| 87 | |
| 88 | .. versionadded:: 3.4 |
| 89 | |
| 90 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 91 | .. function:: set_threshold(threshold0[, threshold1[, threshold2]]) |
| 92 | |
| 93 | Set the garbage collection thresholds (the collection frequency). Setting |
| 94 | *threshold0* to zero disables collection. |
| 95 | |
| 96 | The GC classifies objects into three generations depending on how many |
| 97 | collection sweeps they have survived. New objects are placed in the youngest |
| 98 | generation (generation ``0``). If an object survives a collection it is moved |
| 99 | into the next older generation. Since generation ``2`` is the oldest |
| 100 | generation, objects in that generation remain there after a collection. In |
| 101 | order to decide when to run, the collector keeps track of the number object |
| 102 | allocations and deallocations since the last collection. When the number of |
| 103 | allocations minus the number of deallocations exceeds *threshold0*, collection |
| 104 | starts. Initially only generation ``0`` is examined. If generation ``0`` has |
| 105 | been examined more than *threshold1* times since generation ``1`` has been |
| 106 | examined, then generation ``1`` is examined as well. Similarly, *threshold2* |
| 107 | controls the number of collections of generation ``1`` before collecting |
| 108 | generation ``2``. |
| 109 | |
| 110 | |
| 111 | .. function:: get_count() |
| 112 | |
| 113 | Return the current collection counts as a tuple of ``(count0, count1, |
| 114 | count2)``. |
| 115 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 116 | |
| 117 | .. function:: get_threshold() |
| 118 | |
| 119 | Return the current collection thresholds as a tuple of ``(threshold0, |
| 120 | threshold1, threshold2)``. |
| 121 | |
| 122 | |
| 123 | .. function:: get_referrers(*objs) |
| 124 | |
| 125 | Return the list of objects that directly refer to any of objs. This function |
| 126 | will only locate those containers which support garbage collection; extension |
| 127 | types which do refer to other objects but do not support garbage collection will |
| 128 | not be found. |
| 129 | |
| 130 | Note that objects which have already been dereferenced, but which live in cycles |
| 131 | and have not yet been collected by the garbage collector can be listed among the |
| 132 | resulting referrers. To get only currently live objects, call :func:`collect` |
| 133 | before calling :func:`get_referrers`. |
| 134 | |
| 135 | Care must be taken when using objects returned by :func:`get_referrers` because |
| 136 | some of them could still be under construction and hence in a temporarily |
| 137 | invalid state. Avoid using :func:`get_referrers` for any purpose other than |
| 138 | debugging. |
| 139 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 140 | |
| 141 | .. function:: get_referents(*objs) |
| 142 | |
| 143 | Return a list of objects directly referred to by any of the arguments. The |
| 144 | referents returned are those objects visited by the arguments' C-level |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 145 | :c:member:`~PyTypeObject.tp_traverse` methods (if any), and may not be all objects actually |
| 146 | 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] | 147 | that support garbage collection, and are only required to visit objects that may |
| 148 | be involved in a cycle. So, for example, if an integer is directly reachable |
| 149 | from an argument, that integer object may or may not appear in the result list. |
| 150 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 151 | |
Antoine Pitrou | 3a652b1 | 2009-03-23 18:52:06 +0000 | [diff] [blame] | 152 | .. function:: is_tracked(obj) |
| 153 | |
Serhiy Storchaka | fbc1c26 | 2013-11-29 12:17:13 +0200 | [diff] [blame] | 154 | Returns ``True`` if the object is currently tracked by the garbage collector, |
| 155 | ``False`` otherwise. As a general rule, instances of atomic types aren't |
Antoine Pitrou | 3a652b1 | 2009-03-23 18:52:06 +0000 | [diff] [blame] | 156 | tracked and instances of non-atomic types (containers, user-defined |
| 157 | objects...) are. However, some type-specific optimizations can be present |
| 158 | in order to suppress the garbage collector footprint of simple instances |
| 159 | (e.g. dicts containing only atomic keys and values):: |
| 160 | |
| 161 | >>> gc.is_tracked(0) |
| 162 | False |
| 163 | >>> gc.is_tracked("a") |
| 164 | False |
| 165 | >>> gc.is_tracked([]) |
| 166 | True |
| 167 | >>> gc.is_tracked({}) |
| 168 | False |
| 169 | >>> gc.is_tracked({"a": 1}) |
| 170 | False |
| 171 | >>> gc.is_tracked({"a": []}) |
| 172 | True |
| 173 | |
Georg Brandl | 705d9d5 | 2009-05-05 09:29:50 +0000 | [diff] [blame] | 174 | .. versionadded:: 3.1 |
Antoine Pitrou | 3a652b1 | 2009-03-23 18:52:06 +0000 | [diff] [blame] | 175 | |
| 176 | |
brainfvck | c75edab | 2017-10-16 12:49:41 -0700 | [diff] [blame] | 177 | .. function:: freeze() |
| 178 | |
| 179 | Freeze all the objects tracked by gc - move them to a permanent generation |
| 180 | and ignore all the future collections. This can be used before a POSIX |
| 181 | fork() call to make the gc copy-on-write friendly or to speed up collection. |
| 182 | Also collection before a POSIX fork() call may free pages for future |
| 183 | allocation which can cause copy-on-write too so it's advised to disable gc |
| 184 | in master process and freeze before fork and enable gc in child process. |
| 185 | |
| 186 | .. versionadded:: 3.7 |
| 187 | |
| 188 | |
| 189 | .. function:: unfreeze() |
| 190 | |
| 191 | Unfreeze the objects in the permanent generation, put them back into the |
| 192 | oldest generation. |
| 193 | |
| 194 | .. versionadded:: 3.7 |
| 195 | |
| 196 | |
| 197 | .. function:: get_freeze_count() |
| 198 | |
| 199 | Return the number of objects in the permanent generation. |
| 200 | |
| 201 | .. versionadded:: 3.7 |
| 202 | |
| 203 | |
Kristján Valur Jónsson | 69c6352 | 2012-04-15 11:41:32 +0000 | [diff] [blame] | 204 | The following variables are provided for read-only access (you can mutate the |
| 205 | values but should not rebind them): |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 206 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 207 | .. data:: garbage |
| 208 | |
Antoine Pitrou | 796564c | 2013-07-30 19:59:21 +0200 | [diff] [blame] | 209 | A list of objects which the collector found to be unreachable but could |
| 210 | not be freed (uncollectable objects). Starting with Python 3.4, this |
| 211 | list should be empty most of the time, except when using instances of |
| 212 | C extension types with a non-NULL ``tp_del`` slot. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 213 | |
Antoine Pitrou | 796564c | 2013-07-30 19:59:21 +0200 | [diff] [blame] | 214 | If :const:`DEBUG_SAVEALL` is set, then all unreachable objects will be |
| 215 | added to this list rather than freed. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 216 | |
Antoine Pitrou | 696e035 | 2010-08-08 22:18:46 +0000 | [diff] [blame] | 217 | .. versionchanged:: 3.2 |
Antoine Pitrou | 5db1bb8 | 2014-12-07 01:28:27 +0100 | [diff] [blame] | 218 | If this list is non-empty at :term:`interpreter shutdown`, a |
Georg Brandl | 08be72d | 2010-10-24 15:11:22 +0000 | [diff] [blame] | 219 | :exc:`ResourceWarning` is emitted, which is silent by default. If |
| 220 | :const:`DEBUG_UNCOLLECTABLE` is set, in addition all uncollectable objects |
| 221 | are printed. |
Antoine Pitrou | 696e035 | 2010-08-08 22:18:46 +0000 | [diff] [blame] | 222 | |
Antoine Pitrou | 796564c | 2013-07-30 19:59:21 +0200 | [diff] [blame] | 223 | .. versionchanged:: 3.4 |
| 224 | Following :pep:`442`, objects with a :meth:`__del__` method don't end |
| 225 | up in :attr:`gc.garbage` anymore. |
| 226 | |
Kristján Valur Jónsson | 69c6352 | 2012-04-15 11:41:32 +0000 | [diff] [blame] | 227 | .. data:: callbacks |
| 228 | |
| 229 | A list of callbacks that will be invoked by the garbage collector before and |
| 230 | after collection. The callbacks will be called with two arguments, |
Brian Curtin | c07bda0 | 2012-04-16 15:24:02 -0500 | [diff] [blame] | 231 | *phase* and *info*. |
Kristján Valur Jónsson | 69c6352 | 2012-04-15 11:41:32 +0000 | [diff] [blame] | 232 | |
Gregory P. Smith | 89bbe68 | 2012-09-30 10:36:07 -0700 | [diff] [blame] | 233 | *phase* can be one of two values: |
Kristján Valur Jónsson | 69c6352 | 2012-04-15 11:41:32 +0000 | [diff] [blame] | 234 | |
| 235 | "start": The garbage collection is about to start. |
| 236 | |
| 237 | "stop": The garbage collection has finished. |
| 238 | |
Gregory P. Smith | 89bbe68 | 2012-09-30 10:36:07 -0700 | [diff] [blame] | 239 | *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] | 240 | keys are currently defined: |
| 241 | |
| 242 | "generation": The oldest generation being collected. |
| 243 | |
Brian Curtin | c07bda0 | 2012-04-16 15:24:02 -0500 | [diff] [blame] | 244 | "collected": When *phase* is "stop", the number of objects |
Kristján Valur Jónsson | 69c6352 | 2012-04-15 11:41:32 +0000 | [diff] [blame] | 245 | successfully collected. |
| 246 | |
Gregory P. Smith | 89bbe68 | 2012-09-30 10:36:07 -0700 | [diff] [blame] | 247 | "uncollectable": When *phase* is "stop", the number of objects |
Kristján Valur Jónsson | 69c6352 | 2012-04-15 11:41:32 +0000 | [diff] [blame] | 248 | that could not be collected and were put in :data:`garbage`. |
| 249 | |
| 250 | Applications can add their own callbacks to this list. The primary |
| 251 | use cases are: |
| 252 | |
| 253 | Gathering statistics about garbage collection, such as how often |
| 254 | various generations are collected, and how long the collection |
| 255 | takes. |
| 256 | |
| 257 | Allowing applications to identify and clear their own uncollectable |
| 258 | types when they appear in :data:`garbage`. |
| 259 | |
| 260 | .. versionadded:: 3.3 |
| 261 | |
Antoine Pitrou | 696e035 | 2010-08-08 22:18:46 +0000 | [diff] [blame] | 262 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 263 | The following constants are provided for use with :func:`set_debug`: |
| 264 | |
| 265 | |
| 266 | .. data:: DEBUG_STATS |
| 267 | |
| 268 | Print statistics during collection. This information can be useful when tuning |
| 269 | the collection frequency. |
| 270 | |
| 271 | |
| 272 | .. data:: DEBUG_COLLECTABLE |
| 273 | |
| 274 | Print information on collectable objects found. |
| 275 | |
| 276 | |
| 277 | .. data:: DEBUG_UNCOLLECTABLE |
| 278 | |
| 279 | Print information of uncollectable objects found (objects which are not |
Georg Brandl | 08be72d | 2010-10-24 15:11:22 +0000 | [diff] [blame] | 280 | reachable but cannot be freed by the collector). These objects will be added |
| 281 | to the ``garbage`` list. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 282 | |
Antoine Pitrou | 696e035 | 2010-08-08 22:18:46 +0000 | [diff] [blame] | 283 | .. versionchanged:: 3.2 |
Antoine Pitrou | 5db1bb8 | 2014-12-07 01:28:27 +0100 | [diff] [blame] | 284 | Also print the contents of the :data:`garbage` list at |
| 285 | :term:`interpreter shutdown`, if it isn't empty. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 286 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 287 | .. data:: DEBUG_SAVEALL |
| 288 | |
| 289 | When set, all unreachable objects found will be appended to *garbage* rather |
| 290 | than being freed. This can be useful for debugging a leaking program. |
| 291 | |
| 292 | |
| 293 | .. data:: DEBUG_LEAK |
| 294 | |
| 295 | The debugging flags necessary for the collector to print information about a |
| 296 | leaking program (equal to ``DEBUG_COLLECTABLE | DEBUG_UNCOLLECTABLE | |
Amaury Forgeot d'Arc | ad8dcd5 | 2007-12-10 23:58:35 +0000 | [diff] [blame] | 297 | DEBUG_SAVEALL``). |