mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-07-29 14:15:07 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 9

bpo-43774: Enhance debug build documentation (GH-25712)

Browse source 
* Add also references to --with-trace-refs option.
* Move _ob_next and _ob_prev at the end, since they don't exist by
  default and are related to debug.
This commit is contained in:
Victor Stinner 2021-04-29 13:06:59 +02:00 • committed by GitHub
parent 8ec2f0dc0c
commit abfd6388cd
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 53 additions and 69 deletions
Download patch file Download diff file Expand all files Collapse all files

32
Doc/c-api/intro.rst
View file

@ -749,34 +749,12 @@ It is also implied by the presence of the
not-Python-specific :c:macro:`_DEBUG` macro. When :c:macro:`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:
In addition to the reference count debugging described below, extra checks are
performed, see :ref:`Python Debug Build <debug-build>`.
* Extra checks are added to the object allocator.
* Extra checks are added to the parser and compiler.
* Downcasts from wide types to narrow types are checked for loss of information.
* A number of assertions are added to the dictionary and set implementations.
In addition, the set object acquires a :meth:`test_c_api` method.
* Sanity checks of the input arguments are added to frame creation.
* The storage for ints is initialized with a known invalid pattern to catch
reference to uninitialized digits.
* Low-level tracing and extra exception checking are added to the runtime
virtual machine.
* Extra checks are added to the memory arena implementation.
* Extra debugging is added to the thread module.
There may be additional checks not mentioned here.
Defining :c:macro:`Py_TRACE_REFS` enables reference tracing. When defined, a
circular doubly linked list of active objects is maintained by adding two extra
Defining :c:macro:`Py_TRACE_REFS` enables reference tracing
(see the :option:`configure --with-trace-refs option <--with-trace-refs>`).
When defined, a circular doubly linked list of active objects is maintained by adding two extra
fields to every :c:type:`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.)

43
Doc/c-api/typeobj.rst
View file

@ -482,27 +482,6 @@ metatype) initializes :c:member:`~PyTypeObject.tp_itemsize`, which means that it
type objects) *must* have the :attr:`ob_size` field.
.. c:member:: PyObject* PyObject._ob_next
PyObject* PyObject._ob_prev
These fields are only present when the macro ``Py_TRACE_REFS`` is defined.
Their initialization to ``NULL`` is taken care of by the
``PyObject_HEAD_INIT`` macro. For :ref:`statically allocated objects
<static-types>`, these fields always remain ``NULL``. For :ref:`dynamically
allocated objects <heap-types>`, these two fields are used to link the
object into a doubly-linked list of *all* live objects on the heap.
This could be used for various debugging purposes; currently the only uses
are the :func:`sys.getobjects` function and to print the objects that are
still alive at the end of a run when the environment variable
:envvar:`PYTHONDUMPREFS` is set.
**Inheritance:**
These fields are not inherited by subtypes.
.. c:member:: Py_ssize_t PyObject.ob_refcnt
This is the type object's reference count, initialized to ``1`` by the
@ -540,6 +519,28 @@ type objects) *must* have the :attr:`ob_size` field.
This field is inherited by subtypes.
.. c:member:: PyObject* PyObject._ob_next
PyObject* PyObject._ob_prev
These fields are only present when the macro ``Py_TRACE_REFS`` is defined
(see the :option:`configure --with-trace-refs option <--with-trace-refs>`).
Their initialization to ``NULL`` is taken care of by the
``PyObject_HEAD_INIT`` macro. For :ref:`statically allocated objects
<static-types>`, these fields always remain ``NULL``. For :ref:`dynamically
allocated objects <heap-types>`, these two fields are used to link the
object into a doubly-linked list of *all* live objects on the heap.
This could be used for various debugging purposes; currently the only uses
are the :func:`sys.getobjects` function and to print the objects that are
still alive at the end of a run when the environment variable
:envvar:`PYTHONDUMPREFS` is set.
**Inheritance:**
These fields are not inherited by subtypes.
PyVarObject Slots
-----------------