  % -*- Mode:TeX -*-
\chapter{Miscellaneous}
\label{MiscChapter}

\section{Errors}

Compiler modules may detect errors or other conditions that require some
indication to the compiler user.  The following function is provided for
making such indications.  Note that this is completely orthogonal to Common
Lisp's error system; this facility only handles the display of messages.  If a
compiler module invokes the error system, the action taken by the compiler may
depend on whether the compiler is running interactively or not, or on other
factors.

\lispdoc message class format-string \rest format-args [Function]
         This function displays a message to the compiler user.  The message is
obtained by applying {\tt format} to the arguments {\tt nil}, {\it
format-string}, and {\it format-args\/} (which yields a string).  The argument
{\it class\/} describes the severity of the condition which caused the message,
and is used to decide whether or not to actually display the message, and where
to display it ({\it e.g.}, console or listing file).  The following classes are
defined:

\begin{description}
\item[{\tt :unrecoverable}] An error from which the compiler cannot recover,
compilation of the entire file is immediately terminated.

\item[{\tt :fatal}] An error which forces the termination of the currently
executing module. The effect is to drop the offending source code input
unit of that module. The compiler may continue processing the units that
follow.

\item[{\tt :error}] A program error which prevents reasonable compilation.  The
compiler may continue to process the program (so that other errors may be
detected), and may even generate code, but any results are almost assuredly
incorrect.

\item[{\tt :warning}] The compiler has made an assumption about what the user
intended, or has detected a situation which, while legal, probably represents a
program bug.

\item[{\tt :informatory}] Anything which does not represent a program or compiler
error, but which might be of interest to the compiler user.  For example, a
report on how well an optimization phase performed.

\item[{\tt :debug}] A message of interest only to the maintainers of the compiler.

\item[{\tt :log}] A message that is only inserted in the log file, if any.
\end{description}

\subsection{Message Hooks}
\label{message-hooks}

\lispdoc *message-output* [Internal Variable]
{\tt *message-output*} is a stream synonym for {\tt *error-output*}. 

 When {\tt message} is invoked, it normally prints a message to the stream
{\tt *message-output*}.  Particular compilers may also want to perform
other actions when message is invoked.  DFCS supports this by allowing
compilers to provide {\em message-hooks\/}.  A message-hook is a function
that takes a type, place, module-name, format-string and format-args as
arguments and performs an application-specific operation.  After {\tt
message} prints a message to {\tt *message-output*}, it invokes the
message-hook, if one was provided.  The functions {\tt
standard-message-string} and {\tt fill-and-indent} may be useful in the
definition of message hooks.

\lispdoc standard-message-string type place module-name format-string
         format-args [Function]

 {\tt Standard-message-string} is the function that constructs the standard
message string that is printed to the stream {\tt *message-output*\/} when
{\tt message} is called.  This function may be useful in message hooks.

\lispdoc fill-and-indent string line-length indent [Function]

 Fills and indents string {\em string\/} so that it fits into {\em
line-length\/} characters and each line begins with {\em indent\/}
characters of white-space.

\lispdoc *message-break-characters* [Variable]

 Characters at which {\tt fill-and-indent} will break lines.  Internal
variable.

\begin{lispdocs}
\lispdoc *handle-lisp-errors* [Internal Variable]
\lispdoc *message-types-debugged* [Internal Constant]
\lispdoc *unrecoverable-catch-active-p* [Internal Variable]
\lispdoc *fatal-catch-active-p* [Internal Variable]
\end{lispdocs}

{\tt *handle-lisp-errors*} is an internal variable which is normally set to
{\tt t}. This instructs the internal compiler error catcher wrapper to
prevent the user from entering the debugger when there are lisp errors
(bugs in the compiler).  Compiler hackers almost always set it to {\tt nil}
so as to invoke the lisp debugger when a bug is caught.

Adding a message type to the list {\tt *message-types-debugged*} causes a
break to be entered when that type of message is processed. 

{\tt *unrecoverable-catch-active-p*} and {\tt *fatal-catch-active-p*} are
dynamic variables that are bound to {\tt t} by the error catching wrappers.
If during compiler execution (or outside the cycling of compiler) this
binding is set to {\tt nil}, then the {\tt :unrecoverable} and {\tt
:fatal} messages cause a break to take place.

\section{Performance Metering}
\label{perf-meters}

The Dataflow Compiler Substrate has a limited performance
metering\index{performance metering}
capability apart from any that may be offered by the native LISP system.
These performance meters give an idea of how much time does the compiler
spend in each module and how much consing does it do among its various data
structures, \ie, ptnodes, instructions, and frames. 

