@c DO NOT EDIT!  Generated automatically by munge-texi.pl.

@c Copyright (C) 1996-2025 The Octave Project Developers
@c
@c This file is part of Octave.
@c
@c Octave is free software: you can redistribute it and/or modify it
@c under the terms of the GNU General Public License as published by
@c the Free Software Foundation, either version 3 of the License, or
@c (at your option) any later version.
@c
@c Octave is distributed in the hope that it will be useful, but
@c WITHOUT ANY WARRANTY; without even the implied warranty of
@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
@c GNU General Public License for more details.
@c
@c You should have received a copy of the GNU General Public License
@c along with Octave; see the file COPYING.  If not, see
@c <https://www.gnu.org/licenses/>.

@node Debugging
@chapter Debugging

Octave includes a built-in debugger to aid in the development of
scripts.  This can be used to interrupt the execution of an Octave script
at a certain point, or when certain conditions are met.  Once execution
has stopped, and debug mode is entered, the symbol table at the point
where execution has stopped can be examined and modified to check for
errors.

The normal command-line editing and history functions are available in
debug mode.

@menu
* Entering Debug Mode::
* Leaving Debug Mode::
* Breakpoints::
* Debug Mode::
* Call Stack::
* Profiling::
* Profiler Example::
@end menu

@node Entering Debug Mode
@section Entering Debug Mode

There are two basic means of interrupting the execution of an Octave
script.  These are breakpoints (@pxref{Breakpoints}), discussed in the next
section, and interruption based on some condition.

Octave supports three means to stop execution based on the values set in
the functions @code{debug_on_interrupt}, @code{debug_on_warning}, and
@code{debug_on_error}.

@c debug_on_interrupt libinterp/corefcn/sighandlers.cc
@anchor{XREFdebug_on_interrupt}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{val} =} debug_on_interrupt ()
@deftypefnx {} {@var{old_val} =} debug_on_interrupt (@var{new_val})
@deftypefnx {} {@var{old_val} =} debug_on_interrupt (@var{new_val}, "local")
Query or set the internal variable that controls whether Octave will try
to enter debugging mode when it receives an interrupt signal (typically
generated with @kbd{C-c}).

If a second interrupt signal is received before reaching the debugging mode,
a normal interrupt will occur.

When called from inside a function with the @qcode{"local"} option, the
variable is changed locally for the function and any subroutines it calls.
The original variable value is restored when exiting the function.
@xseealso{@ref{XREFdebug_on_error,,debug_on_error}, @ref{XREFdebug_on_warning,,debug_on_warning}}
@end deftypefn


@c debug_on_warning libinterp/corefcn/error.cc
@anchor{XREFdebug_on_warning}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{val} =} debug_on_warning ()
@deftypefnx {} {@var{old_val} =} debug_on_warning (@var{new_val})
@deftypefnx {} {@var{old_val} =} debug_on_warning (@var{new_val}, "local")
Query or set the internal variable that controls whether Octave will try
to enter the debugger when a warning is encountered.

When called from inside a function with the @qcode{"local"} option, the
variable is changed locally for the function and any subroutines it calls.
The original variable value is restored when exiting the function.
@xseealso{@ref{XREFdebug_on_error,,debug_on_error}, @ref{XREFdebug_on_interrupt,,debug_on_interrupt}}
@end deftypefn


@c debug_on_error libinterp/corefcn/error.cc
@anchor{XREFdebug_on_error}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{val} =} debug_on_error ()
@deftypefnx {} {@var{old_val} =} debug_on_error (@var{new_val})
@deftypefnx {} {@var{old_val} =} debug_on_error (@var{new_val}, "local")
Query or set the internal variable that controls whether Octave will try
to enter the debugger when an error is encountered.

This will also inhibit printing of the normal traceback message (you will
only see the top-level error message).

When called from inside a function with the @qcode{"local"} option, the
variable is changed locally for the function and any subroutines it calls.
The original variable value is restored when exiting the function.
@xseealso{@ref{XREFdebug_on_warning,,debug_on_warning}, @ref{XREFdebug_on_interrupt,,debug_on_interrupt}}
@end deftypefn


