PEP 454

* rename disable/enable/is_enabled() to stop/start/is_tracing()
* add disable/enable/is_enabled() which are temporary, and disable() doesn't
  clear traces
* a traceback now always contains a least 1 frame, use (('<unknown>', 0),) if
  the traceback cannot read or if the traceback limit is 0
* write more documentation on filter functions

pep-0454.txt

@@ -117,20 +117,23 @@ Main functions
 
 ``disable()`` function:
 
-    Stop tracing Python memory allocations and clear traces of memory
-    blocks allocated by Python.
+    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.
 
-    Call ``get_traces()`` or ``take_snapshot()`` function to get traces
-    before clearing them.
+    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:
 
-    Start tracing Python memory allocations.
+    Reenable tracing Python memory allocations if was disabled by te
+    ``disable()`` method.
 
-    See also ``disable()`` and ``is_enabled()`` functions.
+    See also ``is_enabled()`` functions.
 
 
 ``get_traced_memory()`` function:
@@ -147,10 +150,50 @@ Main functions
 
 ``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.
 
-    See also ``disable()`` and ``enable()`` functions.
+    The ``tracemalloc`` module only traces new allocations if
+    ``is_tracing()`` and ``is_enabled()`` are ``True``.
+
+    See also ``start()`` and ``stop()`` functions.
+
+
+``stop()`` function:
+
+    Stop tracing Python memory allocations and clear traces of memory
+    blocks allocated by Python.
+
+    The function uninstalls hooks on Python memory allocators, so the
+    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.
+
+    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.
 
 
 ``take_snapshot()`` function:
@@ -177,8 +220,10 @@ traceback)`` tuple. *size* is the size of the memory block in bytes.
 frame, limited to ``get_traceback_limit()`` frames. A frame is
 a ``(filename: str, lineno: int)`` tuple.
 
-If ``tracemalloc`` failed to get the whole traceback, the traceback may be
-empty, truncated or contain ``"<unknown>"`` filename and line number 0.
+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
@@ -238,6 +283,9 @@ has a size of 32 bytes and was allocated at ``x.py:7``, line called from line
     function to measure the overhead and the ``add_filter()`` function
     to select which memory allocations are traced.
 
+    If the limit is set to ``0`` frame, the traceback ``(('<unknown>',
+    0),)`` will be used for all traces.
+
     Use the ``get_traceback_limit()`` function to get the current limit.
 
     The ``PYTHONTRACEMALLOC`` environment variable and the ``-X``
@@ -248,6 +296,24 @@ has a size of 32 bytes and was allocated at ``x.py:7``, line called from line
 Filter functions
 ----------------
 
+Tracing all Python memroy allocations has an important overhead on performances
+and on the memory usage.
+
+To limit the overhead, some files can be excluded or tracing can be restricted
+to a set of files using filters. Examples: ``add_filter(Filter(True,
+subprocess.__file__))`` only traces memory allocations in the ``subprocess``
+module, and ``add_filter(Filter(False, tracemalloc.__file__))`` do not trace
+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.
+
 ``add_filter(filter)`` function:
 
     Add a new filter on Python memory allocations, *filter* is a
@@ -274,9 +340,6 @@ Filter functions
     Get the filters on Python memory allocations. Return a list of
     ``Filter`` instances.
 
-    By default, there is one exclusive filter to ignore Python memory
-    blocks allocated by the ``tracemalloc`` module.
-
     See also the ``clear_filters()`` function.