reduce-historical/r38/packages/rtrace/rtrace.tex

\documentclass[11pt,a4paper]{article}

\usepackage{reduce}

\newcommand{\til}{\symbol{'176}}  % tilde character
\newcommand{\rdebug}{\texttt{rdebug}}
\newcommand{\rtrace}{\texttt{rtrace}}

\title{Tracing in \REDUCE{}}

\author{
Herbert Melenk \\[0.05in]
Konrad--Zuse--Zentrum \\
f\"ur Informationstechnik Berlin \\
% Heilbronner Strasse 10 \\
% D--10711 Berlin Wilmersdorf \\
Takustra\ss{}e 7 \\
D--14195 Berlin--Dahlem \\
Federal Republic of Germany \\[0.05in]
E-mail: \texttt{melenk@zib.de} \\
\and
Francis J. Wright \\[0.05in]
School of Mathematical Sciences \\
Queen Mary and Westfield College, University of London \\
Mile End Road, London E1 4NS, UK. \\[0.05in]
E-mail: \texttt{F.J.Wright@QMW.ac.uk} \\
\texttt{http://www.maths.qmw.ac.uk/\til fjw/}}

\date{14 March 1999}

\begin{document}
\maketitle

\section{Introduction}

The package \rtrace{} provides portable tracing facilities for
\REDUCE{} programming.  These include
\begin{itemize}
\item entry-exit tracing of procedures,
\item assignment tracing of procedures,
%\item setting of break points,
%\item conditional trace and break.
\item tracing of rules when they fire.
\end{itemize}
In contrast to conventional Lisp-level tracing, values are printed in
algebraic style whenever possible if the switch \rtrace{} is on, which
it is by default.  The output has been specially tailored for the
needs of algebraic-mode programming.  Most features can be applied
without explicitly modifying the target program, and they can be
turned on and off dynamically at run time.  If the switch \rtrace{} is
turned off then values are printed in conventional Lisp style, and the
result should be similar to the tracing provided by the underlying
Lisp system.

To make the facilities available, load the package using the command
\begin{verbatim}
load_package rtrace;
\end{verbatim}
Alternatively, the package can be set up to auto load by putting
appropriate code in your \REDUCE{} initialisation file.  An example is
provided in the file \texttt{reduce.rc} in the \rtrace{} source
directory.

\section{RTrace versus RDebug}

The \rtrace{} package is a modification (by FJW) of the \rdebug{}
package (written by HM, and included in the \rtrace{} source
directory).  The modifications are as follows.  The procedure-tracing
facilities in \rdebug{} rely upon the low-level tracing facilities in
PSL; in \rtrace{} these low-level facilities have been (partly)
re-implemented portably.  The names of the tracing commands that have
been re-implemented portably have been changed to avoid conflicting
with those provided by the underlying Lisp system by preceding them
with the letter ``r'', and they provide a generalized interface that
supports algebraic mode better.  An additional set of rule tracing
facilities for inactive rules has been provided.  Beware that the
\rtrace{} package is still experimental!

This package is intended to be portable, and has been tested with both
CSL- and PSL-based \REDUCE{}.  However, it is intended not as a
replacement for \rdebug{} but as a partial re-implementation of
\rdebug{} that works with CSL-\REDUCE{}, and it is assumed that PSL
users will continue to use \rdebug{}.  It should, in principle, be
possible to use both.  Any \rtrace{} functions with the same names as
\rdebug{} functions should either be identical or compatible;
\rtrace{} should be loaded after \rdebug{} in order to retain any
enhancements provided by \rtrace{}.  Perhaps at some future time the
two packages should be merged.  However, note that \rtrace{} currently
provides \emph{only tracing} (hence the name) and does not support
break points.  (The current version also does not support conditional
tracing.)

\section{Procedure tracing: RTR, UNRTR}

Tracing of one or more procedures is initiated by the command
\texttt{rtr}:
\begin{verbatim}
rtr <proc1>, <proc2>, ..., <procn>;
\end{verbatim}
and cancelled by the command \texttt{unrtr}:
\begin{verbatim}
unrtr <proc1>, <proc2>, ..., <procn>;
\end{verbatim}

Every time a traced procedure is executed, a message is printed when
the procedure is entered or exited.  The entry message displays the
actual procedure arguments equated to the dummy parameter names, and
the exit message displays the value returned by the procedure.
Recursive calls are marked by
% an indentation and
a level number.  Here is a (simplistic) example, using first the
default algebraic display and second conventional Lisp display:
\begin{verbatim}
algebraic procedure power(x, n);
   if n = 0 then 1 else x*power(x, n-1)$

rtr power;

(power)

power(x+1, 2);

Enter (1) power
   x:  x + 1$
   n:  2$
Enter (2) power
   x:  x + 1$
   n:  1$
Enter (3) power
   x:  x + 1$
   n:  0$
Leave (3) power = 1$
Leave (2) power = x + 1$
Leave (1) power = x**2 + 2*x + 1$

 2
x  + 2*x + 1

off rtrace;

power(x+1, 2);

Enter (1) power
   x:  (plus x 1)
   n:  2
Enter (2) power
   x:  (plus x 1)
   n:  1
Enter (3) power
   x:  (plus x 1)
   n:  0
Leave (3) power = 1
Leave (2) power = (!*sq ((((x . 1) . 1) . 1) . 1) t)
Leave (1) power = (!*sq ((((x . 2) . 1) ((x . 1) . 2) . 1) . 1) t)

 2
x  + 2*x + 1

on rtrace;

unrtr power;

(power)
\end{verbatim}

Many algebraic-mode operators are implemented as internal procedures
with different names.  If an internal procedure with the specified
name does not exist then \rtrace{} tracing automatically applies to
the appropriate internal procedure and returns a list of the names of
the internal procedures, e.g.
\begin{verbatim}
rtr int;

(simpint)
\end{verbatim}
This facility is an extension of the \rdebug{} package.

Tracing of \emph{compiled} procedures by the \rtrace{} package is not
completely reliable, in that recursive calls may not be traced.  This
is essentially because tracing works only when the procedure is called
by name and not when it is called directly via an internal compiled
pointer.  It may not be possible to avoid this restriction in a
portable way.  Also, arguments of compiled procedures are not
displayed using the names given to them in the source code, because
these names are no longer available.  Instead, they are displayed
using the names \texttt{Arg1}, \texttt{Arg2}, etc.

\section{Assignment tracing: RTRST, UNRTRST}

One often needs information about the internal behaviour of a
procedure, especially if it is a longer piece of code.  For an
interpreted procedure declared in an \texttt{rtrst} command:
\begin{verbatim}
rtrst <proc1>, <proc2>, ..., <procn>;
\end{verbatim}
all explicit assignments executed (as either the symbolic-mode
\texttt{setq} or the algebraic-mode \texttt{setk})
% and passed labels
inside these procedures are displayed during procedure execution.  All
procedure tracing (assignment and entry-exit) is removed by the
command \texttt{unrtrst} (or \texttt{unrtr}, for which it is just a
synonym):
\begin{verbatim}
unrtrst <proc1>, <proc2>, ..., <procn>;
\end{verbatim}
Assignment tracing is not possible if a procedure is compiled, either
because it was loaded from a ``fasl'' file or image, or because it was
compiled as it was read in as source code.  This is because assignment
tracing works by modifying the interpreted code of the procedure,
which must therefore be available.

Applying \texttt{rtr} to a procedure that has been declared in an
\texttt{rtrst} command, or vice versa, toggles the type of tracing
applied (and displays an explanatory message).

Note that when a program contains a \texttt{for} loop, \REDUCE{}
translates this to a sequence of Lisp instructions.  When using
\texttt{rtrst}, the printout is driven by the ``unfolded'' code.  When
the code contains a \texttt{for each \ldots{} in} statement, the name
of the control variable is internally used to keep the remainder of
the list during the loop, and you will see the corresponding
assignments in the trace rather than the individual values in the loop
steps, e.g.
\begin{verbatim}
procedure fold u;
   for each x in u sum x$

rtrst fold;

(fold)

fold {z, z*y, y};
\end{verbatim}
produces the following output (using CSL-\REDUCE{}):
\begin{verbatim}
Enter (1) fold
   u:  {z,y*z,y}$
x := [z,y*z,y]$
G0 := 0$
G0 := z$
x := [y*z,y]$
G0 := z*(y + 1)$
x := [y]$
G0 := y*z + y + z$
x := []$
Leave (1) fold = y*z + y + z$

y*z + y + z

unrtrst fold;

(fold)
\end{verbatim}
In this example, the printed assignments for \texttt{x} show the
various stages of the loop.  The variable \texttt{G0} is an internally
generated place-holder for the sum, and may have a slightly different
name depending on the underlying Lisp systems.

\section{Tracing active rules: TRRL, UNTRRL}

The command \texttt{trrl} initiates tracing when they fire of
individual rules or rule lists that have been activated using
\texttt{let}.
\begin{verbatim}
trrl <rl1>, <rl2>, ..., <rln>;
\end{verbatim}
where each of the $<rl_i>$ is:
\begin{itemize}
\item a rule or rule list;
\item the name of a rule or rule list (that is, a non-indexed variable
      which is bound to a rule or rule list);
\item an operator name, representing the rules assigned to this
      operator.
\end{itemize}
The specified rules are (re-) activated in \REDUCE{} such that each of
them prints a report every time it fires.  The report is composed of
the name of the rule or the name of the rule list together with the
number of the rule in the list, the form matching the left side
(``input'') and the resulting right side (``output'').  For an
explicitly given rule or rule list, \texttt{trrl} assigns a unique
generated name.

Note, however, that \texttt{trrl} does not trace rules with constant
expressions on the left, on the assumption that they are not
particularly interesting.  [This behaviour may be made
user-controllable in a future version.]

The command \texttt{untrrl} removes the tracing from rules:
\begin{verbatim}
untrrl <rl1>, <rl2>, ..., <rln>;
\end{verbatim}
where each of the $<rl_i>$ is:
\begin{itemize}
\item a rule or rule list;
\item the name of a rule or rule list (that is, a non-indexed variable
which is bound to a rule or rule list or a unique name generated by
\texttt{trrl});
\item an operator name, representing the rules assigned to this
operator.
\end{itemize}
The rules are reactivated in their original form.  Alternatively you
can use the command \texttt{clearrules} to remove the rules totally
from the system.  Please do not modify the rules between \texttt{trrl}
and \texttt{untrrl} -- the result may be unpredictable.

Here are two simple examples that show tracing via the rule name and
via the operator name:
\begin{verbatim}
trigrules := {sin(~x)^2 => 1 - cos(x)^2};

                     2              2
trigrules := {sin(~x)  => 1 - cos(x) }

let trigrules;
trrl trigrules;

1 - sin(x)^2;

Rule trigrules.1: sin(x)**2 => 1 - cos(x)**2$

      2
cos(x)

untrrl trigrules;
trrl sin;

1 - sin(x)^2;

Rule sin.23: sin(x)**2 => 1 - cos(x)**2$

      2
cos(x)

untrrl sin;
clearrules trigrules;
\end{verbatim}

\section{Tracing inactive rules: TRRLID, UNTRRLID}

The command \texttt{trrlid} initiates tracing of individual rule lists
that have been assigned to variables, but have not been activated
using \texttt{let}:
\begin{verbatim}
trrlid <rlid1>, <rlid2>, ..., <rlidn>;
\end{verbatim}
where each of the $<rlid_i>$ is an identifier of a rule list (that is,
a non-indexed variable which is bound to a rule list).  It is assumed
that they will be activated later, either via a \texttt{let} command
or by using the \texttt{where} operator.  When they are activated and
fire, tracing output will be as if they had been traced using
\texttt{trrl}.  The command \texttt{untrrlid} clears the tracing.
This facility is an extension of the \rdebug{} package.

Here is a simple example that continues the example above:
\begin{verbatim}
trrlid trigrules;

1 - sin(x)^2 where trigrules;

Rule trigrules.1: sin(x)**2 => 1 - cos(x)**2$

      2
cos(x)

untrrlid trigrules;
\end{verbatim}

\section{Output control: RTROUT}

The trace output (only) can be redirected to a separate file by using
the command \texttt{rtrout}, followed by a file name in string quotes.
A second call of \texttt{rtrout} closes any current output file and
opens a new one.  The file name \texttt{NIL} (without string quotes)
closes any current output file and causes the trace output to be
redirected to the standard output device.

The \rdebug{} variables \texttt{trlimit} and \texttt{trprinter!*} are
not implemented in \rtrace{}.  If you want to select Lisp-style
tracing then turn off the switch \rtrace{}:
\begin{verbatim}
off rtrace;
\end{verbatim}
after loading the \rtrace{} package.  Note that the \rtrace{} switch
controls the display format of both procedure and rule tracing.

\end{document}