octave: Profiling
13.6 Profiling
==============
Octave supports profiling of code execution on a per-function level. If
profiling is enabled, each call to a function (supporting built-ins,
operators, functions in oct- and mex-files, user-defined functions in
Octave code and anonymous functions) is recorded while running Octave
code. After that, this data can aid in analyzing the code behavior, and
is in particular helpful for finding “hot spots” in the code which use
up a lot of computation time and are the best targets to spend
optimization efforts on.
The main command for profiling is ‘profile’, which can be used to
start or stop the profiler and also to query collected data afterwards.
The data is returned in an Octave data structure which can then be
examined or further processed by other routines or tools.
-- : profile on
-- : profile off
-- : profile resume
-- : profile clear
-- : S = profile ("status")
-- : T = profile ("info")
Control the built-in profiler.
‘profile on’
Start the profiler, clearing all previously collected data if
there is any.
‘profile off’
Stop profiling. The collected data can later be retrieved and
examined with ‘T = profile ("info")’.
‘profile clear’
Clear all collected profiler data.
‘profile resume’
Restart profiling without clearing the old data. All newly
collected statistics are added to the existing ones.
‘S = profile ("status")’
Return a structure with information about the current status
of the profiler. At the moment, the only field is
‘ProfilerStatus’ which is either "on" or "off".
‘T = profile ("info")’
Return the collected profiling statistics in the structure T.
The flat profile is returned in the field ‘FunctionTable’
which is an array of structures, each entry corresponding to a
function which was called and for which profiling statistics
are present. In addition, the field ‘Hierarchical’ contains
the hierarchical call tree. Each node has an index into the
‘FunctionTable’ identifying the function it corresponds to as
well as data fields for number of calls and time spent at this
level in the call tree.
DONTPRINTYET See also: 
profshow XREFprofshow, *noteprofexplore:
DONTPRINTYET See also: profshow XREFprofshow, profexplore
XREFprofexplore.
An easy way to get an overview over the collected data is ‘profshow’.
This function takes the profiler data returned by ‘profile’ as input and
prints a flat profile, for instance:
Function Attr Time (s) Calls
----------------------------------------
>myfib R 2.195 13529
binary <= 0.061 13529
binary - 0.050 13528
binary + 0.026 6764
This shows that most of the run time was spent executing the function
‘myfib’, and some minor proportion evaluating the listed binary
operators. Furthermore, it is shown how often the function was called
and the profiler also records that it is recursive.
-- : profshow (DATA)
-- : profshow (DATA, N)
-- : profshow ()
-- : profshow (N)
Display flat per-function profiler results.
Print out profiler data (execution time, number of calls) for the
most critical N functions. The results are sorted in descending
order by the total time spent in each function. If N is
unspecified it defaults to 20.
The input DATA is the structure returned by ‘profile ("info")’. If
unspecified, ‘profshow’ will use the current profile dataset.
The attribute column displays ‘R’ for recursive functions, and is
blank for all other function types.
DONTPRINTYET See also: profexplore XREFprofexplore, *noteprofile:
DONTPRINTYET See also: profexplore XREFprofexplore, profile
XREFprofile.
-- : profexport (DIR)
-- : profexport (DIR, DATA)
-- : profexport (DIR, NAME)
-- : profexport (DIR, NAME, DATA)
Export profiler data as HTML.
Export the profiling data in DATA into a series of HTML files in
the folder DIR. The initial file will be ‘DATA/index.html’.
If NAME is specified, it must be a string that contains a “name”
for the profile being exported. This name is included in the HTML.
The input DATA is the structure returned by ‘profile ("info")’. If
unspecified, ‘profexport’ will use the current profile dataset.
DONTPRINTYET See also: profshow XREFprofshow, *noteprofexplore:
DONTPRINTYET See also: profshow XREFprofshow, profexplore
XREFprofexplore, profile XREFprofile.
-- : profexplore ()
-- : profexplore (DATA)
Interactively explore hierarchical profiler output.
Assuming DATA is the structure with profile data returned by
‘profile ("info")’, this command opens an interactive prompt that
can be used to explore the call-tree. Type ‘help’ to get a list of
possible commands. If DATA is omitted, ‘profile ("info")’ is
called and used in its place.
See also: profile XREFprofile, profshow XREFprofshow.
Info Catalog
octave: Call Stack
octave: Debugging
octave: Profiler Example