PEP 454
* Add Trace, Traceback and Frame classes: generated on-demand read-only views of traces * Add a new StatisticDiff class and add new Snapshot.compare_to() method. The method return a list of StatisticDiff instances and replaces the compare_to parameter of Snapshot.statistics() * Remove Statistic.size_diff and Statistic.count_diff attributes * Remove get_traces()
This commit is contained in:
Victor Stinner
parent
b4fb332c27
commit
4841d22de4
216
pep-0454.txt
216
pep-0454.txt
|
|
@ -161,13 +161,20 @@ Main functions
|
|||
|
||||
``take_snapshot()`` function:
|
||||
|
||||
Take a snapshot of traces of memory blocks allocated by Python using
|
||||
the ``get_traces()`` function. Return a new ``Snapshot`` instance.
|
||||
Take a snapshot of traces of memory blocks allocated by Python.
|
||||
Return a new ``Snapshot`` instance.
|
||||
|
||||
The snapshot does not include memory blocks allocated before the
|
||||
``tracemalloc`` module started to trace memory allocations nor
|
||||
memory blocks ignored by filters (see ``get_filters()``).
|
||||
|
||||
Tracebacks of traces are limited to ``traceback_limit`` frames. Use
|
||||
``set_traceback_limit()`` to store more frames.
|
||||
|
||||
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.
|
||||
See also the ``get_object_traceback()`` function.
|
||||
|
||||
|
||||
Trace functions
|
||||
|
|
@ -175,31 +182,15 @@ Trace functions
|
|||
|
||||
When Python allocates a memory block, ``tracemalloc`` attachs a "trace" to
|
||||
the memory block to store its size in bytes and the traceback where the
|
||||
allocation occurred.
|
||||
|
||||
The following functions give access to these traces. A trace is a ``(size: int,
|
||||
traceback)`` tuple. *size* is the size of the memory block in bytes.
|
||||
*traceback* is a tuple of frames sorted from the most recent to the oldest
|
||||
frame, limited to ``get_traceback_limit()`` frames. A frame is
|
||||
a ``(filename: str, lineno: int)`` tuple.
|
||||
|
||||
A traceback contains at least ``1`` frame. If the ``tracemalloc`` module
|
||||
failed to get a frame, the ``"<unknown>"`` filename and the line number ``0``
|
||||
are used. If it failed to get the traceback or if the traceback limit is ``0``,
|
||||
the traceback is ``(('<unknown>', 0),)``.
|
||||
|
||||
Example of a trace: ``(32, (('x.py', 7), ('x.py', 11)))``. The memory block
|
||||
has a size of 32 bytes and was allocated at ``x.py:7``, line called from line
|
||||
``x.py:11``.
|
||||
allocation occurred. See the ``Trace`` class.
|
||||
|
||||
|
||||
``get_object_traceback(obj)`` function:
|
||||
|
||||
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 not tracing memory
|
||||
allocations or did not trace the allocation of the object.
|
||||
Return a ``Traceback`` instance, or ``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.
|
||||
|
||||
|
|
@ -214,30 +205,6 @@ has a size of 32 bytes and was allocated at ``x.py:7``, line called from line
|
|||
Use the ``set_traceback_limit()`` function to change the limit.
|
||||
|
||||
|
||||
``get_traces()`` function:
|
||||
|
||||
Get traces of memory blocks allocated by Python. Return a list of
|
||||
``(size: int, traceback: tuple)`` tuples. *traceback* is a tuple of
|
||||
``(filename: str, lineno: int)`` tuples.
|
||||
|
||||
The list of traces does not include memory blocks allocated before
|
||||
the ``tracemalloc`` module started to trace memory allocations nor
|
||||
memory blocks ignored by filters (see ``get_filters()``).
|
||||
|
||||
The list has an undefined order. Take a snapshot using
|
||||
``take_snapshot()`` and use the ``Snapshot.statistics()`` method to
|
||||
get a sorted list of statistics.
|
||||
|
||||
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 not tracing
|
||||
memory allocations.
|
||||
|
||||
See also ``take_snapshot()`` and ``get_object_traceback()``
|
||||
functions.
|
||||
|
||||
|
||||
``set_traceback_limit(nframe: int)`` function:
|
||||
|
||||
Set the maximum number of frames stored in the traceback of a trace.
|
||||
|
|
@ -351,10 +318,28 @@ Filter
|
|||
See the ``get_traceback_limit()`` function.
|
||||
|
||||
|
||||
Frame
|
||||
-----
|
||||
|
||||
``Frame`` class:
|
||||
|
||||
Frame of a traceback.
|
||||
|
||||
The ``Traceback`` class is a sequence of ``Frame`` instances.
|
||||
|
||||
``filename`` attribute:
|
||||
|
||||
Filename (``str``).
|
||||
|
||||
``lineno`` attribute:
|
||||
|
||||
Line number (``int``).
|
||||
|
||||
|
||||
Snapshot
|
||||
--------
|
||||
|
||||
``Snapshot(timestamp: datetime.datetime, traceback_limit: int, traces: dict=None)`` class:
|
||||
``Snapshot`` class:
|
||||
|
||||
Snapshot of traces of memory blocks allocated by Python.
|
||||
|
||||
|
|
@ -362,14 +347,28 @@ Snapshot
|
|||
|
||||
``apply_filters(filters)`` method:
|
||||
|
||||
Apply filters on the ``traces`` dictionary, *filters* is a list of
|
||||
``Filter`` instances. Return a new ``Snapshot`` instance with the
|
||||
filtered traces.
|
||||
Create a new ``Snapshot`` instance with the filtered ``traces``,
|
||||
*filters* is a list of ``Filter`` instances.
|
||||
|
||||
If *filters* is an empty list, return a new ``Snapshot`` instance
|
||||
with a copy of the traces.
|
||||
|
||||
|
||||
``compare_to(old_snapshot: Snapshot, group_by: str, cumulative: bool=False)`` method:
|
||||
|
||||
Compute the differences with an old snapshot *old_snapshot*. Get
|
||||
statistics as a sorted list of ``StatisticDiff`` instances, grouped
|
||||
by *group_by*.
|
||||
|
||||
See the ``statistics()`` method for *group_by* and *cumulative*
|
||||
parameters.
|
||||
|
||||
The result is sorted from the biggest to the smallest by: absolute
|
||||
value of ``StatisticDiff.size_diff``, ``StatisticDiff.size``,
|
||||
absolute value of ``StatisticDiff.count_diff``, ``Statistic.count``
|
||||
and then by ``StatisticDiff.traceback``.
|
||||
|
||||
|
||||
``dump(filename)`` method:
|
||||
|
||||
Write the snapshot into a file.
|
||||
|
|
@ -384,7 +383,7 @@ Snapshot
|
|||
See also ``dump()``.
|
||||
|
||||
|
||||
``statistics(group_by: str, cumulative: bool=False, compare_to=None)`` method:
|
||||
``statistics(group_by: str, cumulative: bool=False)`` method:
|
||||
|
||||
Get statistics as a sorted list of ``Statistic`` instances, grouped
|
||||
by *group_by*:
|
||||
|
|
@ -403,15 +402,9 @@ Snapshot
|
|||
``'filename'`` and ``'lineno'`` with ``traceback_limit`` greater
|
||||
than ``1``.
|
||||
|
||||
If *compare_to* is set to a previous ``Snapshot`` instance, compute
|
||||
the differences betwen the two snapshots. Otherwise,
|
||||
``Statistic.size_diff`` and ``Statistic.count_diff`` attributes are
|
||||
set to zero.
|
||||
|
||||
The result is sorted from the biggest to the smallest by: absolute
|
||||
value of ``Statistic.size_diff``, ``Statistic.size``, absolute value
|
||||
of ``Statistic.count_diff``, ``Statistic.count`` and then by
|
||||
``Statistic.key``.
|
||||
The result is sorted from the biggest to the smallest by:
|
||||
``Statistic.size``, ``Statistic.count`` and then by
|
||||
``Statistic.traceback``.
|
||||
|
||||
|
||||
``traceback_limit`` attribute:
|
||||
|
|
@ -421,8 +414,11 @@ Snapshot
|
|||
|
||||
``traces`` attribute:
|
||||
|
||||
Traces of all memory blocks allocated by Python: see the
|
||||
``get_traces()`` function.
|
||||
Traces of all memory blocks allocated by Python: sequence of
|
||||
``Trace`` instances.
|
||||
|
||||
The sequence has an undefined order. Use the
|
||||
``Snapshot.statistics()`` method to get a sorted list of statistics.
|
||||
|
||||
``timestamp`` attribute:
|
||||
|
||||
|
|
@ -433,7 +429,7 @@ Snapshot
|
|||
Statistic
|
||||
---------
|
||||
|
||||
``Statistic(key, size, size_diff, count, count_diff)`` class:
|
||||
``Statistic`` class:
|
||||
|
||||
Statistic on memory allocations.
|
||||
|
||||
|
|
@ -442,25 +438,101 @@ Statistic
|
|||
|
||||
``Snapshot.statistics()`` returns a list of ``Statistic`` instances.
|
||||
|
||||
``traceback`` attribute:
|
||||
|
||||
Tuple of ``(filename: str, lineno: int)`` tuples.
|
||||
See also the ``StatisticDiff`` class.
|
||||
|
||||
``count`` attribute:
|
||||
|
||||
Number of memory blocks (``int``).
|
||||
|
||||
``count_diff`` attribute:
|
||||
|
||||
Difference of number of memory blocks (``int``).
|
||||
|
||||
``size`` attribute:
|
||||
|
||||
Total size of memory blocks in bytes (``int``).
|
||||
|
||||
``traceback`` attribute:
|
||||
|
||||
Traceback where the memory block was allocated, ``Traceback``
|
||||
instance.
|
||||
|
||||
|
||||
StatisticDiff
|
||||
-------------
|
||||
|
||||
``StatisticDiff`` class:
|
||||
|
||||
Statistic difference on memory allocations between an old and a new
|
||||
``Snapshot`` instance.
|
||||
|
||||
``Snapshot.compare_to()`` returns a list of ``StatisticDiff``
|
||||
instances. See also the ``Statistic`` class.
|
||||
|
||||
``count`` attribute:
|
||||
|
||||
Number of memory blocks in the new snapshot (``int``): ``0`` if the
|
||||
memory blocks have been released in the new snapshot.
|
||||
|
||||
``count_diff`` attribute:
|
||||
|
||||
Difference of number of memory blocks between the old and the new
|
||||
snapshots (``int``): ``0`` if the memory blocks have been allocated
|
||||
in the new snapshot.
|
||||
|
||||
``size`` attribute:
|
||||
|
||||
Total size of memory blocks in bytes in the new snapshot (``int``):
|
||||
``0`` if the memory blocks have been released in the new snapshot.
|
||||
|
||||
``size_diff`` attribute:
|
||||
|
||||
Difference of total size of memory blocks in bytes (``int``).
|
||||
Difference of total size of memory blocks in bytes between the old
|
||||
and the new snapshots (``int``): ``0`` if the memory blocks have
|
||||
been allocated in the new snapshot.
|
||||
|
||||
``traceback`` attribute:
|
||||
|
||||
Traceback where the memory blocks were allocated, ``Traceback``
|
||||
instance.
|
||||
|
||||
|
||||
Trace
|
||||
-----
|
||||
|
||||
``Trace`` class:
|
||||
|
||||
Trace of a memory block.
|
||||
|
||||
The ``Snapshot.traces`` attribute is a sequence of ``Trace``
|
||||
instances.
|
||||
|
||||
``size`` attribute:
|
||||
|
||||
Size of the memory block in bytes (``int``).
|
||||
|
||||
``traceback`` attribute:
|
||||
|
||||
Traceback where the memory block was allocated, ``Traceback``
|
||||
instance.
|
||||
|
||||
|
||||
Traceback
|
||||
---------
|
||||
|
||||
``Traceback`` class:
|
||||
|
||||
Sequence of ``Frame`` instances sorted from the most recent frame to
|
||||
the oldest frame.
|
||||
|
||||
A traceback contains at least ``1`` frame. If the ``tracemalloc``
|
||||
module failed to get a frame, the filename ``"<unknown>"`` and the
|
||||
line number ``0`` are used. If it failed to get the traceback or if
|
||||
the traceback limit is ``0``, the traceback only contains a frame:
|
||||
filename ``'<unknown>'`` and line number ``0``.
|
||||
|
||||
When a snapshot is taken, tracebacks of traces are limited to
|
||||
``get_traceback_limit()`` frames. See the ``take_snapshot()``
|
||||
function.
|
||||
|
||||
The ``Trace.traceback`` attribute is an instance of ``Traceback``
|
||||
instance.
|
||||
|
||||
|
||||
Rejected Alternatives
|
||||
|
|
|
|||
Loading…
Reference in New Issue