133 lines
5.0 KiB
TeX
133 lines
5.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}
|
|
|
|
The \module{gc} module is only available if the interpreter was built
|
|
with the optional cyclic garbage detector (enabled by default). If
|
|
this was not enabled, an \exception{ImportError} is raised by attempts
|
|
to import this module.
|
|
|
|
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)}.
|
|
|
|
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}{}
|
|
Run a full collection. All generations are examined and the
|
|
number of unreachable objects found is returned.
|
|
\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}{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_threshold}{}
|
|
Return the current collection thresholds as a tuple of
|
|
\code{(\var{threshold0}, \var{threshold1}, \var{threshold2})}.
|
|
\end{funcdesc}
|
|
|
|
|
|
The following variable is provided for read-only access:
|
|
|
|
\begin{datadesc}{garbage}
|
|
A list of objects which the collector found to be unreachable
|
|
but could not be freed (uncollectable objects). Objects that have
|
|
\method{__del__()} methods and create part of a reference cycle cause
|
|
the entire reference cycle to be uncollectable. 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}
|