PEP 454: remove enable/disble/is_enabled() functions
This commit is contained in:
Victor Stinner
parent
f729d23f82
commit
59accfc791
100
pep-0454.txt
100
pep-0454.txt
|
|
@ -64,13 +64,12 @@ following information:
|
|||
number: total size, number and average size of allocated memory blocks
|
||||
* Computed differences between two snapshots to detect memory leaks
|
||||
|
||||
The API of the tracemalloc module is similar to the API of the
|
||||
faulthandler module: ``enable()``, ``disable()`` and ``is_enabled()``
|
||||
functions, an environment variable (``PYTHONFAULTHANDLER`` and
|
||||
``PYTHONTRACEMALLOC``), and a ``-X`` command line option (``-X
|
||||
faulthandler`` and ``-X tracemalloc``). See the
|
||||
`documentation of the faulthandler module
|
||||
<http://docs.python.org/3/library/faulthandler.html>`_.
|
||||
The API of the tracemalloc module is similar to the API of the faulthandler
|
||||
module: ``enable()`` / ``start()``, ``disable()`` / ``stop()`` and
|
||||
``is_enabled()`` / ``is_tracing()`` functions, an environment variable
|
||||
(``PYTHONFAULTHANDLER`` and ``PYTHONTRACEMALLOC``), and a ``-X`` command line
|
||||
option (``-X faulthandler`` and ``-X tracemalloc``). See the `documentation of
|
||||
the faulthandler module <http://docs.python.org/3/library/faulthandler.html>`_.
|
||||
|
||||
The idea of tracing memory allocations is not new. It was first
|
||||
implemented in the PySizer project in 2005. PySizer was implemented
|
||||
|
|
@ -79,7 +78,7 @@ types were linked the trace with the name of object type. PySizer patch
|
|||
on CPython adds a overhead on performances and memory footprint, even if
|
||||
the PySizer was not used. tracemalloc attachs a traceback to the
|
||||
underlying layer, to memory blocks, and has no overhead when the module
|
||||
is disabled.
|
||||
is not tracing memory allocations.
|
||||
|
||||
The tracemalloc module has been written for CPython. Other
|
||||
implementations of Python may not be able to provide it.
|
||||
|
|
@ -89,9 +88,9 @@ API
|
|||
===
|
||||
|
||||
To trace most memory blocks allocated by Python, the module should be
|
||||
enabled as early as possible by setting the ``PYTHONTRACEMALLOC``
|
||||
started as early as possible by setting the ``PYTHONTRACEMALLOC``
|
||||
environment variable to ``1``, or by using ``-X tracemalloc`` command
|
||||
line option. The ``tracemalloc.enable()`` function can be called at
|
||||
line option. The ``tracemalloc.start()`` function can be called at
|
||||
runtime to start tracing Python memory allocations.
|
||||
|
||||
By default, a trace of an allocated memory block only stores the most
|
||||
|
|
@ -112,28 +111,7 @@ Main functions
|
|||
|
||||
Clear traces of memory blocks allocated by Python.
|
||||
|
||||
See also ``disable()``.
|
||||
|
||||
|
||||
``disable()`` function:
|
||||
|
||||
Disable temporarily tracing new Python memory allocations,
|
||||
deallocations are still traced. The change is process-wide, tracing
|
||||
new Python memory allocations is disabled in all threads. Call
|
||||
``enable()`` to reenable tracing new Python memory allocations.
|
||||
|
||||
Filters can be used to not trace memory allocations in some files:
|
||||
use the ``add_filter()`` function.
|
||||
|
||||
See also ``enable()`` and ``is_enabled()`` functions.
|
||||
|
||||
|
||||
``enable()`` function:
|
||||
|
||||
Reenable tracing Python memory allocations if was disabled by te
|
||||
``disable()`` method.
|
||||
|
||||
See also ``is_enabled()`` functions.
|
||||
See also ``stop()``.
|
||||
|
||||
|
||||
``get_traced_memory()`` function:
|
||||
|
|
@ -148,28 +126,25 @@ Main functions
|
|||
store traces of memory blocks. Return an ``int``.
|
||||
|
||||
|
||||
``is_enabled()`` function:
|
||||
|
||||
``True`` if the ``tracemalloc`` module is enabled Python memory
|
||||
allocations, ``False`` if the module is disabled.
|
||||
|
||||
The ``tracemalloc`` module only traces new allocations if
|
||||
``is_tracing()`` and ``is_enabled()`` are ``True``.
|
||||
|
||||
See also ``enable()`` and ``disable()`` functions.
|
||||
|
||||
|
||||
``is_tracing()`` function:
|
||||
|
||||
``True`` if the ``tracemalloc`` module is tracing Python memory
|
||||
allocations, ``False`` otherwise.
|
||||
|
||||
The ``tracemalloc`` module only traces new allocations if
|
||||
``is_tracing()`` and ``is_enabled()`` are ``True``.
|
||||
|
||||
See also ``start()`` and ``stop()`` functions.
|
||||
|
||||
|
||||
``start()`` function:
|
||||
|
||||
Start tracing Python memory allocations.
|
||||
|
||||
The function installs hooks on Python memory allocators. These hooks
|
||||
have important overhead in term of performances and memory usage:
|
||||
see `Filter functions`_ to limit the overhead.
|
||||
|
||||
See also ``stop()`` and ``is_tracing()`` functions.
|
||||
|
||||
|
||||
``stop()`` function:
|
||||
|
||||
Stop tracing Python memory allocations and clear traces of memory
|
||||
|
|
@ -179,21 +154,9 @@ Main functions
|
|||
overhead of the module becomes null.
|
||||
|
||||
Call ``get_traces()`` or ``take_snapshot()`` function to get traces
|
||||
before clearing them. Use ``disable()`` to disable tracing
|
||||
temporarily.
|
||||
before clearing them.
|
||||
|
||||
See also ``enable()`` and ``is_enabled()`` functions.
|
||||
|
||||
|
||||
``start()`` function:
|
||||
|
||||
Start tracing Python memory allocations.
|
||||
|
||||
The function installs hooks on Python memory allocators. These hooks
|
||||
have important overhead in term of performances and memory usage:
|
||||
see `Filter functions`_ to limit the overhead.
|
||||
|
||||
See also ``disable()`` and ``is_tracing()`` functions.
|
||||
See also ``start()`` and ``is_tracing()`` functions.
|
||||
|
||||
|
||||
``take_snapshot()`` function:
|
||||
|
|
@ -201,8 +164,8 @@ Main functions
|
|||
Take a snapshot of traces of memory blocks allocated by Python using
|
||||
the ``get_traces()`` function. Return a new ``Snapshot`` instance.
|
||||
|
||||
The ``tracemalloc`` module must be enabled to take a snapshot, see
|
||||
the the ``enable()`` function.
|
||||
The ``tracemalloc`` module must be tracing memory allocations to take a
|
||||
snapshot, see the the ``start()`` function.
|
||||
|
||||
See also ``get_traces()`` and ``get_object_traceback()`` functions.
|
||||
|
||||
|
|
@ -235,8 +198,8 @@ has a size of 32 bytes and was allocated at ``x.py:7``, line called from line
|
|||
Get the traceback where the Python object *obj* was allocated.
|
||||
Return a tuple of ``(filename: str, lineno: int)`` tuples.
|
||||
|
||||
Return ``None`` if the ``tracemalloc`` module is disabled or did not
|
||||
trace the allocation of the object.
|
||||
Return ``None`` if the ``tracemalloc`` module is not tracing memory
|
||||
allocations or did not trace the allocation of the object.
|
||||
|
||||
See also ``gc.get_referrers()`` and ``sys.getsizeof()`` functions.
|
||||
|
||||
|
|
@ -258,8 +221,8 @@ has a size of 32 bytes and was allocated at ``x.py:7``, line called from line
|
|||
``(filename: str, lineno: int)`` tuples.
|
||||
|
||||
The list of traces do not include memory blocks allocated before the
|
||||
``tracemalloc`` module was enabled nor memory blocks ignored by
|
||||
filters (see ``get_filters()``).
|
||||
``tracemalloc`` module started to trace memory allocations nor memory
|
||||
blocks ignored by filters (see ``get_filters()``).
|
||||
|
||||
The list is not sorted. Take a snapshot using ``take_snapshot()``
|
||||
and use the ``Snapshot.statistics()`` method to get a sorted list of
|
||||
|
|
@ -268,7 +231,8 @@ has a size of 32 bytes and was allocated at ``x.py:7``, line called from line
|
|||
Tracebacks of traces are limited to ``traceback_limit`` frames. Use
|
||||
``set_traceback_limit()`` to store more frames.
|
||||
|
||||
Return an empty list if the ``tracemalloc`` module is disabled.
|
||||
Return an empty list if the ``tracemalloc`` module is not tracing memory
|
||||
allocations.
|
||||
|
||||
See also ``take_snapshot()`` and ``get_object_traceback()``
|
||||
functions.
|
||||
|
|
@ -308,8 +272,6 @@ memory allocations in the ``tracemalloc`` module
|
|||
By default, there is one exclusive filter to ignore Python memory blocks
|
||||
allocated by the ``tracemalloc`` module.
|
||||
|
||||
Tracing can be also be disabled temporarily using the ``disable()`` function.
|
||||
|
||||
Use the ``get_tracemalloc_memory()`` function to measure the memory usage.
|
||||
See also the ``set_traceback_limit()`` function to configure how many
|
||||
frames are stored.
|
||||
|
|
|
|||
Loading…
Reference in New Issue