http://hg.python.org/peps/rev/50539da3ea22 changeset: 5241:50539da3ea22 user: Victor Stinner <victor.stinner@gmail.com> date: Fri Nov 01 12:05:37 2013 +0100 summary: 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 files: pep-0454.txt | 87 ++++++++++++++++++++++++++++++++++----- 1 files changed, 75 insertions(+), 12 deletions(-) diff --git a/pep-0454.txt b/pep-0454.txt --- a/pep-0454.txt +++ b/pep-0454.txt @@ -117,20 +117,23 @@ ``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 @@ ``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 @@ 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 @@ 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 @@ 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 @@ 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. -- Repository URL: http://hg.python.org/peps