@node Leaving Debug Mode
@section Leaving Debug Mode

Use either @code{dbcont} or @code{return} to leave the debug mode and
continue the normal execution of the script.

@c dbcont libinterp/corefcn/debug.cc
@anchor{XREFdbcont}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {} dbcont
Leave command-line debugging mode and continue code execution normally.
@xseealso{@ref{XREFdbstep,,dbstep}, @ref{XREFdbquit,,dbquit}}
@end deftypefn


To quit debug mode and return directly to the prompt without executing
any additional code use @code{dbquit}.

@c dbquit libinterp/corefcn/debug.cc
@anchor{XREFdbquit}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} dbquit
@deftypefnx {} {} dbquit all
Quit debugging mode immediately without further code execution.

With no arguments, exit the current debugging level.  With argument @code{all},
exit all debugging levels and return to the Octave prompt.
@xseealso{@ref{XREFdbcont,,dbcont}, @ref{XREFdbstep,,dbstep}}
@end deftypefn


Finally, typing @code{exit} or @code{quit} at the debug prompt will
result in Octave terminating normally.

@node Breakpoints
@section Breakpoints

Breakpoints can be set in any m-file function by using the @code{dbstop}
function.

@c dbstop libinterp/corefcn/debug.cc
@anchor{XREFdbstop}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} dbstop @var{fcn}
@deftypefnx {} {} dbstop @var{fcn} @var{line}
@deftypefnx {} {} dbstop @var{fcn} @var{line1} @var{line2} @dots{}
@deftypefnx {} {} dbstop @var{line1} @dots{}
@deftypefnx {} {} dbstop in @var{fcn}
@deftypefnx {} {} dbstop in @var{fcn} at @var{line}
@deftypefnx {} {} dbstop in @var{fcn} at @var{line} if "@var{condition}"
@deftypefnx {} {} dbstop in @var{class} at @var{method}
@deftypefnx {} {} dbstop if @var{event}
@deftypefnx {} {} dbstop if @var{event} @var{ID}
@deftypefnx {} {} dbstop (@var{bp_struct})
@deftypefnx {} {@var{rline} =} dbstop (@dots{})

Set breakpoints for the built-in debugger.

@var{fcn} is the name of a function on the current @code{path}.  When
already in debug mode the @var{fcn} argument can be omitted and the current
function will be used.  Breakpoints at subfunctions are set with the scope
operator @samp{>}.  For example, If @file{file.m} has a subfunction
@code{fcn2}, then a breakpoint in @code{fcn2} can be specified by
@code{file>fcn2}.

@var{line} is the line number at which to break.  If @var{line} is not
specified, it defaults to the first executable line in the file
@file{fcn.m}.  Multiple lines can be specified in a single command; when
function syntax is used, the lines may also be passed as a single vector
argument (@code{[@var{line1}, @var{line2}, @dots{}]}).

