Moved COUNT_ALLOCS down and finished writing its description.

diff --git a/Misc/SpecialBuilds.txt b/Misc/SpecialBuilds.txt
index e55d82197c22d1b20cb5eeb0d74d0c4d3d8aa8a5..b6446dd826b27b9ffb85ff97a4d8fc58a16a3cb4 100644 (file)
--- 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.
+---------------------------------------------------------------------------