Added more information about reference counting limitations and the cycle

detector.
This closes SF bug #484950.

diff --git a/Doc/ext/extending.tex b/Doc/ext/extending.tex
index e78e1d1f4b2c6a233e8bfaf076c8ed0ffcfadb8c..7fe07b838b310131868f55ceeb9c613969b27188 100644 (file)
--- a/Doc/ext/extending.tex
+++ b/Doc/ext/extending.tex
@@ -1232,6 +1232,33 @@ Maybe some day a sufficiently portable automatic garbage collector
 will be available for C.  Until then, we'll have to live with
 reference counts.
 
+While Python uses the traditional reference counting implementation,
+it also offers a cycle detector that works to detect reference
+cycles.  This allows applications to not worry about creating direct
+or indirect circular references; these are the weakness of garbage
+collection implemented using only reference counting.  Reference
+cycles consist of objects which contain (possibly indirect) references
+themselves so that each object in the cycle has a reference count
+which is non-zero.  Typical reference counting implementations are not
+able to reclaim the memory beloning to any objects in a reference
+cycle, or referenced from the objects in the cycle, even though there
+are no further references to the cycle itself.
+
+The cycle detector is able to detect garbage cycles and can reclaim
+them so long as there are no finalizers implemented in Python
+(\method{__del__()} methods).  When there are such finalizers, the
+detector exposes the cycles through the \ulink{\module{gc}
+module}{../lib/module-gc.html}.  The \module{gc} module also exposes
+configuration interfaces and the ability to disable the detector at
+runtime.  The cycle detector is considered an optional component;
+though it is included by default, it can be disabled at compile time
+using the \longprogramopt{without-cycle-gc} option to the
+\program{configure} script on \UNIX{} platforms (including Mac OS X)
+or by removing the definition of \code{WITH_CYCLE_GC} in the
+\file{pyconfig.h} header on other platforms.  If the cycle detector is
+disabled in this way, the \module{gc} module will not be available.
+
+
 \subsection{Reference Counting in Python
             \label{refcountsInPython}}