@var{condition} is any Octave expression that can be evaluated in the code
context that exists at the breakpoint.  When the breakpoint is encountered,
@var{condition} will be evaluated, and execution will stop if
@var{condition} is true.  If @var{condition} cannot be evaluated, for
example because it refers to an undefined variable, an error will be thrown.
Expressions with side effects (such as @code{y++ > 1}) will alter variables,
and should generally be avoided.  Conditions containing quotes (@samp{"},
@samp{'}) or comment characters (@samp{#}, @samp{%}) must be enclosed in
quotes.  (This does not apply to conditions entered from the editor's context
menu.)  For example:

@example
dbstop in axis at 246 if 'any (opt == "x")'
@end example

The form specifying @var{event} does not cause a specific breakpoint at a given
function and line number.  Instead it causes debug mode to be entered when
certain unexpected events are encountered.  Possible values are

@table @code
@item error
Stop when an error is reported.  This is equivalent to specifying both
@code{debug_on_error (true)} and @code{debug_on_interrupt (true)}.

@item caught error
Stop when an error is caught by a try-catch block (not yet implemented).

@item interrupt
Stop when an interrupt (@kbd{Ctrl-C}) occurs.

@item naninf
Stop when code returns a non-finite value (not yet implemented).

@item warning
Stop when a warning is reported.  This is equivalent to specifying
@code{debug_on_warning (true)}.
@end table

The events @code{error}, @code{caught error}, and @code{warning} can all be
followed by a string specifying an error ID or warning ID@.  If that is done,
only errors with the specified ID will cause execution to stop.  To stop on one
of a set of IDs, multiple @code{dbstop} commands must be issued.

Breakpoints and events can be removed using the @code{dbclear} command with
the same syntax.

It is possible to save all breakpoints and restore them at once by issuing
the commands @code{bp_state = dbstatus; @dots{}; dbstop (bp_state)}.

The optional output @var{rline} is the real line number where the breakpoint
was set.  This can differ from the specified line if the line is not
executable.  For example, if a breakpoint attempted on a blank line then Octave
will set the real breakpoint at the next executable line.

When a file is re-parsed, such as when it is modified outside the GUI, all
breakpoints within the file are cleared.

@xseealso{@ref{XREFdbclear,,dbclear}, @ref{XREFdbstatus,,dbstatus}, @ref{XREFdbstep,,dbstep}, @ref{XREFdebug_on_error,,debug_on_error}, @ref{XREFdebug_on_warning,,debug_on_warning}, @ref{XREFdebug_on_interrupt,,debug_on_interrupt}}
@end deftypefn


@noindent
Breakpoints in class methods are also supported (e.g.,
@code{dbstop ("@@class/method")}).  However, breakpoints cannot be set in
built-in functions (e.g., @code{sin}, etc.@:) or dynamically loaded functions
(i.e., oct-files).

To set a breakpoint immediately upon entering a function use line number 1, or
omit the line number entirely and just give the function name.  When setting
the breakpoint Octave will ignore the leading comment block, and the breakpoint
will be set on the first executable statement in the function.  For example:

@example
@group
dbstop ("asind", 1)
@result{} 29
@end group
@end example

@noindent
Note that the return value of @code{29} means that the breakpoint was
effectively set to line 29.  The status of breakpoints in a function can
be queried with @code{dbstatus}.

@c dbstatus libinterp/corefcn/debug.cc
@anchor{XREFdbstatus}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} dbstatus
@deftypefnx {} {} dbstatus @var{fcn}
@deftypefnx {} {@var{bp_list} =} dbstatus ()
@deftypefnx {} {@var{bp_list} =} dbstatus (@var{fcn})
Report the location of active breakpoints.

When called with no input or output arguments, print the list of all
functions with breakpoints and the line numbers where those breakpoints are
set.

If a function name @var{fcn} is specified then only report breakpoints
for the named function and its subfunctions.

The optional return argument @var{bp_list} is a struct array with the
following fields:

@table @asis
@item name
The name of the function with a breakpoint.  A subfunction, say @code{fcn2}
within an m-file, say @file{file.m}, is specified as @code{file>fcn2}.

@item file
The name of the m-file where the function code is located.

@item line
The line number with the breakpoint.

@item cond
The condition that must be satisfied for the breakpoint to be active, or
the empty string for unconditional breakpoints.
@end table

@c Note: When @code{dbstatus} is called from the debug prompt within a function,
@c the list of breakpoints is automatically trimmed to the breakpoints in the
@c current function.
If @code{dbstop if error} is true but no explicit IDs are specified, the
return value will have an empty field called @qcode{"errs"}.  If IDs are
specified, the @code{errs} field will have one row per ID@.  If
@code{dbstop if error} is false, there is no @qcode{"errs"} field.
The @qcode{"warn"} field is set similarly by @code{dbstop if warning}.

@xseealso{@ref{XREFdbstop,,dbstop}, @ref{XREFdbclear,,dbclear}, @ref{XREFdbwhere,,dbwhere}, @ref{XREFdblist,,dblist}, @ref{XREFdbstack,,dbstack}}
@end deftypefn


@noindent
Reusing the previous example, @code{dbstatus ("asind")} will return
29.  The breakpoints listed can then be cleared with the @code{dbclear}
function.

@c dbclear libinterp/corefcn/debug.cc
@anchor{XREFdbclear}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} dbclear @var{fcn}
@deftypefnx {} {} dbclear @var{fcn} @var{line}
@deftypefnx {} {} dbclear @var{fcn} @var{line1} @var{line2} @dots{}
@deftypefnx {} {} dbclear @var{line} @dots{}
@deftypefnx {} {} dbclear all
@deftypefnx {} {} dbclear in @var{fcn}
@deftypefnx {} {} dbclear in @var{fcn} at @var{line}
@deftypefnx {} {} dbclear if @var{event}
@deftypefnx {} {} dbclear ("@var{fcn}")
@deftypefnx {} {} dbclear ("@var{fcn}", @var{line})
@deftypefnx {} {} dbclear ("@var{fcn}", @var{line1}, @var{line2}, @dots{})
@deftypefnx {} {} dbclear ("@var{fcn}", @var{line1}, @dots{})
@deftypefnx {} {} dbclear (@var{line}, @dots{})
@deftypefnx {} {} dbclear ("all")
Delete a breakpoint at line number @var{line} in the function @var{fcn}.

Arguments are

@table @var
@item fcn
Function name as a string variable.  When already in debug mode this
argument can be omitted and the current function will be used.

@item line
Line number from which to remove a breakpoint.  Multiple lines may be given
as separate arguments or as a vector.

@item event
An event such as @code{error}, @code{interrupt}, or @code{warning}
(@pxref{XREFdbstop,,@code{dbstop}} for details).
@end table

When called without a line number specification all breakpoints in the named
function are cleared.

If the requested line is not a breakpoint no action is performed.

The special keyword @qcode{"all"} will clear all breakpoints from all
files.
@xseealso{@ref{XREFdbstop,,dbstop}, @ref{XREFdbstatus,,dbstatus}, @ref{XREFdbwhere,,dbwhere}}
@end deftypefn


@noindent

A breakpoint may also be set in a subfunction.  For example, if a file contains
the functions

@example
@group
function y = func1 (x)
  y = func2 (x);
endfunction
function y = func2 (x)
  y = x + 1;
endfunction
@end group
@end example

@noindent
then a breakpoint can be set at the start of the subfunction directly with

@example
@group
dbstop func1>func2
@result{} 5
@end group
@end example

Note that @samp{>} is the character that distinguishes subfunctions from the
m-file containing them.

Another simple way of setting a breakpoint in an Octave script is the
use of the @code{keyboard} function.

@c keyboard libinterp/corefcn/input.cc
@anchor{XREFkeyboard}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} keyboard ()
@deftypefnx {} {} keyboard ("@var{prompt}")
Stop m-file execution and enter debug mode.

