Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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@arctrix.com> |
| 8 | .. sectionauthor:: Neil Schemenauer <nas@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 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 47 | |
| 48 | .. function:: set_debug(flags) |
| 49 | |
| 50 | Set the garbage collection debugging flags. Debugging information will be |
| 51 | written to ``sys.stderr``. See below for a list of debugging flags which can be |
| 52 | combined using bit operations to control debugging. |
| 53 | |
| 54 | |
| 55 | .. function:: get_debug() |
| 56 | |
| 57 | Return the debugging flags currently set. |
| 58 | |
| 59 | |
| 60 | .. function:: get_objects() |
| 61 | |
| 62 | Returns a list of all objects tracked by the collector, excluding the list |
| 63 | returned. |
| 64 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 65 | |
| 66 | .. function:: set_threshold(threshold0[, threshold1[, threshold2]]) |
| 67 | |
| 68 | Set the garbage collection thresholds (the collection frequency). Setting |
| 69 | *threshold0* to zero disables collection. |
| 70 | |
| 71 | The GC classifies objects into three generations depending on how many |
| 72 | collection sweeps they have survived. New objects are placed in the youngest |
| 73 | generation (generation ``0``). If an object survives a collection it is moved |
| 74 | into the next older generation. Since generation ``2`` is the oldest |
| 75 | generation, objects in that generation remain there after a collection. In |
| 76 | order to decide when to run, the collector keeps track of the number object |
| 77 | allocations and deallocations since the last collection. When the number of |
| 78 | allocations minus the number of deallocations exceeds *threshold0*, collection |
| 79 | starts. Initially only generation ``0`` is examined. If generation ``0`` has |
| 80 | been examined more than *threshold1* times since generation ``1`` has been |
| 81 | examined, then generation ``1`` is examined as well. Similarly, *threshold2* |
| 82 | controls the number of collections of generation ``1`` before collecting |
| 83 | generation ``2``. |
| 84 | |
| 85 | |
| 86 | .. function:: get_count() |
| 87 | |
| 88 | Return the current collection counts as a tuple of ``(count0, count1, |
| 89 | count2)``. |
| 90 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 91 | |
| 92 | .. function:: get_threshold() |
| 93 | |
| 94 | Return the current collection thresholds as a tuple of ``(threshold0, |
| 95 | threshold1, threshold2)``. |
| 96 | |
| 97 | |
| 98 | .. function:: get_referrers(*objs) |
| 99 | |
| 100 | Return the list of objects that directly refer to any of objs. This function |
| 101 | will only locate those containers which support garbage collection; extension |
| 102 | types which do refer to other objects but do not support garbage collection will |
| 103 | not be found. |
| 104 | |
| 105 | Note that objects which have already been dereferenced, but which live in cycles |
| 106 | and have not yet been collected by the garbage collector can be listed among the |
| 107 | resulting referrers. To get only currently live objects, call :func:`collect` |
| 108 | before calling :func:`get_referrers`. |
| 109 | |
| 110 | Care must be taken when using objects returned by :func:`get_referrers` because |
| 111 | some of them could still be under construction and hence in a temporarily |
| 112 | invalid state. Avoid using :func:`get_referrers` for any purpose other than |
| 113 | debugging. |
| 114 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 115 | |
| 116 | .. function:: get_referents(*objs) |
| 117 | |
| 118 | Return a list of objects directly referred to by any of the arguments. The |
| 119 | referents returned are those objects visited by the arguments' C-level |
| 120 | :attr:`tp_traverse` methods (if any), and may not be all objects actually |
| 121 | directly reachable. :attr:`tp_traverse` methods are supported only by objects |
| 122 | that support garbage collection, and are only required to visit objects that may |
| 123 | be involved in a cycle. So, for example, if an integer is directly reachable |
| 124 | from an argument, that integer object may or may not appear in the result list. |
| 125 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 126 | |
| 127 | The following variable is provided for read-only access (you can mutate its |
| 128 | value but should not rebind it): |
| 129 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 130 | .. data:: garbage |
| 131 | |
| 132 | A list of objects which the collector found to be unreachable but could not be |
| 133 | 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^] | 134 | :meth:`__del__` methods. Objects that have :meth:`__del__` methods and are |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 135 | part of a reference cycle cause the entire reference cycle to be uncollectable, |
| 136 | including objects not necessarily in the cycle but reachable only from it. |
| 137 | Python doesn't collect such cycles automatically because, in general, it isn't |
| 138 | possible for Python to guess a safe order in which to run the :meth:`__del__` |
| 139 | methods. If you know a safe order, you can force the issue by examining the |
| 140 | *garbage* list, and explicitly breaking cycles due to your objects within the |
| 141 | list. Note that these objects are kept alive even so by virtue of being in the |
| 142 | *garbage* list, so they should be removed from *garbage* too. For example, |
| 143 | after breaking cycles, do ``del gc.garbage[:]`` to empty the list. It's |
| 144 | generally better to avoid the issue by not creating cycles containing objects |
| 145 | with :meth:`__del__` methods, and *garbage* can be examined in that case to |
| 146 | verify that no such cycles are being created. |
| 147 | |
| 148 | If :const:`DEBUG_SAVEALL` is set, then all unreachable objects will be added to |
| 149 | this list rather than freed. |
| 150 | |
| 151 | The following constants are provided for use with :func:`set_debug`: |
| 152 | |
| 153 | |
| 154 | .. data:: DEBUG_STATS |
| 155 | |
| 156 | Print statistics during collection. This information can be useful when tuning |
| 157 | the collection frequency. |
| 158 | |
| 159 | |
| 160 | .. data:: DEBUG_COLLECTABLE |
| 161 | |
| 162 | Print information on collectable objects found. |
| 163 | |
| 164 | |
| 165 | .. data:: DEBUG_UNCOLLECTABLE |
| 166 | |
| 167 | Print information of uncollectable objects found (objects which are not |
| 168 | reachable but cannot be freed by the collector). These objects will be added to |
| 169 | the ``garbage`` list. |
| 170 | |
| 171 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 172 | .. data:: DEBUG_SAVEALL |
| 173 | |
| 174 | When set, all unreachable objects found will be appended to *garbage* rather |
| 175 | than being freed. This can be useful for debugging a leaking program. |
| 176 | |
| 177 | |
| 178 | .. data:: DEBUG_LEAK |
| 179 | |
| 180 | The debugging flags necessary for the collector to print information about a |
| 181 | leaking program (equal to ``DEBUG_COLLECTABLE | DEBUG_UNCOLLECTABLE | |
Amaury Forgeot d'Arc | ad8dcd5 | 2007-12-10 23:58:35 +0000 | [diff] [blame^] | 182 | DEBUG_SAVEALL``). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 183 | |
| 184 | .. rubric:: Footnotes |