Issue 19818: tracemalloc: comments on the doc (original) (raw)

Jim Jewett posted the message to the issue #18874 which is now closed, so I'm opening a new issue. Copy of his message.

These comments refer to http://hg.python.org/cpython/file/5c9af8194d3b/Doc/library/tracemalloc.rst which is newer than the current patches.

I believe I have consolidated the still-open issues that I see (including those that aren't mine) for this file:

http://hg.python.org/cpython/file/5c9af8194d3b/Doc/library/tracemalloc.rst

(line 24, new comment; also repeated at line 315)

frame (1 frame). To store 25 frames at startup: set the :envvar:PYTHONTRACEMALLOC environment variable to 25, or use the :option:-X tracemalloc=25 command line option. ->

frame (1 frame). To store 25 frames at startup: set the :envvar:PYTHONTRACEMALLOC environment variable to 25, or use the :option:-X tracemalloc=25 command line option. If tracing is

started later, the maximum number of frames is a parameter to the

:func:start function.

(line 111)

If the system has little free memory, snapshots can be written on disk using the :meth:Snapshot.dump method to analyze the snapshot offline. Then use the :meth:Snapshot.load method reload the snapshot.

->

Snapshots can be stored to disk using :meth:Snapshot.dump and reloaded using :meth:Snapshot.load.

(line 180, new comment) ... The traceback is where the :mod:importlib loaded data most recently: on the import pdb line of the :mod:doctest module. The traceback may change if a new module is loaded.

->

The traceback represents the call stack when those allocations were made.

As this particular summary is itemized by traceback, it also represents

the call stack for all 903 of those allocations.

(line 252: new comment) .. function:: clear_traces()

Clear traces of memory blocks allocated by Python.

Add "Future allocations will still be traced."

Is this just a shortcut for stop();start() ? If so, please say so. If not, please explain why.

(Line 311: new comment) to measure how much memory is used -> for an approximate measure of how much memory is used

I understand your reluctance to get into too many details, but ... well, it isn't a complete measure. It misses the python objects of tracemalloc itself, it misses the overhead of the module, it misses any filenames that were kept alive only by tracing, etc.

(Line 372, new comment) If inclusive is True (include), only trace memory blocks allocated in a file with a name matching :attr:filename_pattern at line number :attr:lineno.

  If *inclusive* is ``False`` (exclude), ignore memory blocks allocated in
  a file with a name matching :attr:`filename_pattern` at line number
  :attr:`lineno`.

-> If inclusive is True (include), then trace memory blocks allocated in a file with a name matching :attr:filename_pattern at line number :attr:lineno. Also excludes any blocks not selected by any filter.

  If *inclusive* is ``False`` (exclude), ignore memory blocks allocated in
  a file with a name matching :attr:`filename_pattern` at line number
  :attr:`lineno`, even if they would otherwise be included.

(Line 394: new comment) This attribute is ignored if the traceback limit is less than 2. -> This attribute is meaningless if the traceback limit is 1.

Just after Line 428, not quite a new issue: Compute the differences with an old snapshot. Get statistics as a sorted list of :class:StatisticDiff instances grouped by group_by.

->

  Compute the differences with an old snapshot. Get statistics as a sorted
  list of :class:`StatisticDiff` instances grouped by *group_by*.

  Note that applying different Filters can cause spurious differences; users planning to archive a Snapshot may therefore wish to first add various annotations.

(Line 454, new comment) All inclusive filters are applied at once, a trace is ignored if no inclusive filters match it. A trace is ignored if at least one exclusive filter matchs it. -> If there are any inclusive filters, then they are all applied, and traces which do not match at least one of them are excluded. A trace is also ignored if at least one exclusive filter matches it.

Line 544, new comment:

.. attribute:: count_diff

  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.

-> .. attribute:: count_diff

  Difference of number of memory blocks between the old and the new
  snapshots (``int``).  count_diff==count if the memory blocks do not appear in the old snapshot.

Line 558, similar to above: the new snapshots (int): 0 if the memory blocks have been allocated in the new snapshot. -> the new snapshots (int). size_diff==size if the memory blocks do not appear in the old snapshot.

And copy of his second message :

Drat: forgot one at line 277

.. function:: get_traced_memory()

Get the current size and maximum size of memory blocks traced by the :mod:tracemalloc module as a tuple: (size: int, max_size: int).

I have a tendency to read "maximum size" as the most it is willing/able to trace, rather than the most it has traced at a single time so far. I therefore prefer "peak_size".

Also, this doesn't suggests that the object is strictly a tuple, and that results.size or results.peak_size will not work; is that intentional?

Could you please write a patch on Doc/library/tracemalloc.rst? It's really hard to review your raw comments in comments.

You should probably sign the contributor agreement. http://www.python.org/psf/contrib/contrib-form/

""" Is [clear_traces()] just a shortcut for stop();start() ? If so, please say so. """

It's almost the same. clear_traces() does not uninstall and reinstall hooks on memory allocators. I prefer to not give too much details in the high-level documentation.

""" Line 558, similar to above: the new snapshots (int): 0 if the memory blocks have been allocated in the new snapshot. -> the new snapshots (int). size_diff==size if the memory blocks do not appear in the old snapshot. """

This is not correct, size_diff is 0 if memory blocks are new, not size.