When the @code{keyboard} function is executed, Octave prints a prompt and
waits for user input.  The input strings are then evaluated and the results
are printed.  This makes it possible to examine the values of variables
within a function, and to assign new values if necessary.  To leave the
prompt and return to normal execution type @samp{return} or @samp{dbcont}.
The @code{keyboard} function does not return an exit status.

If @code{keyboard} is invoked without arguments, a default prompt of
@samp{debug> } is used.
@xseealso{@ref{XREFdbstop,,dbstop}, @ref{XREFdbcont,,dbcont}, @ref{XREFdbquit,,dbquit}}
@end deftypefn


@noindent
The @code{keyboard} function is placed in a script at the point where the user
desires that the execution be stopped.  It automatically sets the running
script into the debug mode.

@node Debug Mode
@section Debug Mode

There are three additional support functions that allow the user to
find out where in the execution of a script Octave entered the debug
mode, and to print the code in the script surrounding the point where
Octave entered debug mode.

@c dbwhere libinterp/corefcn/debug.cc
@anchor{XREFdbwhere}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {} dbwhere
In debugging mode, report the current file and line number where execution
is stopped.
@xseealso{@ref{XREFdbstack,,dbstack}, @ref{XREFdblist,,dblist}, @ref{XREFdbstatus,,dbstatus}, @ref{XREFdbcont,,dbcont}, @ref{XREFdbstep,,dbstep}, @ref{XREFdbup,,dbup}, @ref{XREFdbdown,,dbdown}}
@end deftypefn


