Documentation for the gc module. Text from Neil Schemenauer

<nascheme@enme.ucalgary.ca>, markup & minor revisions from Fred
Drake.

1 files changed, 106 insertions, 0 deletions

diff --git a/Doc/lib/libgc.tex b/Doc/lib/libgc.tex
new file mode 100644
index 0000000..c5ecfcf
--- /dev/null
+++ b/Doc/lib/libgc.tex
@@ -0,0 +1,106 @@
+\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}