[Python-Dev] PEP 454 (tracemalloc) disable ==> clear?

[Stephen J. Turnbull]

Victor Stinner writes:

 > 2013/10/29 Jim Jewett <jimjjewett at gmail.com>:
 > >     reset() function:
 > >
 > >         Clear traces of memory blocks allocated by Python.
 > >
 > > Does this do anything besides clear?  If not, why not just re-use the
 > > 'clear' name from dicts?
 > 
 > (I like the reset() name. Charles-François suggested this name
 > inspired by OProfile API.)

Just "reset" implies to me that you're ready to start over.  Not just
traced memory blocks but accumulated statistics and any configuration
(such as Filters) would also be reset.  Also tracing would be disabled
until started explicitly.

If you want it to apply just to the traces, reset_traces() would be
more appropriate.

 > >     disable() function:
 > >
 > >         Stop tracing Python memory allocations and clear traces of
 > >         memory blocks allocated by Python.
 > >
 > > I would disable to stop tracing, but I would not expect it to clear
 > > out the traces it had already captured.  If it has to do that, please
 > > put in some sample code showing how to save the current traces before
 > > disabling.
 > 
 > For consistency, you cannot keep traces when tracing is disabled. The
 > free() must be enabled to remove allocated memory blocks, or next
 > malloc() may get the same address which would raise an assertion error
 > (you cannot have two memory blocks at the same address).

Then I would not call this "disable".  disable() should not "destroy" data.

 > Just call get_traces() to get traces before clearing them. I can
 > explain it in the doc.

Shouldn't disable() do this automatically, perhaps with an optional
discard_traces flag (which would be False by default)?

But I definitely agree with Jim:  You *must* provide an example here
showing how to save the traces (even though it's trivial to do so),
because that will make clear that disable() is a destructive
operation.  (It is not destructive in any other debugging tool that
I've used.)  Even with documentation, be prepared for user complaints.