@c dbtype libinterp/corefcn/debug.cc
@anchor{XREFdbtype}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} dbtype
@deftypefnx {} {} dbtype @var{lineno}
@deftypefnx {} {} dbtype @var{startl:endl}
@deftypefnx {} {} dbtype @var{startl}:end
@deftypefnx {} {} dbtype @var{fcn}
@deftypefnx {} {} dbtype @var{fcn} @var{lineno}
@deftypefnx {} {} dbtype @var{fcn} @var{startl:endl}
@deftypefnx {} {} dbtype @var{fcn} @var{startl}:end
Display a script file with line numbers.

When called with no arguments in debugging mode, display the script file
currently being debugged.

An optional range specification can be used to list only a portion of the
file.  The special keyword @qcode{"end"} is a valid line number specification
for the last line of the file.

When called with the name of a function, list that script file with line
numbers.
@xseealso{@ref{XREFdblist,,dblist}, @ref{XREFdbwhere,,dbwhere}, @ref{XREFdbstatus,,dbstatus}, @ref{XREFdbstop,,dbstop}}
@end deftypefn


@c dblist libinterp/corefcn/debug.cc
@anchor{XREFdblist}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} dblist
@deftypefnx {} {} dblist @var{n}
In debugging mode, list @var{n} lines of the function being debugged
centered around the current line to be executed.

If unspecified @var{n} defaults to 10 (+/- 5 lines)
@xseealso{@ref{XREFdbwhere,,dbwhere}, @ref{XREFdbtype,,dbtype}, @ref{XREFdbstack,,dbstack}}
@end deftypefn


You may also use @code{isdebugmode} to determine whether the debugger is
currently active.

@c isdebugmode libinterp/corefcn/debug.cc
@anchor{XREFisdebugmode}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} isdebugmode ()
Return true if in debugging mode, otherwise false.
@xseealso{@ref{XREFdbwhere,,dbwhere}, @ref{XREFdbstack,,dbstack}, @ref{XREFdbstatus,,dbstatus}}
@end deftypefn


Debug mode also allows single line stepping through a function using
the command @code{dbstep}.

@c dbstep libinterp/corefcn/debug.cc
@anchor{XREFdbstep}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} dbstep
@deftypefnx {} {} dbstep @var{n}
@deftypefnx {} {} dbstep in
@deftypefnx {} {} dbstep out
@deftypefnx {} {} dbnext @dots{}
In debugging mode, execute the next @var{n} lines of code.

If @var{n} is omitted, execute the next single line of code.  If the next
line of code is itself defined in terms of an m-file remain in the existing
function.

Using @code{dbstep in} will cause execution of the next line to step into
any m-files defined on the next line.

Using @code{dbstep out} will cause execution to continue until the current
function returns.

Programming Note: @code{dbnext} is an alias for @code{dbstep} and can be used
interchangeably.
@xseealso{@ref{XREFdbcont,,dbcont}, @ref{XREFdbquit,,dbquit}}
@end deftypefn


When in debug mode the @key{RETURN} key will execute the last entered command.
This is useful, for example, after hitting a breakpoint and entering
@code{dbstep} once.  After that, one can advance line by line through the code
with only a single key stroke.  This feature may be disabled using the
@code{auto_repeat_debug_command} function.

@c auto_repeat_debug_command libinterp/corefcn/input.cc
@anchor{XREFauto_repeat_debug_command}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{val} =} auto_repeat_debug_command ()
@deftypefnx {} {@var{old_val} =} auto_repeat_debug_command (@var{new_val})
@deftypefnx {} {@var{old_val} =} auto_repeat_debug_command (@var{new_val}, "local")
Query or set the internal variable that controls whether debugging
commands are automatically repeated when the input line is empty (typing
just @key{RET}).

