(maxima.info)Functions and Variables for Debugging
38.3 Functions and Variables for Debugging
==========================================
-- Option variable: debugmode
Default value: 'false'
When a Maxima error occurs, Maxima will start the debugger if
'debugmode' is 'true'. The user may enter commands to examine the
call stack, set breakpoints, step through Maxima code, and so on.
See 'debugging' for a list of debugger commands.
Enabling 'debugmode' will not catch Lisp errors.
-- Option variable: refcheck
Default value: 'false'
When 'refcheck' is 'true', Maxima prints a message each time a
bound variable is used for the first time in a computation.
-- Option variable: setcheck
Default value: 'false'
If 'setcheck' is set to a list of variables (which can be
subscripted), Maxima prints a message whenever the variables, or
subscripted occurrences of them, are bound with the ordinary
assignment operator ':', the '::' assignment operator, or function
argument binding, but not the function assignment ':=' nor the
macro assignment '::=' operators. The message comprises the name
of the variable and the value it is bound to.
'setcheck' may be set to 'all' or 'true' thereby including all
variables.
Each new assignment of 'setcheck' establishes a new list of
variables to check, and any variables previously assigned to
'setcheck' are forgotten.
The names assigned to 'setcheck' must be quoted if they would
otherwise evaluate to something other than themselves. For
example, if 'x', 'y', and 'z' are already bound, then enter
setcheck: ['x, 'y, 'z]$
to put them on the list of variables to check.
No printout is generated when a variable on the 'setcheck' list is
assigned to itself, e.g., 'X: 'X'.
-- Option variable: setcheckbreak
Default value: 'false'
When 'setcheckbreak' is 'true', Maxima will present a break prompt
whenever a variable on the 'setcheck' list is assigned a new value.
The break occurs before the assignment is carried out. At this
point, 'setval' holds the value to which the variable is about to
be assigned. Hence, one may assign a different value by assigning
to 'setval'.
See also 'setcheck' and 'setval'.
-- System variable: setval
Holds the value to which a variable is about to be set when a
'setcheckbreak' occurs. Hence, one may assign a different value by
assigning to 'setval'.
See also 'setcheck' and 'setcheckbreak'.
-- Function: timer (<f_1>, ..., <f_n>)
timer (all)
timer ()
Given functions <f_1>, ..., <f_n>, 'timer' puts each one on the
list of functions for which timing statistics are collected.
'timer(f)$ timer(g)$' puts 'f' and then 'g' onto the list; the list
accumulates from one call to the next.
'timer(all)' puts all user-defined functions (as named by the
global variable 'functions') on the list of timed functions.
With no arguments, 'timer' returns the list of timed functions.
Maxima records how much time is spent executing each function on
the list of timed functions. 'timer_info' returns the timing
statistics, including the average time elapsed per function call,
the number of calls, and the total time elapsed. 'untimer' removes
functions from the list of timed functions.
'timer' quotes its arguments. 'f(x) := x^2$ g:f$ timer(g)$' does
not put 'f' on the timer list.
If 'trace(f)' is in effect, then 'timer(f)' has no effect; 'trace'
and 'timer' cannot both be in effect at the same time.
See also 'timer_devalue'.
-- Function: untimer (<f_1>, ..., <f_n>)
untimer ()
Given functions <f_1>, ..., <f_n>, 'untimer' removes each function
from the timer list.
With no arguments, 'untimer' removes all functions currently on the
timer list.
After 'untimer (f)' is executed, 'timer_info (f)' still returns
previously collected timing statistics, although 'timer_info()'
(with no arguments) does not return information about any function
not currently on the timer list. 'timer (f)' resets all timing
statistics to zero and puts 'f' on the timer list again.
-- Option variable: timer_devalue
Default value: 'false'
When 'timer_devalue' is 'true', Maxima subtracts from each timed
function the time spent in other timed functions. Otherwise, the
time reported for each function includes the time spent in other
functions. Note that time spent in untimed functions is not
subtracted from the total time.
See also 'timer' and 'timer_info'.
-- Function: timer_info (<f_1>, ..., <f_n>)
timer_info ()
Given functions <f_1>, ..., <f_n>, 'timer_info' returns a matrix
containing timing information for each function. With no
arguments, 'timer_info' returns timing information for all
functions currently on the timer list.
The matrix returned by 'timer_info' contains the function name,
time per function call, number of function calls, total time, and
'gctime', which meant "garbage collection time" in the original
Macsyma but is now always zero.
The data from which 'timer_info' constructs its return value can
also be obtained by the 'get' function:
get(f, 'calls); get(f, 'runtime); get(f, 'gctime);
See also 'timer'.
-- Function: trace (<f_1>, ..., <f_n>)
trace (all)
trace ()
Given functions <f_1>, ..., <f_n>, 'trace' instructs Maxima to
print out debugging information whenever those functions are
called. 'trace(f)$ trace(g)$' puts 'f' and then 'g' onto the list
of functions to be traced; the list accumulates from one call to
the next.
'trace(all)' puts all user-defined functions (as named by the
global variable 'functions') on the list of functions to be traced.
With no arguments, 'trace' returns a list of all the functions
currently being traced.
The 'untrace' function disables tracing. See also 'trace_options'.
'trace' quotes its arguments. Thus, 'f(x) := x^2$ g:f$ trace(g)$'
does not put 'f' on the trace list.
When a function is redefined, it is removed from the timer list.
Thus after 'timer(f)$ f(x) := x^2$', function 'f' is no longer on
the timer list.
If 'timer (f)' is in effect, then 'trace (f)' has no effect;
'trace' and 'timer' can't both be in effect for the same function.
-- Function: trace_options (<f>, <option_1>, ..., <option_n>)
trace_options (<f>)
Sets the trace options for function <f>. Any previous options are
superseded. 'trace_options (<f>, ...)' has no effect unless 'trace
(<f>)' is also called (either before or after 'trace_options').
'trace_options (<f>)' resets all options to their default values.
The option keywords are:
* 'noprint' Do not print a message at function entry and exit.
* 'break' Put a breakpoint before the function is entered, and
after the function is exited. See 'break'.
* 'lisp_print' Display arguments and return values as Lisp
objects.
* 'info' Print '-> true' at function entry and exit.
* 'errorcatch' Catch errors, giving the option to signal an
error, retry the function call, or specify a return value.
Trace options are specified in two forms. The presence of the
option keyword alone puts the option into effect unconditionally.
(Note that option <foo> is not put into effect by specifying
'<foo>: true' or a similar form; note also that keywords need not
be quoted.) Specifying the option keyword with a predicate
function makes the option conditional on the predicate.
The argument list to the predicate function is always '[level,
direction, function, item]' where 'level' is the recursion level
for the function, 'direction' is either 'enter' or 'exit',
'function' is the name of the function, and 'item' is the argument
list (on entering) or the return value (on exiting).
Here is an example of unconditional trace options:
(%i1) ff(n) := if equal(n, 0) then 1 else n * ff(n - 1)$
(%i2) trace (ff)$
(%i3) trace_options (ff, lisp_print, break)$
(%i4) ff(3);
Here is the same function, with the 'break' option conditional on a
predicate:
(%i5) trace_options (ff, break(pp))$
(%i6) pp (level, direction, function, item) := block (print (item),
return (function = 'ff and level = 3 and direction = exit))$
(%i7) ff(6);
-- Function: untrace
untrace (<f_1>, ..., <f_n>)
untrace ()
Given functions <f_1>, ..., <f_n>, 'untrace' disables tracing
enabled by the 'trace' function. With no arguments, 'untrace'
disables tracing for all functions.
'untrace' returns a list of the functions for which it disabled
tracing.
automatically generated by info2www version 1.2.2.9