197 lines
8.0 KiB
TeX
197 lines
8.0 KiB
TeX
\section{\module{gc} ---
|
|
Garbage Collector interface}
|
|
|
|
\declaremodule{extension}{gc}
|
|
\modulesynopsis{Interface to the cycle-detecting garbage collector.}
|
|
\moduleauthor{Neil Schemenauer}{nas@arctrix.com}
|
|
\sectionauthor{Neil Schemenauer}{nas@arctrix.com}
|
|
|
|
This module provides an interface to the optional garbage collector. It
|
|
provides the ability to disable the collector, tune the collection
|
|
frequency, and set debugging options. It also provides access to
|
|
unreachable objects that the collector found but cannot free. Since the
|
|
collector supplements the reference counting already used in Python, you
|
|
can disable the collector if you are sure your program does not create
|
|
reference cycles. Automatic collection can be disabled by calling
|
|
\code{gc.disable()}. To debug a leaking program call
|
|
\code{gc.set_debug(gc.DEBUG_LEAK)}. Notice that this includes
|
|
\code{gc.DEBUG_SAVEALL}, causing garbage-collected objects to be
|
|
saved in gc.garbage for inspection.
|
|
|
|
The \module{gc} module provides the following functions:
|
|
|
|
\begin{funcdesc}{enable}{}
|
|
Enable automatic garbage collection.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{disable}{}
|
|
Disable automatic garbage collection.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{isenabled}{}
|
|
Returns true if automatic collection is enabled.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{collect}{\optional{generation}}
|
|
With no arguments, run a full collection. The optional argument
|
|
\var{generation} may be an integer specifying which generation to collect
|
|
(from 0 to 2). A \exception{ValueError} is raised if the generation number
|
|
is invalid.
|
|
The number of unreachable objects found is returned.
|
|
|
|
\versionchanged[The optional \var{generation} argument was added]{2.5}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{set_debug}{flags}
|
|
Set the garbage collection debugging flags.
|
|
Debugging information will be written to \code{sys.stderr}. See below
|
|
for a list of debugging flags which can be combined using bit
|
|
operations to control debugging.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{get_debug}{}
|
|
Return the debugging flags currently set.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{get_objects}{}
|
|
Returns a list of all objects tracked by the collector, excluding the
|
|
list returned.
|
|
\versionadded{2.2}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{set_threshold}{threshold0\optional{,
|
|
threshold1\optional{, threshold2}}}
|
|
Set the garbage collection thresholds (the collection frequency).
|
|
Setting \var{threshold0} to zero disables collection.
|
|
|
|
The GC classifies objects into three generations depending on how many
|
|
collection sweeps they have survived. New objects are placed in the
|
|
youngest generation (generation \code{0}). If an object survives a
|
|
collection it is moved into the next older generation. Since
|
|
generation \code{2} is the oldest generation, objects in that
|
|
generation remain there after a collection. In order to decide when
|
|
to run, the collector keeps track of the number object allocations and
|
|
deallocations since the last collection. When the number of
|
|
allocations minus the number of deallocations exceeds
|
|
\var{threshold0}, collection starts. Initially only generation
|
|
\code{0} is examined. If generation \code{0} has been examined more
|
|
than \var{threshold1} times since generation \code{1} has been
|
|
examined, then generation \code{1} is examined as well. Similarly,
|
|
\var{threshold2} controls the number of collections of generation
|
|
\code{1} before collecting generation \code{2}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{get_count}{}
|
|
Return the current collection counts as a tuple of
|
|
\code{(\var{count0}, \var{count1}, \var{count2})}.
|
|
\versionadded{2.5}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{get_threshold}{}
|
|
Return the current collection thresholds as a tuple of
|
|
\code{(\var{threshold0}, \var{threshold1}, \var{threshold2})}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{get_referrers}{*objs}
|
|
Return the list of objects that directly refer to any of objs. This
|
|
function will only locate those containers which support garbage
|
|
collection; extension types which do refer to other objects but do not
|
|
support garbage collection will not be found.
|
|
|
|
Note that objects which have already been dereferenced, but which live
|
|
in cycles and have not yet been collected by the garbage collector can
|
|
be listed among the resulting referrers. To get only currently live
|
|
objects, call \function{collect()} before calling
|
|
\function{get_referrers()}.
|
|
|
|
Care must be taken when using objects returned by
|
|
\function{get_referrers()} because some of them could still be under
|
|
construction and hence in a temporarily invalid state. Avoid using
|
|
\function{get_referrers()} for any purpose other than debugging.
|
|
|
|
\versionadded{2.2}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{get_referents}{*objs}
|
|
Return a list of objects directly referred to by any of the arguments.
|
|
The referents returned are those objects visited by the arguments'
|
|
C-level \member{tp_traverse} methods (if any), and may not be all
|
|
objects actually directly reachable. \member{tp_traverse} methods
|
|
are supported only by objects that support garbage collection, and are
|
|
only required to visit objects that may be involved in a cycle. So,
|
|
for example, if an integer is directly reachable from an argument, that
|
|
integer object may or may not appear in the result list.
|
|
|
|
\versionadded{2.3}
|
|
\end{funcdesc}
|
|
|
|
The following variable is provided for read-only access (you can
|
|
mutate its value but should not rebind it):
|
|
|
|
\begin{datadesc}{garbage}
|
|
A list of objects which the collector found to be unreachable
|
|
but could not be freed (uncollectable objects). By default, this list
|
|
contains only objects with \method{__del__()} methods.\footnote{Prior to
|
|
Python 2.2, the list contained all instance objects in unreachable
|
|
cycles, not only those with \method{__del__()} methods.}
|
|
Objects that have
|
|
\method{__del__()} methods and are part of a reference cycle cause
|
|
the entire reference cycle to be uncollectable, including objects
|
|
not necessarily in the cycle but reachable only from it. Python doesn't
|
|
collect such cycles automatically because, in general, it isn't possible
|
|
for Python to guess a safe order in which to run the \method{__del__()}
|
|
methods. If you know a safe order, you can force the issue by examining
|
|
the \var{garbage} list, and explicitly breaking cycles due to your
|
|
objects within the list. Note that these objects are kept alive even
|
|
so by virtue of being in the \var{garbage} list, so they should be
|
|
removed from \var{garbage} too. For example, after breaking cycles, do
|
|
\code{del gc.garbage[:]} to empty the list. It's generally better
|
|
to avoid the issue by not creating cycles containing objects with
|
|
\method{__del__()} methods, and \var{garbage} can be examined in that
|
|
case to verify that no such cycles are being created.
|
|
|
|
If \constant{DEBUG_SAVEALL} is set, then all unreachable objects will
|
|
be added to this list rather than freed.
|
|
\end{datadesc}
|
|
|
|
|
|
The following constants are provided for use with
|
|
\function{set_debug()}:
|
|
|
|
\begin{datadesc}{DEBUG_STATS}
|
|
Print statistics during collection. This information can
|
|
be useful when tuning the collection frequency.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{DEBUG_COLLECTABLE}
|
|
Print information on collectable objects found.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{DEBUG_UNCOLLECTABLE}
|
|
Print information of uncollectable objects found (objects which are
|
|
not reachable but cannot be freed by the collector). These objects
|
|
will be added to the \code{garbage} list.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{DEBUG_INSTANCES}
|
|
When \constant{DEBUG_COLLECTABLE} or \constant{DEBUG_UNCOLLECTABLE} is
|
|
set, print information about instance objects found.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{DEBUG_OBJECTS}
|
|
When \constant{DEBUG_COLLECTABLE} or \constant{DEBUG_UNCOLLECTABLE} is
|
|
set, print information about objects other than instance objects found.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{DEBUG_SAVEALL}
|
|
When set, all unreachable objects found will be appended to
|
|
\var{garbage} rather than being freed. This can be useful for debugging
|
|
a leaking program.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{DEBUG_LEAK}
|
|
The debugging flags necessary for the collector to print
|
|
information about a leaking program (equal to \code{DEBUG_COLLECTABLE |
|
|
DEBUG_UNCOLLECTABLE | DEBUG_INSTANCES | DEBUG_OBJECTS | DEBUG_SAVEALL}).
|
|
\end{datadesc}
|