When called from inside a function with the @qcode{"local"} option, the
variable is changed locally for the function and any subroutines it calls.
The original variable value is restored when exiting the function.
@end deftypefn


@node Call Stack
@section Call Stack

The function being debugged may be the leaf node of a series of function calls.
After examining values in the current subroutine it may turn out that the
problem occurred in earlier pieces of code.  Use @code{dbup} and @code{dbdown}
to move up and down through the series of function calls to locate where
variables first took on the wrong values.  @code{dbstack} shows the entire
series of function calls and at what level debugging is currently taking place.

@c dbstack libinterp/corefcn/debug.cc
@anchor{XREFdbstack}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} dbstack
@deftypefnx {} {} dbstack @var{n}
@deftypefnx {} {} dbstack @var{-completenames}
@deftypefnx {} {[@var{stack}, @var{idx}] =} dbstack (@dots{})
Display or return current debugging function stack information.

With optional argument @var{n}, omit the @var{n} innermost stack frames.

Although accepted, the argument @var{-completenames} is silently ignored.
Octave always returns absolute filenames.

The arguments @var{n} and @var{-completenames} can both be specified and may
appear in any order.

The optional return argument @var{stack} is a struct array with the
following fields:

@table @asis
@item file
The name of the m-file where the function code is located.

@item name
The name of the function with a breakpoint.

@item line
The line number of an active breakpoint.

@item column
The column number of the line where the breakpoint begins.

@end table

The return argument @var{idx} specifies which element of the @var{stack}
struct array is currently active.
@xseealso{@ref{XREFdbup,,dbup}, @ref{XREFdbdown,,dbdown}, @ref{XREFdbwhere,,dbwhere}, @ref{XREFdblist,,dblist}, @ref{XREFdbstatus,,dbstatus}}
@end deftypefn


@c dbup libinterp/corefcn/debug.cc
@anchor{XREFdbup}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} dbup
@deftypefnx {} {} dbup @var{n}
In debugging mode, move up the execution stack @var{n} frames.

If @var{n} is omitted, move up one frame.
@xseealso{@ref{XREFdbstack,,dbstack}, @ref{XREFdbdown,,dbdown}}
@end deftypefn


@c dbdown libinterp/corefcn/debug.cc
@anchor{XREFdbdown}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} dbdown
@deftypefnx {} {} dbdown @var{n}
In debugging mode, move down the execution stack @var{n} frames.

If @var{n} is omitted, move down one frame.
@xseealso{@ref{XREFdbstack,,dbstack}, @ref{XREFdbup,,dbup}}
@end deftypefn


@node Profiling
@section Profiling
@cindex profiler
@cindex code 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 @code{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.

@c profile scripts/profiler/profile.m
@anchor{XREFprofile}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} profile on
@deftypefnx {} {} profile off
@deftypefnx {} {} profile resume
@deftypefnx {} {} profile clear
@deftypefnx {} {@var{S} =} profile ("status")
@deftypefnx {} {@var{T} =} profile ("info")
Control the built-in profiler.

@table @code
@item profile on
Start the profiler.  Any previously collected data is cleared.

@item profile off
Stop profiling.  The collected data can later be retrieved and examined
with @code{T = profile ("info")}.

@item profile clear
Clear all collected profiler data and stop profiling.

@item profile resume
Restart profiling without clearing the old data.  All newly collected
statistics are added to the existing ones.

@item @var{S} = profile ("status")
Return a structure with information about the current status of the
profiler.  At the moment, the only field is @code{ProfilerStatus} which is
either @qcode{"on"} or @qcode{"off"}.

