From: Fred Drake <fdrake@acm.org>
Date: Fri, 7 Dec 2001 17:30:40 +0000 (+0000)
Subject: Added more information about reference counting limitations and the cycle
X-Git-Tag: v2.2.1c1~484
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=024e647972671cdced6fc3487740ca8580860416;p=python

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 e78e1d1f4b..7fe07b838b 100644
--- 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}}