← Back to branch summary

~malept/ubuntu/lucid/python2.6/dev-dependency-fix

« back to all changes in this revision

Viewing changes to Doc/library/gc.rst

  • Committer: Bazaar Package Importer
  • Author(s): Matthias Klose
  • Date: 2009-02-13 12:51:00 UTC
  • Revision ID: james.westby@ubuntu.com-20090213125100-uufgcb9yeqzujpqw
Tags: upstream-2.6.1
Import upstream version 2.6.1

Show diffs side-by-side

added added

removed removed

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