diff options
| -rw-r--r-- | Doc/Makefile.deps | 1 | ||||
| -rw-r--r-- | Doc/lib/lib.tex | 1 | ||||
| -rw-r--r-- | Doc/lib/libgc.tex | 106 |
3 files changed, 108 insertions, 0 deletions
diff --git a/Doc/Makefile.deps b/Doc/Makefile.deps index af3d8cc..9b82b2e 100644 --- a/Doc/Makefile.deps +++ b/Doc/Makefile.deps @@ -48,6 +48,7 @@ LIBFILES= $(MANSTYLES) $(COMMONTEX) \ ../lib/libfuncs.tex \ ../lib/libpython.tex \ ../lib/libsys.tex \ + ../lib/libgc.tex \ ../lib/libtypes.tex \ ../lib/libtraceback.tex \ ../lib/libpickle.tex \ diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex index 55e0ea9..f15f98f 100644 --- a/Doc/lib/lib.tex +++ b/Doc/lib/lib.tex @@ -73,6 +73,7 @@ and how to embed it in other applications. \input{libpython} % Python Services \input{libsys} +\input{libgc} \input{libatexit} \input{libtypes} \input{libuserdict} 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} |