@item @var{T} = profile ("info")
Return the collected profiling statistics in the structure @var{T}.  The
flat profile is returned in the field @code{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
@code{Hierarchical} contains the hierarchical call tree.  Each node has an
index into the @code{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.
@end table

@xseealso{@ref{XREFprofshow,,profshow}, @ref{XREFprofexplore,,profexplore}}
@end deftypefn


An easy way to get an overview over the collected data is
@code{profshow}.  This function takes the profiler data returned by
@code{profile} as input and prints a flat profile, for instance:

@example
@group
 Function Attr     Time (s)        Calls
----------------------------------------
   >myfib    R        2.195        13529
binary <=             0.061        13529
 binary -             0.050        13528
 binary +             0.026         6764
@end group
@end example

This shows that most of the run time was spent executing the function
@samp{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.

@c profshow scripts/profiler/profshow.m
@anchor{XREFprofshow}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} profshow (@var{data})
@deftypefnx {} {} profshow (@var{data}, @var{n})
@deftypefnx {} {} profshow ()
@deftypefnx {} {} profshow (@var{n})
Display flat per-function profiler results.

Print out profiler data (execution time, number of calls) for the most
critical @var{n} functions.  The results are sorted in descending order by
the total time spent in each function.  If @var{n} is unspecified it
defaults to 20.

The input @var{data} is the structure returned by @code{profile ("info")}.
If unspecified, @code{profshow} will use the current profile dataset.

The attribute column displays @samp{R} for recursive functions, and is blank
for all other function types.
@xseealso{@ref{XREFprofexplore,,profexplore}, @ref{XREFprofile,,profile}}
@end deftypefn


@c profexport scripts/profiler/profexport.m
@anchor{XREFprofexport}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} profexport (@var{dir})
@deftypefnx {} {} profexport (@var{dir}, @var{data})
@deftypefnx {} {} profexport (@var{dir}, @var{name})
@deftypefnx {} {} profexport (@var{dir}, @var{name}, @var{data})

Export profiler data as HTML.

Export the profiling data in @var{data} into a series of HTML files in
the folder @var{dir}.  The initial file will be
@file{@var{data}/index.html}.

If @var{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 @var{data} is the structure returned by @code{profile ("info")}.
If unspecified, @code{profexport} will use the current profile dataset.

@xseealso{@ref{XREFprofshow,,profshow}, @ref{XREFprofexplore,,profexplore}, @ref{XREFprofile,,profile}}
@end deftypefn


@c profexplore scripts/profiler/profexplore.m
@anchor{XREFprofexplore}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} profexplore ()
@deftypefnx {} {} profexplore (@var{data})
Interactively explore hierarchical profiler output.

Assuming @var{data} is the structure with profile data returned by
@code{profile (@qcode{"info"})}, this command opens an interactive prompt
that can be used to explore the call-tree.  Type @kbd{help} to get a list
of possible commands.  If @var{data} is omitted, @code{profile ("info")}
is called and used in its place.
@xseealso{@ref{XREFprofile,,profile}, @ref{XREFprofshow,,profshow}}
@end deftypefn


@node Profiler Example
@section Profiler Example

Below, we will give a short example of a profiler session.
@xref{Profiling}, for the documentation of the profiler functions in
detail.  Consider the code:

@example
global N A;

N = 300;
A = rand (N, N);

function xt = timesteps (steps, x0, expM)
  global N;

  if (steps == 0)
    xt = NA (N, 0);
  else
    xt = NA (N, steps);
    x1 = expM * x0;
    xt(:, 1) = x1;
    xt(:, 2 : end) = timesteps (steps - 1, x1, expM);
  endif
endfunction

function foo ()
  global N A;

  initial = @@(x) sin (x);
  x0 = (initial (linspace (0, 2 * pi, N)))';

  expA = expm (A);
  xt = timesteps (100, x0, expA);
endfunction

function fib = bar (N)
  if (N <= 2)
    fib = 1;
  else
    fib = bar (N - 1) + bar (N - 2);
  endif
endfunction
@end example

If we execute the two main functions, we get:

@example
@group
tic; foo; toc;
@result{} Elapsed time is 2.37338 seconds.

tic; bar (20); toc;
@result{} Elapsed time is 2.04952 seconds.
@end group
@end example

But this does not give much information about where this time is spent;
for instance, whether the single call to @code{expm} is more expensive
or the recursive time-stepping itself.  To get a more detailed picture,
we can use the profiler.

@example
@group
profile on;
foo;
profile off;

data = profile ("info");
profshow (data, 10);
@end group
@end example

This prints a table like:

@example
@group
   #  Function Attr     Time (s)        Calls
---------------------------------------------
   7      expm             1.034            1
   3  binary *             0.823          117
  41  binary \             0.188            1
  38  binary ^             0.126            2
  43 timesteps    R        0.111          101
  44        NA             0.029          101
  39  binary +             0.024            8
  34      norm             0.011            1
  40  binary -             0.004          101
  33   balance             0.003            1
@end group
@end example

The entries are the individual functions which have been executed (only
the 10 most important ones), together with some information for each of
them.  The entries like @samp{binary *} denote operators, while other
entries are ordinary functions.  They include both built-ins like
@code{expm} and our own routines (for instance @code{timesteps}).  From
this profile, we can immediately deduce that @code{expm} uses up the
largest proportion of the processing time, even though it is only called
once.  The second expensive operation is the matrix-vector product in the
routine @code{timesteps}.  @footnote{We only know it is the binary
multiplication operator, but fortunately this operator appears only at
one place in the code and thus we know which occurrence takes so much
time.  If there were multiple places, we would have to use the
hierarchical profile to find out the exact place which uses up the time
which is not covered in this example.}

Timing, however, is not the only information available from the profile.
The attribute column shows us that @code{timesteps} calls itself
recursively.  This may not be that remarkable in this example (since it's
clear anyway), but could be helpful in a more complex setting.  As to the
question of why is there a @samp{binary \} in the output, we can easily
shed some light on that too.  Note that @code{data} is a structure array
(@ref{Structure Arrays}) which contains the field @code{FunctionTable}.
This stores the raw data for the profile shown.  The number in the first
column of the table gives the index under which the shown function can
be found there.  Looking up @code{data.FunctionTable(41)} gives:

@example
@group
  scalar structure containing the fields:

    FunctionName = binary \
    TotalTime =  0.18765
    NumCalls =  1
    IsRecursive = 0
    Parents =  7
    Children = [](1x0)
@end group
@end example

Here we see the information from the table again, but have additional
fields @code{Parents} and @code{Children}.  Those are both arrays, which
contain the indices of functions which have directly called the function
in question (which is entry 7, @code{expm}, in this case) or been called
by it (no functions).  Hence, the backslash operator has been used
internally by @code{expm}.

Now let's take a look at @code{bar}.  For this, we start a fresh
profiling session (@code{profile on} does this; the old data is removed
before the profiler is restarted):

@example
@group
profile on;
bar (20);
profile off;

profshow (profile ("info"));
@end group
@end example

This gives:

@example
@group
   #            Function Attr     Time (s)        Calls
-------------------------------------------------------
   1                 bar    R        2.091        13529
   2           binary <=             0.062        13529
   3            binary -             0.042        13528
   4            binary +             0.023         6764
   5             profile             0.000            1
   8               false             0.000            1
   6              nargin             0.000            1
   7           binary !=             0.000            1
   9 __profiler_enable__             0.000            1
@end group
@end example

Unsurprisingly, @code{bar} is also recursive.  It has been called 13,529
times in the course of recursively calculating the Fibonacci number in a
suboptimal way, and most of the time was spent in @code{bar} itself.

Finally, let's say we want to profile the execution of both @code{foo}
and @code{bar} together.  Since we already have the run-time data
collected for @code{bar}, we can restart the profiler without clearing
the existing data and collect the missing statistics about @code{foo}.
This is done by:

@example
@group
profile resume;
foo;
profile off;

profshow (profile ("info"), 10);
@end group
@end example

As you can see in the table below, now we have both profiles mixed
together.

@example
@group
   #  Function Attr     Time (s)        Calls
---------------------------------------------
   1       bar    R        2.091        13529
  16      expm             1.122            1
  12  binary *             0.798          117
  46  binary \             0.185            1
  45  binary ^             0.124            2
  48 timesteps    R        0.115          101
   2 binary <=             0.062        13529
   3  binary -             0.045        13629
   4  binary +             0.041         6772
  49        NA             0.036          101
@end group
@end example