iSharkFly-Open
/
python-peps
mirror of https://github.com/python/peps.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

PEP 454: rename reset() to clear_traces() 

Explain also in clear_traces() documentation how to get traces before clearing them.
This commit is contained in:
Victor Stinner 2013-10-30 11:24:34 +01:00
parent adc68f3b3d
commit b134f468c8
1 changed files with 15 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
pep-0454.txt
View File

@ -24,12 +24,12 @@ Classic generic tools like Valgrind can get the C traceback where a
memory block was allocated. Using such tools to analyze Python memory
allocations does not help because most memory blocks are allocated in
the same C function, in ``PyMem_Malloc()`` for example. Moreover, Python
has an allocator for small object called "pymalloc" which keeps free
has an allocator for small objects called "pymalloc" which keeps free
blocks for efficiency. This is not well handled by these tools.
There are debug tools dedicated to the Python language like ``Heapy``
``Pympler`` and ``Meliae`` which lists all live objects using the
garbage module (functions like ``gc.get_objects()``,
``Pympler`` and ``Meliae`` which lists all alive objects using the
garbage collector module (functions like ``gc.get_objects()``,
``gc.get_referrers()`` and ``gc.get_referents()``), compute their size
(ex: using ``sys.getsizeof()``) and group objects by type. These tools
provide a better estimation of the memory usage of an application. They
@ -108,7 +108,7 @@ memory allocations.
Main functions
--------------
``reset()`` function:
``clear_traces()`` function:
Clear traces of memory blocks allocated by Python.
@ -120,6 +120,9 @@ Main functions
Stop tracing Python memory allocations and clear traces of memory
blocks allocated by Python.
Call ``get_traces()`` or ``take_snapshot()`` function to get traces
before clearing them.
See also ``enable()`` and ``is_enabled()`` functions.
@ -154,7 +157,7 @@ Trace functions
---------------
When Python allocates a memory block, ``tracemalloc`` attachs a "trace" to
it to store information on it: its size in bytes and the traceback where the
the memory block to store its size in bytes and the traceback where the
allocation occured.
The following functions give access to these traces. A trace is a ``(size: int,
@ -199,8 +202,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 and memory blocks ignored by
filters (see ``get_filters()()``).
``tracemalloc`` module was enabled nor memory blocks ignored by
filters (see ``get_filters()``).
Return an empty list if the ``tracemalloc`` module is disabled.
@ -248,7 +251,8 @@ Filter functions
is ignored if at least one exclusive filter matchs its trace.
The new filter is not applied on already collected traces. Use the
``reset()`` function to ensure that all traces match the new filter.
``clear_traces()`` function to ensure that all traces match the new
filter.
``clear_filters()`` function:
@ -284,8 +288,7 @@ Filter
the comparison is case insensitive and the alternative separator
``'/'`` is replaced with the standard separator ``'\'``.
For example, use ``Filter(False, "<unknown>")`` to exclude empty
tracebacks.
Use ``Filter(False, "<unknown>")`` to exclude empty tracebacks.
``inclusive`` attribute:
@ -384,7 +387,8 @@ Snapshot
Traces of all memory blocks allocated by Python, result of the
``get_traces()`` function: list of ``(size: int, traceback: tuple)``
tuples, *traceback* is a tuple of ``(filename: str, lineno: int)``
tuples.
tuples. *size* is the size of the memory block in bytes, *traceback*
is the Python stack where the allocation occured.
``timestamp`` attribute: