[Python-checkins] peps: PEP 454: rename reset() to clear_traces()

[victor.stinner]

http://hg.python.org/peps/rev/b511af0f336b
changeset:   5236:b511af0f336b
user:        Victor Stinner <victor.stinner at gmail.com>
date:        Wed Oct 30 11:24:34 2013 +0100
summary:
  PEP 454: rename reset() to clear_traces()

Explain also in clear_traces() documentation how to get traces before clearing them.

files:
  pep-0454.txt |  26 +++++++++++++++-----------
  1 files changed, 15 insertions(+), 11 deletions(-)


diff --git a/pep-0454.txt b/pep-0454.txt
--- a/pep-0454.txt
+++ b/pep-0454.txt
@@ -24,12 +24,12 @@
 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 @@
 Main functions
 --------------
 
-``reset()`` function:
+``clear_traces()`` function:
 
     Clear traces of memory blocks allocated by Python.
 
@@ -120,6 +120,9 @@
     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 @@
 ---------------
 
 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 @@
     ``(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 @@
     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 @@
     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 @@
     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:
 

-- 
Repository URL: http://hg.python.org/peps