mirror of https://github.com/python/cpython
107 lines
4.2 KiB
TeX
107 lines
4.2 KiB
TeX
\section{\module{gc} ---
|
|
Garbage Collector interface}
|
|
|
|
\declaremodule{extension}{gc}
|
|
\moduleauthor{Neil Schemenauer}{nascheme@enme.ucalgary.ca}
|
|
\sectionauthor{Neil Schemenauer}{nascheme@enme.ucalgary.ca}
|
|
|
|
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. The collector can be disabled by
|
|
calling \code{gc.set_threshold(0)}. To debug a leaking program call
|
|
\code{gc.set_debug(gc.DEBUG_LEAK)}.
|
|
|
|
The \module{gc} module provides the following functions:
|
|
|
|
\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.
|
|
\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_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}).
|
|
\end{datadesc}
|