.. module:: Base.Profile

.. _stdlib-profiling:

Profiling
=========

.. currentmodule:: Base

.. function:: @profile

   ``@profile <expression>`` runs your expression while taking
   periodic backtraces.  These are appended to an internal buffer of
   backtraces.

.. currentmodule:: Base.Profile

.. function:: clear()

   Clear any existing backtraces from the internal buffer.

.. function:: print([io::IO = STDOUT,] [data::Vector]; format = :tree, C = false, combine = true, cols = tty_cols())

   Prints profiling results to ``io`` (by default, ``STDOUT``). If you
   do not supply a ``data`` vector, the internal buffer of accumulated
   backtraces will be used.  ``format`` can be ``:tree`` or
   ``:flat``. If ``C==true``, backtraces from C and Fortran code are
   shown. ``combine==true`` merges instruction pointers that
   correspond to the same line of code.  ``cols`` controls the width
   of the display.

.. function:: print([io::IO = STDOUT,] data::Vector, lidict::Dict; format = :tree, combine = true, cols = tty_cols())

   Prints profiling results to ``io``. This variant is used to examine
   results exported by a previous call to :func:`retrieve`.
   Supply the vector ``data`` of backtraces and a dictionary
   ``lidict`` of line information.

.. function:: init(; n::Integer, delay::Float64)

   Configure the ``delay`` between backtraces (measured in seconds),
   and the number ``n`` of instruction pointers that may be
   stored. Each instruction pointer corresponds to a single line of
   code; backtraces generally consist of a long list of instruction
   pointers. Default settings can be obtained by calling this function
   with no arguments, and each can be set independently using keywords
   or in the order ``(n, delay)``.

.. function:: fetch() -> data

   Returns a reference to the internal buffer of backtraces. Note that
   subsequent operations, like :func:`clear`, can affect
   ``data`` unless you first make a copy. Note that the values in
   ``data`` have meaning only on this machine in the current session,
   because it depends on the exact memory addresses used in
   JIT-compiling. This function is primarily for internal use;
   :func:`retrieve` may be a better choice for most users.

.. function:: retrieve() -> data, lidict

   "Exports" profiling results in a portable format, returning the set
   of all backtraces (``data``) and a dictionary that maps the
   (session-specific) instruction pointers in ``data`` to ``LineInfo``
   values that store the file name, function name, and line
   number. This function allows you to save profiling results for
   future analysis.

.. 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 :func:`clear_malloc_data`.
   Then execute your command(s) again, quit julia, and examine the
   resulting ``*.mem`` files.