Moved COUNT_ALLOCS down and finished writing its description.

1 files changed, 45 insertions, 6 deletions

diff --git a/Misc/SpecialBuilds.txt b/Misc/SpecialBuilds.txt
index e55d821..b6446dd 100644
--- a/Misc/SpecialBuilds.txt
+++ b/Misc/SpecialBuilds.txt
@@ -53,12 +53,6 @@ envar PYTHONDUMPREFS
     If this envar exists, Py_Finalize() arranges to print a list of
     all still-live heap objects.
 ---------------------------------------------------------------------------
-COUNT_ALLOCS
-
-Special gimmicks:
-
-sys.getcounts()
----------------------------------------------------------------------------
 PYMALLOC_DEBUG
 
 Special gimmicks:
@@ -75,3 +69,48 @@ This is what is generally meant by "a debug build" of Python.
 Py_DEBUG implies Py_REF_DEBUG, Py_TRACE_REFS, and PYMALLOC_DEBUG (if
 WITH_PYMALLOC is enabled).
 ---------------------------------------------------------------------------
+COUNT_ALLOCS
+
+Each type object grows three new members:
+
+    /* Number of times an object of this type was allocated. */
+	int tp_allocs;
+
+    /* Number of times an object of this type was deallocated. */
+	int tp_frees;
+
+	/* Highwater mark:  the maximum value of tp_allocs - tp_frees so
+	 * far; or, IOW, the largest number of objects of this type alive at
+	 * the same time.
+	 */
+	int tp_maxalloc;
+
+Allocation and deallocation code keeps these counts up to date.
+Py_Finalize() displays a summary of the info returned by sys.getcounts()
+(see below), along with assorted other special allocation counts (like
+the number of tuple allocations satisfied by a tuple free-list, the number
+of 1-character strings allocated, etc).
+
+Before Python 2.2, type objects were immortal, and the COUNT_ALLOCS
+implementation relies on that.  As of Python 2.2, heap-allocated type/
+class objects can go away.  COUNT_ALLOCS can blow up in 2.2 and 2.2.1
+because of this; this was fixed in 2.2.2.  Use of COUNT_ALLOCS makes
+all heap-allocated type objects immortal, except for those for which no
+object of that type is ever allocated.
+
+Special gimmicks:
+
+sys.getcounts()
+    Return a list of 4-tuples, one entry for each type object for which
+    at least one object of that type was allocated.  Each tuple is of
+    the form:
+
+        (tp_name, tp_allocs, tp_frees, tp_maxalloc)
+
+    Each distinct type objects gets a distinct entry in this list, even
+    if two or more type objects have the same tp_name (in which case
+    there's no way to distinguish them by looking at this list).  The
+    list is ordered by time of first object allocation:  the type object
+    for which the first allocation of an object of that type occurred
+    most recently is at the front of the list.
+---------------------------------------------------------------------------