2 :mod:`gc` --- Garbage Collector interface
3 =========================================
6 :synopsis: Interface to the cycle-detecting garbage collector.
7 .. moduleauthor:: Neil Schemenauer <nas@arctrix.com>
8 .. sectionauthor:: Neil Schemenauer <nas@arctrix.com>
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.
22 The :mod:`gc` module provides the following functions:
25 .. function:: enable()
27 Enable automatic garbage collection.
30 .. function:: disable()
32 Disable automatic garbage collection.
35 .. function:: isenabled()
37 Returns true if automatic collection is enabled.
40 .. function:: collect([generation])
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.
47 .. versionchanged:: 2.5
48 The optional *generation* argument was added.
51 .. function:: set_debug(flags)
53 Set the garbage collection debugging flags. Debugging information will be
54 written to ``sys.stderr``. See below for a list of debugging flags which can be
55 combined using bit operations to control debugging.
58 .. function:: get_debug()
60 Return the debugging flags currently set.
63 .. function:: get_objects()
65 Returns a list of all objects tracked by the collector, excluding the list
71 .. function:: set_threshold(threshold0[, threshold1[, threshold2]])
73 Set the garbage collection thresholds (the collection frequency). Setting
74 *threshold0* to zero disables collection.
76 The GC classifies objects into three generations depending on how many
77 collection sweeps they have survived. New objects are placed in the youngest
78 generation (generation ``0``). If an object survives a collection it is moved
79 into the next older generation. Since generation ``2`` is the oldest
80 generation, objects in that generation remain there after a collection. In
81 order to decide when to run, the collector keeps track of the number object
82 allocations and deallocations since the last collection. When the number of
83 allocations minus the number of deallocations exceeds *threshold0*, collection
84 starts. Initially only generation ``0`` is examined. If generation ``0`` has
85 been examined more than *threshold1* times since generation ``1`` has been
86 examined, then generation ``1`` is examined as well. Similarly, *threshold2*
87 controls the number of collections of generation ``1`` before collecting
91 .. function:: get_count()
93 Return the current collection counts as a tuple of ``(count0, count1,
99 .. function:: get_threshold()
101 Return the current collection thresholds as a tuple of ``(threshold0,
102 threshold1, threshold2)``.
105 .. function:: get_referrers(*objs)
107 Return the list of objects that directly refer to any of objs. This function
108 will only locate those containers which support garbage collection; extension
109 types which do refer to other objects but do not support garbage collection will
112 Note that objects which have already been dereferenced, but which live in cycles
113 and have not yet been collected by the garbage collector can be listed among the
114 resulting referrers. To get only currently live objects, call :func:`collect`
115 before calling :func:`get_referrers`.
117 Care must be taken when using objects returned by :func:`get_referrers` because
118 some of them could still be under construction and hence in a temporarily
119 invalid state. Avoid using :func:`get_referrers` for any purpose other than
122 .. versionadded:: 2.2
125 .. function:: get_referents(*objs)
127 Return a list of objects directly referred to by any of the arguments. The
128 referents returned are those objects visited by the arguments' C-level
129 :attr:`tp_traverse` methods (if any), and may not be all objects actually
130 directly reachable. :attr:`tp_traverse` methods are supported only by objects
131 that support garbage collection, and are only required to visit objects that may
132 be involved in a cycle. So, for example, if an integer is directly reachable
133 from an argument, that integer object may or may not appear in the result list.
135 .. versionadded:: 2.3
137 The following variable is provided for read-only access (you can mutate its
138 value but should not rebind it):
143 A list of objects which the collector found to be unreachable but could not be
144 freed (uncollectable objects). By default, this list contains only objects with
145 :meth:`__del__` methods. [#]_ Objects that have :meth:`__del__` methods and are
146 part of a reference cycle cause the entire reference cycle to be uncollectable,
147 including objects not necessarily in the cycle but reachable only from it.
148 Python doesn't collect such cycles automatically because, in general, it isn't
149 possible for Python to guess a safe order in which to run the :meth:`__del__`
150 methods. If you know a safe order, you can force the issue by examining the
151 *garbage* list, and explicitly breaking cycles due to your objects within the
152 list. Note that these objects are kept alive even so by virtue of being in the
153 *garbage* list, so they should be removed from *garbage* too. For example,
154 after breaking cycles, do ``del gc.garbage[:]`` to empty the list. It's
155 generally better to avoid the issue by not creating cycles containing objects
156 with :meth:`__del__` methods, and *garbage* can be examined in that case to
157 verify that no such cycles are being created.
159 If :const:`DEBUG_SAVEALL` is set, then all unreachable objects will be added to
160 this list rather than freed.
162 The following constants are provided for use with :func:`set_debug`:
165 .. data:: DEBUG_STATS
167 Print statistics during collection. This information can be useful when tuning
168 the collection frequency.
171 .. data:: DEBUG_COLLECTABLE
173 Print information on collectable objects found.
176 .. data:: DEBUG_UNCOLLECTABLE
178 Print information of uncollectable objects found (objects which are not
179 reachable but cannot be freed by the collector). These objects will be added to
180 the ``garbage`` list.
183 .. data:: DEBUG_INSTANCES
185 When :const:`DEBUG_COLLECTABLE` or :const:`DEBUG_UNCOLLECTABLE` is set, print
186 information about instance objects found.
189 .. data:: DEBUG_OBJECTS
191 When :const:`DEBUG_COLLECTABLE` or :const:`DEBUG_UNCOLLECTABLE` is set, print
192 information about objects other than instance objects found.
195 .. data:: DEBUG_SAVEALL
197 When set, all unreachable objects found will be appended to *garbage* rather
198 than being freed. This can be useful for debugging a leaking program.
203 The debugging flags necessary for the collector to print information about a
204 leaking program (equal to ``DEBUG_COLLECTABLE | DEBUG_UNCOLLECTABLE |
205 DEBUG_INSTANCES | DEBUG_OBJECTS | DEBUG_SAVEALL``).
207 .. rubric:: Footnotes
209 .. [#] Prior to Python 2.2, the list contained all instance objects in unreachable
210 cycles, not only those with :meth:`__del__` methods.