Doc/lib/libgc.tex

   1 \section{\module{gc} ---
   2          Garbage Collector interface}
   3
   4 \declaremodule{extension}{gc}
   5 \modulesynopsis{Interface to the cycle-detecting garbage collector.}
   6 \moduleauthor{Neil Schemenauer}{nas@arctrix.com}
   7 \sectionauthor{Neil Schemenauer}{nas@arctrix.com}
   8
   9 The \module{gc} module is only available if the interpreter was built
  10 with the optional cyclic garbage detector (enabled by default).  If
  11 this was not enabled, an \exception{ImportError} is raised by attempts
  12 to import this module.
  13
  14 This module provides an interface to the optional garbage collector.  It
  15 provides the ability to disable the collector, tune the collection
  16 frequency, and set debugging options.  It also provides access to
  17 unreachable objects that the collector found but cannot free.  Since the
  18 collector supplements the reference counting already used in Python, you
  19 can disable the collector if you are sure your program does not create
  20 reference cycles.  Automatic collection can be disabled by calling
  21 \code{gc.disable()}.  To debug a leaking program call
  22 \code{gc.set_debug(gc.DEBUG_LEAK)}.
  23
  24 The \module{gc} module provides the following functions:
  25
  26 \begin{funcdesc}{enable}{}
  27 Enable automatic garbage collection.
  28 \end{funcdesc}
  29
  30 \begin{funcdesc}{disable}{}
  31 Disable automatic garbage collection.
  32 \end{funcdesc}
  33
  34 \begin{funcdesc}{isenabled}{}
  35 Returns true if automatic collection is enabled.
  36 \end{funcdesc}
  37
  38 \begin{funcdesc}{collect}{}
  39 Run a full collection.  All generations are examined and the
  40 number of unreachable objects found is returned.
  41 \end{funcdesc}
  42
  43 \begin{funcdesc}{set_debug}{flags}
  44 Set the garbage collection debugging flags.
  45 Debugging information will be written to \code{sys.stderr}.  See below
  46 for a list of debugging flags which can be combined using bit
  47 operations to control debugging.
  48 \end{funcdesc}
  49
  50 \begin{funcdesc}{get_debug}{}
  51 Return the debugging flags currently set.
  52 \end{funcdesc}
  53
  54 \begin{funcdesc}{set_threshold}{threshold0\optional{,
  55                                 threshold1\optional{, threshold2}}}
  56 Set the garbage collection thresholds (the collection frequency).
  57 Setting \var{threshold0} to zero disables collection.
  58
  59 The GC classifies objects into three generations depending on how many
  60 collection sweeps they have survived.  New objects are placed in the
  61 youngest generation (generation \code{0}).  If an object survives a
  62 collection it is moved into the next older generation.  Since
  63 generation \code{2} is the oldest generation, objects in that
  64 generation remain there after a collection.  In order to decide when
  65 to run, the collector keeps track of the number object allocations and
  66 deallocations since the last collection.  When the number of
  67 allocations minus the number of deallocations exceeds
  68 \var{threshold0}, collection starts.  Initially only generation
  69 \code{0} is examined.  If generation \code{0} has been examined more
  70 than \var{threshold1} times since generation \code{1} has been
  71 examined, then generation \code{1} is examined as well.  Similarly,
  72 \var{threshold2} controls the number of collections of generation
  73 \code{1} before collecting generation \code{2}.
  74 \end{funcdesc}
  75
  76 \begin{funcdesc}{get_threshold}{}
  77 Return the current collection thresholds as a tuple of
  78 \code{(\var{threshold0}, \var{threshold1}, \var{threshold2})}.
  79 \end{funcdesc}
  80
  81 \begin{funcdesc}{get_referrers}{*objs}
  82 Return the list of objects that directly refer to any of objs. This
  83 function will only locate those containers which support garbage
  84 collection; extension types which do refer to other objects but do not
  85 support garbage collection will not be found.
  86
  87 Note that objects which have already been dereferenced, but which live
  88 in cycles and have not yet been collected by the garbage collector can
  89 be listed among the resulting referrers.  To get only currently live
  90 objects, call \function{collect()} before calling
  91 \function{get_referrers()}.
  92
  93 \versionadded{2.2}
  94 \end{funcdesc}
  95
  96 The following variable is provided for read-only access (you can
  97 mutate its value but should not rebind it):
  98
  99 \begin{datadesc}{garbage}
 100 A list of objects which the collector found to be unreachable
 101 but could not be freed (uncollectable objects).  By default, this list
 102 contains only objects with \method{__del__()} methods.\footnote{Prior to
 103   Python 2.2, the list contained all instance objects in unreachable
 104   cycles,  not only those with \method{__del__()} methods.}
 105 Objects that have
 106 \method{__del__()} methods and are part of a reference cycle cause
 107 the entire reference cycle to be uncollectable, including objects
 108 not necessarily in the cycle but reachable only from it.  Python doesn't
 109 collect such cycles automatically because, in general, it isn't possible
 110 for Python to guess a safe order in which to run the \method{__del__()}
 111 methods.  If you know a safe order, you can force the issue by examining
 112 the \var{garbage} list, and explicitly breaking cycles due to your
 113 objects within the list.  Note that these objects are kept alive even
 114 so by virtue of being in the \var{garbage} list, so they should be
 115 removed from \var{garbage} too.  For example, after breaking cycles, do
 116 \code{del gc.garbage[:]} to empty the list.  It's generally better
 117 to avoid the issue by not creating cycles containing objects with
 118 \method{__del__()} methods, and \var{garbage} can be examined in that
 119 case to verify that no such cycles are being created.
 120
 121 If \constant{DEBUG_SAVEALL} is set, then all unreachable objects will
 122 be added to this list rather than freed.
 123 \end{datadesc}
 124
 125
 126 The following constants are provided for use with
 127 \function{set_debug()}:
 128
 129 \begin{datadesc}{DEBUG_STATS}
 130 Print statistics during collection.  This information can
 131 be useful when tuning the collection frequency.
 132 \end{datadesc}
 133
 134 \begin{datadesc}{DEBUG_COLLECTABLE}
 135 Print information on collectable objects found.
 136 \end{datadesc}
 137
 138 \begin{datadesc}{DEBUG_UNCOLLECTABLE}
 139 Print information of uncollectable objects found (objects which are
 140 not reachable but cannot be freed by the collector).  These objects
 141 will be added to the \code{garbage} list.
 142 \end{datadesc}
 143
 144 \begin{datadesc}{DEBUG_INSTANCES}
 145 When \constant{DEBUG_COLLECTABLE} or \constant{DEBUG_UNCOLLECTABLE} is
 146 set, print information about instance objects found.
 147 \end{datadesc}
 148
 149 \begin{datadesc}{DEBUG_OBJECTS}
 150 When \constant{DEBUG_COLLECTABLE} or \constant{DEBUG_UNCOLLECTABLE} is
 151 set, print information about objects other than instance objects found.
 152 \end{datadesc}
 153
 154 \begin{datadesc}{DEBUG_SAVEALL}
 155 When set, all unreachable objects found will be appended to
 156 \var{garbage} rather than being freed.  This can be useful for debugging
 157 a leaking program.
 158 \end{datadesc}
 159
 160 \begin{datadesc}{DEBUG_LEAK}
 161 The debugging flags necessary for the collector to print
 162 information about a leaking program (equal to \code{DEBUG_COLLECTABLE |
 163 DEBUG_UNCOLLECTABLE | DEBUG_INSTANCES | DEBUG_OBJECTS | DEBUG_SAVEALL}).
 164 \end{datadesc}