[Python-checkins] python/dist/src/Misc README.valgrind,1.1,1.2

[tim_one at users.sourceforge.net]

Update of /cvsroot/python/python/dist/src/Misc
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv28795/Misc

Modified Files:
	README.valgrind 
Log Message:
Made the explanation more accurate; trimmed trailing whitespace; fixed
a typo.


Index: README.valgrind
===================================================================
RCS file: /cvsroot/python/python/dist/src/Misc/README.valgrind,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** README.valgrind	6 Jun 2004 19:58:40 -0000	1.1
--- README.valgrind	7 Jul 2004 02:46:03 -0000	1.2
***************
*** 1,23 ****
  This document describes some caveats about the use of Valgrind with
! Python.  Valgrind is used periodically by Python developers to try 
  to ensure there are no memory leaks or invalid memory reads/writes.
  
  If you don't want to read about the details of using Valgrind, there
! are still two things you must do to suppress the warnings.  First, 
  you must use a suppressions file.  One is supplied in
  Misc/valgrind-python.supp.  Second, you must do one of the following:
  
    * Uncomment Py_USING_MEMORY_DEBUGGER in Objects/obmalloc.c,
!     then rebuild Python 
!   * Uncomment the lines in Misc/valgrind-python.supp that 
      suppress the warnings for PyObject_Free and PyObject_Realloc
  
  Details:
  --------
! Python uses its own allocation scheme on top of malloc called PyMalloc.
! Valgrind my show some unexpected results when PyMalloc is used.
  Starting with Python 2.3, PyMalloc is used by default.  You can disable
  PyMalloc when configuring python by adding the --without-pymalloc option.
! If you disable PyMalloc, most of the information in this document and 
  the supplied suppressions file will not be useful.
  
--- 1,25 ----
  This document describes some caveats about the use of Valgrind with
! Python.  Valgrind is used periodically by Python developers to try
  to ensure there are no memory leaks or invalid memory reads/writes.
  
  If you don't want to read about the details of using Valgrind, there
! are still two things you must do to suppress the warnings.  First,
  you must use a suppressions file.  One is supplied in
  Misc/valgrind-python.supp.  Second, you must do one of the following:
  
    * Uncomment Py_USING_MEMORY_DEBUGGER in Objects/obmalloc.c,
!     then rebuild Python
!   * Uncomment the lines in Misc/valgrind-python.supp that
      suppress the warnings for PyObject_Free and PyObject_Realloc
  
  Details:
  --------
! Python uses its own small-object allocation scheme on top of malloc,
! called PyMalloc.
! 
! Valgrind may show some unexpected results when PyMalloc is used.
  Starting with Python 2.3, PyMalloc is used by default.  You can disable
  PyMalloc when configuring python by adding the --without-pymalloc option.
! If you disable PyMalloc, most of the information in this document and
  the supplied suppressions file will not be useful.
  
***************
*** 33,37 ****
  
          PyMalloc needs to know whether an arbitrary address is one
! 	that's managed by it, or is managed by the system malloc.  
  	The current scheme allows this to be determined in constant
  	time, regardless of how many memory areas are under pymalloc's
--- 35,39 ----
  
          PyMalloc needs to know whether an arbitrary address is one
! 	that's managed by it, or is managed by the system malloc.
  	The current scheme allows this to be determined in constant
  	time, regardless of how many memory areas are under pymalloc's
***************
*** 39,48 ****
  
          The memory pymalloc manages itself is in one or more "arenas",
! 	each a large contiguous memory area obtained from malloc.  
! 	The base address of each arena is saved by pymalloc 
! 	in a vector, and a field at the start of each arena contains
! 	the index of that arena's base address in that vector.
  
!         Given an arbitrary address, pymalloc computes the arena base
  	address corresponding to it, then looks at "the index" stored
  	near there.  If the index read up is out of bounds for the
--- 41,51 ----
  
          The memory pymalloc manages itself is in one or more "arenas",
! 	each a large contiguous memory area obtained from malloc.
! 	The base address of each arena is saved by pymalloc
! 	in a vector.  Each arena is carved into "pools", and a field at
! 	the start of each pool contains the index of that pool's arena's
! 	base address in that vector.
  
!         Given an arbitrary address, pymalloc computes the pool base
  	address corresponding to it, then looks at "the index" stored
  	near there.  If the index read up is out of bounds for the
***************
*** 56,67 ****
          to
  
!             the computed arena address
  
!         pymalloc controls this arena if and only if they're equal.
  
          It doesn't matter whether the memory pymalloc reads up ("the
  	index") is initialized.  If it's not initialized, then
  	whatever trash gets read up will lead pymalloc to conclude
! 	(correctly) that the address isn't controlled by it.
  
          This determination has to be made on every call to one of
--- 59,73 ----
          to
  
!             the arbitrary address pymalloc is investigating
  
!         pymalloc controls this arbitrary address if and only if it lies
!         in the arena the address's pool's index claims it lies in.
  
          It doesn't matter whether the memory pymalloc reads up ("the
  	index") is initialized.  If it's not initialized, then
  	whatever trash gets read up will lead pymalloc to conclude
! 	(correctly) that the address isn't controlled by it, either
! 	because the index is out of bounds, or the index is in bounds
! 	but the arena it represents doesn't contain the address.
  
          This determination has to be made on every call to one of