The performance meters are not usually loaded into the system. They have to
be loaded separately into the DFCS system. The file required to be loaded
for this facility is given in appendix~\ref{files}.

\subsection{Space Meters}

The following consing statistics are collected.

\begin{lispdocs}
\lispdoc *instructions-consed* [Internal Variable]
\lispdoc *instruction-words-consed* [Internal Variable]
\lispdoc *ptnodes-consed* [Internal Variable]
\lispdoc *ptnode-words-consed* [Internal Variable]
\lispdoc *frames-consed* [Internal Variable]
\lispdoc *frame-words-consed* [Internal Variable]
\lispdoc *n-wirings* [Internal Variable]
\end{lispdocs}

{\tt *instructions-consed*} counts the number of dataflow graph
instructions allocated. 

{\tt *instruction-words-consed*} gives a rough idea
about the size of the instructions being allocated. It counts 12 words per
instruction allocated and 1 word each per the basic input and output ports
of an instruction. This is a VERY coarse measure of the amount of basic
dataflow graph storage used.  This does not include any extra storage
required by the {\tt instruction-slot} properties.

{\tt *ptnodes-consed*} counts the number of ptnodes allocated. {\tt
*ptnode-words-consed*} counts 11 words of constant storage per ptnode
allocated, and 1 per permanent or memoized attribute slot of that ptnode.
Again, this is an extremely coarse description of the actual storage used. 

{\tt *frames-consed*} counts the number of frames allocated. {\tt
*frame-words-consed} counts 17 words per frame allocated along with the
size of the input and the output hash tables. 

{\tt *n-wirings*} counts the number of wirings done in a dataflow graph.

\lispdoc reset [Internal Function]
Resets the internal space statistics collection counters. 

\lispdoc print-performance-meters [Internal Function]
Prints the values of various space statistics counters.

\subsection{Time Meters}

A useful performance meter is the amount and the percentage of time spent
within each module during a compilation. This is an abstract and
useful measure of the time taken by each phase of the compiler. The time is
computed in seconds of real time spent within each module and is printed as
both actual time and as a percentage of the total. The Common LISP
function {\tt get-internal-real-time} is used for this purpose. 

\lispdoc reset-compiler-times compiler-name [Function]
Resets the time counters associated with each module of the compiler {\em
compiler-name}. 

\lispdoc print-compiler-times compiler-name [Function]
Prints the time taken in seconds and as a percentage of the total by each
module of the compiler {\em compiler-name}.

\section{Sxhash Tables}

\lispdoc sxhash-table [Defstruct]

An SXHASH table is essentially an EQL hash table that uses SXHASH to
compute the hash codes.  Collisions are handled by using alists as buckets.
SXHASH-TABLEs are intended to be used when the keys are symbols, for in
that case they end up being quite a bit faster than any of the Common Lisp
hash table varieties, at least on the Lisp Machine, because SXHASH-TABLEs
don't do rehashing upon GC or locking out of other processes.  Also, they
can be made smaller than the Lisp Machine is willing to make Common Lisp
hash tables.  We represent SXHASH-TABLEs as defstructs.  The ENTRIES-ARRAY
is indexed by SXHASH code mod the size.

\lispdoc clrsxhash sxhash-table [Function]

\lispdoc getsxhash key sxhash-table \optional default [Function]

\lispdoc remsxhash key sxhash-table [Function]

\lispdoc mapsxhash fcn sxhash-table [Function]
{\tt Mapsxhash} calls {\em fcn\/} with two arguments, a key and its value,
for every entry in the sxhash-table.  It returns {\tt NIL}.

\section{Miscellaneous Functions}
\label{misc-fns}

\lispdoc pointer object [Internal Function]
Returns a number for a structure. It is useful in printing structure in
order to distinguish them from similar structures.

\lispdoc record-source-file-name function-spec \optional type no-query
[Function]
System Independent implementation of {\tt record-source-file-name}.

\lispdoc write-verbose-dataflow-graph dataflow-graph stream [Function]
Writes the dataflow graph {\em dataflow-graph} on stream {\em stream} in a
tabular format. First the property list of the dataflow graph is printed.
Then all the instructions are printed one by one starting from the root
set. 

An entry describes the instruction offset, its opcode, and
for each output name, its destination instruction offset and the input name
it is wired to. If there is an annotation associated with the arc, its
first 26 characters are also shown.

