Misc/SpecialBuilds.txt

This file describes some special Python build types enabled via
compile-time preprocessor defines.

---------------------------------------------------------------------------
Py_REF_DEBUG

Turn on aggregate reference counting.  This arranges that extern
_Py_RefTotal hold a count of all references, the sum of ob_refcnt across
all objects.  In a debug-mode build, this is where the "8288" comes from
in

    >>> 23
    23
    [8288 refs]
    >>>

Note that if this count increases when you're not storing away new objects,
there's probably a leak.  Remember, though, that in interactive mode the
special name "_" holds a reference to the last result displayed!

Py_REF_DEBUG also checks after every decref to verify that the refcount
hasn't gone negative, and causes an immediate fatal error if it has.

Special gimmicks:

sys.gettotalrefcount()
    Return current total of all refcounts.
    Available under Py_REF_DEBUG in Python 2.3.
    Before 2.3, Py_TRACE_REFS was required to enable this function.
---------------------------------------------------------------------------
Py_TRACE_REFS

Turn on heavy reference debugging.  This is major surgery.  Every PyObject
grows two more pointers, to maintain a doubly-linked list of all live
heap-allocated objects (note that, e.g., most builtin type objects are not
in this list, as they're statically allocated).  Note that because the
fundamental PyObject layout changes, Python modules compiled with
Py_TRACE_REFS are incompatible with modules compiled without it.

Py_TRACE_REFS implies Py_REF_DEBUG.

Special gimmicks:

sys.getobjects(max[, type])
    Return list of the (no more than) max most-recently allocated objects,
    most recently allocated first in the list, least-recently allocated
    last in the list.  max=0 means no limit on list length.
    If an optional type object is passed, the list is also restricted to
    objects of that type.
    The return list itself, and some temp objects created just to call
    sys.getobjects(), are excluded from the return list.  Note that the
    list returned is just another object, though, so may appear in the
    return list the next time you call getobjects(); note that every
    object in the list is kept alive too, simply by virtue of being in
    the list.

envar PYTHONDUMPREFS
    If this envar exists, Py_Finalize() arranges to print a list of
    all still-live heap objects.
---------------------------------------------------------------------------
PYMALLOC_DEBUG

Special gimmicks:

envar PYTHONMALLOCSTATS
    If this envar exists, a report of pymalloc summary statistics is
    printed to stderr whenever a new arena is allocated, and also
    by Py_Finalize().
---------------------------------------------------------------------------
Py_DEBUG

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 object 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.
---------------------------------------------------------------------------