[Python-checkins] python/dist/src/Misc SpecialBuilds.txt,1.2,1.3

[tim_one@users.sourceforge.net]

Update of /cvsroot/python/python/dist/src/Misc
In directory usw-pr-cvs1:/tmp/cvs-serv22922

Modified Files:
	SpecialBuilds.txt 
Log Message:
Moved COUNT_ALLOCS down and finished writing its description.


Index: SpecialBuilds.txt
===================================================================
RCS file: /cvsroot/python/python/dist/src/Misc/SpecialBuilds.txt,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** SpecialBuilds.txt	9 Jul 2002 18:48:32 -0000	1.2
--- SpecialBuilds.txt	9 Jul 2002 19:24:54 -0000	1.3
***************
*** 54,63 ****
      all still-live heap objects.
  ---------------------------------------------------------------------------
- COUNT_ALLOCS
- 
- Special gimmicks:
- 
- sys.getcounts()
- ---------------------------------------------------------------------------
  PYMALLOC_DEBUG
  
--- 54,57 ----
***************
*** 75,77 ****
--- 69,116 ----
  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.
  ---------------------------------------------------------------------------