| Tim Peters | 6045d48 | 2002-07-09 18:35:34 +0000 | [diff] [blame^] | 1 | This file describes some special Python build types enabled via |
| 2 | compile-time preprocessor defines. |
| 3 | |
| 4 | --------------------------------------------------------------------------- |
| 5 | Py_REF_DEBUG |
| 6 | |
| 7 | Turn on aggregate reference counting. This arranges that extern |
| 8 | _Py_RefTotal hold a count of all references, the sum of ob_refcnt across |
| 9 | all objects. In a debug-mode build, this is where the "8288" comes from |
| 10 | in |
| 11 | |
| 12 | >>> 23 |
| 13 | 23 |
| 14 | [8288 refs] |
| 15 | >>> |
| 16 | |
| 17 | Note that if this count increases when you're not storing away new objects, |
| 18 | there's probably a leak. Remember, though, that in interactive mode the |
| 19 | special name "_" holds a reference to the last result displayed! |
| 20 | |
| 21 | Py_REF_DEBUG also checks after every decref to verify that the refcount |
| 22 | hasn't gone negative, and causes an immediate fatal error if it has. |
| 23 | |
| 24 | Special gimmicks: |
| 25 | |
| 26 | sys.gettotalrefcount() |
| 27 | Return current total of all refcounts. |
| 28 | Available under Py_REF_DEBUG in Python 2.3. |
| 29 | Before 2.3, Py_TRACE_REFS was required to enable this function. |
| 30 | --------------------------------------------------------------------------- |
| 31 | Py_TRACE_REFS |
| 32 | |
| 33 | Turn on heavy reference debugging. This is major surgery. Every PyObject |
| 34 | grows two more pointers, to maintain a doubly-linked list of all live |
| 35 | heap-allocated objects (note that, e.g., most builtin type objects are not |
| 36 | in this list, as they're statically allocated). Note that because the |
| 37 | fundamental PyObject layout changes, Python modules compiled with |
| 38 | Py_TRACE_REFS are incompatible with modules compiled without it. |
| 39 | |
| 40 | Py_TRACE_REFS implies Py_REF_DEBUG. |
| 41 | |
| 42 | Special gimmicks: |
| 43 | |
| 44 | sys.getobjects(max[, type]) |
| 45 | Return list of the most-recently allocated max objects, most recently |
| 46 | allocated first in the list, least-recently allocated last in the |
| 47 | list. max=0 means no limit on list length. If an optional type |
| 48 | object is passed, the list is also restricted to objects of that |
| 49 | type. |
| 50 | |
| 51 | envar PYTHONDUMPREFS |
| 52 | If this envar exists, Py_Finalize() arranges to print a list of |
| 53 | all still-live heap objects. |
| 54 | --------------------------------------------------------------------------- |
| 55 | COUNT_ALLOCS |
| 56 | |
| 57 | Special gimmicks: |
| 58 | |
| 59 | sys.getcounts() |
| 60 | --------------------------------------------------------------------------- |
| 61 | PYMALLOC_DEBUG |
| 62 | |
| 63 | Special gimmicks: |
| 64 | |
| 65 | envar PYTHONMALLOCSTATS |
| 66 | If this envar exists, a report of pymalloc summary statistics is |
| 67 | printed to stderr whenever a new arena is allocated, and also |
| 68 | by Py_Finalize(). |
| 69 | --------------------------------------------------------------------------- |
| 70 | Py_DEBUG |
| 71 | |
| 72 | This is what is generally meant by "a debug build" of Python. |
| 73 | |
| 74 | Py_DEBUG implies Py_REF_DEBUG, Py_TRACE_REFS, and PYMALLOC_DEBUG (if |
| 75 | WITH_PYMALLOC is enabled). |
| 76 | --------------------------------------------------------------------------- |