diff options
Diffstat (limited to 'Doc/api/intro.tex')
| -rw-r--r-- | Doc/api/intro.tex | 56 |
1 files changed, 56 insertions, 0 deletions
diff --git a/Doc/api/intro.tex b/Doc/api/intro.tex index 96f18ecdf8..c2c3fecf83 100644 --- a/Doc/api/intro.tex +++ b/Doc/api/intro.tex @@ -577,3 +577,59 @@ information about these functions is given in a later chapter. Notice that \cfunction{Py_Finalize} does \emph{not} free all memory allocated by the Python interpreter, e.g. memory allocated by extension modules currently cannot be released. + + +\section{Debugging Builds \label{debugging}} + +Python can be built with several macros to enable extra checks of the +interpreter and extension modules. These checks tend to add a large +amount of overhead to the runtime so they are not enabled by default. + +A full list of the various types of debugging builds is in the file +\file{Misc/SpecialBuilds.txt} in the Python source distribution. +Builds are available that support tracing of reference counts, +debugging the memory allocator, or low-level profiling of the main +interpreter loop. Only the most frequently-used builds will be +described in the remainder of this section. + +Compiling the interpreter with the \csimplemacro{Py_DEBUG} macro +defined produces what is generally meant by "a debug build" of Python. +\csimplemacro{Py_DEBUG} is enabled in the \UNIX{} build by adding +\longprogramopt{with-pydebug} to the \file{configure} command. It is also +implied by the presence of the not-Python-specific +\csimplemacro{_DEBUG} macro. When \csimplemacro{Py_DEBUG} is enabled +in the \UNIX{} build, compiler optimization is disabled. + +In addition to the reference count debugging described below, the +following extra checks are performed: + +\begin{itemize} + \item Extra checks are added to the object allocator. + \item Extra checks are added to the parser and compiler. + \item Downcasts from wide types to narrow types are checked for + loss of information. + \item A number of assertions are added to the dictionary and set + implementations. In addition, the set object acquires a + \method{test_c_api} method. + \item Sanity checks of the input arguments are added to frame + creation. + \item The storage for long ints is initialized with a known + invalid pattern to catch reference to uninitialized + digits. + \item Low-level tracing and extra exception checking are added + to the runtime virtual machine. + \item Extra checks are added to the memory arena implementation. + \item Extra debugging is added to the thread module. +\end{itemize} + +There may be additional checks not mentioned here. + +Defining \csimplemacro{Py_TRACE_REFS} enables reference tracing. When +defined, a circular doubly linked list of active objects is maintained +by adding two extra fields to every \ctype{PyObject}. Total +allocations are tracked as well. Upon exit, all existing references +are printed. (In interactive mode this happens after every statement +run by the interpreter.) Implied by \csimplemacro{Py_DEBUG}. + +Please refer to \file{Misc/SpecialBuilds.txt} in the Python source +distribution for more detailed information. |