diff --git a/pep-0454.txt b/pep-0454.txt index 2fc4d8933..828640af0 100644 --- a/pep-0454.txt +++ b/pep-0454.txt @@ -110,15 +110,15 @@ Main Functions ``reset()`` function: - Clear traces and statistics on Python memory allocations. + Clear traces of memory blocks allocated by Python. See also ``disable()``. ``disable()`` function: - Stop tracing Python memory allocations and clear traces and - statistics. + Stop tracing Python memory allocations and clear traces of memory + blocks allocated by Python. See also ``enable()`` and ``is_enabled()`` functions. @@ -130,23 +130,6 @@ Main Functions See also ``disable()`` and ``is_enabled()`` functions. -``get_stats()`` function: - - Get statistics on traced Python memory blocks as a dictionary - ``{filename (str): {line_number (int): stats}}`` where *stats* in a - ``(size: int, count: int)`` tuple, *filename* and *line_number* can - be ``None``. - - *size* is the total size in bytes of all memory blocks allocated on - the line, or *count* is the number of memory blocks allocated on the - line. - - Return an empty dictionary if the ``tracemalloc`` module is - disabled. - - See also the ``get_traces()`` function. - - ``get_traced_memory()`` function: Get the current size and maximum size of memory blocks traced by the @@ -178,58 +161,25 @@ 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 where *filename* and *lineno* can be -``None``. +a ``(filename: str, lineno: int)`` tuple. + +If ``tracemalloc`` failed to get the whole traceback, the traceback may be +empty, truncated or contain ``""`` filename and line number 0. Example of 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``. -``get_object_address(obj)`` function: - - Get the address of the main memory block of the specified Python - object. - - A Python object can be composed by multiple memory blocks, the - function only returns the address of the main memory block. For - example, items of ``dict`` and ``set`` containers are stored in a - second memory block. - - See also ``get_object_traceback()`` and ``gc.get_referrers()`` - functions. - - .. note:: - - The builtin function ``id()`` returns a different address for - objects tracked by the garbage collector, because ``id()`` - returns the address after the garbage collector header. - - ``get_object_traceback(obj)`` function: Get the traceback where the Python object *obj* was allocated. - Return a tuple of ``(filename: str, lineno: int)`` tuples, - *filename* and *lineno* can be ``None``. + Return a tuple of ``(filename: str, lineno: int)`` tuples. - Return ``None`` if the ``tracemalloc`` module did not trace the - allocation of the object. + Return ``None`` if the ``tracemalloc`` module is disabled or did not + trace the allocation of the object. - See also ``get_object_address()``, ``gc.get_referrers()`` and - ``sys.getsizeof()`` functions. - - -``get_trace(address)`` function: - - Get the trace of a memory block allocated by Python. Return a tuple: - ``(size: int, traceback)``, *traceback* is a tuple of ``(filename: - str, lineno: int)`` tuples, *filename* and *lineno* can be ``None``. - - Return ``None`` if the ``tracemalloc`` module did not trace the - allocation of the memory block. - - See also ``get_object_traceback()``, ``get_stats()`` and - ``get_traces()`` functions. + See also ``gc.get_referrers()`` and ``sys.getsizeof()`` functions. ``get_traceback_limit()`` function: @@ -237,24 +187,20 @@ a size of 32 bytes and was allocated at ``x.py:7``, line called from line Get the maximum number of frames stored in the traceback of a trace. By default, a trace of an allocated memory block only stores the - most recent frame: the limit is ``1``. This limit is enough to get - statistics using ``get_stats()``. + most recent frame: the limit is ``1``. Use the ``set_traceback_limit()`` function to change the limit. ``get_traces()`` function: - Get traces of all memory blocks allocated by Python. Return a - dictionary: ``{address (int): trace}``, *trace* is a ``(size: int, - traceback)`` tuple, *traceback* is a tuple of ``(filename: str, - lineno: int)`` tuples, *filename* and *lineno* can be None. + Get traces of all memory blocks allocated by Python. Return a list + of ``(size: int, traceback: tuple)`` tuples. *traceback* is a tuple + of ``(filename: str, lineno: int)`` tuples. - Return an empty dictionary if the ``tracemalloc`` module is - disabled. + Return an empty list if the ``tracemalloc`` module is disabled. - See also ``get_object_traceback()``, ``get_stats()`` and - ``get_trace()`` functions. + See also the ``get_object_traceback()`` function. ``set_traceback_limit(nframe: int)`` function: @@ -273,6 +219,18 @@ a size of 32 bytes and was allocated at ``x.py:7``, line called from line limit at startup. +``take_snapshot()`` function: + + Take a snapshot of traces of memory blocks allocated by Python. + + Tracebacks of traces are limited to ``traceback_limit`` frames. Use + ``set_traceback_limit()`` to store more frames. + + The ``tracemalloc`` module must be enabled to take a snapshot, see + the the ``enable()`` function. + + + Filter Functions ---------------- @@ -289,31 +247,6 @@ Filter Functions The new filter is not applied on already collected traces. Use the ``reset()`` function to ensure that all traces match the new filter. -``add_inclusive_filter(filename_pattern: str, lineno: int=None, traceback: bool=False)`` function: - - Add an inclusive filter: helper for the ``add_filter()`` function - creating a ``Filter`` instance with the ``Filter.include`` attribute - set to ``True``. - - The ``*`` joker character can be used in *filename_pattern* to match - any substring, including empty string. - - Example: ``tracemalloc.add_inclusive_filter(subprocess.__file__)`` - only includes memory blocks allocated by the ``subprocess`` module. - - -``add_exclusive_filter(filename_pattern: str, lineno: int=None, traceback: bool=False)`` function: - - Add an exclusive filter: helper for the ``add_filter()`` function - creating a ``Filter`` instance with the ``Filter.include`` attribute - set to ``False``. - - The ``*`` joker character can be used in *filename_pattern* to match - any substring, including empty string. - - Example: ``tracemalloc.add_exclusive_filter(tracemalloc.__file__)`` - ignores memory blocks allocated by the ``tracemalloc`` module. - ``clear_filters()`` function: @@ -348,6 +281,8 @@ Filter comparison is case insensitive and the alternative separator ``/`` is replaced with the standard separator ``\``. + Use ``Filter(False, "")`` to exclude empty tracebacks. + ``include`` attribute: If *include* is ``True``, only trace memory blocks allocated in a @@ -359,8 +294,8 @@ Filter ``lineno`` attribute: - Line number (``int``) of the filter. If *lineno* is is ``None`` or - less than ``1``, the filter matches any line number. + Line number (``int``) of the filter. If *lineno* is ``None``, the + filter matches any line number. ``filename_pattern`` attribute: @@ -378,9 +313,9 @@ Filter GroupedStats ------------ -``GroupedStats(timestamp: datetime.datetime, traceback_limit: int, stats: dict, key_type: str, cumulative: bool)`` class: +``GroupedStats(timestamp: datetime.datetime, traceback_limit: int, key_type: str, stats: dict, cumulative: bool)`` class: - Top of allocated memory blocks grouped by *key_type* as a + Statistics of allocated memory blocks grouped by *key_type* as a dictionary. The ``Snapshot.group_by()`` method creates a ``GroupedStats`` @@ -396,10 +331,6 @@ GroupedStats *key*. Set the *sort* parameter to ``False`` to get the list unsorted. - ``None`` values in keys are replaced with an empty string for - filenames or zero for line numbers, because ``str`` and ``int`` - cannot be compared to ``None``. - See also the ``statistics()`` method. ``statistics(sort=True)`` method: @@ -413,10 +344,6 @@ GroupedStats *key*. Set the *sort* parameter to ``False`` to get the list unsorted. - ``None`` values in keys are replaced with an empty string for - filenames or zero for line numbers, because ``str`` and ``int`` - cannot be compared to ``None``. - See also the ``compare_to()`` method. ``cumulative`` attribute: @@ -450,35 +377,16 @@ GroupedStats Snapshot -------- -``Snapshot(timestamp: datetime.datetime, traceback_limit: int, stats: dict=None, traces: dict=None)`` class: +``Snapshot(timestamp: datetime.datetime, traceback_limit: int, traces: dict=None)`` class: - Snapshot of statistics and traces of memory blocks allocated by - Python. + Snapshot of traces of memory blocks allocated by Python. ``apply_filters(filters)`` method: - Apply filters on the ``traces`` and ``stats`` dictionaries, - *filters* is a list of ``Filter`` instances. + Apply filters on the ``traces`` dictionary, *filters* is a list of + ``Filter`` instances. -``create(traces=False)`` classmethod: - - Take a snapshot of statistics and traces of memory blocks allocated - by Python. - - If *traces* is ``True``, ``get_traces()`` is called and its result - is stored in the ``Snapshot.traces`` attribute. This attribute - contains more information than ``Snapshot.stats`` and uses more - memory and more disk space. If *traces* is ``False``, - ``Snapshot.traces`` is set to ``None``. - - Tracebacks of traces are limited to ``traceback_limit`` frames. Call - ``set_traceback_limit()`` before calling ``Snapshot.create()`` to - store more frames. - - The ``tracemalloc`` module must be enabled to take a snapshot, see - the the ``enable()`` function. - ``dump(filename)`` method: Write the snapshot into a file. @@ -495,32 +403,23 @@ Snapshot ``group_by(key_type: str, cumulative: bool=False)`` method: - Group statistics by *key_type* as a ``GroupedStats`` instance: + Group statistics by *key_type*. Return a ``GroupedStats`` instance: - ===================== =================================== ================================ - key_type description type - ===================== =================================== ================================ - ``'filename'`` filename ``str`` - ``'line'`` filename and line number ``(filename: str, lineno: int)`` - ``'address'`` memory block address ``int`` - ``'traceback'`` memory block address with traceback ``(address: int, traceback)`` - ===================== =================================== ================================ - - The ``traceback`` type is a tuple of ``(filename: str, lineno: - int)`` tuples, *filename* and *lineno* can be ``None``. + ===================== ======================== ================================================ + key_type description type + ===================== ======================== ================================================ + ``'filename'`` filename ``str`` + ``'lineno'`` filename and line number ``(filename: str, lineno: int)`` + ``'traceback'`` traceback tuple of ``(filename: str, lineno: int)`` tuples + ===================== ======================== ================================================ If *cumulative* is ``True``, cumulate size and count of memory blocks of all frames of the traceback of a trace, not only the most recent frame. The *cumulative* parameter is set to ``False`` if - *key_type* is ``'address'``, or if the traceback limit is less than - ``2``. + *key_type* is ``'traceback'``, or if the ``traceback_limit`` + attribute is less than ``2``. -``stats`` attribute: - - Statistics on traced Python memory, result of the ``get_stats()`` - function. - ``traceback_limit`` attribute: Maximum number of frames stored in the traceback of ``traces``, @@ -528,8 +427,10 @@ Snapshot ``traces`` attribute: - Traces of Python memory allocations, result of the ``get_traces()`` - function, can be ``None``. + 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. ``timestamp`` attribute: @@ -552,7 +453,6 @@ Statistic Key identifying the statistic. The key type depends on ``GroupedStats.key_type``, see the ``Snapshot.group_by()`` method. - ``count`` attribute: Number of memory blocks (``int``).