[Python-checkins] peps: PEP 454
victor.stinner
python-checkins at python.org
Fri Nov 8 16:25:21 CET 2013
http://hg.python.org/peps/rev/9ea9c6ac801d
changeset: 5256:9ea9c6ac801d
user: Victor Stinner <victor.stinner at gmail.com>
date: Fri Nov 08 16:25:13 2013 +0100
summary:
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()
files:
pep-0454.txt | 216 ++++++++++++++++++++++++++-------------
1 files changed, 144 insertions(+), 72 deletions(-)
diff --git a/pep-0454.txt b/pep-0454.txt
--- a/pep-0454.txt
+++ b/pep-0454.txt
@@ -161,13 +161,20 @@
``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 @@
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 @@
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 @@
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 @@
``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 @@
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 @@
``'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 @@
``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 @@
Statistic
---------
-``Statistic(key, size, size_diff, count, count_diff)`` class:
+``Statistic`` class:
Statistic on memory allocations.
@@ -442,25 +438,101 @@
``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
--
Repository URL: http://hg.python.org/peps
More information about the Python-checkins
mailing list