Move clear_malloc_data into Profile and add more documentation

base/deprecated.jl

@@ -86,6 +86,9 @@ const Ranges = Range
 export Range1
 const Range1 = UnitRange
 
+export clear_malloc_data
+@deprecate clear_malloc_data() Profile.clear_malloc_data()
+
 @deprecate set_rounding(r::RoundingMode) set_rounding(Float64,r)
 @deprecate get_rounding() get_rounding(Float64)
 @deprecate with_rounding(f::Function, r::RoundingMode) with_rounding(f::Function, Float64, r)

base/exports.jl

@@ -1090,7 +1090,6 @@ export
     gc_disable,
     gc_enable,
     precompile,
-    clear_malloc_data,
 
 # misc
     atexit,

base/profile.jl

@@ -82,6 +82,13 @@ callers(funcname::ByteString; kwargs...) = callers(funcname, retrieve()...; kwar
 callers(func::Function, bt::Vector{Uint}, lidict; kwargs...) = callers(string(func), bt, lidict; kwargs...)
 callers(func::Function; kwargs...) = callers(string(func), retrieve()...; kwargs...)
 
+##
+## For --track-allocation
+##
+# Reset the malloc log. Used to avoid counting memory allocated during
+# compilation.
+clear_malloc_data() = ccall(:jl_clear_malloc_data, Void, ())
+
 
 ####
 #### Internal interface

base/util.jl

@@ -12,9 +12,6 @@ gc_time_ns() = ccall(:jl_gc_total_hrtime, Uint64, ())
 # total number of bytes allocated so far
 gc_bytes() = ccall(:jl_gc_total_bytes, Int64, ())
 
-# reset the malloc log. Used to avoid counting memory allocated during compilation.
-clear_malloc_data() = ccall(:jl_clear_malloc_data, Void, ())
-
 function tic()
     t0 = time_ns()
     task_local_storage(:TIMERS, (t0, get(task_local_storage(), :TIMERS, ())))

doc/manual/performance-tips.rst

@@ -109,7 +109,7 @@ diagnose problems and improve the performance of your code:
   suspect a type problem.  You can also start julia with the
   ``--track-allocation=user`` option and examine the resulting
   ``*.mem`` files to see information about where those allocations
-  occur.
+  occur.  See :ref:`stdlib-track-allocation`.
 
 - The `TypeCheck <https://github.com/astrieanna/TypeCheck.jl>`_
   package can help identify certain kinds of type problems. A more

doc/stdlib/base.rst

@@ -139,14 +139,6 @@ Getting Around
 
    This function should only be used interactively.
 
-.. function:: clear_malloc_data()
-
-   Clears any stored memory allocation data when running julia with
-   ``--track-allocation``.  Execute the command(s) you want to test
-   (to force JIT-compilation), then call ``clear_malloc_data()``.
-   Then execute your command(s) again, quit julia, and examine the
-   resulting ``*.mem`` files.
-
 All Objects
 -----------
 

doc/stdlib/profile.rst

@@ -293,6 +293,42 @@ as well as increase it; however, the overhead of profiling grows once
 the delay becomes similar to the amount of time needed to take a
 backtrace (~30 microseconds on the author's laptop).
 
+.. _stdlib-track-allocation:
+
+Direct analysis of memory allocation
+====================================
+
+One of the most common techniques to improve performance is to reduce
+memory allocation.  The total amount of allocation can be measured
+with ``@time`` and ``@allocated``, and specific lines triggering
+allocation can often be inferred from profiling via the cost of
+garbage collection that these lines incur.  However, sometimes it is
+more efficient to directly measure the amount of memory allocated by
+each line of code.
+
+To measure allocation line-by-line, start julia with the
+``--track-allocation=<setting>`` command-line option, for which you
+can choose ``none`` (the default, do not measure allocation), ``user``
+(measure memory allocation everywhere except julia's core code), or
+``all`` (measure memory allocation at each line of julia code).
+Allocation gets measured for each line of compiled code.  When you quit
+julia, the cumulative results are written to text files with ``.mem``
+appended after the file name, residing in the same directory as the
+source file.  Each line lists the total number of bytes allocated.
+The ``Coverage`` package contains some elementary analysis tools, for
+example to sort the lines in order of number of bytes allocated.
+
+In interpreting the results, there are a few important details.  Under
+the ``user`` setting, the first line of any function directly called
+from the REPL will exhibit allocation due to events that happen in the
+REPL code itself.  More significantly, JIT-compilation also adds to
+allocation counts, because much of julia's compiler is written in
+Julia (and compilation usually requires memory allocation).  The
+recommended procedure it to force compilation by executing all the
+commands you want to analyze, then call ``clear_malloc_data()`` to
+reset all allocation counters.  Finally, execute the desired commands
+and quit julia to trigger the generation of the ``.mem`` files.
+
 Function reference
 ------------------
 
@@ -366,3 +402,11 @@ Function reference
    about the caller.  One can optionally supply backtrace data
    obtained from ``retrieve``; otherwise, the current internal profile
    buffer is used.
+
+.. function:: clear_malloc_data()
+
+   Clears any stored memory allocation data when running julia with
+   ``--track-allocation``.  Execute the command(s) you want to test
+   (to force JIT-compilation), then call ``clear_malloc_data()``.
+   Then execute your command(s) again, quit julia, and examine the
+   resulting ``*.mem`` files.