--- a
+++ b/doc/cmucl/cmu-user/cmu-user.tex
@@ -0,0 +1,13321 @@
+%% CMU Common Lisp User's Manual.
+%%
+%% Aug 97   Raymond Toy
+%% This is a modified version of the original CMUCL User's Manual.
+%% The key changes are modification of this file to use standard
+%% LaTeX2e.  This means latexinfo isn't going to work anymore.
+%% However, Latex2html support has been added.
+%%
+%% Jan 1998 Paul Werkowski
+%% A few of the packages below are not part of the standard LaTeX2e
+%% distribution, and must be obtained from a repository. At this time
+%% I was able to fetch from
+%% ftp.cdrom.com:pub/tex/ctan/macros/latex/contrib/supported/
+%%			camel/index.ins
+%%			camel/index.dtx
+%%			calc/calc.ins
+%%			calc/calc.dtx
+%%			changebar/changebar.ins
+%%			changebar/changebar.dtx
+%% One runs latex on the .ins file to produce .tex and/or .sty
+%% files that must be put in a path searched by latex.
+%%
+\documentclass{report}
+\usepackage{changebar}
+\usepackage{xspace}
+\usepackage{alltt}
+\usepackage{index}
+\usepackage{verbatim}
+\usepackage{ifthen}
+\usepackage{calc}
+%\usepackage{html2e}
+\usepackage{html,color}
+\usepackage{varioref}
+
+%% Define the indices.  We need one for Types, Variables, Functions,
+%% and a general concept index.
+\makeindex
+\newindex{types}{tdx}{tnd}{Type Index}
+\newindex{vars}{vdx}{vnd}{Variable Index}
+\newindex{funs}{fdx}{fnd}{Function Index}
+\newindex{concept}{cdx}{cnd}{Concept Index}
+
+\newcommand{\tindexed}[1]{\index[types]{#1}\textsf{#1}}
+\newcommand{\findexed}[1]{\index[funs]{#1}\textsf{#1}}
+\newcommand{\vindexed}[1]{\index[vars]{#1}\textsf{*#1*}}
+\newcommand{\cindex}[1]{\index[concept]{#1}}
+\newcommand{\cpsubindex}[2]{\index[concept]{#1!#2}}
+
+%% This code taken from the LaTeX companion.  It's meant as a
+%% replacement for the description environment.  We want one that
+%% prints description items in a fixed size box and puts the
+%% description itself on the same line or the next depending on the
+%% size of the item.
+\newcommand{\entrylabel}[1]{\mbox{#1}\hfil}
+\newenvironment{entry}{%
+  \begin{list}{}%
+    {\renewcommand{\makelabel}{\entrylabel}%
+      \setlength{\labelwidth}{45pt}%
+      \setlength{\leftmargin}{\labelwidth+\labelsep}}}%
+  {\end{list}}
+
+\newlength{\Mylen}
+\newcommand{\Lentrylabel}[1]{%
+  \settowidth{\Mylen}{#1}%
+  \ifthenelse{\lengthtest{\Mylen > \labelwidth}}%
+  {\parbox[b]{\labelwidth}%  term > labelwidth
+    {\makebox[0pt][l]{#1}\\}}%
+  {#1}%
+  \hfil\relax}
+\newenvironment{Lentry}{%
+  \renewcommand{\entrylabel}{\Lentrylabel}
+  \begin{entry}}%
+  {\end{entry}}
+
+\newcommand{\fcntype}[1]{\textit{#1}}
+\newcommand{\argtype}[1]{\textit{#1}}
+\newcommand{\fcnname}[1]{\textsf{#1}}
+
+\newlength{\formnamelen}        % length of a name of a form
+\newlength{\pboxargslen}        % length of parbox for arguments
+\newlength{\typelen}            % length of the type label for the form
+
+\newcommand{\args}[1]{#1}
+\newcommand{\keys}[1]{\textsf{\&key} \= #1}
+\newcommand{\morekeys}[1]{\\ \> #1}
+\newcommand{\yetmorekeys}[1]{\\ \> #1}
+
+\newcommand{\defunvspace}{\ifhmode\unskip \par\fi\addvspace{18pt plus 12pt minus 6pt}}
+
+
+%% \layout[pkg]{name}{param list}{type}
+%%
+%% This lays out a entry like so:
+%%
+%% pkg:name arg1 arg2                             [Function]
+%%
+%% where [Function] is flush right.
+%%
+\newcommand{\layout}[4][\mbox{}]{%
+  \par\noindent
+  \fcnname{#1#2\hspace{1em}}%
+  \settowidth{\formnamelen}{\fcnname{#1#2\hspace{1em}}}%
+  \settowidth{\typelen}{[\argtype{#4}]}%
+  \setlength{\pboxargslen}{\linewidth}%
+  \begin{minipage}[t]{\pboxargslen}
+    \begin{tabbing}
+      #3
+    \end{tabbing}
+  \end{minipage}
+  \hfill[\fcntype{#4}]%
+  \par\addvspace{2pt plus 2pt minus 2pt}}
+
+\newcommand{\vrindexbold}[1]{\index[vars]{#1|textbf}}
+\newcommand{\fnindexbold}[1]{\index[funs]{#1|textbf}}
+
+%% Define a new type
+%%
+%% \begin{deftp}{typeclass}{typename}{args}
+%%    some description
+%% \end{deftp}
+\newenvironment{deftp}[3]{%
+  \par\bigskip\index[types]{#2|textbf}%
+  \layout{#2}{\var{#3}}{#1}
+  }{}
+
+%% Define a function
+%%
+%% \begin{defun}{pkg}{name}{params}
+%%   \defunx[pkg]{name}{params}
+%%   description of function
+%% \end{defun}
+\newenvironment{defun}[3]{%
+  \par\defunvspace\fnindexbold{#2}\label{FN:#2}%
+  \layout[#1]{#2}{#3}{Function}
+  }{}
+\newcommand{\defunx}[3][\mbox{}]{%
+  \par\fnindexbold{#2}\label{FN:#2}%
+  \layout[#1]{#2}{#3}{Function}}
+
+%% Define a macro
+%%
+%% \begin{defmac}{pkg}{name}{params}
+%%   \defmacx[pkg]{name}{params}
+%%   description of macro
+%% \end{defmac}
+\newenvironment{defmac}[3]{%
+  \par\defunvspace\fnindexbold{#2}\label{FN:#2}%
+  \layout[#1]{#2}{#3}{Macro}}{}
+\newcommand{\defmacx}[3][\mbox{}]{%
+  \par\fnindexbold{#2}\label{FN:#2}%
+  \layout[#1]{#2}{#3}{Function}}
+
+%% Define a variable
+%%
+%% \begin{defvar}{pkg}{name}
+%%   \defvarx[pkg]{name}
+%%   description of defvar
+%% \end{defvar}
+\newenvironment{defvar}[2]{%
+  \par\defunvspace\vrindexbold{#2}\label{VR:#2}
+  \layout[#1]{*#2*}{}{Variable}}{}
+\newcommand{\defvarx}[2][\mbox{}]{%
+  \par\vrindexbold{#2}\label{VR:#2}
+  \layout[#1]{*#2*}{}{Variable}}
+
+%% Define a constant
+%%
+%% \begin{defconst}{pkg}{name}
+%%   \ddefconstx[pkg]{name}
+%%   description of defconst
+%% \end{defconst}
+\newcommand{\defconstx}[2][\mbox{}]{%
+  \layout[#1]{#2}{}{Constant}}
+\newenvironment{defconst}[2]{%
+  \defunvspace\defconstx[#1]{#2}}
+
+\newenvironment{example}{\begin{quote}\begin{alltt}}{\end{alltt}\end{quote}}
+\newenvironment{lisp}{\begin{example}}{\end{example}}
+\newenvironment{display}{\begin{quote}\begin{alltt}}{\end{alltt}\end{quote}}
+
+\newcommand{\hide}[1]{}
+\newcommand{\trnumber}[1]{#1}
+\newcommand{\citationinfo}[1]{#1}
+\newcommand{\var}[1]{{\textsf{\textsl{#1}}\xspace}}
+\newcommand{\code}[1]{\textnormal{{\sffamily #1}}}
+\newcommand{\file}[1]{\texttt{#1}'}
+\newcommand{\samp}[1]{\texttt{#1}'}
+\newcommand{\kwd}[1]{\code{:#1}}
+\newcommand{\F}[1]{\code{#1}}
+\newcommand{\w}[1]{\hbox{#1}}
+\renewcommand{\b}[1]{\textrm{\textbf{#1}}}
+\renewcommand{\i}[1]{\textit{#1}}
+\newcommand{\ctrl}[1]{$\uparrow$\textsf{#1}}
+\newcommand{\result}{$\Rightarrow$}
+\newcommand{\myequiv}{$\equiv$}
+\newcommand{\back}[1]{$$\backslash$$#1}
+\newcommand{\pxlref}[1]{see section~\ref{#1}, page~\pageref{#1}}
+\newcommand{\xlref}[1]{See section~\ref{#1}, page~\pageref{#1}}
+
+\newcommand{\false}{\textsf{nil}}
+\newcommand{\true}{\textsf{t}}
+\newcommand{\nil}{\textsf{nil}}
+\newcommand{\FALSE}{\textsf{nil}}
+\newcommand{\TRUE}{\textsf{t}}
+\newcommand{\NIL}{\textsf{nil}}
+
+\newcommand{\ampoptional}{\textsf{\&optional}}
+\newcommand{\amprest}{\textsf{\&rest}}
+\newcommand{\ampbody}{\textsf{\&body}}
+\newcommand{\mopt}[1]{{$\,\{$}\textnormal{\textsf{\textsl{#1\/}}}{$\}\,$}}
+\newcommand{\mstar}[1]{{$\,\{$}\textnormal{\textsf{\textsl{#1\/}}}{$\}^*\,$}}
+\newcommand{\mplus}[1]{{$\,\{$}\textnormal{\textsf{\textsl{#1\/}}}{$\}^+\,$}}
+\newcommand{\mgroup}[1]{{$\,\{$}\textnormal{\textsf{\textsl{#1\/}}}{$\}\,$}}
+\newcommand{\mor}{$|$}
+
+\newcommand{\funref}[1]{\findexed{#1} (page~\pageref{FN:#1})}
+\newcommand{\specref}[1]{\findexed{#1} (page~\pageref{FN:#1})}
+\newcommand{\macref}[1]{\findexed{#1} (page~\pageref{FN:#1})}
+\newcommand{\varref}[1]{\vindexed{#1} (page~\pageref{VR:#1})}
+\newcommand{\conref}[1]{\conindexed{#1} (page~\pageref{VR:#1})}
+
+%% Some common abbreviations
+\newcommand{\clisp}{Common Lisp}
+\newcommand{\dash}{---}
+\newcommand{\alien}{Alien}
+\newcommand{\aliens}{Aliens}
+\newcommand{\Aliens}{Aliens}
+\newcommand{\Alien}{Alien}
+\newcommand{\Hemlock}{Hemlock}
+\newcommand{\hemlock}{Hemlock}
+\newcommand{\python}{Python}
+\newcommand{\Python}{Python}
+\newcommand{\cmucl}{CMU Common Lisp}
+\newcommand{\llisp}{Common Lisp}
+\newcommand{\Llisp}{Common Lisp}
+\newcommand{\cltl}{\emph{Common Lisp: The Language}}
+\newcommand{\cltltwo}{\emph{Common Lisp: The Language 2}}
+
+%% Replacement commands when we run latex2html.  This should be last
+%% so that latex2html uses these commands instead of the LaTeX
+%% commands above.
+\begin{htmlonly}
+  \usepackage{makeidx}
+
+  \newcommand{\var}[1]{\textnormal{\textit{#1}}}
+  \newcommand{\code}[1]{\textnormal{\texttt{#1}}}
+  %%\newcommand{\printindex}[1][\mbox{}]{}
+
+  %% We need the quote environment because the alltt is broken.  The
+  %% quote environment helps us in postprocessing to result to get
+  %% what we want.
+  \newenvironment{example}{\begin{quote}\begin{alltt}}{\end{alltt}\end{quote}}
+  \newenvironment{display}{\begin{quote}\begin{alltt}}{\end{alltt}\end{quote}}
+
+  \newcommand{\textnormal}[1]{\rm #1}
+  \newcommand{\hbox}[1]{\mbox{#1}}
+  \newcommand{\xspace}{}
+  \newcommand{newindex}[4]{}
+
+  \newcommand{\pxlref}[1]{see section~\ref{#1}}
+  \newcommand{\xlref}[1]{See section~\ref{#1}}
+
+  \newcommand{\tindexed}[1]{\index{#1}\texttt{#1}}
+  \newcommand{\findexed}[1]{\index{#1}\texttt{#1}}
+  \newcommand{\vindexed}[1]{\index{#1}\texttt{*#1*}}
+  \newcommand{\cindex}[1]{\index{#1}}
+  \newcommand{\cpsubindex}[2]{\index{#1!#2}}
+
+  \newcommand{\keys}[1]{\texttt{\&key} #1}
+  \newcommand{\morekeys}[1]{#1}
+  \newcommand{\yetmorekeys}[1]{#1}
+
+  \newenvironment{defun}[3]{%
+    \textbf{[Function]}\\
+    \texttt{#1#2} \emph{#3}\\}{}
+  \newcommand{\defunx}[3][\mbox{}]{%
+    \texttt{#1#2} {\em #3}\\}
+  \newenvironment{defmac}[3]{%
+    \textbf{[Macro]}\\
+    \texttt{#1#2} \emph{#3}\\}{}
+  \newcommand{\defmacx}[3][\mbox{}]{%
+    \texttt{#1#2} {\em #3}\\}
+  \newenvironment{defvar}[2]{%
+    \textbf{[Variable]}\\
+    \texttt{#1*#2*}\\ \\}{}
+  \newcommand{\defvarx}[2][\mbox{}]{%
+    \texttt{#1*#2*}\\}
+  \newenvironment{defconst}[2]{%
+    \textbf{[Constant]}\\
+    \texttt{#1#2}\\}{}
+  \newcommand{\defconstx}[2][\mbox{}]{\texttt{#1#2}\\}
+  \newenvironment{deftp}[3]{%
+    \textbf{[#1]}\\
+    \texttt{#2} \textit{#3}\\}{}
+  \newenvironment{Lentry}{\begin{description}}{\end{description}}
+\end{htmlonly}
+
+%% Set up margins
+\setlength{\oddsidemargin}{-10pt}
+\setlength{\evensidemargin}{-10pt}
+\setlength{\topmargin}{-40pt}
+\setlength{\footskip}{30pt}
+\setlength{\textheight}{9.25in}
+\setlength{\textwidth}{6.75in}
+\setlength{\columnsep}{0.375in}
+\setlength{\columnseprule}{0pt}
+
+
+\setcounter{tocdepth}{2}
+\setcounter{secnumdepth}{3}
+\def\textfraction{.1}
+\def\bottomfraction{.9}         % was .3
+\def\topfraction{.9}
+
+
+\begin{document}
+%%\alwaysrefill
+\relax
+%%\newindex{cp}
+%%\newindex{ky}
+
+\newcommand{\theabstract}{%
+
+  CMU Common Lisp is an implementation of that Common Lisp runs on
+  various Unix workstations.  See the README file in the distribution
+  for current platforms.  The largest single part of this document
+  describes the Python compiler and the programming styles and
+  techniques that the compiler encourages.  The rest of the document
+  describes extensions and the implementation dependent choices made
+  in developing this implementation of Common Lisp.  We have added
+  several extensions, including a source level debugger, an interface
+  to Unix system calls, a foreign function call interface, support for
+  interprocess communication and remote procedure call, and other
+  features that provide a good environment for developing Lisp code.
+  }
+
+\newcommand{\researchcredit}{%
+  Projects Agency, Information Science and Technology Office, under
+  the title \emph{Research on Parallel Computing} issued by DARPA/CMO
+  under Contract MDA972-90-C-0035 ARPA Order No.  7330.
+
+  The views and conclusions contained in this document are those of
+  the authors and should not be interpreted as representing the
+  official policies, either expressed or implied, of the Defense
+  Advanced Research Projects Agency or the U.S. government.}
+
+\pagestyle{empty}
+\title{CMU Common Lisp User's Manual}
+
+%%\author{Robert A. MacLachlan, \var{Editor}}
+%%\date{July 1992}
+%%\trnumber{CMU-CS-92-161}
+%%\citationinfo{
+%%\begin{center}
+%%Supersedes Technical Reports CMU-CS-87-156 and CMU-CS-91-108.
+%%\end{center}
+%%}
+%%%%\arpasupport{strategic}
+%%\abstract{\theabstract}
+%%%%\keywords{lisp, Common Lisp, manual, compiler,
+%%%%          programming language implementation, programming environment}
+
+%%\maketitle
+\begin{latexonly}
+
+%%  \title{CMU Common Lisp User's Manual}
+
+  \author{Robert A. MacLachlan,
+  \emph{Editor}%
+    Research Projects Agency, Information Science and Technology
+    Office, under the title \emph{Research on Parallel Computing}
+    issued by DARPA/CMO under Contract MDA972-90-C-0035 ARPA Order No.
+    7330.  The views and conclusions contained in this document are
+    those of the authors and should not be interpreted as representing
+    the official policies, either expressed or implied, of the Defense
+    Advanced Research Projects Agency or the U.S. government.}}
+
+
+
+\date{\bigskip
+  July 1992 \\ CMU-CS-92-161 \\
+  \vspace{0.25in}
+  October 31, 1997 \\
+  Net Version \\
+  \vspace{0.75in} {\small
+    School of Computer Science \\
+    Carnegie Mellon University \\
+    Pittsburgh, PA 15213} \\
+  \vspace{0.5in} \small Supersedes Technical Reports CMU-CS-87-156 and
+  CMU-CS-91-108.\\
+  \vspace{0.5in} \textbf{Abstract} \medskip
+  \begin{quote}
+    \theabstract
+  \end{quote}
+  }
+
+\maketitle
+\end{latexonly}
+
+%% Nice HTML version of the title page
+\begin{rawhtml}
+
+  <h1 align=center>CMU Common Lisp User's Manual</h1>
+
+    <p align=center>Robert A. MacLachlan, <EM>Editor</EM>
+    </p>
+    <p align=center>
+      July 1992 <BR>
+      CMU-CS-92-161 <BR>
+    </p>
+    <br>
+    <p align=center>
+      July 1997 <BR>
+      Net Version <BR>
+    </p>
+
+    <p align=center>
+      School of Computer Science <BR>
+      Carnegie Mellon University <BR>
+      Pittsburgh, PA 15213 <BR>
+    </p>
+    <br>
+    <p>
+      Supersedes Technical Reports CMU-CS-87-156 and
+      CMU-CS-91-108.<BR>
+    </p>
+
+    <p align=center>
+      <b>Abstract</b>
+    <blockquote>
+      CMU Common Lisp is an implementation of that Common Lisp runs on
+      various Unix workstations.  See the README file in the
+      distribution for current platforms.  The largest single part of
+      this document describes the Python compiler and the programming
+      styles and techniques that the compiler encourages.  The rest of
+      the document describes extensions and the implementation
+      dependent choices made in developing this implementation of
+      Common Lisp.  We have added several extensions, including a
+      source level debugger, an interface to Unix system calls, a
+      foreign function call interface, support for interprocess
+      communication and remote procedure call, and other features that
+      provide a good environment for developing Lisp code.
+    </blockquote>
+    </p>
+    <blockquote><font size=-1>
+    Projects Agency, Information Science and Technology Office, under
+    the title <em>Research on Parallel Computing</em> issued by DARPA/CMO
+    under Contract MDA972-90-C-0035 ARPA Order No.  7330.
+    <p>
+    The views and conclusions contained in this document are those of
+    the authors and should not be interpreted as representing the
+    official policies, either expressed or implied, of the Defense
+    Advanced Research Projects Agency or the U.S. government.
+    </p></font>
+  </blockquote>
+    </p>
+\end{rawhtml}
+\clearpage
+\vspace*{\fill}
+\textbf{Keywords:} lisp, Common Lisp, manual, compiler,
+programming language implementation, programming environment
+\clearpage
+\pagenumbering{roman}
+\tableofcontents
+
+\clearpage
+\pagenumbering{arabic}
+%%\end{iftex}
+
+%%\setfilename{cmu-user.info}
+%%\node Top, Introduction, (dir), (dir)
+
+
+\hide{File:/afs/cs.cmu.edu/project/clisp/hackers/ram/docs/cmu-user/intro.ms}
+
+
+
+\hide{ -*- Dictionary: cmu-user -*- }
+\begin{comment}
+* Introduction::
+* Design Choices and Extensions::
+* The Debugger::
+* The Compiler::
+* Advanced Compiler Use and Efficiency Hints::
+* UNIX Interface::
+* Event Dispatching with SERVE-EVENT::
+* Alien Objects::
+* Interprocess Communication under LISP::
+* Debugger Programmer's Interface::
+* Function Index::
+* Variable Index::
+* Type Index::
+* Concept Index::
+
+ --- The Detailed Node Listing ---
+
+Introduction
+
+* Support::
+* Local Distribution of CMU Common Lisp::
+* Net Distribution of CMU Common Lisp::
+* Source Availability::
+* Command Line Options::
+* Credits::
+
+Design Choices and Extensions
+
+* Data Types::
+* Default Interrupts for Lisp::
+* Packages::
+* The Editor::
+* Garbage Collection::
+* Describe::
+* The Inspector::
+* Running Programs from Lisp::
+* Saving a Core Image::
+* Pathnames::
+* Filesystem Operations::
+* Time Parsing and Formatting::
+* Lisp Library::
+
+Data Types
+
+* Symbols::
+* Integers::
+* Floats::
+* Characters::
+* Array Initialization::
+
+Floats
+
+* IEEE Special Values::
+* Negative Zero::
+* Denormalized Floats::
+* Floating Point Exceptions::
+* Floating Point Rounding Mode::
+* Accessing the Floating Point Modes::
+
+The Inspector
+
+* The Graphical Interface::
+* The TTY Inspector::
+
+Running Programs from Lisp
+
+* Process Accessors::
+
+Pathnames
+
+* Unix Pathnames::
+* Wildcard Pathnames::
+* Logical Pathnames::
+* Search Lists::
+* Predefined Search-Lists::
+* Search-List Operations::
+* Search List Example::
+
+Logical Pathnames
+
+* Search Lists::
+* Search List Example::
+
+Search-List Operations
+
+* Search List Example::
+
+Filesystem Operations
+
+* Wildcard Matching::
+* File Name Completion::
+* Miscellaneous Filesystem Operations::
+
+The Debugger
+
+* Debugger Introduction::
+* The Command Loop::
+* Stack Frames::
+* Variable Access::
+* Source Location Printing::
+* Compiler Policy Control::
+* Exiting Commands::
+* Information Commands::
+* Breakpoint Commands::
+* Function Tracing::
+* Specials::
+
+Stack Frames
+
+* Stack Motion::
+* How Arguments are Printed::
+* Function Names::
+* Funny Frames::
+* Debug Tail Recursion::
+* Unknown Locations and Interrupts::
+
+Variable Access
+
+* Variable Value Availability::
+* Note On Lexical Variable Access::
+
+Source Location Printing
+
+* How the Source is Found::
+* Source Location Availability::
+
+Breakpoint Commands
+
+* Breakpoint Example::
+
+Function Tracing
+
+* Encapsulation Functions::
+
+The Compiler
+
+* Compiler Introduction::
+* Calling the Compiler::
+* Compilation Units::
+* Interpreting Error Messages::
+* Types in Python::
+* Getting Existing Programs to Run::
+* Compiler Policy::
+* Open Coding and Inline Expansion::
+
+Compilation Units
+
+* Undefined Warnings::
+
+Interpreting Error Messages
+
+* The Parts of the Error Message::
+* The Original and Actual Source::
+* The Processing Path::
+* Error Severity::
+* Errors During Macroexpansion::
+* Error Message Parameterization::
+
+Types in Python
+
+* Compile Time Type Errors::
+* Precise Type Checking::
+* Weakened Type Checking::
+
+Compiler Policy
+
+* The Optimize Declaration::
+* The Optimize-Interface Declaration::
+
+Advanced Compiler Use and Efficiency Hints
+
+* More About Types in Python::
+* Type Inference::
+* Source Optimization::
+* Tail Recursion::
+* Local Call::
+* Block Compilation::
+* Inline Expansion::
+* Byte Coded Compilation::
+* Object Representation::
+* Numbers::
+* General Efficiency Hints::
+* Efficiency Notes::
+* Profiling::
+
+
+* Types::
+* Optimization::
+* Function Call::
+* Representation of Objects::
+* Writing Efficient Code::
+
+
+* More Types Meaningful::
+* Canonicalization::
+* Member Types::
+* Union Types::
+* The Empty Type::
+* Function Types::
+* The Values Declaration::
+* Structure Types::
+* The Freeze-Type Declaration::
+* Type Restrictions::
+* Type Style Recommendations::
+
+Type Inference
+
+* Variable Type Inference::
+* Local Function Type Inference::
+* Global Function Type Inference::
+* Operation Specific Type Inference::
+* Dynamic Type Inference::
+* Type Check Optimization::
+
+Source Optimization
+
+* Let Optimization::
+* Constant Folding::
+* Unused Expression Elimination::
+* Control Optimization::
+* Unreachable Code Deletion::
+* Multiple Values Optimization::
+* Source to Source Transformation::
+* Style Recommendations::
+
+Tail Recursion
+
+* Tail Recursion Exceptions::
+
+Local Call
+
+* Self-Recursive Calls::
+* Let Calls::
+* Closures::
+* Local Tail Recursion::
+* Return Values::
+
+Block Compilation
+
+* Block Compilation Semantics::
+* Block Compilation Declarations::
+* Compiler Arguments::
+* Practical Difficulties::
+* Context Declarations::
+* Context Declaration Example::
+
+Inline Expansion
+
+* Inline Expansion Recording::
+* Semi-Inline Expansion::
+* The Maybe-Inline Declaration::
+
+Object Representation
+
+* Think Before You Use a List::
+* Structure Representation::
+* Arrays::
+* Vectors::
+* Bit-Vectors::
+* Hashtables::
+
+Numbers
+
+* Descriptors::
+* Non-Descriptor Representations::
+* Variables::
+* Generic Arithmetic::
+* Fixnums::
+* Word Integers::
+* Floating Point Efficiency::
+* Specialized Arrays::
+* Specialized Structure Slots::
+* Interactions With Local Call::
+* Representation of Characters::
+
+General Efficiency Hints
+
+* Avoid Unnecessary Consing::
+* Complex Argument Syntax::
+* Mapping and Iteration::
+* Trace Files and Disassembly::
+
+Efficiency Notes
+
+* Type Uncertainty::
+* Efficiency Notes and Type Checking::
+* Representation Efficiency Notes::
+* Verbosity Control::
+
+Profiling
+
+* Profile Interface::
+* Profiling Techniques::
+* Nested or Recursive Calls::
+* Clock resolution::
+* A Note on Timing::
+* Benchmarking Techniques::
+
+UNIX Interface
+
+* Lisp Equivalents for C Routines::
+* Type Translations::
+* System Area Pointers::
+* Unix System Calls::
+* File Descriptor Streams::
+* Making Sense of Mach Return Codes::
+* Unix Interrupts::
+
+Unix Interrupts
+
+* Changing Interrupt Handlers::
+* Examples of Signal Handlers::
+
+Event Dispatching with SERVE-EVENT
+
+* Object Sets::
+* The SERVE-EVENT Function::
+* Using SERVE-EVENT with Unix File Descriptors::
+* Using SERVE-EVENT with the CLX Interface to X::
+* A SERVE-EVENT Example::
+
+Using SERVE-EVENT with the CLX Interface to X
+
+* Without Object Sets::
+* With Object Sets::
+
+A SERVE-EVENT Example
+
+* Without Object Sets Example::
+* With Object Sets Example::
+
+Alien Objects
+
+* Introduction to Aliens::
+* Alien Types::
+* Alien Operations::
+* Alien Variables::
+* Alien Data Structure Example::
+* Alien Function Calls::
+* Step-by-Step Alien Example::
+
+Alien Types
+
+* Defining Alien Types::
+* Alien Types and Lisp Types::
+* Alien Type Specifiers::
+* The C-Call Package::
+
+Alien Operations
+
+* Alien Access Operations::
+* Alien Coercion Operations::
+* Alien Dynamic Allocation::
+
+Alien Variables
+
+* Local Alien Variables::
+* External Alien Variables::
+
+Alien Function Calls
+
+* alien-funcall::               The alien-funcall Primitive
+* def-alien-routine::           The def-alien-routine Macro
+* def-alien-routine Example::
+* Calling Lisp from C::
+
+Interprocess Communication under LISP
+
+* The REMOTE Package::
+* The WIRE Package::
+* Out-Of-Band Data::
+
+The REMOTE Package
+
+* Connecting Servers and Clients::
+* Remote Evaluations::
+* Remote Objects::
+
+The WIRE Package
+
+* Untagged Data::
+* Tagged Data::
+
+Debugger Programmer's Interface
+
+* DI Exceptional Conditions::
+* Debug-variables::
+* Frames::
+* Debug-functions::
+* Debug-blocks::
+* Breakpoints::
+* Code-locations::
+* Debug-sources::
+* Source Translation Utilities::
+
+DI Exceptional Conditions
+
+* Debug-conditions::
+* Debug-errors::
+\end{comment}
+
+%%\node Introduction, Design Choices and Extensions, Top, Top
+\chapter{Introduction}
+
+CMU Common Lisp is a public-domain implementation of Common Lisp developed in
+the Computer Science Department of Carnegie Mellon University.  \cmucl{} runs
+on various Unix workstations---see the README file in the distribution for
+current platforms.  This document describes the implementation based on the
+Python compiler.  Previous versions of CMU Common Lisp ran on the IBM RT PC
+and (when known as Spice Lisp) on the Perq workstation.  See \code{man cmucl}
+(\file{man/man1/cmucl.1}) for other general information.
+
+\cmucl{} sources and executables are freely available via anonymous FTP; this
+software is as is'', and has no warranty of any kind.  CMU and the
+authors assume no responsibility for the consequences of any use of this
+software.  See \file{doc/release-notes.txt} for a description of the
+state of the release you have.
+
+\begin{comment}
+* Support::
+* Local Distribution of CMU Common Lisp::
+* Net Distribution of CMU Common Lisp::
+* Source Availability::
+* Command Line Options::
+* Credits::
+\end{comment}
+
+%%\node Support, Local Distribution of CMU Common Lisp, Introduction, Introduction
+\section{Support}
+
+The CMU Common Lisp project is no longer funded, so only minimal support is
+being done at CMU.  There is a net community of \cmucl{} users and maintainers
+who communicate via comp.lang.lisp and the cmucl-bugs@cs.cmu.edu
+\begin{changebar}
+  cmucl-imp@cons.org
+\end{changebar}
+mailing lists.
+
+This manual contains only implementation-specific information about
+\cmucl.  Users will also need a separate manual describing the
+\clisp{} standard.  \clisp{} was initially defined in \i{Common Lisp:
+  The Language}, by Guy L.  Steele Jr.  \clisp{} is now undergoing
+standardization by the X3J13 committee of ANSI.  The X3J13 spec is not
+yet completed, but a number of clarifications and modification have
+been approved.  We intend that \cmucl{} will eventually adhere to the
+X3J13 spec, and we have already implemented many of the changes
+approved by X3J13.
+
+Until the X3J13 standard is completed, the second edition of
+\cltltwo{} is probably the best available manual for the language and
+for our implementation of it.  This book has no official role in the
+standardization process, but it does include many of the changes
+adopted since the first edition was completed.
+
+In addition to the language itself, this document describes a number
+of useful library modules that run in \cmucl. \hemlock, an Emacs-like
+text editor, is included as an integral part of the \cmucl{}
+environment.  Two documents describe \hemlock{}: the \i{Hemlock User's
+  Manual}, and the \i{Hemlock Command Implementor's Manual}.
+
+%%\node Local Distribution of CMU Common Lisp, Net Distribution of CMU Common Lisp, Support, Introduction
+\section{Local Distribution of CMU Common Lisp}
+
+In CMU CS, \cmucl{} should be runnable as \file{/usr/local/bin/cmucl}.
+The full binary distribution should appear under
+\file{/usr/local/lib/cmucl/}.  Note that the first time you run Lisp,
+it will take AFS several minutes to copy the image into its local
+cache.  Subsequent starts will be much faster.
+
+Or, you can run directly out of the AFS release area (which may be
+script:
+\begin{example}
+setenv CMUCLLIB "/afs/cs/misc/cmucl/@sys/beta/lib"
+setenv PATH \${PATH}:/afs/cs/misc/cmucl/@sys/beta/bin +\end{example} + +If you also set \code{MANPATH} or \code{MPATH} (depending on the Unix) +to point to \file{/usr/local/lib/cmucl/man/}, then \code{man cmucl}' +will give an introduction to CMU CL and \samp{man lisp} will describe +command line options. For installation notes, see the \file{README} +file in the release area. + +See \file{/usr/local/lib/cmucl/doc} for release notes and +documentation. Hardcopy documentation is available in the document +room. Documentation supplements may be available for recent +additions: see the \file{README} file. + +Send bug reports and questions to \samp{cmucl-bugs@cs.cmu.edu}. If +you send a bug report to \samp{gripe} or \samp{help}, they will just +forward it to this mailing list. + +%%\node Net Distribution of CMU Common Lisp, Source Availability, Local Distribution of CMU Common Lisp, Introduction +\section{Net Distribution of CMU Common Lisp} + +\subsection{CMU Distribution} +Externally, CMU Common Lisp is only available via anonymous FTP. We +don't have the manpower to make tapes. These are our distribution +machines: +\begin{example} +lisp-rt1.slisp.cs.cmu.edu (128.2.217.9) +lisp-rt2.slisp.cs.cmu.edu (128.2.217.10) +\end{example} + +Log in with the user \samp{anonymous} and \samp{username@host} as +password (i.e. your EMAIL address.) When you log in, the current +directory should be set to the \cmucl{} release area. If you have any +trouble with FTP access, please send mail to \samp{slisp@cs.cmu.edu}. + +The release area holds compressed tar files with names of the form: +\begin{example} +\var{version}-\var{machine}_\var{os}.tar.Z +\end{example} +FTP compressed tar archives in binary mode. To extract, \samp{cd} to +the directory that is to be the root of the tree, then type: +\begin{example} +uncompress <file.tar.Z | tar xf - . +\end{example} +The resulting tree is about 23 megabytes. For installation +directions, see the section site initialization'' in README file at +the root of the tree. + +If poor network connections make it difficult to transfer a 10 meg +file, the release is also available split into five parts, with the +suffix \file{.0} to \file{.4}. To extract from multiple files, use: +\begin{example} +cat file.tar.Z.* | uncompress | tar xf - . +\end{example} + +The release area also contains source distributions and other binary +distributions. A listing of the current contents of the release area +is in \file{FILES}. Major release announcements will be made to +\code{comp.lang.lisp} until there is enough volume to warrant a +\code{comp.lang.lisp.cmu}. + +\begin{changebar} +\subsection{Net Distribution} +Although the CMU Common Lisp project is no longer actively developed +by CMU, development has continued. You can obtain this version from +either +\begin{example} + ftp://ftp2.cons.org/pub/languages/lisp/cmucl + http://www2.cons.org:8000/ftp-area/cmucl/ +\end{example} +Further information can be found via the World Wide Web at +\begin{example} + http://www.cons.org/cmucl +\end{example} +\end{changebar} +%%\node Source Availability, Command Line Options, Net Distribution of CMU Common Lisp, Introduction +\section{Source Availability} + +Lisp and documentation sources are available via anonymous FTP ftp to +any CMU CS machine. All CMU written code is public domain, but CMU CL +also makes use of two imported packages: PCL and CLX. Although these +packages are copyrighted, they may be freely distributed without any +licensing agreement or fee. See the \file{README} file in the binary +distribution for up-to-date source pointers. + +The release area contains a source distribution, which is an image of +all the \file{.lisp} source files used to build a particular system +\var{version}: +\begin{example} +\var{version}-source.tar.Z (3.6 meg) +\end{example} + +All of our files (including the release area) are actually in the AFS +file system. On the release machines, the FTP server's home is the +release directory: \file{/afs/cs.cmu.edu/project/clisp/release}. The +actual working source areas are in other subdirectories of +\file{clisp}, and you can directly cd'' to those directories if you +know the name. Due to the way anonymous FTP access control is done, +it is important to cd'' to the source directory with a single +command, and then do a get'' operation. + +\begin{changebar} + Alternatively, you can obtain the current sources via WWW at + \begin{example} + http://www.cons.org/cmucl + \end{example} + which contains pointers on how to get a \code{tar} file of the + current sources or how to get an individual file from the sources. + Binary versions for selected platforms are also available as well. +\end{changebar} + +%%\node Command Line Options, Credits, Source Availability, Introduction +\section{Command Line Options} + +The command line syntax and environment is described in the lisp(1) +man page in the man/man1 directory of the distribution. See also +cmucl(1). Currently Lisp accepts the following switches: +\begin{Lentry} + \begin{changebar} + \item[\code{-batch}] specifies batch mode, where all input is + directed from standard-input. An error code of 0 is returned upon + encountering an EOF and 1 otherwise. + \end{changebar} +\item[\code{-core}] requires an argument that should be the name of a + core file. Rather than using the default core file + (\file{lib/lisp.core}), the specified core file is loaded. + +\item[\code{-edit}] specifies to enter Hemlock. A file to edit may be + specified by placing the name of the file between the program name + (usually \file{lisp}) and the first switch. + +\item[\code{-eval}] accepts one argument which should be a Lisp form + to evaluate during the start up sequence. The value of the form + will not be printed unless it is wrapped in a form that does output. + +\item[\code{-hinit}] accepts an argument that should be the name of + the hemlock init file to load the first time the function + \findexed{ed} is invoked. The default is to load + \file{hemlock-init.\var{object-type}}, or if that does not exist, + \file{hemlock-init.lisp} from the user's home directory. If the + file is not in the user's home directory, the full path must be + specified. + +\item[\code{-init}] accepts an argument that should be the name of an + init file to load during the normal start up sequence. The default + is to load \file{init.\var{object-type}} or, if that does not exist, + \file{init.lisp} from the user's home directory. If the file is not + in the user's home directory, the full path must be specified. + +\item[\code{-noinit}] accepts no arguments and specifies that an init + file should not be loaded during the normal start up sequence. + Also, this switch suppresses the loading of a hemlock init file when + Hemlock is started up with the \code{-edit} switch. + +\item[\code{-load}] accepts an argument which should be the name of a + file to load into Lisp before entering Lisp's read-eval-print loop. + +\item[\code{-slave}] specifies that Lisp should start up as a + \i{slave} Lisp and try to connect to an editor Lisp. The name of + the editor to connect to must be specified\dash{}to find the + editor's name, use the \hemlock{} \code{Accept Slave + Connections}'' command. The name for the editor Lisp is of the + form: + \begin{example} + \var{machine-name}\code{:}\var{socket} + \end{example} + where \var{machine-name} is the internet host name for the machine + and \var{socket} is the decimal number of the socket to connect to. +\end{Lentry} +For more details on the use of the \code{-edit} and \code{-slave} +switches, see the \i{Hemlock User's Manual}. + +Arguments to the above switches can be specified in one of two ways: +\w{\var{switch}\code{=}\var{value}} or +\w{\var{switch}<\var{space}>\var{value}}. For example, to start up +the saved core file mylisp.core use either of the following two +commands: +\begin{example} +\code{lisp -core=mylisp.core +lisp -core mylisp.core} +\end{example} + +%%\node Credits, , Command Line Options, Introduction +\section{Credits} + +Since 1981 many people have contributed to the development of CMU +Common Lisp. The currently active members are: +\begin{display} +Marco Antoniotti +David Axmark +Miles Bader +Casper Dik +Scott Fahlman * (fearless leader) +Paul Gleichauf * +Richard Harris +Joerg-Cyril Hoehl +Chris Hoover +Simon Leinen +Sandra Loosemore +William Lott * +Robert A. Maclachlan * +\end{display} +\noindent +Many people are voluntarily working on improving CMU Common Lisp. *'' +means a full-time CMU employee, and +'' means a part-time student +employee. A partial listing of significant past contributors follows: +\begin{display} +Tim Moore +Sean Hallgren + +Mike Garland + +Ted Dunning +Rick Busdiecker +Bill Chiles * +John Kolojejchick +Todd Kaufmann + +Dave McDonald * +Skef Wholey * +\end{display} + + +\vspace{2 em} +\researchcredit + +\begin{changebar} + From 1995, development of CMU Common Lisp has been continued by a + group of volunteers. A partial list of volunteers includes the + following + \begin{table}[h] + \begin{center} + \begin{tabular}{ll} + Paul Werkowski & pw@snoopy.mv.com \\ + Peter VanEynde & s950045@uia.ua.ac.be \\ + Marco Antoniotti & marcoxa@PATH.Berkeley.EDU\\ + Martin Cracauer & cracauer@cons.org\\ + Douglas Thomas Crosher & dtc@scrooge.ee.swin.oz.au\\ + Simon Leinen & simon@switch.ch\\ + Rob MacLachlan & ram+@CS.cmu.edu\\ + Raymond Toy & toy@rtp.ericsson.se + \end{tabular} + \end{center} + \end{table} + + In particular Paul Werkowski completed the port for the x86 + architecture for FreeBSD. Peter VanEnyde took the FreeBSD port and + created a Linux version. +\end{changebar} + + +\hide{File:/afs/cs.cmu.edu/project/clisp/hackers/ram/docs/cmu-user/design.ms} + +\hide{ -*- Dictionary: cmu-user -*- } +%%\node Design Choices and Extensions, The Debugger, Introduction, Top +\chapter{Design Choices and Extensions} + +Several design choices in Common Lisp are left to the individual +implementation, and some essential parts of the programming environment +are left undefined. This chapter discusses the most important design +choices and extensions. + +\begin{comment} +* Data Types:: +* Default Interrupts for Lisp:: +* Packages:: +* The Editor:: +* Garbage Collection:: +* Describe:: +* The Inspector:: +* Load:: +* The Reader:: +* Running Programs from Lisp:: +* Saving a Core Image:: +* Pathnames:: +* Filesystem Operations:: +* Time Parsing and Formatting:: +* Lisp Library:: +\end{comment} + +%%\node Data Types, Default Interrupts for Lisp, Design Choices and Extensions, Design Choices and Extensions +\section{Data Types} + +\begin{comment} +* Symbols:: +* Integers:: +* Floats:: +* Characters:: +* Array Initialization:: +\end{comment} + +%%\node Symbols, Integers, Data Types, Data Types +\subsection{Symbols} + +As in \cltl, all symbols and package names are printed in lower case, as +a user is likely to type them. Internally, they are normally stored +upper case only. + +%%\node Integers, Floats, Symbols, Data Types +\subsection{Integers} + +The \tindexed{fixnum} type is equivalent to \code{(signed-byte 30)}. +Integers outside this range are represented as a \tindexed{bignum} or +a word integer (\pxlref{word-integers}.) Almost all integers that +appear in programs can be represented as a \code{fixnum}, so integer +number consing is rare. + +%%\node Floats, Characters, Integers, Data Types +\subsection{Floats} +\label{ieee-float} + +\cmucl{} supports two floating point formats: \tindexed{single-float} +and \tindexed{double-float}. These are implemented with IEEE single +and double float arithmetic, respectively. \code{short-float} is a +synonym for \code{single-float}, and \code{long-float} is a synonym +for \code{double-float}. The initial value of +\vindexed{read-default-float-format} is \code{single-float}. + +Both \code{single-float} and \code{double-float} are represented with +a pointer descriptor, so float operations can cause number consing. +Number consing is greatly reduced if programs are written to allow the +use of non-descriptor representations (\pxlref{numeric-types}.) + + +\begin{comment} +* IEEE Special Values:: +* Negative Zero:: +* Denormalized Floats:: +* Floating Point Exceptions:: +* Floating Point Rounding Mode:: +* Accessing the Floating Point Modes:: +\end{comment} + +%%\node IEEE Special Values, Negative Zero, Floats, Floats +\subsubsection{IEEE Special Values} + +\cmucl{} supports the IEEE infinity and NaN special values. These +non-numeric values will only be generated when trapping is disabled +for some floating point exception (\pxlref{float-traps}), so users of +the default configuration need not concern themselves with special +values. + +\begin{defconst}{extensions:}{short-float-positive-infinity} + \defconstx[extensions:]{short-float-negative-infinity} + \defconstx[extensions:]{single-float-positive-infinity} + \defconstx[extensions:]{single-float-negative-infinity} + \defconstx[extensions:]{double-float-positive-infinity} + \defconstx[extensions:]{double-float-negative-infinity} + \defconstx[extensions:]{long-float-positive-infinity} + \defconstx[extensions:]{long-float-negative-infinity} + + The values of these constants are the IEEE positive and negative + infinity objects for each float format. +\end{defconst} + +\begin{defun}{extensions:}{float-infinity-p}{\args{\var{x}}} + + This function returns true if \var{x} is an IEEE float infinity (of + either sign.) \var{x} must be a float. +\end{defun} + +\begin{defun}{extensions:}{float-nan-p}{\args{\var{x}}} + \defunx[extensions:]{float-trapping-nan-p}{\args{\var{x}}} + + \code{float-nan-p} returns true if \var{x} is an IEEE NaN (Not A + Number) object. \code{float-trapping-nan-p} returns true only if + \var{x} is a trapping NaN. With either function, \var{x} must be a + float. +\end{defun} + +%%\node Negative Zero, Denormalized Floats, IEEE Special Values, Floats +\subsubsection{Negative Zero} + +The IEEE float format provides for distinct positive and negative +zeros. To test the sign on zero (or any other float), use the +\clisp{} \findexed{float-sign} function. Negative zero prints as +\code{-0.0f0} or \code{-0.0d0}. + +%%\node Denormalized Floats, Floating Point Exceptions, Negative Zero, Floats +\subsubsection{Denormalized Floats} + +\cmucl{} supports IEEE denormalized floats. Denormalized floats +provide a mechanism for gradual underflow. The \clisp{} +\findexed{float-precision} function returns the actual precision of a +denormalized float, which will be less than \findexed{float-digits}. +Note that in order to generate (or even print) denormalized floats, +trapping must be disabled for the underflow exception +(\pxlref{float-traps}.) The \clisp{} +\w{\code{least-positive-}\var{format}-\code{float}} constants are +denormalized. + +\begin{defun}{extensions:}{float-normalized-p}{\args{\var{x}}} + + This function returns true if \var{x} is a denormalized float. + \var{x} must be a float. +\end{defun} + +%%\node Floating Point Exceptions, Floating Point Rounding Mode, Denormalized Floats, Floats +\subsubsection{Floating Point Exceptions} +\label{float-traps} + +The IEEE floating point standard defines several exceptions that occur +when the result of a floating point operation is unclear or +undesirable. Exceptions can be ignored, in which case some default +action is taken, such as returning a special value. When trapping is +enabled for an exception, a error is signalled whenever that exception +occurs. These are the possible floating point exceptions: +\begin{Lentry} + +\item[\kwd{underflow}] This exception occurs when the result of an + operation is too small to be represented as a normalized float in + its format. If trapping is enabled, the + \tindexed{floating-point-underflow} condition is signalled. + Otherwise, the operation results in a denormalized float or zero. + +\item[\kwd{overflow}] This exception occurs when the result of an + operation is too large to be represented as a float in its format. + If trapping is enabled, the \tindexed{floating-point-overflow} + exception is signalled. Otherwise, the operation results in the + appropriate infinity. + +\item[\kwd{inexact}] This exception occurs when the result of a + floating point operation is not exact, i.e. the result was rounded. + If trapping is enabled, the \code{extensions:floating-point-inexact} + condition is signalled. Otherwise, the rounded result is returned. + +\item[\kwd{invalid}] This exception occurs when the result of an + operation is ill-defined, such as \code{\w{(/ 0.0 0.0)}}. If + trapping is enabled, the \code{extensions:floating-point-invalid} + condition is signalled. Otherwise, a quiet NaN is returned. + +\item[\kwd{divide-by-zero}] This exception occurs when a float is + divided by zero. If trapping is enabled, the + \tindexed{divide-by-zero} condition is signalled. Otherwise, the + appropriate infinity is returned. +\end{Lentry} + +%%\node Floating Point Rounding Mode, Accessing the Floating Point Modes, Floating Point Exceptions, Floats +\subsubsection{Floating Point Rounding Mode} +\label{float-rounding-modes} + +IEEE floating point specifies four possible rounding modes: +\begin{Lentry} + +\item[\kwd{nearest}] In this mode, the inexact results are rounded to + the nearer of the two possible result values. If the neither + possibility is nearer, then the even alternative is chosen. This + form of rounding is also called round to even'', and is the form + of rounding specified for the \clisp{} \findexed{round} function. + +\item[\kwd{positive-infinity}] This mode rounds inexact results to the + possible value closer to positive infinity. This is analogous to + the \clisp{} \findexed{ceiling} function. + +\item[\kwd{negative-infinity}] This mode rounds inexact results to the + possible value closer to negative infinity. This is analogous to + the \clisp{} \findexed{floor} function. + +\item[\kwd{zero}] This mode rounds inexact results to the possible + value closer to zero. This is analogous to the \clisp{} + \findexed{truncate} function. +\end{Lentry} + +\paragraph{Warning:} + +Although the rounding mode can be changed with +\code{set-floating-point-modes}, use of any value other than the +default (\kwd{nearest}) can cause unusual behavior, since it will +affect rounding done by \llisp{} system code as well as rounding in +user code. In particular, the unary \code{round} function will stop +doing round-to-nearest on floats, and instead do the selected form of +rounding. + +%%\node Accessing the Floating Point Modes, , Floating Point Rounding Mode, Floats +\subsubsection{Accessing the Floating Point Modes} + +These functions can be used to modify or read the floating point modes: + +\begin{defun}{extensions:}{set-floating-point-modes}{% + \keys{\kwd{traps} \kwd{rounding-mode}} + \morekeys{\kwd{fast-mode} \kwd{accrued-exceptions}} + \yetmorekeys{\kwd{current-exceptions}}} + \defunx[extensions:]{get-floating-point-modes}{} + + The keyword arguments to \code{set-floating-point-modes} set various + modes controlling how floating point arithmetic is done: + \begin{Lentry} + + \item[\kwd{traps}] A list of the exception conditions that should + cause traps. Possible exceptions are \kwd{underflow}, + \kwd{overflow}, \kwd{inexact}, \kwd{invalid} and + \kwd{divide-by-zero}. Initially all traps except \kwd{inexact} + are enabled. \xlref{float-traps}. + + \item[\kwd{rounding-mode}] The rounding mode to use when the result + is not exact. Possible values are \kwd{nearest}, + \latex{\kwd{positive\-infinity}}\html{\kwd{positive-infinity}}, + \kwd{negative-infinity} and \kwd{zero}. Initially, the rounding + mode is \kwd{nearest}. See the warning in section + \ref{float-rounding-modes} about use of other rounding modes. + + \item[\kwd{current-exceptions}, \kwd{accrued-exceptions}] Lists of + exception keywords used to set the exception flags. The + \var{current-exceptions} are the exceptions for the previous + operation, so setting it is not very useful. The + \var{accrued-exceptions} are a cumulative record of the exceptions + that occurred since the last time these flags were cleared. + Specifying \code{()} will clear any accrued exceptions. + + \item[\kwd{fast-mode}] Set the hardware's fast mode'' flag, if + any. When set, IEEE conformance or debuggability may be impaired. + Some machines may not have this feature, in which case the value + is always \false. No currently supported machines have a fast + mode. + \end{Lentry} + If a keyword argument is not supplied, then the associated state is + not changed. + + \code{get-floating-point-modes} returns a list representing the + state of the floating point modes. The list is in the same format + as the keyword arguments to \code{set-floating-point-modes}, so + \code{apply} could be used with \code{set-floating-point-modes} to + restore the modes in effect at the time of the call to + \code{get-floating-point-modes}. +\end{defun} + +\begin{changebar} +To make handling control of floating-point exceptions, the following +macro is useful. + +\begin{defmac}{ext:}{with-float-traps-masked}{traps \ampbody\ body} + \code{body} is executed with the selected floating-point exceptions + given by \code{traps} masked out (disabled). \code{traps} should be + a list of possible floating-point exceptions that should be ignored. + Possible values are \kwd{underflow}, \kwd{overflow}, \kwd{inexact}, + \kwd{invalid} and \kwd{divide-by-zero}. + + This is equivalent to saving the current traps from + \code{get-floating-point-modes}, setting the floating-point modes to + the desired exceptions, running the \code{body}, and restoring the + saved floating-point modes. The advantage of this macro is that it + causes less consing to occur. + + Some points about the with-float-traps-masked: + + \begin{itemize} + \item Two approaches are available for detecting FP exceptions: + \begin{enumerate} + \item enabling the traps and handling the exceptions + \item disabling the traps and either handling the return values or + checking the accrued exceptions. + \end{enumerate} + Of these the latter is the most portable because on the alpha port + it is not possible to enable some traps at run-time. + + \item To assist the checking of the exceptions within the body any + accrued exceptions matching the given traps are cleared at the + start of the body when the traps are masked. + + \item To allow the macros to be nested these accrued exceptions are + restored at the end of the body to their values at the start of + the body. Thus any exceptions that occurred within the body will + not affect the accrued exceptions outside the macro. + + \item Note that only the given exceptions are restored at the end of + the body so other exception will be visible in the accrued + exceptions outside the body. + + \item On the x86, setting the accrued exceptions of an unmasked + exception would cause a FP trap. The macro behaviour of restoring + the accrued exceptions ensures than if an accrued exception is + initially not flagged and occurs within the body it will be + restored/cleared at the exit of the body and thus not cause a + trap. + + \item On the x86, and, perhaps, the hppa, the FP exceptions may be + delivered at the next FP instruction which requires a FP + \code{wait} instruction (\code{%vm::float-wait}) if using the lisp + conditions to catch trap within a \code{handler-bind}. The + \code{handler-bind} macro does the right thing and inserts a + float-wait (at the end of its body on the x86). The masking and + noting of exceptions is also safe here. + + \item The setting of the FP flags uses the + \code{(floating-point-modes)} and the \code{(set + (floating-point-modes)\ldots)} VOPs. These VOPs blindly update + the flags which may include other state. We assume this state + hasn't changed in between getting and setting the state. For + example, if you used the FP unit between the above calls, the + state may be incorrectly restored! The + \code{with-float-traps-masked} macro keeps the intervening code to + a minimum and uses only integer operations. + %% Safe byte-compiled? + %% Perhaps the VOPs (x86) should be smarter and only update some of + %% the flags, the trap masks and exceptions? + \end{itemize} + +\end{defmac} +\end{changebar} + +%%\node Characters, Array Initialization, Floats, Data Types +\subsection{Characters} + +\cmucl{} implements characters according to \i{Common Lisp: the + Language II}. The main difference from the first version is that +character bits and font have been eliminated, and the names of the +types have been changed. \tindexed{base-character} is the new +equivalent of the old \tindexed{string-char}. In this implementation, +all characters are base characters (there are no extended characters.) +Character codes range between \code{0} and \code{255}, using the ASCII +encoding. +\begin{changebar} + Table~\ref{tbl:chars}~\vpageref{tbl:chars} shows characters + recognized by \cmucl. +\end{changebar} + +\begin{changebar} +\begin{table}[tbhp] + \begin{center} + \begin{tabular}{|c|c|l|l|l|l|} + \hline + \multicolumn{2}{|c|}{ASCII} & \multicolumn{1}{|c}{Lisp} & + \multicolumn{3}{|c|}{} \\ + \cline{1-2} + Name & Code & \multicolumn{1}{|c|}{Name} & \multicolumn{3}{|c|}{\raisebox{1.5ex}{Alternatives}}\\ + \hline + \hline + \code{nul} & 0 & \code{\#\back{NULL}} & \code{\#\back{NUL}} & &\\ + \code{bel} & 7 & \code{\#\back{BELL}} & & &\\ + \code{bs} & 8 & \code{\#\back{BACKSPACE}} & \code{\#\back{BS}} & &\\ + \code{tab} & 9 & \code{\#\back{TAB}} & & &\\ + \code{lf} & 10 & \code{\#\back{NEWLINE}} & \code{\#\back{NL}} & \code{\#\back{LINEFEED}} & \code{\#\back{LF}}\\ + \code{ff} & 11 & \code{\#\back{VT}} & \code{\#\back{PAGE}} & \code{\#\back{FORM}} &\\ + \code{cr} & 13 & \code{\#\back{RETURN}} & \code{\#\back{CR}} & &\\ + \code{esc} & 27 & \code{\#\back{ESCAPE}} & \code{\#\back{ESC}} & \code{\#\back{ALTMODE}} & \code{\#\back{ALT}}\\ + \code{sp} & 32 & \code{\#\back{SPACE}} & \code{\#\back{SP}} & &\\ + \code{del} & 127 & \code{\#\back{DELETE}} & \code{\#\back{RUBOUT}} & &\\ + \hline + \end{tabular} + \caption{Characters recognized by \cmucl} + \label{tbl:chars} + \end{center} +\end{table} +\end{changebar} + +%%\node Array Initialization, , Characters, Data Types +\subsection{Array Initialization} + +If no \kwd{initial-value} is specified, arrays are initialized to zero. + + +%%\node Default Interrupts for Lisp, Packages, Data Types, Design Choices and Extensions +\section{Default Interrupts for Lisp} + +CMU Common Lisp has several interrupt handlers defined when it starts up, +as follows: +\begin{Lentry} + +\item[\code{SIGINT} (\ctrl{c})] causes Lisp to enter a break loop. + This puts you into the debugger which allows you to look at the + current state of the computation. If you proceed from the break + loop, the computation will proceed from where it was interrupted. + +\item[\code{SIGQUIT} (\ctrl{L})] causes Lisp to do a throw to the + top-level. This causes the current computation to be aborted, and + control returned to the top-level read-eval-print loop. + +\item[\code{SIGTSTP} (\ctrl{z})] causes Lisp to suspend execution and + return to the Unix shell. If control is returned to Lisp, the + computation will proceed from where it was interrupted. + +\item[\code{SIGILL}, \code{SIGBUS}, \code{SIGSEGV}, and \code{SIGFPE}] + cause Lisp to signal an error. +\end{Lentry} +For keyboard interrupt signals, the standard interrupt character is in +parentheses. Your \file{.login} may set up different interrupt +characters. When a signal is generated, there may be some delay before +it is processed since Lisp cannot be interrupted safely in an arbitrary +place. The computation will continue until a safe point is reached and +then the interrupt will be processed. \xlref{signal-handlers} to define +your own signal handlers. + +%%\node Packages, The Editor, Default Interrupts for Lisp, Design Choices and Extensions +\section{Packages} + +When CMU Common Lisp is first started up, the default package is the +\code{user} package. The \code{user} package uses the +\code{common-lisp}, \code{extensions}, and \code{pcl} packages. The +symbols exported from these three packages can be referenced without +package qualifiers. This section describes packages which have +exported interfaces that may concern users. The numerous internal +packages which implement parts of the system are not described here. +Package nicknames are in parenthesis after the full name. +\begin{Lentry} +\item[\code{alien}, \code{c-call}] Export the features of the Alien + foreign data structure facility (\pxlref{aliens}.) + +\item[\code{pcl}] This package contains PCL (Portable CommonLoops), + which is a portable implementation of CLOS (the Common Lisp Object + System.) This implements most (but not all) of the features in the + CLOS chapter of \cltltwo. + +\item[\code{debug}] The \code{debug} package contains the command-line + oriented debugger. It exports utility various functions and + switches. + +\item[\code{debug-internals}] The \code{debug-internals} package + exports the primitives used to write debuggers. + \xlref{debug-internals}. + +\item[\code{extensions (ext)}] The \code{extensions} packages exports + local extensions to Common Lisp that are documented in this manual. + Examples include the \code{save-lisp} function and time parsing. + +\item[\code{hemlock (ed)}] The \code{hemlock} package contains all the + code to implement Hemlock commands. The \code{hemlock} package + currently exports no symbols. + +\item[\code{hemlock-internals (hi)}] The \code{hemlock-internals} + package contains code that implements low level primitives and + exports those symbols used to write Hemlock commands. + +\item[\code{keyword}] The \code{keyword} package contains keywords + (e.g., \kwd{start}). All symbols in the \code{keyword} package are + exported and evaluate to themselves (i.e., the value of the symbol + is the symbol itself). + +\item[\code{profile}] The \code{profile} package exports a simple + run-time profiling facility (\pxlref{profiling}). + +\item[\code{common-lisp (cl lisp)}] The \code{common-lisp} package + exports all the symbols defined by \i{Common Lisp: the Language} and + only those symbols. Strictly portable Lisp code will depend only on + the symbols exported from the \code{lisp} package. + +\item[\code{unix}, \code{mach}] These packages export system call + interfaces to generic BSD Unix and Mach (\pxlref{unix-interface}). + +\item[\code{system (sys)}] The \code{system} package contains + functions and information necessary for system interfacing. This + package is used by the \code{lisp} package and exports several + symbols that are necessary to interface to system code. + +\item[\code{common-lisp-user (user cl-user)}] The + \code{common-lisp-user} package is the default package and is where + a user's code and data is placed unless otherwise specified. This + package exports no symbols. + +\item[\code{xlib}] The \code{xlib} package contains the Common Lisp X + interface (CLX) to the X11 protocol. This is mostly Lisp code with + a couple of functions that are defined in C to connect to the + server. + +\item[\code{wire}] The \code{wire} package exports a remote procedure + call facility (\pxlref{remote}). +\end{Lentry} + + +%%\node The Editor, Garbage Collection, Packages, Design Choices and Extensions +\section{The Editor} + +The \code{ed} function invokes the Hemlock editor which is described +in \i{Hemlock User's Manual} and \i{Hemlock Command Implementor's + Manual}. Most users at CMU prefer to use Hemlock's slave \Llisp{} +mechanism which provides an interactive buffer for the +\code{read-eval-print} loop and editor commands for evaluating and +compiling text from a buffer into the slave \Llisp. Since the editor +runs in the \Llisp, using slaves keeps users from trashing their +editor by developing in the same \Llisp{} with \Hemlock. + + +%%\node Garbage Collection, Describe, The Editor, Design Choices and Extensions +\section{Garbage Collection} + +CMU Common Lisp uses a stop-and-copy garbage collector that compacts +the items in dynamic space every time it runs. Most users cause the +system to garbage collect (GC) frequently, long before space is +exhausted. With 16 or 24 megabytes of memory, causing GC's more +frequently on less garbage allows the system to GC without much (if +any) paging. + +\hide{ +With the default value for the following variable, you can expect a GC to take +about one minute of elapsed time on a 6 megabyte machine running X as well as +Lisp. On machines with 8 megabytes or more of memory a GC should run without +much (if any) paging. GC's run more frequently but tend to take only about 5 +seconds. +} + +The following functions invoke the garbage collector or control whether +automatic garbage collection is in effect: + +\begin{defun}{extensions:}{gc}{} + + This function runs the garbage collector. If + \code{ext:*gc-verbose*} is non-\nil, then it invokes + \code{ext:*gc-notify-before*} before GC'ing and + \code{ext:*gc-notify-after*} afterwards. +\end{defun} + +\begin{defun}{extensions:}{gc-off}{} + + This function inhibits automatic garbage collection. After calling + it, the system will not GC unless you call \code{ext:gc} or + \code{ext:gc-on}. +\end{defun} + +\begin{defun}{extensions:}{gc-on}{} + + This function reinstates automatic garbage collection. If the + system would have GC'ed while automatic GC was inhibited, then this + will call \code{ext:gc}. +\end{defun} + +%%\node +\subsection{GC Parameters} +The following variables control the behavior of the garbage collector: + +\begin{defvar}{extensions:}{bytes-consed-between-gcs} + + CMU Common Lisp automatically GC's whenever the amount of memory + allocated to dynamic objects exceeds the value of an internal + variable. After each GC, the system sets this internal variable to + the amount of dynamic space in use at that point plus the value of + the variable \code{ext:*bytes-consed-between-gcs*}. The default + value is 2000000. +\end{defvar} + +\begin{defvar}{extensions:}{gc-verbose} + + This variable controls whether \code{ext:gc} invokes the functions + in \code{ext:*gc-notify-before*} and + \code{ext:*gc-notify-after*}. If \code{*gc-verbose*} is \nil, + \code{ext:gc} foregoes printing any messages. The default value is + \code{T}. +\end{defvar} + +\begin{defvar}{extensions:}{gc-notify-before} + + This variable's value is a function that should notify the user that + the system is about to GC. It takes one argument, the amount of + dynamic space in use before the GC measured in bytes. The default + value of this variable is a function that prints a message similar + to the following: +\begin{display} + \b{[GC threshold exceeded with 2,107,124 bytes in use. Commencing GC.]} +\end{display} +\end{defvar} + +\begin{defvar}{extensions:}{gc-notify-after} + + This variable's value is a function that should notify the user when + a GC finishes. The function must take three arguments, the amount + of dynamic spaced retained by the GC, the amount of dynamic space + freed, and the new threshold which is the minimum amount of space in + use before the next GC will occur. All values are byte quantities. + The default value of this variable is a function that prints a + message similar to the following: + \begin{display} + \b{[GC completed with 25,680 bytes retained and 2,096,808 bytes freed.]} + \b{[GC will next occur when at least 2,025,680 bytes are in use.]} + \end{display} +\end{defvar} + +Note that a garbage collection will not happen at exactly the new +threshold printed by the default \code{ext:*gc-notify-after*} +function. The system periodically checks whether this threshold has +been exceeded, and only then does a garbage collection. + +\begin{defvar}{extensions:}{gc-inhibit-hook} + + This variable's value is either a function of one argument or \nil. + When the system has triggered an automatic GC, if this variable is a + function, then the system calls the function with the amount of + dynamic space currently in use (measured in bytes). If the function + returns \nil, then the GC occurs; otherwise, the system inhibits + automatic GC as if you had called \code{ext:gc-off}. The writer of + this hook is responsible for knowing when automatic GC has been + turned off and for calling or providing a way to call + \code{ext:gc-on}. The default value of this variable is \nil. +\end{defvar} + +\begin{defvar}{extensions:}{before-gc-hooks} + \defvarx[extensions:]{after-gc-hooks} + + These variables' values are lists of functions to call before or + after any GC occurs. The system provides these purely for + side-effect, and the functions take no arguments. +\end{defvar} + +%%\node +\subsection{Weak Pointers} + +A weak pointer provides a way to maintain a reference to an object +without preventing an object from being garbage collected. If the +garbage collector discovers that the only pointers to an object are +weak pointers, then it breaks the weak pointers and deallocates the +object. + +\begin{defun}{extensions:}{make-weak-pointer}{\args{\var{object}}} + \defunx[extensions:]{weak-pointer-value}{\args{\var{weak-pointer}}} + + \code{make-weak-pointer} returns a weak pointer to an object. + \code{weak-pointer-value} follows a weak pointer, returning the two + values: the object pointed to (or \false{} if broken) and a boolean + value which is true if the pointer has been broken. +\end{defun} + +%%\node +\subsection{Finalization} + +Finalization provides a hook'' that is triggered when the garbage +collector reclaims an object. It is usually used to recover non-Lisp +resources that were allocated to implement the finalized Lisp object. +For example, when a unix file-descriptor stream is collected, +finalization is used to close the underlying file descriptor. + +\begin{defun}{extensions:}{finalize}{\args{\var{object} \var{function}}} + + This function registers \var{object} for finalization. + \var{function} is called with no arguments when \var{object} is + reclaimed. Normally \var{function} will be a closure over the + underlying state that needs to be freed, e.g. the unix file + descriptor in the fd-stream case. Note that \var{function} must not + close over \var{object} itself, as this prevents the object from + ever becoming garbage. +\end{defun} + +\begin{defun}{extensions:}{cancel-finalization}{\args{\var{object}}} + + This function cancel any finalization request for \var{object}. +\end{defun} + +%%\node Describe, The Inspector, Garbage Collection, Design Choices and Extensions +\section{Describe} + +In addition to the basic function described below, there are a number of +switches and other things that can be used to control \code{describe}'s +behavior. + +\begin{defun}{}{describe}{ \args{\var{object} \&optional{} \var{stream}}} + + The \code{describe} function prints useful information about + \var{object} on \var{stream}, which defaults to + \code{*standard-output*}. For any object, \code{describe} will + print out the type. Then it prints other information based on the + type of \var{object}. The types which are presently handled are: + + \begin{Lentry} + + \item[\tindexed{hash-table}] \code{describe} prints the number of + entries currently in the hash table and the number of buckets + currently allocated. + + \item[\tindexed{function}] \code{describe} prints a list of the + function's name (if any) and its formal parameters. If the name + has function documentation, then it will be printed. If the + function is compiled, then the file where it is defined will be + printed as well. + + \item[\tindexed{fixnum}] \code{describe} prints whether the integer + is prime or not. + + \item[\tindexed{symbol}] The symbol's value, properties, and + documentation are printed. If the symbol has a function + definition, then the function is described. + \end{Lentry} + If there is anything interesting to be said about some component of + the object, describe will invoke itself recursively to describe that + object. The level of recursion is indicated by indenting output. +\end{defun} + +\begin{defvar}{extensions:}{describe-level} + + The maximum level of recursive description allowed. Initially two. +\end{defvar} + +\begin{defvar}{extensions:}{describe-indentation} + +The number of spaces to indent for each level of recursive +description, initially three. +\end{defvar} + +\begin{defvar}{extensions:}{describe-print-level} + \defvarx[extensions:]{describe-print-length} + + The values of \code{*print-level*} and \code{*print-length*} during + description. Initially two and five. +\end{defvar} + +%%\node The Inspector, Load, Describe, Design Choices and Extensions +\section{The Inspector} + +\cmucl{} has both a graphical inspector that uses X windows and a simple +terminal-based inspector. + +\begin{defun}{}{inspect}{ \args{\ampoptional{} \var{object}}} + + \code{inspect} calls the inspector on the optional argument + \var{object}. If \var{object} is unsupplied, \code{inspect} + immediately returns \false. Otherwise, the behavior of inspect + depends on whether Lisp is running under X. When \code{inspect} is + eventually exited, it returns some selected Lisp object. +\end{defun} + +\begin{comment} +* The Graphical Interface:: +* The TTY Inspector:: +\end{comment} + +%%\node The Graphical Interface, The TTY Inspector, The Inspector, The Inspector +\subsection{The Graphical Interface} +\label{motif-interface} + +CMU Common Lisp has an interface to Motif which is functionally similar to +CLM, but works better in CMU CL. See: +\begin{example} +\file{doc/motif-toolkit.doc} +\file{doc/motif-internals.doc} +\end{example} + +This motif interface has been used to write the inspector and graphical +debugger. There is also a Lisp control panel with a simple file management +facility, apropos and inspector dialogs, and controls for setting global +options. See the \code{interface} and \code{toolkit} packages. + +\begin{defun}{interface:}{lisp-control-panel}{} + + This function creates a control panel for the Lisp process. +\end{defun} + +\begin{defvar}{interface:}{interface-style} + + When the graphical interface is loaded, this variable controls + whether it is used by \code{inspect} and the error system. If the + value is \kwd{graphics} (the default) and the \code{DISPLAY} + environment variable is defined, the graphical inspector and + debugger will be invoked by \findexed{inspect} or when an error is + signalled. Possible values are \kwd{graphics} and {tty}. If the + value is \kwd{graphics}, but there is no X display, then we quietly + use the TTY interface. +\end{defvar} + +%%\node The TTY Inspector, , The Graphical Interface, The Inspector +\subsection{The TTY Inspector} + +If X is unavailable, a terminal inspector is invoked. The TTY inspector +is a crude interface to \code{describe} which allows objects to be +traversed and maintains a history. This inspector prints information +about and object and a numbered list of the components of the object. +The command-line based interface is a normal +\code{read}--\code{eval}--\code{print} loop, but an integer \var{n} +descends into the \var{n}'th component of the current object, and +symbols with these special names are interpreted as commands: +\begin{Lentry} +\item[U] Move back to the enclosing object. As you descend into the +components of an object, a stack of all the objects previously seen is +kept. This command pops you up one level of this stack. + +\item[Q, E] Return the current object from \code{inspect}. + +\item[R] Recompute object display, and print again. Useful if the +object may have changed. + +\item[D] Display again without recomputing. + +\item[H, ?] Show help message. +\end{Lentry} + +%%\node Load, The Reader, The Inspector, Design Choices and Extensions +\section{Load} + +\begin{defun}{}{load}{% + \args{\var{filename} + \keys{\kwd{verbose} \kwd{print} \kwd{if-does-not-exist}} + \morekeys{\kwd{if-source-newer} \kwd{contents}}}} + + As in standard Common Lisp, this function loads a file containing + source or object code into the running Lisp. Several CMU extensions + have been made to \code{load} to conveniently support a variety of + program file organizations. \var{filename} may be a wildcard + pathname such as \file{*.lisp}, in which case all matching files are + loaded. + + If \var{filename} has a \code{pathname-type} (or extension), then + that exact file is loaded. If the file has no extension, then this + tells \code{load} to use a heuristic to load the right'' file. + The \code{*load-source-types*} and \code{*load-object-types*} + variables below are used to determine the default source and object + file types. If only the source or the object file exists (but not + both), then that file is quietly loaded. Similarly, if both the + source and object file exist, and the object file is newer than the + source file, then the object file is loaded. The value of the + \var{if-source-newer} argument is used to determine what action to + take when both the source and object files exist, but the object + file is out of date: + \begin{Lentry} + \item[\kwd{load-object}] The object file is loaded even though the + source file is newer. + + \item[\kwd{load-source}] The source file is loaded instead of the + older object file. + + \item[\kwd{compile}] The source file is compiled and then the new + object file is loaded. + + \item[\kwd{query}] The user is asked a yes or no question to + determine whether the source or object file is loaded. + \end{Lentry} + This argument defaults to the value of + \code{ext:*load-if-source-newer*} (initially \kwd{load-object}.) + + The \var{contents} argument can be used to override the heuristic + (based on the file extension) that normally determines whether to + load the file as a source file or an object file. If non-null, this + argument must be either \kwd{source} or \kwd{binary}, which forces + loading in source and binary mode, respectively. You really + shouldn't ever need to use this argument. +\end{defun} + +\begin{defvar}{extensions:}{load-source-types} + \defvarx[extensions:]{load-object-types} + + These variables are lists of possible \code{pathname-type} values + for source and object files to be passed to \code{load}. These + variables are only used when the file passed to \code{load} has no + type; in this case, the possible source and object types are used to + default the type in order to determine the names of the source and + object files. +\end{defvar} + +\begin{defvar}{extensions:}{load-if-source-newer} + + This variable determines the default value of the + \var{if-source-newer} argument to \code{load}. Its initial value is + \kwd{load-object}. +\end{defvar} + +%%\node The Reader, Stream Extensions, Load, Design Choices and Extensions +\section{The Reader} + +\begin{defvar}{extensions:}{ignore-extra-close-parentheses} + + If this variable is \true{} (the default), then the reader merely + prints a warning when an extra close parenthesis is detected + (instead of signalling an error.) +\end{defvar} + +%%\node Stream Extensions, Running Programs from Lisp, The Reader, Design Choices and Extensions +\section{Stream Extensions} +\begin{defun}{extensions:}{read-n-bytes}{% + \args{\var{stream buffer start numbytes} + \ampoptional{} \var{eof-error-p}}} + + On streams that support it, this function reads multiple bytes of + data into a buffer. The buffer must be a \code{simple-string} or + \code{(simple-array (unsigned-byte 8) (*))}. The argument + \var{nbytes} specifies the desired number of bytes, and the return + value is the number of bytes actually read. + \begin{itemize} + \item If \var{eof-error-p} is true, an \tindexed{end-of-file} + condition is signalled if end-of-file is encountered before + \var{count} bytes have been read. + + \item If \var{eof-error-p} is false, \code{read-n-bytes reads} as + much data is currently available (up to count bytes.) On pipes or + similar devices, this function returns as soon as any data is + available, even if the amount read is less than \var{count} and + eof has not been hit. See also \funref{make-fd-stream}. + \end{itemize} +\end{defun} +%%\node Running Programs from Lisp, Saving a Core Image, The Reader, Design Choices and Extensions +\section{Running Programs from Lisp} + +It is possible to run programs from Lisp by using the following function. + +\begin{defun}{extensions:}{run-program}{% + \args{\var{program} \var{args} + \keys{\kwd{env} \kwd{wait} \kwd{pty} \kwd{input}} + \morekeys{\kwd{if-input-does-not-exist}} + \yetmorekeys{\kwd{output} \kwd{if-output-exists}} + \yetmorekeys{\kwd{error} \kwd{if-error-exists}} + \yetmorekeys{\kwd{status-hook} \kwd{before-execve}}}} + + \code{run-program} runs \var{program} in a child process. + \var{Program} should be a pathname or string naming the program. + \var{Args} should be a list of strings which this passes to + \var{program} as normal Unix parameters. For no arguments, specify + \var{args} as \nil. The value returned is either a process + structure or \nil. The process interface follows the description of + \code{run-program}. If \code{run-program} fails to fork the child + process, it returns \nil. + + Except for sharing file descriptors as explained in keyword argument + descriptions, \code{run-program} closes all file descriptors in the + child process before running the program. When you are done using a + process, call \code{process-close} to reclaim system resources. You + only need to do this when you supply \kwd{stream} for one of + \kwd{input}, \kwd{output}, or \kwd{error}, or you supply \kwd{pty} + non-\nil. You can call \code{process-close} regardless of whether + you must to reclaim resources without penalty if you feel safer. + + \code{run-program} accepts the following keyword arguments: + \begin{Lentry} + + \item[\kwd{env}] This is an a-list mapping keywords and + simple-strings. The default is \code{ext:*environment-list*}. If + \kwd{env} is specified, \code{run-program} uses the value given + and does not combine the environment passed to Lisp with the one + specified. + + \item[\kwd{wait}] If non-\nil{} (the default), wait until the child + process terminates. If \nil, continue running Lisp while the + child process runs. + + \item[\kwd{pty}] This should be one of \true, \nil, or a stream. If + specified non-\nil, the subprocess executes under a Unix \i{PTY}. + If specified as a stream, the system collects all output to this + pty and writes it to this stream. If specified as \true, the + \code{process-pty} slot contains a stream from which you can read + the program's output and to which you can write input for the + program. The default is \nil. + + \item[\kwd{input}] This specifies how the program gets its input. + If specified as a string, it is the name of a file that contains + input for the child process. \code{run-program} opens the file as + standard input. If specified as \nil{} (the default), then + standard input is the file \file{/dev/null}. If specified as + \true, the program uses the current standard input. This may + cause some confusion if \kwd{wait} is \nil{} since two processes + may use the terminal at the same time. If specified as + \kwd{stream}, then the \code{process-input} slot contains an + output stream. Anything written to this stream goes to the + program as input. \kwd{input} may also be an input stream that + already contains all the input for the process. In this case + \code{run-program} reads all the input from this stream before + returning, so this cannot be used to interact with the process. + + \item[\kwd{if-input-does-not-exist}] This specifies what to do if + the input file does not exist. The following values are valid: + \nil{} (the default) causes \code{run-program} to return \nil{} + without doing anything; \kwd{create} creates the named file; and + \kwd{error} signals an error. + + \item[\kwd{output}] This specifies what happens with the program's + output. If specified as a pathname, it is the name of a file that + contains output the program writes to its standard output. If + specified as \nil{} (the default), all output goes to + \file{/dev/null}. If specified as \true, the program writes to + the Lisp process's standard output. This may cause confusion if + \kwd{wait} is \nil{} since two processes may write to the terminal + at the same time. If specified as \kwd{stream}, then the + \code{process-output} slot contains an input stream from which you + can read the program's output. + + \item[\kwd{if-output-exists}] This specifies what to do if the + output file already exists. The following values are valid: + \nil{} causes \code{run-program} to return \nil{} without doing + anything; \kwd{error} (the default) signals an error; + \kwd{supersede} overwrites the current file; and \kwd{append} + appends all output to the file. + + \item[\kwd{error}] This is similar to \kwd{output}, except the file + becomes the program's standard error. Additionally, \kwd{error} + can be \kwd{output} in which case the program's error output is + routed to the same place specified for \kwd{output}. If specified + as \kwd{stream}, the \code{process-error} contains a stream + similar to the \code{process-output} slot when specifying the + \kwd{output} argument. + + \item[\kwd{if-error-exists}] This specifies what to do if the error + output file already exists. It accepts the same values as + \kwd{if-output-exists}. + + \item[\kwd{status-hook}] This specifies a function to call whenever + the process changes status. This is especially useful when + specifying \kwd{wait} as \nil. The function takes the process as + a required argument. + + \item[\kwd{before-execve}] This specifies a function to run in the + child process before it becomes the program to run. This is + useful for actions such as authenticating the child process + without modifying the parent Lisp process. + \end{Lentry} +\end{defun} + + +\begin{comment} +* Process Accessors:: +\end{comment} + +%%\node Process Accessors, , Running Programs from Lisp, Running Programs from Lisp +\subsection{Process Accessors} + +The following functions interface the process returned by \code{run-program}: + +\begin{defun}{extensions:}{process-p}{\args{\var{thing}}} + + This function returns \true{} if \var{thing} is a process. + Otherwise it returns \nil{} +\end{defun} + +\begin{defun}{extensions:}{process-pid}{\args{\var{process}}} + + This function returns the process ID, an integer, for the + \var{process}. +\end{defun} + +\begin{defun}{extensions:}{process-status}{\args{\var{process}}} + + This function returns the current status of \var{process}, which is + one of \kwd{running}, \kwd{stopped}, \kwd{exited}, or + \kwd{signaled}. +\end{defun} + +\begin{defun}{extensions:}{process-exit-code}{\args{\var{process}}} + + This function returns either the exit code for \var{process}, if it + is \kwd{exited}, or the termination signal \var{process} if it is + \kwd{signaled}. The result is undefined for processes that are + still alive. +\end{defun} + +\begin{defun}{extensions:}{process-core-dumped}{\args{\var{process}}} + + This function returns \true{} if someone used a Unix signal to + terminate the \var{process} and caused it to dump a Unix core image. +\end{defun} + +\begin{defun}{extensions:}{process-pty}{\args{\var{process}}} + + This function returns either the two-way stream connected to + \var{process}'s Unix \i{PTY} connection or \nil{} if there is none. +\end{defun} + +\begin{defun}{extensions:}{process-input}{\args{\var{process}}} + \defunx[extensions:]{process-output}{\args{\var{process}}} + \defunx[extensions:]{process-error}{\args{\var{process}}} + + If the corresponding stream was created, these functions return the + input, output or error file descriptor. \nil{} is returned if there + is no stream. +\end{defun} + +\begin{defun}{extensions:}{process-status-hook}{\args{\var{process}}} + + This function returns the current function to call whenever + \var{process}'s status changes. This function takes the + \var{process} as a required argument. \code{process-status-hook} is + \code{setf}'able. +\end{defun} + +\begin{defun}{extensions:}{process-plist}{\args{\var{process}}} + + This function returns annotations supplied by users, and it is + \code{setf}'able. This is available solely for users to associate + information with \var{process} without having to build a-lists or + hash tables of process structures. +\end{defun} + +\begin{defun}{extensions:}{process-wait}{ + \args{\var{process} \ampoptional{} \var{check-for-stopped}}} + + This function waits for \var{process} to finish. If + \var{check-for-stopped} is non-\nil, this also returns when + \var{process} stops. +\end{defun} + +\begin{defun}{extensions:}{process-kill}{% + \args{\var{process} \var{signal} \ampoptional{} \var{whom}}} + + This function sends the Unix \var{signal} to \var{process}. + \var{Signal} should be the number of the signal or a keyword with + the Unix name (for example, \kwd{sigsegv}). \var{Whom} should be + one of the following: + \begin{Lentry} + + \item[\kwd{pid}] This is the default, and it indicates sending the + signal to \var{process} only. + + \item[\kwd{process-group}] This indicates sending the signal to + \var{process}'s group. + + \item[\kwd{pty-process-group}] This indicates sending the signal to + the process group currently in the foreground on the Unix \i{PTY} + connected to \var{process}. This last option is useful if the + running program is a shell, and you wish to signal the program + running under the shell, not the shell itself. If + \code{process-pty} of \var{process} is \nil, using this option is + an error. + \end{Lentry} +\end{defun} + +\begin{defun}{extensions:}{process-alive-p}{\args{\var{process}}} + + This function returns \true{} if \var{process}'s status is either + \kwd{running} or \kwd{stopped}. +\end{defun} + +\begin{defun}{extensions:}{process-close}{\args{\var{process}}} + + This function closes all the streams associated with \var{process}. + When you are done using a process, call this to reclaim system + resources. +\end{defun} + + +%%\node Saving a Core Image, Pathnames, Running Programs from Lisp, Design Choices and Extensions +\section{Saving a Core Image} + +A mechanism has been provided to save a running Lisp core image and to +later restore it. This is convenient if you don't want to load several files +into a Lisp when you first start it up. The main problem is the large +size of each saved Lisp image, typically at least 20 megabytes. + +\begin{defun}{extensions:}{save-lisp}{% + \args{\var{file} + \keys{\kwd{purify} \kwd{root-structures} \kwd{init-function}} + \morekeys{\kwd{load-init-file} \kwd{print-herald} \kwd{site-init}} + \yetmorekeys{\kwd{process-command-line}}}} + + The \code{save-lisp} function saves the state of the currently + running Lisp core image in \var{file}. The keyword arguments have + the following meaning: + \begin{Lentry} + + \item[\kwd{purify}] If non-NIL (the default), the core image is + purified before it is saved (see \funref{purify}.) This reduces + the amount of work the garbage collector must do when the + resulting core image is being run. Also, if more than one Lisp is + running on the same machine, this maximizes the amount of memory + that can be shared between the two processes. + + \item[\kwd{root-structures}] + \begin{changebar} + This should be a list of the main entry points in any newly + loaded systems. This need not be supplied, but locality and/or + GC performance will be better if they are. Meaningless if + \kwd{purify} is \nil. See \funref{purify}. + \end{changebar} + + \item[\kwd{init-function}] This is the function that starts running + when the created core file is resumed. The default function + simply invokes the top level read-eval-print loop. If the + function returns the lisp will exit. + + \item[\kwd{load-init-file}] If non-NIL, then load an init file; + either the one specified on the command line or + \w{\file{init.}\var{fasl-type}}'', or, if + \w{\file{init.}\var{fasl-type}}'' does not exist, + \code{init.lisp} from the user's home directory. If the init file + is found, it is loaded into the resumed core file before the + read-eval-print loop is entered. + + \item[\kwd{site-init}] If non-NIL, the name of the site init file to + quietly load. The default is \file{library:site-init}. No error + is signalled if the file does not exist. + + \item[\kwd{print-herald}] If non-NIL (the default), then print out + the standard Lisp herald when starting. + + \item[\kwd{process-command-line}] If non-NIL (the default), + processes the command line switches and performs the appropriate + actions. + \end{Lentry} +\end{defun} + +To resume a saved file, type: +\begin{example} +lisp -core file +\end{example} + +\begin{defun}{extensions:}{purify}{ + \args{\var{file} + \keys{\kwd{root-structures} \kwd{environment-name}}}} + + This function optimizes garbage collection by moving all currently + live objects into non-collected storage. Once statically allocated, + the objects can never be reclaimed, even if all pointers to them are + dropped. This function should generally be called after a large + system has been loaded and initialized. + + \begin{Lentry} + \item[\kwd{root-structures}] is an optional list of objects which + should be copied first to maximize locality. This should be a + list of the main entry points for the resulting core image. The + purification process tries to localize symbols, functions, etc., + in the core image so that paging performance is improved. The + default value is NIL which means that Lisp objects will still be + localized but probably not as optimally as they could be. + + \var{defstruct} structures defined with the \code{(:pure t)} + option are moved into read-only storage, further reducing GC cost. + List and vector slots of pure structures are also moved into + read-only storage. + + \item[\kwd{environment-name}] is gratuitous documentation for the + compacted version of the current global environment (as seen in + \code{c::*info-environment*}.) If \false{} is supplied, then + environment compaction is inhibited. + \end{Lentry} +\end{defun} + +%%\node Pathnames, Filesystem Operations, Saving a Core Image, Design Choices and Extensions +\section{Pathnames} + +In \clisp{} quite a few aspects of \tindexed{pathname} semantics are left to +the implementation. + +\begin{comment} +* Unix Pathnames:: +* Wildcard Pathnames:: +* Logical Pathnames:: +* Search Lists:: +* Predefined Search-Lists:: +* Search-List Operations:: +* Search List Example:: +\end{comment} + +%%\node Unix Pathnames, Wildcard Pathnames, Pathnames, Pathnames +\subsection{Unix Pathnames} +\cpsubindex{unix}{pathnames} + +Unix pathnames are always parsed with a \code{unix-host} object as the host and +\code{nil} as the device. The last two dots (\code{.}) in the namestring mark +the type and version, however if the first character is a dot, it is considered +part of the name. If the last character is a dot, then the pathname has the +empty-string as its type. The type defaults to \code{nil} and the version +defaults to \kwd{newest}. +\begin{example} +(defun parse (x) + (values (pathname-name x) (pathname-type x) (pathname-version x))) + +(parse "foo") \result "foo", NIL, :NEWEST +(parse "foo.bar") \result "foo", "bar", :NEWEST +(parse ".foo") \result ".foo", NIL, :NEWEST +(parse ".foo.bar") \result ".foo", "bar", :NEWEST +(parse "..") \result ".", "", :NEWEST +(parse "foo.") \result "foo", "", :NEWEST +(parse "foo.bar.1") \result "foo", "bar", 1 +(parse "foo.bar.baz") \result "foo.bar", "baz", :NEWEST +\end{example} + +The directory of pathnames beginning with a slash (or a search-list, +\pxlref{search-lists}) is starts \kwd{absolute}, others start with +\kwd{relative}. The \code{..} directory is parsed as \kwd{up}; there is no +namestring for \kwd{back}: +\begin{example} +(pathname-directory "/usr/foo/bar.baz") \result (:ABSOLUTE "usr" "foo") +(pathname-directory "../foo/bar.baz") \result (:RELATIVE :UP "foo") +\end{example} + +%%\node Wildcard Pathnames, Logical Pathnames, Unix Pathnames, Pathnames +\subsection{Wildcard Pathnames} + +Wildcards are supported in Unix pathnames. If \code{*}' is specified for a +part of a pathname, that is parsed as \kwd{wild}. \code{**}' can be used as a +directory name to indicate \kwd{wild-inferiors}. Filesystem operations +treat \kwd{wild-inferiors} the same as\ \kwd{wild}, but pathname pattern +matching (e.g. for logical pathname translation, \pxlref{logical-pathnames}) +matches any number of directory parts with \code{**}' (see +\pxlref{wildcard-matching}.) + + +\code{*}' embedded in a pathname part matches any number of characters. +Similarly, \code{?}' matches exactly one character, and \code{[a,b]}' +matches the characters \code{a}' or \code{b}'. These pathname parts are +parsed as \code{pattern} objects. + +Backslash can be used as an escape character in namestring +parsing to prevent the next character from being treated as a wildcard. Note +that if typed in a string constant, the backslash must be doubled, since the +string reader also uses backslash as a quote: +\begin{example} +(pathname-name "foo$$\backslash\backslash$$*bar") => "foo*bar" +\end{example} + +%%\node Logical Pathnames, Search Lists, Wildcard Pathnames, Pathnames +\subsection{Logical Pathnames} +\cindex{logical pathnames} +\label{logical-pathnames} + +If a namestring begins with the name of a defined logical pathname +host followed by a colon, then it will be parsed as a logical +pathname. Both \code{*}' and \code{**}' wildcards are implemented. +\findexed{load-logical-pathname-defaults} on \var{name} looks for a +logical host definition file in +\w{\file{library:\var{name}.translations}}. Note that \file{library:} +designates the search list (\pxlref{search-lists}) initialized to the +\cmucl{} \file{lib/} directory, not a logical pathname. The format of +the file is a single list of two-lists of the from and to patterns: +\begin{example} +(("foo;*.text" "/usr/ram/foo/*.txt") + ("foo;*.lisp" "/usr/ram/foo/*.l")) +\end{example} + +\begin{comment} +* Search Lists:: +* Search List Example:: +\end{comment} + +%%\node Search Lists, Predefined Search-Lists, Logical Pathnames, Pathnames +\subsection{Search Lists} +\cindex{search lists} +\label{search-lists} + +Search lists are an extension to Common Lisp pathnames. They serve a function +somewhat similar to Common Lisp logical pathnames, but work more like Unix PATH +variables. Search lists are used for two purposes: +\begin{itemize} +\item They provide a convenient shorthand for commonly used directory names, +and + +\item They allow the abstract (directory structure independent) specification +of file locations in program pathname constants (similar to logical pathnames.) +\end{itemize} +Each search list has an associated list of directories (represented as +pathnames with no name or type component.) The namestring for any relative +pathname may be prefixed with \var{slist}\code{:}'', indicating that the +pathname is relative to the search list \var{slist} (instead of to the current +working directory.) Once qualified with a search list, the pathname is no +longer considered to be relative. + +When a search list qualified pathname is passed to a file-system operation such +as \code{open}, \code{load} or \code{truename}, each directory in the search +list is successively used as the root of the pathname until the file is +located. When a file is written to a search list directory, the file is always +written to the first directory in the list. + +%%\node Predefined Search-Lists, Search-List Operations, Search Lists, Pathnames +\subsection{Predefined Search-Lists} + +These search-lists are initialized from the Unix environment or when Lisp was +built: +\begin{Lentry} +\item[\code{default:}] The current directory at startup. + +\item[\code{home:}] The user's home directory. + +\item[\code{library:}] The \cmucl{} \file{lib/} directory (\code{CMUCLLIB} environment +variable.) + +\item[\code{path:}] The Unix command path (\code{PATH} environment variable.) + +\item[\code{target:}] The root of the tree where \cmucl{} was compiled. +\end{Lentry} +It can be useful to redefine these search-lists, for example, \file{library:} +can be augmented to allow logical pathname translations to be located, and +\file{target:} can be redefined to point to where \cmucl{} system sources are +locally installed. + +%%\node Search-List Operations, Search List Example, Predefined Search-Lists, Pathnames +\subsection{Search-List Operations} + +These operations define and access search-list definitions. A search-list name +may be parsed into a pathname before the search-list is actually defined, but +the search-list must be defined before it can actually be used in a filesystem +operation. + +\begin{defun}{extensions:}{search-list}{\var{name}} + + This function returns the list of directories associated with the + search list \var{name}. If \var{name} is not a defined search list, + then an error is signaled. When set with \code{setf}, the list of + directories is changed to the new value. If the new value is just a + namestring or pathname, then it is interpreted as a one-element + list. Note that (unlike Unix pathnames), search list names are + case-insensitive. +\end{defun} + +\begin{defun}{extensions:}{search-list-defined-p}{\var{name}} + \defunx[extensions:]{clear-search-list}{\var{name}} + + \code{search-list-defined-p} returns \true{} if \var{name} is a + defined search list name, \false{} otherwise. + \code{clear-search-list} make the search list \var{name} undefined. +\end{defun} + +\begin{defmac}{extensions:}{enumerate-search-list}{% + \args{(\var{var} \var{pathname} \mopt{result}) \mstar{form}}} + + This macro provides an interface to search list resolution. The + body \var{forms} are executed with \var{var} bound to each + successive possible expansion for \var{name}. If \var{name} does + not contain a search-list, then the body is executed exactly once. + Everything is wrapped in a block named \nil, so \code{return} can be + used to terminate early. The \var{result} form (default \nil) is + evaluated to determine the result of the iteration. +\end{defmac} + +\begin{comment} +* Search List Example:: +\end{comment} + +%%\node Search List Example, , Search-List Operations, Pathnames +\subsection{Search List Example} + +The search list \code{code:} can be defined as follows: +\begin{example} +(setf (ext:search-list "code:") '("/usr/lisp/code/")) +\end{example} +It is now possible to use \code{code:} as an abbreviation for the directory +\file{/usr/lisp/code/} in all file operations. For example, you can now specify +\code{code:eval.lisp} to refer to the file \file{/usr/lisp/code/eval.lisp}. + +To obtain the value of a search-list name, use the function search-list +as follows: +\begin{example} +(ext:search-list \var{name}) +\end{example} +Where \var{name} is the name of a search list as described above. For example, +calling \code{ext:search-list} on \code{code:} as follows: +\begin{example} +(ext:search-list "code:") +\end{example} +returns the list \code{("/usr/lisp/code/")}. + +%%\node Filesystem Operations, Time Parsing and Formatting, Pathnames, Design Choices and Extensions +\section{Filesystem Operations} + +\cmucl{} provides a number of extensions and optional features beyond those +require by \clisp. + +\begin{comment} +* Wildcard Matching:: +* File Name Completion:: +* Miscellaneous Filesystem Operations:: +\end{comment} + +%%\node Wildcard Matching, File Name Completion, Filesystem Operations, Filesystem Operations +\subsection{Wildcard Matching} +\label{wildcard-matching} + +Unix filesystem operations such as \code{open} will accept wildcard pathnames +that match a single file (of course, \code{directory} allows any number of +matches.) Filesystem operations treat \kwd{wild-inferiors} the same as\ +\kwd{wild}. + +\begin{defun}{}{directory}{\var{wildname} \keys{\kwd{all} \kwd{check-for-subdirs}} + \morekeys{\kwd{follow-links}}} + + The keyword arguments to this \clisp{} function are a CMU extension. + The arguments (all default to \code{t}) have the following + functions: + \begin{Lentry} + \item[\kwd{all}] Include files beginning with dot such as + \file{.login}, similar to \code{ls -a}''. + + \item[\kwd{check-for-subdirs}] Test whether files are directories, + similar to \code{ls -F}''. + + \item[\kwd{follow-links}] Call \code{truename} on each file, which + expands out all symbolic links. Note that this option can easily + result in pathnames being returned which have a different + directory from the one in the \var{wildname} argument. + \end{Lentry} +\end{defun} + +\begin{defun}{extensions:}{print-directory}{% + \args{\var{wildname} + \ampoptional{} \var{stream} + \keys{\kwd{all} \kwd{verbose}} + \morekeys{\kwd{return-list}}}} + + Print a directory of \var{wildname} listing to \var{stream} (default + \code{*standard-output*}.) \kwd{all} and \kwd{verbose} both default + to \false{} and correspond to the \code{-a}'' and \code{-l}'' + options of \file{ls}. Normally this function returns \false{}, but + if \kwd{return-list} is true, a list of the matched pathnames are + returned. +\end{defun} + +%%\node File Name Completion, Miscellaneous Filesystem Operations, Wildcard Matching, Filesystem Operations +\subsection{File Name Completion} + +\begin{defun}{extensions:}{complete-file}{% + \args{\var{pathname} + \keys{\kwd{defaults} \kwd{ignore-types}}}} + + Attempt to complete a file name to the longest unambiguous prefix. + If supplied, directory from \kwd{defaults} is used as the working + directory'' when doing completion. \kwd{ignore-types} is a list of + strings of the pathname types (a.k.a. extensions) that should be + disregarded as possible matches (binary file names, etc.) +\end{defun} + +\begin{defun}{extensions:}{ambiguous-files}{% + \args{\var{pathname} + \ampoptional{} \var{defaults}}} + + Return a list of pathnames for all the possible completions of + \var{pathname} with respect to \var{defaults}. +\end{defun} + +%%\node Miscellaneous Filesystem Operations, , File Name Completion, Filesystem Operations +\subsection{Miscellaneous Filesystem Operations} + +\begin{defun}{extensions:}{default-directory}{} + + Return the current working directory as a pathname. If set with + \code{setf}, set the working directory. +\end{defun} + +\begin{defun}{extensions:}{file-writable}{\var{name}} + + This function accepts a pathname and returns \true{} if the current + process can write it, and \false{} otherwise. +\end{defun} + +\begin{defun}{extensions:}{unix-namestring}{% + \args{\var{pathname} + \ampoptional{} \var{for-input}}} + + This function converts \var{pathname} into a string that can be used + with UNIX system calls. Search-lists and wildcards are expanded. + \var{for-input} controls the treatment of search-lists: when true + (the default) and the file exists anywhere on the search-list, then + that absolute pathname is returned; otherwise the first element of + the search-list is used as the directory. +\end{defun} + +%%\node Time Parsing and Formatting, Lisp Library, Filesystem Operations, Design Choices and Extensions +\section{Time Parsing and Formatting} + +\cindex{time parsing} \cindex{time formatting} +Functions are provided to allow parsing strings containing time information +and printing time in various formats are available. + +\begin{defun}{extensions:}{parse-time}{% + \args{\var{time-string} + \keys{\kwd{error-on-mismatch} \kwd{default-seconds}} + \morekeys{\kwd{default-minutes} \kwd{default-hours}} + \yetmorekeys{\kwd{default-day} \kwd{default-month}} + \yetmorekeys{\kwd{default-year} \kwd{default-zone}} + \yetmorekeys{\kwd{default-weekday}}}} + + \code{parse-time} accepts a string containing a time (e.g., + \w{"\code{Jan 12, 1952}"}) and returns the universal time if it is + successful. If it is unsuccessful and the keyword argument + \kwd{error-on-mismatch} is non-\FALSE, it signals an error. + Otherwise it returns \FALSE. The other keyword arguments have the + following meaning: + \begin{Lentry} + + \item[\kwd{default-seconds}] specifies the default value for the + seconds value if one is not provided by \var{time-string}. The + default value is 0. + + \item[\kwd{default-minutes}] specifies the default value for the + minutes value if one is not provided by \var{time-string}. The + default value is 0. + + \item[\kwd{default-hours}] specifies the default value for the hours + value if one is not provided by \var{time-string}. The default + value is 0. + + \item[\kwd{default-day}] specifies the default value for the day + value if one is not provided by \var{time-string}. The default + value is the current day. + + \item[\kwd{default-month}] specifies the default value for the month + value if one is not provided by \var{time-string}. The default + value is the current month. + + \item[\kwd{default-year}] specifies the default value for the year + value if one is not provided by \var{time-string}. The default + value is the current year. + + \item[\kwd{default-zone}] specifies the default value for the time + zone value if one is not provided by \var{time-string}. The + default value is the current time zone. + + \item[\kwd{default-weekday}] specifies the default value for the day + of the week if one is not provided by \var{time-string}. The + default value is the current day of the week. + \end{Lentry} + Any of the above keywords can be given the value \kwd{current} which + means to use the current value as determined by a call to the + operating system. +\end{defun} + +\begin{defun}{extensions:}{format-universal-time}{ + \args{\var{dest} \var{universal-time} + \\ + \keys{\kwd{timezone}} + \morekeys{\kwd{style} \kwd{date-first}} + \yetmorekeys{\kwd{print-seconds} \kwd{print-meridian}} + \yetmorekeys{\kwd{print-timezone} \kwd{print-weekday}}}} + \defunx[extensions:]{format-decoded-time}{ + \args{\var{dest} \var{seconds} \var{minutes} \var{hours} \var{day} \var{month} \var{year} + \\ + \keys{\kwd{timezone}} + \morekeys{\kwd{style} \kwd{date-first}} + \yetmorekeys{\kwd{print-seconds} \kwd{print-meridian}} + \yetmorekeys{\kwd{print-timezone} \kwd{print-weekday}}}} + + \code{format-universal-time} formats the time specified by + \var{universal-time}. \code{format-decoded-time} formats the time + specified by \var{seconds}, \var{minutes}, \var{hours}, \var{day}, + \var{month}, and \var{year}. \var{Dest} is any destination + accepted by the \code{format} function. The keyword arguments have + the following meaning: + \begin{Lentry} + + \item[\kwd{timezone}] is an integer specifying the hours west of + Greenwich. \kwd{timezone} defaults to the current time zone. + + \item[\kwd{style}] specifies the style to use in formatting the + time. The legal values are: + \begin{Lentry} + + \item[\kwd{short}] specifies to use a numeric date. + + \item[\kwd{long}] specifies to format months and weekdays as + words instead of numbers. + + \item[\kwd{abbreviated}] is similar to long except the words are + abbreviated. + + \item[\kwd{government}] is similar to abbreviated, except the + date is of the form day month year'' instead of month day, + year''. + \end{Lentry} + + \item[\kwd{date-first}] if non-\false{} (default) will place the + date first. Otherwise, the time is placed first. + + \item[\kwd{print-seconds}] if non-\false{} (default) will format + the seconds as part of the time. Otherwise, the seconds will be + omitted. + + \item[\kwd{print-meridian}] if non-\false{} (default) will format + AM'' or PM'' as part of the time. Otherwise, the AM'' or + PM'' will be omitted. + + \item[\kwd{print-timezone}] if non-\false{} (default) will format + the time zone as part of the time. Otherwise, the time zone will + be omitted. + + %%\item[\kwd{print-seconds}] + %%if non-\false{} (default) will format the seconds as part of + %%the time. Otherwise, the seconds will be omitted. + + \item[\kwd{print-weekday}] if non-\false{} (default) will format + the weekday as part of date. Otherwise, the weekday will be + omitted. + \end{Lentry} +\end{defun} + +%% New stuff +\begin{changebar} +\section{Random Number Generation} +\cindex{random number generation} + +\clisp{} includes a random number generator as a standard part of the +language; however, the implementation of the generator is not +specified. Two random number generators are available in \cmucl{}, +depending on the version. + +\subsection{Original Generator} +\cpsubindex{random number generation}{original generator} +The default random number generator uses a lagged Fibonacci generator +given by +\begin{displaymath} + z[i] = z[i - 24] - z[i - 55] \bmod 536870908 +\end{displaymath} +where$z[i]$is the$i$'th random number. This generator produces +small integer-valued numbers. For larger integer, the small random +integers are concatenated to produce larger integers. For +floating-point numbers, the bits from this generator are used as the +bits of the floating-point significand. + +\subsection{New Generator} +\cpsubindex{random number generation}{new generator} + +In some versions of \cmucl{}, the original generator above has been +replaced with a subtract-with-borrow generator +combined with a Weyl generator.\footnote{The generator described here + is available if the feature \kwd{new-random} is available.} The +reason for the change was to use a documented generator which has +passed tests for randomness. + +The subtract-with-borrow generator is described by the following +equation +\begin{displaymath} + z[i] = z[i + 20] - z[i + 5] - b +\end{displaymath} +where$z[i]$is the$i$'th random number, which is a +\code{double-float}. All of the indices in this equation are +interpreted modulo 32. The quantity$b$is carried over from the +previous iteration and is either 0 or \code{double-float-epsilon}. If +$z[i]$is positive,$b$is set to zero. Otherwise,$b$is set to +\code{double-float-epsilon}. + +To increase the randomness of this generator, this generator is +combined with a Weyl generator defined by +\begin{displaymath} + x[i] = x[i - 1] - y \bmod 1, +\end{displaymath} +where$y = 7097293079245107 \times 2^{-53}$. Thus, the resulting +random number$r[i]$is +\begin{displaymath} + r[i] = (z[i] - x[i]) \bmod 1 +\end{displaymath} + +This generator has been tested by Peter VanEynde using Marsaglia's +diehard test suite for random number generators; this generator +passes the test suite. + +This generator is designed for generating floating-point random +numbers. To obtain integers, the bits from the significand of the +floating-point number are used as the bits of the integer. As many +floating-point numbers as needed are generated to obtain the desired +number of bits in the random integer. + +For floating-point numbers, this generator can by significantly faster +than the original generator. +\end{changebar} + +%%\node Lisp Library, , Time Parsing and Formatting, Design Choices and Extensions +\section{Lisp Library} +\label{lisp-lib} + +The CMU Common Lisp project maintains a collection of useful or interesting +programs written by users of our system. The library is in +\file{lib/contrib/}. Two files there that users should read are: +\begin{Lentry} + +\item[CATALOG.TXT] +This file contains a page for each entry in the library. It +contains information such as the author, portability or dependency issues, how +to load the entry, etc. + +\item[READ-ME.TXT] +This file describes the library's organization and all the +possible pieces of information an entry's catalog description could contain. +\end{Lentry} + +Hemlock has a command \F{Library Entry} that displays a list of the current +library entries in an editor buffer. There are mode specific commands that +display catalog descriptions and load entries. This is a simple and convenient +way to browse the library. + + +\hide{File:/afs/cs.cmu.edu/project/clisp/hackers/ram/docs/cmu-user/debug.ms} + + + +%%\node The Debugger, The Compiler, Design Choices and Extensions, Top +\chapter{The Debugger} \hide{-*- Dictionary: cmu-user -*-} +\begin{center} +\b{By Robert MacLachlan} +\end{center} +\cindex{debugger} +\label{debugger} + +\begin{comment} +* Debugger Introduction:: +* The Command Loop:: +* Stack Frames:: +* Variable Access:: +* Source Location Printing:: +* Compiler Policy Control:: +* Exiting Commands:: +* Information Commands:: +* Breakpoint Commands:: +* Function Tracing:: +* Specials:: +\end{comment} + +%%\node Debugger Introduction, The Command Loop, The Debugger, The Debugger +\section{Debugger Introduction} + +The \cmucl{} debugger is unique in its level of support for source-level +debugging of compiled code. Although some other debuggers allow access of +variables by name, this seems to be the first \llisp{} debugger that: +\begin{itemize} + +\item +Tells you when a variable doesn't have a value because it hasn't been +initialized yet or has already been deallocated, or + +\item +Can display the precise source location corresponding to a code +location in the debugged program. +\end{itemize} +These features allow the debugging of compiled code to be made almost +indistinguishable from interpreted code debugging. + +The debugger is an interactive command loop that allows a user to examine +the function call stack. The debugger is invoked when: +\begin{itemize} + +\item +A \tindexed{serious-condition} is signaled, and it is not handled, or + +\item +\findexed{error} is called, and the condition it signals is not handled, or + +\item +The debugger is explicitly invoked with the \clisp{} \findexed{break} +or \findexed{debug} functions. +\end{itemize} + +{\it Note: there are two debugger interfaces in CMU CL: the TTY debugger +(described below) and the Motif debugger. Since the difference is only in the +user interface, much of this chapter also applies to the Motif version. +\xlref{motif-interface} for a very brief discussion of the graphical +interface.} + +When you enter the TTY debugger, it looks something like this: +\begin{example} +Error in function CAR. +Wrong type argument, 3, should have been of type LIST. + +Restarts: + 0: Return to Top-Level. + +Debug (type H for help) + +(CAR 3) +0] +\end{example} +The first group of lines describe what the error was that put us in the +debugger. In this case \code{car} was called on \code{3}. After \code{Restarts:} +is a list of all the ways that we can restart execution after this error. In +this case, the only option is to return to top-level. After printing its +banner, the debugger prints the current frame and the debugger prompt. + +%% +%%\node The Command Loop, Stack Frames, Debugger Introduction, The Debugger +\section{The Command Loop} + +The debugger is an interactive read-eval-print loop much like the normal +top-level, but some symbols are interpreted as debugger commands instead +of being evaluated. A debugger command starts with the symbol name of +the command, possibly followed by some arguments on the same line. Some +commands prompt for additional input. Debugger commands can be +abbreviated by any unambiguous prefix: \code{help} can be typed as +\code{h}, \code{he}, etc. For convenience, some commands have +ambiguous one-letter abbreviations: \code{f} for \code{frame}. + +The package is not significant in debugger commands; any symbol with the +name of a debugger command will work. If you want to show the value of +a variable that happens also to be the name of a debugger command, you +can use the \code{list-locals} command or the \code{debug:var} +function, or you can wrap the variable in a \code{progn} to hide it from +the command loop. + +The debugger prompt is \var{frame}\code{]}'', where \var{frame} is the number +of the current frame. Frames are numbered starting from zero at the top (most +recent call), increasing down to the bottom. The current frame is the frame +that commands refer to. The current frame also provides the lexical +environment for evaluation of non-command forms. + +\cpsubindex{evaluation}{debugger} The debugger evaluates forms in the lexical +environment of the functions being debugged. The debugger can only +access variables. You can't \code{go} or \code{return-from} into a +function, and you can't call local functions. Special variable +references are evaluated with their current value (the innermost binding +around the debugger invocation)\dash{}you don't get the value that the +special had in the current frame. \xlref{debug-vars} for more +information on debugger variable access. + +%% +%%\node Stack Frames, Variable Access, The Command Loop, The Debugger +\section{Stack Frames} +\cindex{stack frames} \cpsubindex{frames}{stack} + +A stack frame is the run-time representation of a call to a function; +the frame stores the state that a function needs to remember what it is +doing. Frames have: +\begin{itemize} + +\item +Variables (\pxlref{debug-vars}), which are the values being operated +on, and + +\item +Arguments to the call (which are really just particularly interesting +variables), and + +\item +A current location (\pxlref{source-locations}), which is the place in +the program where the function was running when it stopped to call another +function, or because of an interrupt or error. +\end{itemize} + + +%% +\begin{comment} +* Stack Motion:: +* How Arguments are Printed:: +* Function Names:: +* Funny Frames:: +* Debug Tail Recursion:: +* Unknown Locations and Interrupts:: +\end{comment} + +%%\node Stack Motion, How Arguments are Printed, Stack Frames, Stack Frames +\subsection{Stack Motion} + +These commands move to a new stack frame and print the name of the function +and the values of its arguments in the style of a Lisp function call: +\begin{Lentry} + +\item[\code{up}] +Move up to the next higher frame. More recent function calls are considered +to be higher on the stack. + +\item[\code{down}] +Move down to the next lower frame. + +\item[\code{top}] +Move to the highest frame. + +\item[\code{bottom}] +Move to the lowest frame. + +\item[\code{frame} [\textit{n}]] +Move to the frame with the specified number. Prompts for the number if not +supplied. + +\begin{comment} +\key{S} [\var{function-name} [\var{n}]] + +\item +Search down the stack for function. Prompts for the function name if not +supplied. Searches an optional number of times, but doesn't prompt for +this number; enter it following the function. + +\item[\key{R} [\var{function-name} [\var{n}]]] +Search up the stack for function. Prompts for the function name if not +supplied. Searches an optional number of times, but doesn't prompt for +this number; enter it following the function. +\end{comment} +\end{Lentry} +%% +%%\node How Arguments are Printed, Function Names, Stack Motion, Stack Frames +\subsection{How Arguments are Printed} + +A frame is printed to look like a function call, but with the actual argument +values in the argument positions. So the frame for this call in the source: +\begin{lisp} +(myfun (+ 3 4) 'a) +\end{lisp} +would look like this: +\begin{example} +(MYFUN 7 A) +\end{example} +All keyword and optional arguments are displayed with their actual +values; if the corresponding argument was not supplied, the value will +be the default. So this call: +\begin{lisp} +(subseq "foo" 1) +\end{lisp} +would look like this: +\begin{example} +(SUBSEQ "foo" 1 3) +\end{example} +And this call: +\begin{lisp} +(string-upcase "test case") +\end{lisp} +would look like this: +\begin{example} +(STRING-UPCASE "test case" :START 0 :END NIL) +\end{example} + +The arguments to a function call are displayed by accessing the argument +variables. Although those variables are initialized to the actual argument +values, they can be set inside the function; in this case the new value will be +displayed. + +\code{\amprest} arguments are handled somewhat differently. The value of +the rest argument variable is displayed as the spread-out arguments to +the call, so: +\begin{lisp} +(format t "~A is a ~A." "This" 'test) +\end{lisp} +would look like this: +\begin{example} +(FORMAT T "~A is a ~A." "This" 'TEST) +\end{example} +Rest arguments cause an exception to the normal display of keyword +arguments in functions that have both \code{\amprest} and \code{\&key} +arguments. In this case, the keyword argument variables are not +displayed at all; the rest arg is displayed instead. So for these +functions, only the keywords actually supplied will be shown, and the +values displayed will be the argument values, not values of the +(possibly modified) variables. + +If the variable for an argument is never referenced by the function, it will be +deleted. The variable value is then unavailable, so the debugger prints +\code{<unused-arg>} instead of the value. Similarly, if for any of a number of +reasons (described in more detail in section \ref{debug-vars}) the value of the +variable is unavailable or not known to be available, then +\code{<unavailable-arg>} will be printed instead of the argument value. + +Printing of argument values is controlled by \code{*debug-print-level*} and +\varref{debug-print-length}. + +%% +%%\node Function Names, Funny Frames, How Arguments are Printed, Stack Frames +\subsection{Function Names} +\cpsubindex{function}{names} +\cpsubindex{names}{function} + +If a function is defined by \code{defun}, \code{labels}, or \code{flet}, then the +debugger will print the actual function name after the open parenthesis, like: +\begin{example} +(STRING-UPCASE "test case" :START 0 :END NIL) +((SETF AREF) \#\back{a} "for" 1) +\end{example} +Otherwise, the function name is a string, and will be printed in quotes: +\begin{example} +("DEFUN MYFUN" BAR) +("DEFMACRO DO" (DO ((I 0 (1+ I))) ((= I 13))) NIL) +("SETQ *GC-NOTIFY-BEFORE*") +\end{example} +This string name is derived from the \w{\code{def}\var{mumble}} form that encloses +or expanded into the lambda, or the outermost enclosing form if there is no +\w{\code{def}\var{mumble}}. + +%% +%%\node Funny Frames, Debug Tail Recursion, Function Names, Stack Frames +\subsection{Funny Frames} +\cindex{external entry points} +\cpsubindex{entry points}{external} +\cpsubindex{block compilation}{debugger implications} +\cpsubindex{external}{stack frame kind} +\cpsubindex{optional}{stack frame kind} +\cpsubindex{cleanup}{stack frame kind} + +Sometimes the evaluator introduces new functions that are used to implement a +user function, but are not directly specified in the source. The main place +this is done is for checking argument type and syntax. Usually these functions +do their thing and then go away, and thus are not seen on the stack in the +debugger. But when you get some sort of error during lambda-list processing, +you end up in the debugger on one of these funny frames. + +These funny frames are flagged by printing \code{[}\var{keyword}\code{]}'' after the +parentheses. For example, this call: +\begin{lisp} +(car 'a 'b) +\end{lisp} +will look like this: +\begin{example} +(CAR 2 A) [:EXTERNAL] +\end{example} +And this call: +\begin{lisp} +(string-upcase "test case" :end) +\end{lisp} +would look like this: +\begin{example} +("DEFUN STRING-UPCASE" "test case" 335544424 1) [:OPTIONAL] +\end{example} + +As you can see, these frames have only a vague resemblance to the original +call. Fortunately, the error message displayed when you enter the debugger +will usually tell you what problem is (in these cases, too many arguments +and odd keyword arguments.) Also, if you go down the stack to the frame for +the calling function, you can display the original source (\pxlref{source-locations}.) + +With recursive or block compiled functions (\pxlref{block-compilation}), an \kwd{EXTERNAL} frame may appear before the frame +representing the first call to the recursive function or entry to the compiled +block. This is a consequence of the way the compiler does block compilation: +there is nothing odd with your program. You will also see \kwd{CLEANUP} frames +during the execution of \code{unwind-protect} cleanup code. Note that inline +expansion and open-coding affect what frames are present in the debugger, see +sections \ref{debugger-policy} and \ref{open-coding}. + +%% +%%\node Debug Tail Recursion, Unknown Locations and Interrupts, Funny Frames, Stack Frames +\subsection{Debug Tail Recursion} +\label{debug-tail-recursion} +\cindex{tail recursion} +\cpsubindex{recursion}{tail} + +Both the compiler and the interpreter are properly tail recursive.'' If a +function call is in a tail-recursive position, the stack frame will be +deallocated \i{at the time of the call}, rather than after the call returns. +Consider this backtrace: +\begin{example} +(BAR ...) +(FOO ...) +\end{example} +Because of tail recursion, it is not necessarily the case that +\code{FOO} directly called \code{BAR}. It may be that \code{FOO} called +some other function \code{FOO2} which then called \code{BAR} +tail-recursively, as in this example: +\begin{example} +(defun foo () + ... + (foo2 ...) + ...) + +(defun foo2 (...) + ... + (bar ...)) + +(defun bar (...) + ...) +\end{example} + +Usually the elimination of tail-recursive frames makes debugging more +pleasant, since these frames are mostly uninformative. If there is any +doubt about how one function called another, it can usually be +eliminated by finding the source location in the calling frame (section +\ref{source-locations}.) + +For a more thorough discussion of tail recursion, \pxlref{tail-recursion}. + +%% +%%\node Unknown Locations and Interrupts, , Debug Tail Recursion, Stack Frames +\subsection{Unknown Locations and Interrupts} +\label{unknown-locations} +\cindex{unknown code locations} +\cpsubindex{locations}{unknown} +\cindex{interrupts} +\cpsubindex{errors}{run-time} + +The debugger operates using special debugging information attached to +the compiled code. This debug information tells the debugger what it +needs to know about the locations in the code where the debugger can be +invoked. If the debugger somehow encounters a location not described in +the debug information, then it is said to be \var{unknown}. If the code +location for a frame is unknown, then some variables may be +inaccessible, and the source location cannot be precisely displayed. + +There are three reasons why a code location could be unknown: +\begin{itemize} + +\item +There is inadequate debug information due to the value of the \code{debug} +optimization quality. \xlref{debugger-policy}. + +\item +The debugger was entered because of an interrupt such as \code{$\hat{ }C$}. + +\item +A hardware error such as \code{bus error}'' occurred in code that was +compiled unsafely due to the value of the \code{safety} optimization +quality. \xlref{optimize-declaration}. +\end{itemize} + +In the last two cases, the values of argument variables are accessible, +but may be incorrect. \xlref{debug-var-validity} for more details on +when variable values are accessible. + +It is possible for an interrupt to happen when a function call or return is in +progress. The debugger may then flame out with some obscure error or insist +that the bottom of the stack has been reached, when the real problem is that +the current stack frame can't be located. If this happens, return from the +interrupt and try again. + +When running interpreted code, all locations should be known. However, +an interrupt might catch some subfunction of the interpreter at an +unknown location. In this case, you should be able to go up the stack a +frame or two and reach an interpreted frame which can be debugged. + +%% +%%\node Variable Access, Source Location Printing, Stack Frames, The Debugger +\section{Variable Access} +\label{debug-vars} +\cpsubindex{variables}{debugger access} +\cindex{debug variables} + +There are three ways to access the current frame's local variables in the +debugger. The simplest is to type the variable's name into the debugger's +read-eval-print loop. The debugger will evaluate the variable reference as +though it had appeared inside that frame. + +The debugger doesn't really understand lexical scoping; it has just one +namespace for all the variables in a function. If a symbol is the name of +multiple variables in the same function, then the reference appears ambiguous, +even though lexical scoping specifies which value is visible at any given +source location. If the scopes of the two variables are not nested, then the +debugger can resolve the ambiguity by observing that only one variable is +accessible. + +When there are ambiguous variables, the evaluator assigns each one a +small integer identifier. The \code{debug:var} function and the +\code{list-locals} command use this identifier to distinguish between +ambiguous variables: +\begin{Lentry} + +\item[\code{list-locals} \mopt{\var{prefix}}]%%\hfill\\ +This command prints the name and value of all variables in the current +frame whose name has the specified \var{prefix}. \var{prefix} may be a +string or a symbol. If no \var{prefix} is given, then all available +variables are printed. If a variable has a potentially ambiguous name, +then the name is printed with a \code{\#}\var{identifier}'' suffix, where +\var{identifier} is the small integer used to make the name unique. +\end{Lentry} + +\begin{defun}{debug:}{var}{\args{\var{name} \ampoptional{} \var{identifier}}} + + This function returns the value of the variable in the current frame + with the specified \var{name}. If supplied, \var{identifier} + determines which value to return when there are ambiguous variables. + + When \var{name} is a symbol, it is interpreted as the symbol name of + the variable, i.e. the package is significant. If \var{name} is an + uninterned symbol (gensym), then return the value of the uninterned + variable with the same name. If \var{name} is a string, + \code{debug:var} interprets it as the prefix of a variable name, and + must unambiguously complete to the name of a valid variable. + + This function is useful mainly for accessing the value of uninterned + or ambiguous variables, since most variables can be evaluated + directly. +\end{defun} + +%% +\begin{comment} +* Variable Value Availability:: +* Note On Lexical Variable Access:: +\end{comment} + +%%\node Variable Value Availability, Note On Lexical Variable Access, Variable Access, Variable Access +\subsection{Variable Value Availability} +\label{debug-var-validity} +\cindex{availability of debug variables} +\cindex{validity of debug variables} +\cindex{debug optimization quality} + +The value of a variable may be unavailable to the debugger in portions of the +program where \clisp{} says that the variable is defined. If a variable value is +not available, the debugger will not let you read or write that variable. With +one exception, the debugger will never display an incorrect value for a +variable. Rather than displaying incorrect values, the debugger tells you the +value is unavailable. + +The one exception is this: if you interrupt (e.g., with \code{$\hat{ }C$}) or if there is +an unexpected hardware error such as \code{bus error}'' (which should only happen +in unsafe code), then the values displayed for arguments to the interrupted +frame might be incorrect.\footnote{Since the location of an interrupt or hardware +error will always be an unknown location (\pxlref{unknown-locations}), +non-argument variable values will never be available in the interrupted frame.} +This exception applies only to the interrupted frame: any frame farther down +the stack will be fine. + +The value of a variable may be unavailable for these reasons: +\begin{itemize} + +\item +The value of the \code{debug} optimization quality may have omitted debug +information needed to determine whether the variable is available. +Unless a variable is an argument, its value will only be available when +\code{debug} is at least \code{2}. + +\item +The compiler did lifetime analysis and determined that the value was no longer +needed, even though its scope had not been exited. Lifetime analysis is +inhibited when the \code{debug} optimization quality is \code{3}. + +\item +The variable's name is an uninterned symbol (gensym). To save space, the +compiler only dumps debug information about uninterned variables when the +\code{debug} optimization quality is \code{3}. + +\item +The frame's location is unknown (\pxlref{unknown-locations}) because +the debugger was entered due to an interrupt or unexpected hardware error. +Under these conditions the values of arguments will be available, but might be +incorrect. This is the exception above. + +\item +The variable was optimized out of existence. Variables with no reads are +always optimized away, even in the interpreter. The degree to which the +compiler deletes variables will depend on the value of the \code{compile-speed} +optimization quality, but most source-level optimizations are done under all +compilation policies. +\end{itemize} + + +Since it is especially useful to be able to get the arguments to a function, +argument variables are treated specially when the \code{speed} optimization +quality is less than \code{3} and the \code{debug} quality is at least \code{1}. +With this compilation policy, the values of argument variables are almost +always available everywhere in the function, even at unknown locations. For +non-argument variables, \code{debug} must be at least \code{2} for values to be +available, and even then, values are only available at known locations. + +%% +%%\node Note On Lexical Variable Access, , Variable Value Availability, Variable Access +\subsection{Note On Lexical Variable Access} +\cpsubindex{evaluation}{debugger} + +When the debugger command loop establishes variable bindings for available +variables, these variable bindings have lexical scope and dynamic +extent.\footnote{The variable bindings are actually created using the \clisp{} +\code{symbol-macro-let} special form.} You can close over them, but such closures +can't be used as upward funargs. + +You can also set local variables using \code{setq}, but if the variable was closed +over in the original source and never set, then setting the variable in the +debugger may not change the value in all the functions the variable is defined +in. Another risk of setting variables is that you may assign a value of a type +that the compiler proved the variable could never take on. This may result in +bad things happening. + +%% +%%\node Source Location Printing, Compiler Policy Control, Variable Access, The Debugger +\section{Source Location Printing} +\label{source-locations} +\cpsubindex{source location printing}{debugger} + +One of CMU \clisp{}'s unique capabilities is source level debugging of compiled +code. These commands display the source location for the current frame: +\begin{Lentry} + +\item[\code{source} \mopt{\var{context}}]%%\hfill\\ +This command displays the file that the current frame's function was defined +from (if it was defined from a file), and then the source form responsible for +generating the code that the current frame was executing. If \var{context} is +specified, then it is an integer specifying the number of enclosing levels of +list structure to print. + +\item[\code{vsource} \mopt{\var{context}}]%%\hfill\\ +This command is identical to \code{source}, except that it uses the +global values of \code{*print-level*} and \code{*print-length*} instead +of the debugger printing control variables \code{*debug-print-level*} +and \code{*debug-print-length*}. +\end{Lentry} + +The source form for a location in the code is the innermost list present +in the original source that encloses the form responsible for generating +that code. If the actual source form is not a list, then some enclosing +list will be printed. For example, if the source form was a reference +to the variable \code{*some-random-special*}, then the innermost +enclosing evaluated form will be printed. Here are some possible +enclosing forms: +\begin{example} +(let ((a *some-random-special*)) + ...) + +(+ *some-random-special* ...) +\end{example} + +If the code at a location was generated from the expansion of a macro or a +source-level compiler optimization, then the form in the original source that +expanded into that code will be printed. Suppose the file +\file{/usr/me/mystuff.lisp} looked like this: +\begin{example} +(defmacro mymac () + '(myfun)) + +(defun foo () + (mymac) + ...) +\end{example} +If \code{foo} has called \code{myfun}, and is waiting for it to return, then the +\code{source} command would print: +\begin{example} +; File: /usr/me/mystuff.lisp + +(MYMAC) +\end{example} +Note that the macro use was printed, not the actual function call form, +\code{(myfun)}. + +If enclosing source is printed by giving an argument to \code{source} or +\code{vsource}, then the actual source form is marked by wrapping it in a list +whose first element is \code{\#:***HERE***}. In the previous example, +\w{\code{source 1}} would print: +\begin{example} +; File: /usr/me/mystuff.lisp + +(DEFUN FOO () + (#:***HERE*** + (MYMAC)) + ...) +\end{example} + +%% +\begin{comment} +* How the Source is Found:: +* Source Location Availability:: +\end{comment} + +%%\node How the Source is Found, Source Location Availability, Source Location Printing, Source Location Printing +\subsection{How the Source is Found} + +If the code was defined from \llisp{} by \code{compile} or +\code{eval}, then the source can always be reliably located. If the +code was defined from a \code{fasl} file created by +\findexed{compile-file}, then the debugger gets the source forms it +prints by reading them from the original source file. This is a +potential problem, since the source file might have moved or changed +since the time it was compiled. + +The source file is opened using the \code{truename} of the source file +pathname originally given to the compiler. This is an absolute pathname +with all logical names and symbolic links expanded. If the file can't +be located using this name, then the debugger gives up and signals an +error. + +If the source file can be found, but has been modified since the time it was +compiled, the debugger prints this warning: +\begin{example} +; File has been modified since compilation: +; \var{filename} +; Using form offset instead of character position. +\end{example} +where \var{filename} is the name of the source file. It then proceeds using a +robust but not foolproof heuristic for locating the source. This heuristic +works if: +\begin{itemize} + +\item +No top-level forms before the top-level form containing the source have been +added or deleted, and + +\item +The top-level form containing the source has not been modified much. (More +precisely, none of the list forms beginning before the source form have been +added or deleted.) +\end{itemize} + +If the heuristic doesn't work, the displayed source will be wrong, but will +probably be near the actual source. If the shape'' of the top-level form in +the source file is too different from the original form, then an error will be +signaled. When the heuristic is used, the the source location commands are +noticeably slowed. + +Source location printing can also be confused if (after the source was +compiled) a read-macro you used in the code was redefined to expand into +something different, or if a read-macro ever returns the same \code{eq} +list twice. If you don't define read macros and don't use \code{\#\#} in +perverted ways, you don't need to worry about this. + +%% +%%\node Source Location Availability, , How the Source is Found, Source Location Printing +\subsection{Source Location Availability} + +\cindex{debug optimization quality} +Source location information is only available when the \code{debug} +optimization quality is at least \code{2}. If source location information is +unavailable, the source commands will give an error message. + +If source location information is available, but the source location is +unknown because of an interrupt or unexpected hardware error +(\pxlref{unknown-locations}), then the command will print: +\begin{example} +Unknown location: using block start. +\end{example} +and then proceed to print the source location for the start of the \i{basic +block} enclosing the code location. \cpsubindex{block}{basic} +\cpsubindex{block}{start location} +It's a bit complicated to explain exactly what a basic block is, but +here are some properties of the block start location: +\begin{itemize} + +\item The block start location may be the same as the true location. + +\item The block start location will never be later in the the + program's flow of control than the true location. + +\item No conditional control structures (such as \code{if}, + \code{cond}, \code{or}) will intervene between the block start and + the true location (but note that some conditionals present in the + original source could be optimized away.) Function calls \i{do not} + end basic blocks. + +\item The head of a loop will be the start of a block. + +\item The programming language concept of block structure'' and the + \clisp{} \code{block} special form are totally unrelated to the + compiler's basic block. +\end{itemize} + +In other words, the true location lies between the printed location and the +next conditional (but watch out because the compiler may have changed the +program on you.) + +%% +%%\node Compiler Policy Control, Exiting Commands, Source Location Printing, The Debugger +\section{Compiler Policy Control} +\label{debugger-policy} +\cpsubindex{policy}{debugger} +\cindex{debug optimization quality} +\cindex{optimize declaration} + +The compilation policy specified by \code{optimize} declarations affects the +behavior seen in the debugger. The \code{debug} quality directly affects the +debugger by controlling the amount of debugger information dumped. Other +optimization qualities have indirect but observable effects due to changes in +the way compilation is done. + +Unlike the other optimization qualities (which are compared in relative value +to evaluate tradeoffs), the \code{debug} optimization quality is directly +translated to a level of debug information. This absolute interpretation +allows the user to count on a particular amount of debug information being +available even when the values of the other qualities are changed during +compilation. These are the levels of debug information that correspond to the +values of the \code{debug} quality: +\begin{Lentry} + +\item[\code{0}] +Only the function name and enough information to allow the stack to +be parsed. + +\item[\code{\w{$>$0}}] +Any level greater than \code{0} gives level \code{0} plus all +argument variables. Values will only be accessible if the argument +variable is never set and +\code{speed} is not \code{3}. \cmucl{} allows any real value for optimization +qualities. It may be useful to specify \code{0.5} to get backtrace argument +display without argument documentation. + +\item[\code{1}] Level \code{1} provides argument documentation +(printed arglists) and derived argument/result type information. +This makes \findexed{describe} more informative, and allows the +compiler to do compile-time argument count and type checking for any +calls compiled at run-time. + +\item[\code{2}] +Level \code{1} plus all interned local variables, source location +information, and lifetime information that tells the debugger when arguments +are available (even when \code{speed} is \code{3} or the argument is set.) This is +the default. + +\item[\code{3}] +Level \code{2} plus all uninterned variables. In addition, lifetime +analysis is disabled (even when \code{speed} is \code{3}), ensuring that all variable +values are available at any known location within the scope of the binding. +This has a speed penalty in addition to the obvious space penalty. +\end{Lentry} + +As you can see, if the \code{speed} quality is \code{3}, debugger performance is +degraded. This effect comes from the elimination of argument variable +special-casing (\pxlref{debug-var-validity}.) Some degree of +speed/debuggability tradeoff is unavoidable, but the effect is not too drastic +when \code{debug} is at least \code{2}. + +\cindex{inline expansion} +\cindex{semi-inline expansion} +In addition to \code{inline} and \code{notinline} declarations, the relative values +of the \code{speed} and \code{space} qualities also change whether functions are +inline expanded (\pxlref{inline-expansion}.) If a function is inline +expanded, then there will be no frame to represent the call, and the arguments +will be treated like any other local variable. Functions may also be +semi-inline'', in which case there is a frame to represent the call, but the +call is to an optimized local version of the function, not to the original +function. + +%% +%%\node Exiting Commands, Information Commands, Compiler Policy Control, The Debugger +\section{Exiting Commands} + +These commands get you out of the debugger. + +\begin{Lentry} + +\item[\code{quit}] +Throw to top level. + +\item[\code{restart} \mopt{\var{n}}]%%\hfill\\ +Invokes the \var{n}th restart case as displayed by the \code{error} +command. If \var{n} is not specified, the available restart cases are +reported. + +\item[\code{go}] +Calls \code{continue} on the condition given to \code{debug}. If there is no +restart case named \var{continue}, then an error is signaled. + +\item[\code{abort}] +Calls \code{abort} on the condition given to \code{debug}. This is +useful for popping debug command loop levels or aborting to top level, +as the case may be. + +\begin{comment} +(\code{debug:debug-return} \var{expression} \mopt{\var{frame}}) + +\item +From the current or specified frame, return the result of evaluating +expression. If multiple values are expected, then this function should be +called for multiple values. +\end{comment} +\end{Lentry} + +%% +%%\node Information Commands, Breakpoint Commands, Exiting Commands, The Debugger +\section{Information Commands} + +Most of these commands print information about the current frame or +function, but a few show general information. + +\begin{Lentry} + +\item[\code{help}, \code{?}] +Displays a synopsis of debugger commands. + +\item[\code{describe}] +Calls \code{describe} on the current function, displays number of local +variables, and indicates whether the function is compiled or interpreted. + +\item[\code{print}] +Displays the current function call as it would be displayed by moving to +this frame. + +\item[\code{vprint} (or \code{pp}) \mopt{\var{verbosity}}]%%\hfill\\ +Displays the current function call using \code{*print-level*} and +\code{*print-length*} instead of \code{*debug-print-level*} and +\code{*debug-print-length*}. \var{verbosity} is a small integer +(default 2) that controls other dimensions of verbosity. + +\item[\code{error}] +Prints the condition given to \code{invoke-debugger} and the active +proceed cases. + +\item[\code{backtrace} \mopt{\var{n}}]\hfill\\ +Displays all the frames from the current to the bottom. Only shows +\var{n} frames if specified. The printing is controlled by +\code{*debug-print-level*} and \code{*debug-print-length*}. + +\begin{comment} +(\code{debug:debug-function} \mopt{\var{n}}) + +\item +Returns the function from the current or specified frame. + +\item[(\code{debug:function-name} \mopt{\var{n}])] +Returns the function name from the current or specified frame. + +\item[(\code{debug:pc} \mopt{\var{frame}})] +Returns the index of the instruction for the function in the current or +specified frame. This is useful in conjunction with \code{disassemble}. +The pc returned points to the instruction after the one that was fatal. +\end{comment} +\end{Lentry} + +%% +%%\node Breakpoint Commands, Function Tracing, Information Commands, The Debugger +\section{Breakpoint Commands} + +\cmucl{} supports setting of breakpoints inside compiled functions and +stepping of compiled code. Breakpoints can only be set at at known +locations (\pxlref{unknown-locations}), so these commands are largely +useless unless the \code{debug} optimize quality is at least \code{2} +(\pxlref{debugger-policy}). These commands manipulate breakpoints: +\begin{Lentry} +\item[\code{breakpoint} \var{location} \mstar{\var{option} \var{value}}] +%%\hfill\\ +Set a breakpoint in some function. \var{location} may be an integer +code location number (as displayed by \code{list-locations}) or a +keyword. The keyword can be used to indicate setting a breakpoint at +the function start (\kwd{start}, \kwd{s}) or function end +(\kwd{end}, \kwd{e}). The \code{breakpoint} command has +\kwd{condition}, \kwd{break}, \kwd{print} and \kwd{function} +options which work similarly to the \code{trace} options. + +\item[\code{list-locations} (or \code{ll}) \mopt{\var{function}}]%%\hfill\\ +List all the code locations in the current frame's function, or in +\var{function} if it is supplied. The display format is the code +location number, a colon and then the source form for that location: +\begin{example} +3: (1- N) +\end{example} +If consecutive locations have the same source, then a numeric range like +\code{3-5:} will be printed. For example, a default function call has a +known location both immediately before and after the call, which would +result in two code locations with the same source. The listed function +becomes the new default function for breakpoint setting (via the +\code{breakpoint}) command. + +\item[\code{list-breakpoints} (or \code{lb})]%%\hfill\\ +List all currently active breakpoints with their breakpoint number. + +\item[\code{delete-breakpoint} (or \code{db}) \mopt{\var{number}}]%%\hfill\\ +Delete a breakpoint specified by its breakpoint number. If no number is +specified, delete all breakpoints. + +\item[\code{step}]%%\hfill\\ +Step to the next possible breakpoint location in the current function. +This always steps over function calls, instead of stepping into them +\end{Lentry} + +\begin{comment} +* Breakpoint Example:: +\end{comment} + +%%\node Breakpoint Example, , Breakpoint Commands, Breakpoint Commands +\subsection{Breakpoint Example} + +Consider this definition of the factorial function: +\begin{lisp} +(defun ! (n) + (if (zerop n) + 1 + (* n (! (1- n))))) +\end{lisp} +This debugger session demonstrates the use of breakpoints: +\begin{example} +common-lisp-user> (break) ; Invoke debugger + +Break + +Restarts: + 0: [CONTINUE] Return from BREAK. + 1: [ABORT ] Return to Top-Level. + +Debug (type H for help) + +(INTERACTIVE-EVAL (BREAK)) +0] ll #'! +0: #'(LAMBDA (N) (BLOCK ! (IF # 1 #))) +1: (ZEROP N) +2: (* N (! (1- N))) +3: (1- N) +4: (! (1- N)) +5: (* N (! (1- N))) +6: #'(LAMBDA (N) (BLOCK ! (IF # 1 #))) +0] br 2 +(* N (! (1- N))) +1: 2 in ! +Added. +0] q + +common-lisp-user> (! 10) ; Call the function + +*Breakpoint hit* + +Restarts: + 0: [CONTINUE] Return from BREAK. + 1: [ABORT ] Return to Top-Level. + +Debug (type H for help) + +(! 10) ; We are now in first call (arg 10) before the multiply +Source: (* N (! (1- N))) +3] st + +*Step* + +(! 10) ; We have finished evaluation of (1- n) +Source: (1- N) +3] st + +*Breakpoint hit* + +Restarts: + 0: [CONTINUE] Return from BREAK. + 1: [ABORT ] Return to Top-Level. + +Debug (type H for help) + +(! 9) ; We hit the breakpoint in the recursive call +Source: (* N (! (1- N))) +3] +\end{example} + + + +%% +%%\node Function Tracing, Specials, Breakpoint Commands, The Debugger +\section{Function Tracing} +\cindex{tracing} +\cpsubindex{function}{tracing} + +The tracer causes selected functions to print their arguments and +their results whenever they are called. Options allow conditional +printing of the trace information and conditional breakpoints on +function entry or exit. + +\begin{defmac}{}{trace}{% + \args{\mstar{option global-value} \mstar{name \mstar{option + value}}}} + + \code{trace} is a debugging tool that prints information when + specified functions are called. In its simplest form: + \begin{example} + (trace \var{name-1} \var{name-2} ...) + \end{example} + \code{trace} causes a printout on \vindexed{trace-output} each time + that one of the named functions is entered or returns (the + \var{names} are not evaluated.) Trace output is indented according + to the number of pending traced calls, and this trace depth is + printed at the beginning of each line of output. Printing verbosity + of arguments and return values is controlled by + \vindexed{debug-print-level} and \vindexed{debug-print-length}. + + If no \var{names} or \var{options} are are given, \code{trace} + returns the list of all currently traced functions, + \code{*traced-function-list*}. + + Trace options can cause the normal printout to be suppressed, or + cause extra information to be printed. Each option is a pair of an + option keyword and a value form. Options may be interspersed with + function names. Options only affect tracing of the function whose + name they appear immediately after. Global options are specified + before the first name, and affect all functions traced by a given + use of \code{trace}. If an already traced function is traced again, + any new options replace the old options. The following options are + defined: + \begin{Lentry} + \item[\kwd{condition} \var{form}, \kwd{condition-after} \var{form}, + \kwd{condition-all} \var{form}] If \kwd{condition} is specified, + then \code{trace} does nothing unless \var{form} evaluates to true + at the time of the call. \kwd{condition-after} is similar, but + suppresses the initial printout, and is tested when the function + returns. \kwd{condition-all} tries both before and after. + + \item[\kwd{wherein} \var{names}] If specified, \var{names} is a + function name or list of names. \code{trace} does nothing unless + a call to one of those functions encloses the call to this + function (i.e. it would appear in a backtrace.) Anonymous + functions have string names like \code{"DEFUN FOO"}. + + \item[\kwd{break} \var{form}, \kwd{break-after} \var{form}, + \kwd{break-all} \var{form}] If specified, and \var{form} evaluates + to true, then the debugger is invoked at the start of the + function, at the end of the function, or both, according to the + respective option. + + \item[\kwd{print} \var{form}, \kwd{print-after} \var{form}, + \kwd{print-all} \var{form}] In addition to the usual printout, the + result of evaluating \var{form} is printed at the start of the + function, at the end of the function, or both, according to the + respective option. Multiple print options cause multiple values + to be printed. + + \item[\kwd{function} \var{function-form}] This is a not really an + option, but rather another way of specifying what function to + trace. The \var{function-form} is evaluated immediately, and the + resulting function is traced. + + \item[\kwd{encapsulate \mgroup{:default | t | nil}}] In \cmucl, + tracing can be done either by temporarily redefining the function + name (encapsulation), or using breakpoints. When breakpoints are + used, the function object itself is destructively modified to + cause the tracing action. The advantage of using breakpoints is + that tracing works even when the function is anonymously called + via \code{funcall}. + + When \kwd{encapsulate} is true, tracing is done via encapsulation. + \kwd{default} is the default, and means to use encapsulation for + interpreted functions and funcallable instances, breakpoints + otherwise. When encapsulation is used, forms are {\it not} + evaluated in the function's lexical environment, but + \code{debug:arg} can still be used. + \end{Lentry} + + \kwd{condition}, \kwd{break} and \kwd{print} forms are evaluated in + the lexical environment of the called function; \code{debug:var} and + \code{debug:arg} can be used. The \code{-after} and \code{-all} + forms are evaluated in the null environment. +\end{defmac} + +\begin{defmac}{}{untrace}{ \args{\amprest{} \var{function-names}}} + + This macro turns off tracing for the specified functions, and + removes their names from \code{*traced-function-list*}. If no + \var{function-names} are given, then all currently traced functions + are untraced. +\end{defmac} + +\begin{defvar}{extensions:}{traced-function-list} + + A list of function names maintained and used by \code{trace}, + \code{untrace}, and \code{untrace-all}. This list should contain + the names of all functions currently being traced. +\end{defvar} + +\begin{defvar}{extensions:}{max-trace-indentation} + + The maximum number of spaces which should be used to indent trace + printout. This variable is initially set to 40. +\end{defvar} + +\begin{comment} +* Encapsulation Functions:: +\end{comment} + +%%\node Encapsulation Functions, , Function Tracing, Function Tracing +\subsection{Encapsulation Functions} +\cindex{encapsulation} +\cindex{advising} + +The encapsulation functions provide a mechanism for intercepting the +arguments and results of a function. \code{encapsulate} changes the +function definition of a symbol, and saves it so that it can be +restored later. The new definition normally calls the original +definition. The \clisp{} \findexed{fdefinition} function always returns +the original definition, stripping off any encapsulation. + +The original definition of the symbol can be restored at any time by +the \code{unencapsulate} function. \code{encapsulate} and \code{unencapsulate} +allow a symbol to be multiply encapsulated in such a way that different +encapsulations can be completely transparent to each other. + +Each encapsulation has a type which may be an arbitrary lisp object. +If a symbol has several encapsulations of different types, then any +one of them can be removed without affecting more recent ones. +A symbol may have more than one encapsulation of the same type, but +only the most recent one can be undone. + +\begin{defun}{extensions:}{encapsulate}{% + \args{\var{symbol} \var{type} \var{body}}} + + Saves the current definition of \var{symbol}, and replaces it with a + function which returns the result of evaluating the form, + \var{body}. \var{Type} is an arbitrary lisp object which is the + type of encapsulation. + + When the new function is called, the following variables are bound + for the evaluation of \var{body}: + \begin{Lentry} + + \item[\code{extensions:argument-list}] A list of the arguments to + the function. + + \item[\code{extensions:basic-definition}] The unencapsulated + definition of the function. + \end{Lentry} + The unencapsulated definition may be called with the original + arguments by including the form + \begin{lisp} + (apply extensions:basic-definition extensions:argument-list) + \end{lisp} + + \code{encapsulate} always returns \var{symbol}. +\end{defun} + +\begin{defun}{extensions:}{unencapsulate}{\args{\var{symbol} \var{type}}} + + Undoes \var{symbol}'s most recent encapsulation of type \var{type}. + \var{Type} is compared with \code{eq}. Encapsulations of other + types are left in place. +\end{defun} + +\begin{defun}{extensions:}{encapsulated-p}{% + \args{\var{symbol} \var{type}}} + + Returns \true{} if \var{symbol} has an encapsulation of type + \var{type}. Returns \nil{} otherwise. \var{type} is compared with + \code{eq}. +\end{defun} + +%% +\begin{comment} +section{The Single Stepper} + +\begin{defmac}{}{step}{ \args{\var{form}}} + + Evaluates form with single stepping enabled or if \var{form} is + \code{T}, enables stepping until explicitly disabled. Stepping can + be disabled by quitting to the lisp top level, or by evaluating the + form \w{\code{(step ())}}. + + While stepping is enabled, every call to eval will prompt the user + for a single character command. The prompt is the form which is + about to be \code{eval}ed. It is printed with \code{*print-level*} + and \code{*print-length*} bound to \code{*step-print-level*} and + \code{*step-print-length*}. All interaction is done through the + stream \code{*query-io*}. Because of this, the stepper can not be + used in Hemlock eval mode. When connected to a slave Lisp, the + stepper can be used from Hemlock. + + The commands are: + \begin{Lentry} + + \item[\key{n} (next)] Evaluate the expression with stepping still + enabled. + + \item[\key{s} (skip)] Evaluate the expression with stepping + disabled. + + \item[\key{q} (quit)] Evaluate the expression, but disable all + further stepping inside the current call to \code{step}. + + \item[\key{p} (print)] Print current form. (does not use + \code{*step-print-level*} or \code{*step-print-length*}.) + + \item[\key{b} (break)] Enter break loop, and then prompt for the + command again when the break loop returns. + + \item[\key{e} (eval)] Prompt for and evaluate an arbitrary + expression. The expression is evaluated with stepping disabled. + + \item[\key{?} (help)] Prints a brief list of the commands. + + \item[\key{r} (return)] Prompt for an arbitrary value to return as + result of the current call to eval. + + \item[\key{g}] Throw to top level. + \end{Lentry} +\end{defmac} + +\begin{defvar}{extensions:}{step-print-level} + \defvarx[extensions:]{step-print-length} + + \code{*print-level*} and \code{*print-length*} are bound to these + values while printing the current form. \code{*step-print-level*} + and \code{*step-print-length*} are initially bound to 4 and 5, + respectively. +\end{defvar} + +\begin{defvar}{extensions:}{max-step-indentation} + + Step indents the prompts to highlight the nesting of the evaluation. + This variable contains the maximum number of spaces to use for + indenting. Initially set to 40. +\end{defvar} + +\end{comment} + +%% +%%\node Specials, , Function Tracing, The Debugger +\section{Specials} +These are the special variables that control the debugger action. + +\begin{changebar} +\begin{defvar}{debug:}{debug-print-level} + \defvarx[debug:]{debug-print-length} + + \code{*print-level*} and \code{*print-length*} are bound to these + values during the execution of some debug commands. When evaluating + arbitrary expressions in the debugger, the normal values of + \code{*print-level*} and \code{*print-length*} are in effect. These + variables are initially set to 3 and 5, respectively. +\end{defvar} +\end{changebar} + +%% +\hide{File:/afs/cs.cmu.edu/project/clisp/hackers/ram/docs/cmu-user/compiler.ms} + + +%%\node The Compiler, Advanced Compiler Use and Efficiency Hints, The Debugger, Top +\chapter{The Compiler} \hide{ -*- Dictionary: cmu-user -*-} + +\begin{comment} +* Compiler Introduction:: +* Calling the Compiler:: +* Compilation Units:: +* Interpreting Error Messages:: +* Types in Python:: +* Getting Existing Programs to Run:: +* Compiler Policy:: +* Open Coding and Inline Expansion:: +\end{comment} + +%%\node Compiler Introduction, Calling the Compiler, The Compiler, The Compiler +\section{Compiler Introduction} + +This chapter contains information about the compiler that every \cmucl{} user +should be familiar with. Chapter \ref{advanced-compiler} goes into greater +depth, describing ways to use more advanced features. + +The \cmucl{} compiler (also known as \Python{}) has many features +that are seldom or never supported by conventional \llisp{} +compilers: +\begin{itemize} + +\item Source level debugging of compiled code (see chapter + \ref{debugger}.) + +\item Type error compiler warnings for type errors detectable at + compile time. + +\item Compiler error messages that provide a good indication of where + the error appeared in the source. + +\item Full run-time checking of all potential type errors, with + optimization of type checks to minimize the cost. + +\item Scheme-like features such as proper tail recursion and extensive + source-level optimization. + +\item Advanced tuning and optimization features such as comprehensive + efficiency notes, flow analysis, and untagged number representations + (see chapter \ref{advanced-compiler}.) +\end{itemize} + + +%% +%%\node Calling the Compiler, Compilation Units, Compiler Introduction, The Compiler +\section{Calling the Compiler} +\cindex{compiling} +Functions may be compiled using \code{compile}, \code{compile-file}, or +\code{compile-from-stream}. + +\begin{defun}{}{compile}{ \args{\var{name} \ampoptional{} \var{definition}}} + + This function compiles the function whose name is \var{name}. If + \var{name} is \false, the compiled function object is returned. If + \var{definition} is supplied, it should be a lambda expression that + is to be compiled and then placed in the function cell of + \var{name}. As per the proposed X3J13 cleanup + compile-argument-problems'', \var{definition} may also be an + interpreted function. + + The return values are as per the proposed X3J13 cleanup + compiler-diagnostics''. The first value is the function name or + function object. The second value is \false{} if no compiler + diagnostics were issued, and \true{} otherwise. The third value is + \false{} if no compiler diagnostics other than style warnings were + issued. A non-\false{} value indicates that there were serious'' + compiler diagnostics issued, or that other conditions of type + \tindexed{error} or \tindexed{warning} (but not + \tindexed{style-warning}) were signaled during compilation. +\end{defun} + + +\begin{defun}{}{compile-file}{ + \args{\var{input-pathname} + \keys{\kwd{output-file} \kwd{error-file} \kwd{trace-file}} + \morekeys{\kwd{error-output} \kwd{verbose} \kwd{print} \kwd{progress}} + \yetmorekeys{\kwd{load} \kwd{block-compile} \kwd{entry-points}} + \yetmorekeys{\kwd{byte-compile}}}} + + The \cmucl{} \code{compile-file} is extended through the addition of + several new keywords and an additional interpretation of + \var{input-pathname}: + \begin{Lentry} + + \item[\var{input-pathname}] If this argument is a list of input + files, rather than a single input pathname, then all the source + files are compiled into a single object file. In this case, the + name of the first file is used to determine the default output + file names. This is especially useful in combination with + \var{block-compile}. + + \item[\kwd{output-file}] This argument specifies the name of the + output file. \true{} gives the default name, \false{} suppresses + the output file. + + \item[\kwd{error-file}] A listing of all the error output is + directed to this file. If there are no errors, then no error file + is produced (and any existing error file is deleted.) \true{} + gives \w{"\var{name}\code{.err}"} (the default), and \false{} + suppresses the output file. + + \item[\kwd{error-output}] If \true{} (the default), then error + output is sent to \code{*error-output*}. If a stream, then output + is sent to that stream instead. If \false, then error output is + suppressed. Note that this error output is in addition to (but + the same as) the output placed in the \var{error-file}. + + \item[\kwd{verbose}] If \true{} (the default), then the compiler + prints to error output at the start and end of compilation of each + file. See \varref{compile-verbose}. + + \item[\kwd{print}] If \true{} (the default), then the compiler + prints to error output when each function is compiled. See + \varref{compile-print}. + + \item[\kwd{progress}] If \true{} (default \false{}), then the + compiler prints to error output progress information about the + phases of compilation of each function. This is a CMU extension + that is useful mainly in large block compilations. See + \varref{compile-progress}. + + \item[\kwd{trace-file}] If \true{}, several of the intermediate + representations (including annotated assembly code) are dumped out + to this file. \true{} gives \w{"\var{name}\code{.trace}"}. Trace + output is off by default. \xlref{trace-files}. + + \item[\kwd{load}] If \true{}, load the resulting output file. + + \item[\kwd{block-compile}] Controls the compile-time resolution of + function calls. By default, only self-recursive calls are + resolved, unless an \code{ext:block-start} declaration appears in + the source file. \xlref{compile-file-block}. + + \item[\kwd{entry-points}] If non-null, then this is a list of the + names of all functions in the file that should have global + definitions installed (because they are referenced in other + files.) \xlref{compile-file-block}. + + \item[\kwd{byte-compile}] If \true{}, compiling to a compact + interpreted byte code is enabled. Possible values are \true{}, + \false{}, and \kwd{maybe} (the default.) See + \varref{byte-compile-default} and \xlref{byte-compile}. + \end{Lentry} + + The return values are as per the proposed X3J13 cleanup + compiler-diagnostics''. The first value from \code{compile-file} + is the truename of the output file, or \false{} if the file could + not be created. The interpretation of the second and third values + is described above for \code{compile}. +\end{defun} + +\begin{defvar}{}{compile-verbose} + \defvarx{compile-print} + \defvarx{compile-progress} + + These variables determine the default values for the \kwd{verbose}, + \kwd{print} and \kwd{progress} arguments to \code{compile-file}. +\end{defvar} + +\begin{defun}{extensions:}{compile-from-stream}{% + \args{\var{input-stream} + \keys{\kwd{error-stream}} + \morekeys{\kwd{trace-stream}} + \yetmorekeys{\kwd{block-compile} \kwd{entry-points}} + \yetmorekeys{\kwd{byte-compile}}}} + + This function is similar to \code{compile-file}, but it takes all + its arguments as streams. It reads \llisp{} code from + \var{input-stream} until end of file is reached, compiling into the + current environment. This function returns the same two values as + the last two values of \code{compile}. No output files are + produced. +\end{defun} + + +%% +%%\node Compilation Units, Interpreting Error Messages, Calling the Compiler, The Compiler +\section{Compilation Units} +\cpsubindex{compilation}{units} + +\cmucl{} supports the \code{with-compilation-unit} macro added to the +language by the proposed X3J13 with-compilation-unit'' compiler +cleanup. This provides a mechanism for eliminating spurious undefined +warnings when there are forward references across files, and also +provides a standard way to access compiler extensions. + +\begin{defmac}{}{with-compilation-unit}{% + \args{(\mstar{\var{key} \var{value}}) \mstar{\var{form}}}} + + This macro evaluates the \var{forms} in an environment that causes + warnings for undefined variables, functions and types to be delayed + until all the forms have been evaluated. Each keyword \var{value} + is an evaluated form. These keyword options are recognized: + \begin{Lentry} + + \item[\kwd{override}] If uses of \code{with-compilation-unit} are + dynamically nested, the outermost use will take precedence, + suppressing printing of undefined warnings by inner uses. + However, when the \code{override} option is true this shadowing is + inhibited; an inner use will print summary warnings for the + compilations within the inner scope. + + \item[\kwd{optimize}] This is a CMU extension that specifies of the + global'' compilation policy for the dynamic extent of the body. + The argument should evaluate to an \code{optimize} declare form, + like: + \begin{lisp} + (optimize (speed 3) (safety 0)) + \end{lisp} + \xlref{optimize-declaration} + + \item[\kwd{optimize-interface}] Similar to \kwd{optimize}, but + specifies the compilation policy for function interfaces (argument + count and type checking) for the dynamic extent of the body. + \xlref{optimize-interface-declaration}. + + \item[\kwd{context-declarations}] This is a CMU extension that + pattern-matches on function names, automatically splicing in any + appropriate declarations at the head of the function definition. + \xlref{context-declarations}. + \end{Lentry} +\end{defmac} + +\begin{comment} +* Undefined Warnings:: +\end{comment} + +%%\node Undefined Warnings, , Compilation Units, Compilation Units +\subsection{Undefined Warnings} + +\cindex{undefined warnings} +Warnings about undefined variables, functions and types are delayed until the +end of the current compilation unit. The compiler entry functions +(\code{compile}, etc.) implicitly use \code{with-compilation-unit}, so undefined +warnings will be printed at the end of the compilation unless there is an +enclosing \code{with-compilation-unit}. In order the gain the benefit of this +mechanism, you should wrap a single \code{with-compilation-unit} around the calls +to \code{compile-file}, i.e.: +\begin{lisp} +(with-compilation-unit () + (compile-file "file1") + (compile-file "file2") + ...) +\end{lisp} + +Unlike for functions and types, undefined warnings for variables are +not suppressed when a definition (e.g. \code{defvar}) appears after +the reference (but in the same compilation unit.) This is because +doing special declarations out of order just doesn't +work\dash{}although early references will be compiled as special, +bindings will be done lexically. + +Undefined warnings are printed with full source context +(\pxlref{error-messages}), which tremendously simplifies the problem +of finding undefined references that resulted from macroexpansion. +After printing detailed information about the undefined uses of each +name, \code{with-compilation-unit} also prints summary listings of the +names of all the undefined functions, types and variables. + +\begin{defvar}{}{undefined-warning-limit} + + This variable controls the number of undefined warnings for each + distinct name that are printed with full source context when the + compilation unit ends. If there are more undefined references than + this, then they are condensed into a single warning: + \begin{example} + Warning: \var{count} more uses of undefined function \var{name}. + \end{example} + When the value is \code{0}, then the undefined warnings are not + broken down by name at all: only the summary listing of undefined + names is printed. +\end{defvar} + +%% +%%\node Interpreting Error Messages, Types in Python, Compilation Units, The Compiler +\section{Interpreting Error Messages} +\label{error-messages} +\cpsubindex{error messages}{compiler} +\cindex{compiler error messages} + +One of \Python{}'s unique features is the level of source location +information it provides in error messages. The error messages contain +a lot of detail in a terse format, to they may be confusing at first. +Error messages will be illustrated using this example program: +\begin{lisp} +(defmacro zoq (x) + (roq (ploq (+ ,x 3)))) + +(defun foo (y) + (declare (symbol y)) + (zoq y)) +\end{lisp} +The main problem with this program is that it is trying to add \code{3} to a +symbol. Note also that the functions \code{roq} and \code{ploq} aren't defined +anywhere. + +\begin{comment} +* The Parts of the Error Message:: +* The Original and Actual Source:: +* The Processing Path:: +* Error Severity:: +* Errors During Macroexpansion:: +* Read Errors:: +* Error Message Parameterization:: +\end{comment} + +%%\node The Parts of the Error Message, The Original and Actual Source, Interpreting Error Messages, Interpreting Error Messages +\subsection{The Parts of the Error Message} + +The compiler will produce this warning: +\begin{example} +File: /usr/me/stuff.lisp + +In: DEFUN FOO + (ZOQ Y) +--> ROQ PLOQ + +==> + Y +Warning: Result is a SYMBOL, not a NUMBER. +\end{example} +In this example we see each of the six possible parts of a compiler error +message: +\begin{Lentry} + +\item[\w{\code{File: /usr/me/stuff.lisp}}] This is the \var{file} that + the compiler read the relevant code from. The file name is + displayed because it may not be immediately obvious when there is an + error during compilation of a large system, especially when + \code{with-compilation-unit} is used to delay undefined warnings. + +\item[\w{\code{In: DEFUN FOO}}] This is the \var{definition} or + top-level form responsible for the error. It is obtained by taking + the first two elements of the enclosing form whose first element is + a symbol beginning with \code{DEF}''. If there is no enclosing + \w{\var{def}mumble}, then the outermost form is used. If there are + multiple \w{\var{def}mumbles}, then they are all printed from the + out in, separated by \code{$=>$}'s. In this example, the problem + was in the \code{defun} for \code{foo}. + +\item[\w{\code{(ZOQ Y)}}] This is the \i{original source} form + responsible for the error. Original source means that the form + directly appeared in the original input to the compiler, i.e. in the + lambda passed to \code{compile} or the top-level form read from the + source file. In this example, the expansion of the \code{zoq} macro + was responsible for the error. + +\item[\w{\code{--$>$ROQ PLOQ +}} ] This is the \i{processing path} + that the compiler used to produce the errorful code. The processing + path is a representation of the evaluated forms enclosing the actual + source that the compiler encountered when processing the original + source. The path is the first element of each form, or the form + itself if the form is not a list. These forms result from the + expansion of macros or source-to-source transformation done by the + compiler. In this example, the enclosing evaluated forms are the + calls to \code{roq}, \code{ploq} and \code{+}. These calls resulted + from the expansion of the \code{zoq} macro. + +\item[\code{==$>$Y}] This is the \i{actual source} responsible for + the error. If the actual source appears in the explanation, then we + print the next enclosing evaluated form, instead of printing the + actual source twice. (This is the form that would otherwise have + been the last form of the processing path.) In this example, the + problem is with the evaluation of the reference to the variable + \code{y}. + +\item[\w{\code{Warning: Result is a SYMBOL, not a NUMBER.}}] This is + the \var{explanation} the problem. In this example, the problem is + that \code{y} evaluates to a \code{symbol}, but is in a context + where a number is required (the argument to \code{+}). +\end{Lentry} + +Note that each part of the error message is distinctively marked: +\begin{itemize} + +\item \code{File:} and \code{In:} mark the file and definition, + respectively. + +\item The original source is an indented form with no prefix. + +\item Each line of the processing path is prefixed with \code{--$>$}. + +\item The actual source form is indented like the original source, but + is marked by a preceding \code{==$>$} line. This is like the + macroexpands to'' notation used in \cltl. + +\item The explanation is prefixed with the error severity + (\pxlref{error-severity}), either \code{Error:}, \code{Warning:}, or + \code{Note:}. +\end{itemize} + + +Each part of the error message is more specific than the preceding +one. If consecutive error messages are for nearby locations, then the +front part of the error messages would be the same. In this case, the +compiler omits as much of the second message as in common with the +first. For example: +\begin{example} +File: /usr/me/stuff.lisp + +In: DEFUN FOO + (ZOQ Y) +--> ROQ +==> + (PLOQ (+ Y 3)) +Warning: Undefined function: PLOQ + +==> + (ROQ (PLOQ (+ Y 3))) +Warning: Undefined function: ROQ +\end{example} +In this example, the file, definition and original source are +identical for the two messages, so the compiler omits them in the +second message. If consecutive messages are entirely identical, then +the compiler prints only the first message, followed by: +\begin{example} +[Last message occurs \var{repeats} times] +\end{example} +where \var{repeats} is the number of times the message was given. + +If the source was not from a file, then no file line is printed. If +the actual source is the same as the original source, then the +processing path and actual source will be omitted. If no forms +intervene between the original source and the actual source, then the +processing path will also be omitted. + +%% +%%\node The Original and Actual Source, The Processing Path, The Parts of the Error Message, Interpreting Error Messages +\subsection{The Original and Actual Source} +\cindex{original source} +\cindex{actual source} + +The \i{original source} displayed will almost always be a list. If the actual +source for an error message is a symbol, the original source will be the +immediately enclosing evaluated list form. So even if the offending symbol +does appear in the original source, the compiler will print the enclosing list +and then print the symbol as the actual source (as though the symbol were +introduced by a macro.) + +When the \i{actual source} is displayed (and is not a symbol), it will always +be code that resulted from the expansion of a macro or a source-to-source +compiler optimization. This is code that did not appear in the original +source program; it was introduced by the compiler. + +Keep in mind that when the compiler displays a source form in an error message, +it always displays the most specific (innermost) responsible form. For +example, compiling this function: +\begin{lisp} +(defun bar (x) + (let (a) + (declare (fixnum a)) + (setq a (foo x)) + a)) +\end{lisp} +Gives this error message: +\begin{example} +In: DEFUN BAR + (LET (A) (DECLARE (FIXNUM A)) (SETQ A (FOO X)) A) +Warning: The binding of A is not a FIXNUM: + NIL +\end{example} +This error message is not saying there's a problem somewhere in this +\code{let}''\dash{}it is saying that there is a problem with the +\code{let} itself. In this example, the problem is that \code{a}'s +\false{} initial value is not a \code{fixnum}. + +%% +%%\node The Processing Path, Error Severity, The Original and Actual Source, Interpreting Error Messages +\subsection{The Processing Path} +\cindex{processing path} +\cindex{macroexpansion} +\cindex{source-to-source transformation} + +The processing path is mainly useful for debugging macros, so if you don't +write macros, you can ignore the processing path. Consider this example: +\begin{lisp} +(defun foo (n) + (dotimes (i n *undefined*))) +\end{lisp} +Compiling results in this error message: +\begin{example} +In: DEFUN FOO + (DOTIMES (I N *UNDEFINED*)) +--> DO BLOCK LET TAGBODY RETURN-FROM +==> + (PROGN *UNDEFINED*) +Warning: Undefined variable: *UNDEFINED* +\end{example} +Note that \code{do} appears in the processing path. This is because \code{dotimes} +expands into: +\begin{lisp} +(do ((i 0 (1+ i)) (#:g1 n)) + ((>= i #:g1) *undefined*) + (declare (type unsigned-byte i))) +\end{lisp} +The rest of the processing path results from the expansion of \code{do}: +\begin{lisp} +(block nil + (let ((i 0) (#:g1 n)) + (declare (type unsigned-byte i)) + (tagbody (go #:g3) + #:g2 (psetq i (1+ i)) + #:g3 (unless (>= i #:g1) (go #:g2)) + (return-from nil (progn *undefined*))))) +\end{lisp} +In this example, the compiler descended into the \code{block}, +\code{let}, \code{tagbody} and \code{return-from} to reach the +\code{progn} printed as the actual source. This is a place where the +actual source appears in explanation'' rule was applied. The +innermost actual source form was the symbol \code{*undefined*} itself, +but that also appeared in the explanation, so the compiler backed out +one level. + +%% +%%\node Error Severity, Errors During Macroexpansion, The Processing Path, Interpreting Error Messages +\subsection{Error Severity} +\label{error-severity} +\cindex{severity of compiler errors} +\cindex{compiler error severity} + +There are three levels of compiler error severity: +\begin{Lentry} + +\item[Error] This severity is used when the compiler encounters a + problem serious enough to prevent normal processing of a form. + Instead of compiling the form, the compiler compiles a call to + \code{error}. Errors are used mainly for signaling syntax errors. + If an error happens during macroexpansion, the compiler will handle + it. The compiler also handles and attempts to proceed from read + errors. + +\item[Warning] Warnings are used when the compiler can prove that + something bad will happen if a portion of the program is executed, + but the compiler can proceed by compiling code that signals an error + at runtime if the problem has not been fixed: + \begin{itemize} + + \item Violation of type declarations, or + + \item Function calls that have the wrong number of arguments or + malformed keyword argument lists, or + + \item Referencing a variable declared \code{ignore}, or unrecognized + declaration specifiers. + \end{itemize} + + In the language of the \clisp{} standard, these are situations where + the compiler can determine that a situation with undefined + consequences or that would cause an error to be signaled would + result at runtime. + +\item[Note] Notes are used when there is something that seems a bit + odd, but that might reasonably appear in correct programs. +\end{Lentry} +Note that the compiler does not fully conform to the proposed X3J13 +compiler-diagnostics'' cleanup. Errors, warnings and notes mostly +correspond to errors, warnings and style-warnings, but many things +that the cleanup considers to be style-warnings are printed as +warnings rather than notes. Also, warnings, style-warnings and most +errors aren't really signaled using the condition system. + +%% +%%\node Errors During Macroexpansion, Read Errors, Error Severity, Interpreting Error Messages +\subsection{Errors During Macroexpansion} +\cpsubindex{macroexpansion}{errors during} + +The compiler handles errors that happen during macroexpansion, turning +them into compiler errors. If you want to debug the error (to debug a +macro), you can set \code{*break-on-signals*} to \code{error}. For +example, this definition: +\begin{lisp} +(defun foo (e l) + (do ((current l (cdr current)) + ((atom current) nil)) + (when (eq (car current) e) (return current)))) +\end{lisp} +gives this error: +\begin{example} +In: DEFUN FOO + (DO ((CURRENT L #) (# NIL)) (WHEN (EQ # E) (RETURN CURRENT)) ) +Error: (during macroexpansion) + +Error in function LISP::DO-DO-BODY. +DO step variable is not a symbol: (ATOM CURRENT) +\end{example} + + +%% +%%\node Read Errors, Error Message Parameterization, Errors During Macroexpansion, Interpreting Error Messages +\subsection{Read Errors} +\cpsubindex{read errors}{compiler} + +The compiler also handles errors while reading the source. For example: +\begin{example} +Error: Read error at 2: + "(,/\back{foo})" +Error in function LISP::COMMA-MACRO. +Comma not inside a backquote. +\end{example} +The \code{at 2}'' refers to the character position in the source file at +which the error was signaled, which is generally immediately after the +erroneous text. The next line, \code{(,/\back{foo})}'', is the line in +the source that contains the error file position. The \code{/\back{} }'' +indicates the error position within that line (in this example, +immediately after the offending comma.) + +When in \hemlock{} (or any other EMACS-like editor), you can go to a +character position with: +\begin{example} +M-< C-u \var{position} C-f +\end{example} +Note that if the source is from a \hemlock{} buffer, then the position +is relative to the start of the compiled region or \code{defun}, not the +file or buffer start. + +After printing a read error message, the compiler attempts to recover from the +error by backing up to the start of the enclosing top-level form and reading +again with \code{*read-suppress*} true. If the compiler can recover from the +error, then it substitutes a call to \code{cerror} for the unreadable form and +proceeds to compile the rest of the file normally. + +If there is a read error when the file position is at the end of the file +(i.e., an unexpected EOF error), then the error message looks like this: +\begin{example} +Error: Read error in form starting at 14: + "(defun test ()" +Error in function LISP::FLUSH-WHITESPACE. +EOF while reading #<Stream for file "/usr/me/test.lisp"> +\end{example} +In this case, \code{starting at 14}'' indicates the character +position at which the compiler started reading, i.e. the position +before the start of the form that was missing the closing delimiter. +The line \w{"\code{(defun test ()}"} is first line after the starting +position that the compiler thinks might contain the unmatched open +delimiter. + +%% +%%\node Error Message Parameterization, , Read Errors, Interpreting Error Messages +\subsection{Error Message Parameterization} +\cpsubindex{error messages}{verbosity} +\cpsubindex{verbosity}{of error messages} + +There is some control over the verbosity of error messages. See also +\varref{undefined-warning-limit}, \code{*efficiency-note-limit*} and +\varref{efficiency-note-cost-threshold}. + +\begin{defvar}{}{enclosing-source-cutoff} + + This variable specifies the number of enclosing actual source forms + that are printed in full, rather than in the abbreviated processing + path format. Increasing the value from its default of \code{1} + allows you to see more of the guts of the macroexpanded source, + which is useful when debugging macros. +\end{defvar} + +\begin{defvar}{}{error-print-length} + \defvarx{error-print-level} + + These variables are the print level and print length used in + printing error messages. The default values are \code{5} and + \code{3}. If null, the global values of \code{*print-level*} and + \code{*print-length*} are used. +\end{defvar} + +\begin{defmac}{extensions:}{def-source-context}{% + \args{\var{name} \var{lambda-list} \mstar{form}}} + + This macro defines how to extract an abbreviated source context from + the \var{name}d form when it appears in the compiler input. + \var{lambda-list} is a \code{defmacro} style lambda-list used to + parse the arguments. The \var{body} should return a list of + subforms that can be printed on about one line. There are + predefined methods for \code{defstruct}, \code{defmethod}, etc. If + no method is defined, then the first two subforms are returned. + Note that this facility implicitly determines the string name + associated with anonymous functions. +\end{defmac} + +%% +%%\node Types in Python, Getting Existing Programs to Run, Interpreting Error Messages, The Compiler +\section{Types in Python} +\cpsubindex{types}{in python} + +A big difference between \Python{} and all other \llisp{} compilers +is the approach to type checking and amount of knowledge about types: +\begin{itemize} + +\item \Python{} treats type declarations much differently that other + Lisp compilers do. \Python{} doesn't blindly believe type + declarations; it considers them assertions about the program that + should be checked. + +\item \Python{} also has a tremendously greater knowledge of the + \clisp{} type system than other compilers. Support is incomplete + only for the \code{not}, \code{and} and \code{satisfies} types. +\end{itemize} +See also sections \ref{advanced-type-stuff} and \ref{type-inference}. + +%% +\begin{comment} +* Compile Time Type Errors:: +* Precise Type Checking:: +* Weakened Type Checking:: +\end{comment} + +%%\node Compile Time Type Errors, Precise Type Checking, Types in Python, Types in Python +\subsection{Compile Time Type Errors} +\cindex{compile time type errors} +\cpsubindex{type checking}{at compile time} + +If the compiler can prove at compile time that some portion of the +program cannot be executed without a type error, then it will give a +warning at compile time. It is possible that the offending code would +never actually be executed at run-time due to some higher level +consistency constraint unknown to the compiler, so a type warning +doesn't always indicate an incorrect program. For example, consider +this code fragment: +\begin{lisp} +(defun raz (foo) + (let ((x (case foo + (:this 13) + (:that 9) + (:the-other 42)))) + (declare (fixnum x)) + (foo x))) +\end{lisp} +Compilation produces this warning: +\begin{example} +In: DEFUN RAZ + (CASE FOO (:THIS 13) (:THAT 9) (:THE-OTHER 42)) +--> LET COND IF COND IF COND IF +==> + (COND) +Warning: This is not a FIXNUM: + NIL +\end{example} +In this case, the warning is telling you that if \code{foo} isn't any +of \kwd{this}, \kwd{that} or \kwd{the-other}, then \code{x} will be +initialized to \false, which the \code{fixnum} declaration makes +illegal. The warning will go away if \code{ecase} is used instead of +\code{case}, or if \kwd{the-other} is changed to \true. + +This sort of spurious type warning happens moderately often in the +expansion of complex macros and in inline functions. In such cases, +there may be dead code that is impossible to correctly execute. The +compiler can't always prove this code is dead (could never be +executed), so it compiles the erroneous code (which will always signal +an error if it is executed) and gives a warning. + +\begin{defun}{extensions:}{required-argument}{} + + This function can be used as the default value for keyword arguments + that must always be supplied. Since it is known by the compiler to + never return, it will avoid any compile-time type warnings that + would result from a default value inconsistent with the declared + type. When this function is called, it signals an error indicating + that a required keyword argument was not supplied. This function is + also useful for \code{defstruct} slot defaults corresponding to + required arguments. \xlref{empty-type}. + + Although this function is a CMU extension, it is relatively harmless + to use it in otherwise portable code, since you can easily define it + yourself: + \begin{lisp} + (defun required-argument () + (error "A required keyword argument was not supplied.")) + \end{lisp} +\end{defun} + +Type warnings are inhibited when the +\code{extensions:inhibit-warnings} optimization quality is \code{3} +(\pxlref{compiler-policy}.) This can be used in a local declaration +to inhibit type warnings in a code fragment that has spurious +warnings. + +%% +%%\node Precise Type Checking, Weakened Type Checking, Compile Time Type Errors, Types in Python +\subsection{Precise Type Checking} +\label{precise-type-checks} +\cindex{precise type checking} +\cpsubindex{type checking}{precise} + +With the default compilation policy, all type +assertions\footnote{There are a few circumstances where a type + declaration is discarded rather than being used as type assertion. + This doesn't affect safety much, since such discarded declarations + are also not believed to be true by the compiler.} are precisely +checked. Precise checking means that the check is done as though +\code{typep} had been called with the exact type specifier that +appeared in the declaration. \Python{} uses \var{policy} to determine +whether to trust type assertions (\pxlref{compiler-policy}). Type +assertions from declarations are indistinguishable from the type +assertions on arguments to built-in functions. In \Python, adding +type declarations makes code safer. + +If a variable is declared to be \w{\code{(integer 3 17)}}, then its +value must always always be an integer between \code{3} and \code{17}. +If multiple type declarations apply to a single variable, then all the +declarations must be correct; it is as though all the types were +intersected producing a single \code{and} type specifier. + +Argument type declarations are automatically enforced. If you declare +the type of a function argument, a type check will be done when that +function is called. In a function call, the called function does the +argument type checking, which means that a more restrictive type +assertion in the calling function (e.g., from \code{the}) may be lost. + +The types of structure slots are also checked. The value of a +structure slot must always be of the type indicated in any \kwd{type} +slot option.\footnote{The initial value need not be of this type as + long as the corresponding argument to the constructor is always + supplied, but this will cause a compile-time type warning unless + \code{required-argument} is used.} Because of precise type checking, +the arguments to slot accessors are checked to be the correct type of +structure. + +In traditional \llisp{} compilers, not all type assertions are +checked, and type checks are not precise. Traditional compilers +blindly trust explicit type declarations, but may check the argument +type assertions for built-in functions. Type checking is not precise, +since the argument type checks will be for the most general type legal +for that argument. In many systems, type declarations suppress what +little type checking is being done, so adding type declarations makes +code unsafe. This is a problem since it discourages writing type +declarations during initial coding. In addition to being more error +prone, adding type declarations during tuning also loses all the +benefits of debugging with checked type assertions. + +To gain maximum benefit from \Python{}'s type checking, you should +always declare the types of function arguments and structure slots as +precisely as possible. This often involves the use of \code{or}, +\code{member} and other list-style type specifiers. Paradoxically, +even though adding type declarations introduces type checks, it +usually reduces the overall amount of type checking. This is +especially true for structure slot type declarations. + +\Python{} uses the \code{safety} optimization quality (rather than +presence or absence of declarations) to choose one of three levels of +run-time type error checking: \pxlref{optimize-declaration}. +\xlref{advanced-type-stuff} for more information about types in +\Python. + +%% +%%\node Weakened Type Checking, , Precise Type Checking, Types in Python +\subsection{Weakened Type Checking} +\label{weakened-type-checks} +\cindex{weakened type checking} +\cpsubindex{type checking}{weakened} + +When the value for the \code{speed} optimization quality is greater +than \code{safety}, and \code{safety} is not \code{0}, then type +checking is weakened to reduce the speed and space penalty. In +structure-intensive code this can double the speed, yet still catch +most type errors. Weakened type checks provide a level of safety +similar to that of safe'' code in other \llisp{} compilers. + +A type check is weakened by changing the check to be for some +convenient supertype of the asserted type. For example, +\code{\w{(integer 3 17)}} is changed to \code{fixnum}, +\code{\w{(simple-vector 17)}} to \code{simple-vector}, and structure +types are changed to \code{structure}. A complex check like: +\begin{example} +(or node hunk (member :foo :bar :baz)) +\end{example} +will be omitted entirely (i.e., the check is weakened to \code{*}.) If +a precise check can be done for no extra cost, then no weakening is +done. + +Although weakened type checking is similar to type checking done by +other compilers, it is sometimes safer and sometimes less safe. +Weakened checks are done in the same places is precise checks, so all +the preceding discussion about where checking is done still applies. +Weakened checking is sometimes somewhat unsafe because although the +check is weakened, the precise type is still input into type +inference. In some contexts this will result in type inferences not +justified by the weakened check, and hence deletion of some type +checks that would be done by conventional compilers. + +For example, if this code was compiled with weakened checks: +\begin{lisp} +(defstruct foo + (a nil :type simple-string)) + +(defstruct bar + (a nil :type single-float)) + +(defun myfun (x) + (declare (type bar x)) + (* (bar-a x) 3.0)) +\end{lisp} +and \code{myfun} was passed a \code{foo}, then no type error would be +signaled, and we would try to multiply a \code{simple-vector} as +though it were a float (with unpredictable results.) This is because +the check for \code{bar} was weakened to \code{structure}, yet when +compiling the call to \code{bar-a}, the compiler thinks it knows it +has a \code{bar}. + +Note that normally even weakened type checks report the precise type +in error messages. For example, if \code{myfun}'s \code{bar} check is +weakened to \code{structure}, and the argument is \false{}, then the +error will be: +\begin{example} +Type-error in MYFUN: + NIL is not of type BAR +\end{example} +However, there is some speed and space cost for signaling a precise +error, so the weakened type is reported if the \code{speed} +optimization quality is \code{3} or \code{debug} quality is less than +\code{1}: +\begin{example} +Type-error in MYFUN: + NIL is not of type STRUCTURE +\end{example} +\xlref{optimize-declaration} for further discussion of the +\code{optimize} declaration. + +%% +%%\node Getting Existing Programs to Run, Compiler Policy, Types in Python, The Compiler +\section{Getting Existing Programs to Run} +\cpsubindex{existing programs}{to run} +\cpsubindex{types}{portability} +\cindex{compatibility with other Lisps} + +Since \Python{} does much more comprehensive type checking than other +Lisp compilers, \Python{} will detect type errors in many programs +that have been debugged using other compilers. These errors are +mostly incorrect declarations, although compile-time type errors can +find actual bugs if parts of the program have never been tested. + +Some incorrect declarations can only be detected by run-time type +checking. It is very important to initially compile programs with +full type checks and then test this version. After the checking +version has been tested, then you can consider weakening or +eliminating type checks. \b{This applies even to previously debugged + programs.} \Python{} does much more type inference than other +\llisp{} compilers, so believing an incorrect declaration does much +more damage. + +The most common problem is with variables whose initial value doesn't +match the type declaration. Incorrect initial values will always be +flagged by a compile-time type error, and they are simple to fix once +located. Consider this code fragment: +\begin{example} +(prog (foo) + (declare (fixnum foo)) + (setq foo ...) + ...) +\end{example} +Here the variable \code{foo} is given an initial value of \false, but +is declared to be a \code{fixnum}. Even if it is never read, the +initial value of a variable must match the declared type. There are +two ways to fix this problem. Change the declaration: +\begin{example} +(prog (foo) + (declare (type (or fixnum null) foo)) + (setq foo ...) + ...) +\end{example} +or change the initial value: +\begin{example} +(prog ((foo 0)) + (declare (fixnum foo)) + (setq foo ...) + ...) +\end{example} +It is generally preferable to change to a legal initial value rather +than to weaken the declaration, but sometimes it is simpler to weaken +the declaration than to try to make an initial value of the +appropriate type. + + +Another declaration problem occasionally encountered is incorrect +declarations on \code{defmacro} arguments. This probably usually +happens when a function is converted into a macro. Consider this +macro: +\begin{lisp} +(defmacro my-1+ (x) + (declare (fixnum x)) + (the fixnum (1+ ,x))) +\end{lisp} +Although legal and well-defined \clisp, this meaning of this +definition is almost certainly not what the writer intended. For +example, this call is illegal: +\begin{lisp} +(my-1+ (+ 4 5)) +\end{lisp} +The call is illegal because the argument to the macro is \w{\code{(+ 4 + 5)}}, which is a \code{list}, not a \code{fixnum}. Because of +macro semantics, it is hardly ever useful to declare the types of +macro arguments. If you really want to assert something about the +type of the result of evaluating a macro argument, then put a +\code{the} in the expansion: +\begin{lisp} +(defmacro my-1+ (x) + (the fixnum (1+ (the fixnum ,x)))) +\end{lisp} +In this case, it would be stylistically preferable to change this +macro back to a function and declare it inline. Macros have no +efficiency advantage over inline functions when using \Python. +\xlref{inline-expansion}. + + +Some more subtle problems are caused by incorrect declarations that +can't be detected at compile time. Consider this code: +\begin{example} +(do ((pos 0 (position #\back{a} string :start (1+ pos)))) + ((null pos)) + (declare (fixnum pos)) + ...) +\end{example} +Although \code{pos} is almost always a \code{fixnum}, it is \false{} +at the end of the loop. If this example is compiled with full type +checks (the default), then running it will signal a type error at the +end of the loop. If compiled without type checks, the program will go +into an infinite loop (or perhaps \code{position} will complain +because \w{\code{(1+ nil)}} isn't a sensible start.) Why? Because if +you compile without type checks, the compiler just quietly believes +the type declaration. Since \code{pos} is always a \code{fixnum}, it +is never \nil, so \w{\code{(null pos)}} is never true, and the loop +exit test is optimized away. Such errors are sometimes flagged by +unreachable code notes (\pxlref{dead-code-notes}), but it is still +important to initially compile any system with full type checks, even +if the system works fine when compiled using other compilers. + +In this case, the fix is to weaken the type declaration to +\w{\code{(or fixnum null)}}.\footnote{Actually, this declaration is + totally unnecessary in \Python, since it already knows + \code{position} returns a non-negative \code{fixnum} or \false.} +Note that there is usually little performance penalty for weakening a +declaration in this way. Any numeric operations in the body can still +assume the variable is a \code{fixnum}, since \false{} is not a legal +numeric argument. Another possible fix would be to say: +\begin{example} +(do ((pos 0 (position #\back{a} string :start (1+ pos)))) + ((null pos)) + (let ((pos pos)) + (declare (fixnum pos)) + ...)) +\end{example} +This would be preferable in some circumstances, since it would allow a +non-standard representation to be used for the local \code{pos} +variable in the loop body (see section \ref{ND-variables}.) + +In summary, remember that \i{all} values that a variable \i{ever} +has must be of the declared type, and that you should test using safe +code initially. +%% +%%\node Compiler Policy, Open Coding and Inline Expansion, Getting Existing Programs to Run, The Compiler +\section{Compiler Policy} +\label{compiler-policy} +\cpsubindex{policy}{compiler} +\cindex{compiler policy} + +The policy is what tells the compiler \var{how} to compile a program. +This is logically (and often textually) distinct from the program +itself. Broad control of policy is provided by the \code{optimize} +declaration; other declarations and variables control more specific +aspects of compilation. + +%% +\begin{comment} +* The Optimize Declaration:: +* The Optimize-Interface Declaration:: +\end{comment} + +%%\node The Optimize Declaration, The Optimize-Interface Declaration, Compiler Policy, Compiler Policy +\subsection{The Optimize Declaration} +\label{optimize-declaration} +\cindex{optimize declaration} +\cpsubindex{declarations}{\code{optimize}} + +The \code{optimize} declaration recognizes six different +\var{qualities}. The qualities are conceptually independent aspects +of program performance. In reality, increasing one quality tends to +have adverse effects on other qualities. The compiler compares the +relative values of qualities when it needs to make a trade-off; i.e., +if \code{speed} is greater than \code{safety}, then improve speed at +the cost of safety. + +The default for all qualities (except \code{debug}) is \code{1}. +Whenever qualities are equal, ties are broken according to a broad +idea of what a good default environment is supposed to be. Generally +this downplays \code{speed}, \code{compile-speed} and \code{space} in +favor of \code{safety} and \code{debug}. Novice and casual users +should stick to the default policy. Advanced users often want to +improve speed and memory usage at the cost of safety and +debuggability. + +If the value for a quality is \code{0} or \code{3}, then it may have a +special interpretation. A value of \code{0} means totally +unimportant'', and a \code{3} means ultimately important.'' These +extreme optimization values enable heroic'' compilation strategies +that are not always desirable and sometimes self-defeating. +Specifying more than one quality as \code{3} is not desirable, since +it doesn't tell the compiler which quality is most important. + + +These are the optimization qualities: +\begin{Lentry} + +\item[\code{speed}] \cindex{speed optimization quality}How fast the + program should is run. \code{speed 3} enables some optimizations + that hurt debuggability. + +\item[\code{compilation-speed}] \cindex{compilation-speed optimization + quality}How fast the compiler should run. Note that increasing + this above \code{safety} weakens type checking. + +\item[\code{space}] \cindex{space optimization quality}How much space + the compiled code should take up. Inline expansion is mostly + inhibited when \code{space} is greater than \code{speed}. A value + of \code{0} enables promiscuous inline expansion. Wide use of a + \code{0} value is not recommended, as it may waste so much space + that run time is slowed. \xlref{inline-expansion} for a discussion + of inline expansion. + +\item[\code{debug}] \cindex{debug optimization quality}How debuggable + the program should be. The quality is treated differently from the + other qualities: each value indicates a particular level of debugger + information; it is not compared with the other qualities. + \xlref{debugger-policy} for more details. + +\item[\code{safety}] \cindex{safety optimization quality}How much + error checking should be done. If \code{speed}, \code{space} or + \code{compilation-speed} is more important than \code{safety}, then + type checking is weakened (\pxlref{weakened-type-checks}). If + \code{safety} if \code{0}, then no run time error checking is done. + In addition to suppressing type checks, \code{0} also suppresses + argument count checking, unbound-symbol checking and array bounds + checks. + +\item[\code{extensions:inhibit-warnings}] \cindex{inhibit-warnings + optimization quality}This is a CMU extension that determines how + little (or how much) diagnostic output should be printed during + compilation. This quality is compared to other qualities to + determine whether to print style notes and warnings concerning those + qualities. If \code{speed} is greater than \code{inhibit-warnings}, + then notes about how to improve speed will be printed, etc. The + default value is \code{1}, so raising the value for any standard + quality above its default enables notes for that quality. If + \code{inhibit-warnings} is \code{3}, then all notes and most + non-serious warnings are inhibited. This is useful with + \code{declare} to suppress warnings about unavoidable problems. +\end{Lentry} + +%%\node The Optimize-Interface Declaration, , The Optimize Declaration, Compiler Policy +\subsection{The Optimize-Interface Declaration} +\label{optimize-interface-declaration} +\cindex{optimize-interface declaration} +\cpsubindex{declarations}{\code{optimize-interface}} + +The \code{extensions:optimize-interface} declaration is identical in +syntax to the \code{optimize} declaration, but it specifies the policy +used during compilation of code the compiler automatically generates +to check the number and type of arguments supplied to a function. It +is useful to specify this policy separately, since even thoroughly +debugged functions are vulnerable to being passed the wrong arguments. +The \code{optimize-interface} declaration can specify that arguments +should be checked even when the general \code{optimize} policy is +unsafe. + +Note that this argument checking is the checking of user-supplied +arguments to any functions defined within the scope of the +declaration, \code{not} the checking of arguments to \llisp{} +primitives that appear in those definitions. + +The idea behind this declaration is that it allows the definition of +functions that appear fully safe to other callers, but that do no +internal error checking. Of course, it is possible that arguments may +be invalid in ways other than having incorrect type. Functions +compiled unsafely must still protect themselves against things like +user-supplied array indices that are out of bounds and improper lists. +See also the \kwd{context-declarations} option to +\macref{with-compilation-unit}. + +%% +%%\node Open Coding and Inline Expansion, , Compiler Policy, The Compiler +\section{Open Coding and Inline Expansion} +\label{open-coding} +\cindex{open-coding} +\cindex{inline expansion} +\cindex{static functions} + +Since \clisp{} forbids the redefinition of standard functions\footnote{See the +proposed X3J13 lisp-symbol-redefinition'' cleanup.}, the compiler can have +special knowledge of these standard functions embedded in it. This special +knowledge is used in various ways (open coding, inline expansion, source +transformation), but the implications to the user are basically the same: +\begin{itemize} + +\item Attempts to redefine standard functions may be frustrated, since + the function may never be called. Although it is technically + illegal to redefine standard functions, users sometimes want to + implicitly redefine these functions when they are debugging using + the \code{trace} macro. Special-casing of standard functions can be + inhibited using the \code{notinline} declaration. + +\item The compiler can have multiple alternate implementations of + standard functions that implement different trade-offs of speed, + space and safety. This selection is based on the compiler policy, + \pxlref{compiler-policy}. +\end{itemize} + + +When a function call is \i{open coded}, inline code whose effect is +equivalent to the function call is substituted for that function call. +When a function call is \i{closed coded}, it is usually left as is, +although it might be turned into a call to a different function with +different arguments. As an example, if \code{nthcdr} were to be open +coded, then +\begin{lisp} +(nthcdr 4 foobar) +\end{lisp} +might turn into +\begin{lisp} +(cdr (cdr (cdr (cdr foobar)))) +\end{lisp} +or even +\begin{lisp} +(do ((i 0 (1+ i)) + (list foobar (cdr foobar))) + ((= i 4) list)) +\end{lisp} + +If \code{nth} is closed coded, then +\begin{lisp} +(nth x l) +\end{lisp} +might stay the same, or turn into something like: +\begin{lisp} +(car (nthcdr x l)) +\end{lisp} + +In general, open coding sacrifices space for speed, but some functions (such as +\code{car}) are so simple that they are always open-coded. Even when not +open-coded, a call to a standard function may be transformed into a different +function call (as in the last example) or compiled as \i{static call}. Static +function call uses a more efficient calling convention that forbids +redefinition. + +\hide{File:/afs/cs.cmu.edu/project/clisp/hackers/ram/docs/cmu-user/efficiency.ms} + + + +\hide{ -*- Dictionary: cmu-user -*- } +%%\node Advanced Compiler Use and Efficiency Hints, UNIX Interface, The Compiler, Top +\chapter{Advanced Compiler Use and Efficiency Hints} +\begin{center} +\b{By Robert MacLachlan} +\end{center} +\vspace{1 cm} +\label{advanced-compiler} + +\begin{comment} +* Advanced Compiler Introduction:: +* More About Types in Python:: +* Type Inference:: +* Source Optimization:: +* Tail Recursion:: +* Local Call:: +* Block Compilation:: +* Inline Expansion:: +* Byte Coded Compilation:: +* Object Representation:: +* Numbers:: +* General Efficiency Hints:: +* Efficiency Notes:: +* Profiling:: +\end{comment} + +%%\node Advanced Compiler Introduction, More About Types in Python, Advanced Compiler Use and Efficiency Hints, Advanced Compiler Use and Efficiency Hints +\section{Advanced Compiler Introduction} + +In \cmucl, as is any language on any computer, the path to efficient +code starts with good algorithms and sensible programming techniques, +but to avoid inefficiency pitfalls, you need to know some of this +implementation's quirks and features. This chapter is mostly a fairly +long and detailed overview of what optimizations \python{} does. +Although there are the usual negative suggestions of inefficient +features to avoid, the main emphasis is on describing the things that +programmers can count on being efficient. + +The optimizations described here can have the effect of speeding up +existing programs written in conventional styles, but the potential +for new programming styles that are clearer and less error-prone is at +least as significant. For this reason, several sections end with a +discussion of the implications of these optimizations for programming +style. + +\begin{comment} +* Types:: +* Optimization:: +* Function Call:: +* Representation of Objects:: +* Writing Efficient Code:: +\end{comment} + +%%\node Types, Optimization, Advanced Compiler Introduction, Advanced Compiler Introduction +\subsection{Types} + +Python's support for types is unusual in three major ways: +\begin{itemize} + +\item Precise type checking encourages the specific use of type + declarations as a form of run-time consistency checking. This + speeds development by localizing type errors and giving more + meaningful error messages. \xlref{precise-type-checks}. \python{} + produces completely safe code; optimized type checking maintains + reasonable efficiency on conventional hardware + (\pxlref{type-check-optimization}.) + +\item Comprehensive support for the \clisp{} type system makes complex + type specifiers useful. Using type specifiers such as \code{or} and + \code{member} has both efficiency and robustness advantages. + \xlref{advanced-type-stuff}. + +\item Type inference eliminates the need for some declarations, and + also aids compile-time detection of type errors. Given detailed + type declarations, type inference can often eliminate type checks + and enable more efficient object representations and code sequences. + Checking all types results in fewer type checks. See sections + \ref{type-inference} and \ref{non-descriptor}. +\end{itemize} + + +%%\node Optimization, Function Call, Types, Advanced Compiler Introduction +\subsection{Optimization} + +The main barrier to efficient Lisp programs is not that there is no +efficient way to code the program in Lisp, but that it is difficult to +arrive at that efficient coding. Common Lisp is a highly complex +language, and usually has many semantically equivalent reasonable'' +ways to code a given problem. It is desirable to make all of these +equivalent solutions have comparable efficiency so that programmers +don't have to waste time discovering the most efficient solution. + +Source level optimization increases the number of efficient ways to +solve a problem. This effect is much larger than the increase in the +efficiency of the best'' solution. Source level optimization +transforms the original program into a more efficient (but equivalent) +program. Although the optimizer isn't doing anything the programmer +couldn't have done, this high-level optimization is important because: +\begin{itemize} + +\item The programmer can code simply and directly, rather than + obfuscating code to please the compiler. + +\item When presented with a choice of similar coding alternatives, the + programmer can chose whichever happens to be most convenient, + instead of worrying about which is most efficient. +\end{itemize} + +Source level optimization eliminates the need for macros to optimize +their expansion, and also increases the effectiveness of inline +expansion. See sections \ref{source-optimization} and +\ref{inline-expansion}. + +Efficient support for a safer programming style is the biggest +advantage of source level optimization. Existing tuned programs +typically won't benefit much from source optimization, since their +source has already been optimized by hand. However, even tuned +programs tend to run faster under \python{} because: +\begin{itemize} + +\item Low level optimization and register allocation provides modest + speedups in any program. + +\item Block compilation and inline expansion can reduce function call + overhead, but may require some program restructuring. See sections + \ref{inline-expansion}, \ref{local-call} and + \ref{block-compilation}. + +\item Efficiency notes will point out important type declarations that + are often missed even in highly tuned programs. + \xlref{efficiency-notes}. + +\item Existing programs can be compiled safely without prohibitive + speed penalty, although they would be faster and safer with added + declarations. \xlref{type-check-optimization}. + +\item The context declaration mechanism allows both space and runtime + of large systems to be reduced without sacrificing robustness by + semi-automatically varying compilation policy without addition any + \code{optimize} declarations to the source. + \xlref{context-declarations}. + +\item Byte compilation can be used to dramatically reduce the size of + code that is not speed-critical. \xlref{byte-compile} +\end{itemize} + + +%%\node Function Call, Representation of Objects, Optimization, Advanced Compiler Introduction +\subsection{Function Call} + +The sort of symbolic programs generally written in \llisp{} often +favor recursion over iteration, or have inner loops so complex that +they involve multiple function calls. Such programs spend a larger +fraction of their time doing function calls than is the norm in other +languages; for this reason \llisp{} implementations strive to make the +general (or full) function call as inexpensive as possible. \python{} +goes beyond this by providing two good alternatives to full call: +\begin{itemize} + +\item Local call resolves function references at compile time, + allowing better calling sequences and optimization across function + calls. \xlref{local-call}. + +\item Inline expansion totally eliminates call overhead and allows + many context dependent optimizations. This provides a safe and + efficient implementation of operations with function semantics, + eliminating the need for error-prone macro definitions or manual + case analysis. Although most \clisp{} implementations support + inline expansion, it becomes a more powerful tool with \python{}'s + source level optimization. See sections \ref{source-optimization} + and \ref{inline-expansion}. +\end{itemize} + + +Generally, \python{} provides simple implementations for simple uses +of function call, rather than having only a single calling convention. +These features allow a more natural programming style: +\begin{itemize} + +\item Proper tail recursion. \xlref{tail-recursion} + +\item Relatively efficient closures. + +\item A \code{funcall} that is as efficient as normal named call. + +\item Calls to local functions such as from \code{labels} are + optimized: +\begin{itemize} + +\item Control transfer is a direct jump. + +\item The closure environment is passed in registers rather than heap + allocated. + +\item Keyword arguments and multiple values are implemented more + efficiently. +\end{itemize} + +\xlref{local-call}. +\end{itemize} + +%%\node Representation of Objects, Writing Efficient Code, Function Call, Advanced Compiler Introduction +\subsection{Representation of Objects} + +Sometimes traditional \llisp{} implementation techniques compare so +poorly to the techniques used in other languages that \llisp{} can +become an impractical language choice. Terrible inefficiencies appear +in number-crunching programs, since \llisp{} numeric operations often +involve number-consing and generic arithmetic. \python{} supports +efficient natural representations for numbers (and some other types), +and allows these efficient representations to be used in more +contexts. \python{} also provides good efficiency notes that warn +when a crucial declaration is missing. + +See section \ref{non-descriptor} for more about object representations and +numeric types. Also \pxlref{efficiency-notes} about efficiency notes. + +%%\node Writing Efficient Code, , Representation of Objects, Advanced Compiler Introduction +\subsection{Writing Efficient Code} +\label{efficiency-overview} + +Writing efficient code that works is a complex and prolonged process. +It is important not to get so involved in the pursuit of efficiency +that you lose sight of what the original problem demands. Remember +that: +\begin{itemize} + +\item The program should be correct\dash{}it doesn't matter how + quickly you get the wrong answer. + +\item Both the programmer and the user will make errors, so the + program must be robust\dash{}it must detect errors in a way that + allows easy correction. + +\item A small portion of the program will consume most of the + resources, with the bulk of the code being virtually irrelevant to + efficiency considerations. Even experienced programmers familiar + with the problem area cannot reliably predict where these hot + spots'' will be. +\end{itemize} + + + +The best way to get efficient code that is still worth using, is to separate +coding from tuning. During coding, you should: +\begin{itemize} + +\item Use a coding style that aids correctness and robustness without + being incompatible with efficiency. + +\item Choose appropriate data structures that allow efficient + algorithms and object representations + (\pxlref{object-representation}). Try to make interfaces abstract + enough so that you can change to a different representation if + profiling reveals a need. + +\item Whenever you make an assumption about a function argument or + global data structure, add consistency assertions, either with type + declarations or explicit uses of \code{assert}, \code{ecase}, etc. +\end{itemize} + +During tuning, you should: +\begin{itemize} + +\item Identify the hot spots in the program through profiling (section + \ref{profiling}.) + +\item Identify inefficient constructs in the hot spot with efficiency + notes, more profiling, or manual inspection of the source. See + sections \ref{general-efficiency} and \ref{efficiency-notes}. + +\item Add declarations and consider the application of optimizations. + See sections \ref{local-call}, \ref{inline-expansion} and + \ref{non-descriptor}. + +\item If all else fails, consider algorithm or data structure changes. + If you did a good job coding, changes will be easy to introduce. +\end{itemize} + + + +%% +%%\node More About Types in Python, Type Inference, Advanced Compiler Introduction, Advanced Compiler Use and Efficiency Hints +\section{More About Types in Python} +\label{advanced-type-stuff} +\cpsubindex{types}{in python} + +This section goes into more detail describing what types and declarations are +recognized by \python. The area where \python{} differs most radically from +previous \llisp{} compilers is in its support for types: +\begin{itemize} + +\item Precise type checking helps to find bugs at run time. + +\item Compile-time type checking helps to find bugs at compile time. + +\item Type inference minimizes the need for generic operations, and + also increases the efficiency of run time type checking and the + effectiveness of compile time type checking. + +\item Support for detailed types provides a wealth of opportunity for + operation-specific type inference and optimization. +\end{itemize} + + + +\begin{comment} +* More Types Meaningful:: +* Canonicalization:: +* Member Types:: +* Union Types:: +* The Empty Type:: +* Function Types:: +* The Values Declaration:: +* Structure Types:: +* The Freeze-Type Declaration:: +* Type Restrictions:: +* Type Style Recommendations:: +\end{comment} + +%%\node More Types Meaningful, Canonicalization, More About Types in Python, More About Types in Python +\subsection{More Types Meaningful} + +\clisp{} has a very powerful type system, but conventional \llisp{} +implementations typically only recognize the small set of types +special in that implementation. In these systems, there is an +unfortunate paradox: a declaration for a relatively general type like +\code{fixnum} will be recognized by the compiler, but a highly +specific declaration such as \code{\w{(integer 3 17)}} is totally +ignored. + +This is obviously a problem, since the user has to know how to specify +the type of an object in the way the compiler wants it. A very +minimal (but rarely satisfied) criterion for type system support is +that it be no worse to make a specific declaration than to make a +general one. \python{} goes beyond this by exploiting a number of +advantages obtained from detailed type information. + +Using more restrictive types in declarations allows the compiler to do +better type inference and more compile-time type checking. Also, when +type declarations are considered to be consistency assertions that +should be verified (conditional on policy), then complex types are +useful for making more detailed assertions. + +Python understands'' the list-style \code{or}, \code{member}, +\code{function}, array and number type specifiers. Understanding +means that: +\begin{itemize} + +\item If the type contains more information than is used in a + particular context, then the extra information is simply ignored, + rather than derailing type inference. + +\item In many contexts, the extra information from these type + specifier is used to good effect. In particular, type checking in + \code{Python} is \var{precise}, so these complex types can be used + in declarations to make interesting assertions about functions and + data structures (\pxlref{precise-type-checks}.) More specific + declarations also aid type inference and reduce the cost for type + checking. +\end{itemize} + +For related information, \pxlref{numeric-types} for numeric types, and +section \ref{array-types} for array types. + + +%%\node Canonicalization, Member Types, More Types Meaningful, More About Types in Python +\subsection{Canonicalization} +\cpsubindex{types}{equivalence} +\cindex{canonicalization of types} +\cindex{equivalence of types} + +When given a type specifier, \python{} will often rewrite it into a +different (but equivalent) type. This is the mechanism that \python{} +uses for detecting type equivalence. For example, in \python{}'s +canonical representation, these types are equivalent: +\begin{example} +(or list (member :end)) \myequiv (or cons (member nil :end)) +\end{example} +This has two implications for the user: +\begin{itemize} + +\item The standard symbol type specifiers for \code{atom}, + \code{null}, \code{fixnum}, etc., are in no way magical. The + \tindexed{null} type is actually defined to be \code{\w{(member + nil)}}, \tindexed{list} is \code{\w{(or cons null)}}, and + \tindexed{fixnum} is \code{\w{(signed-byte 30)}}. + +\item When the compiler prints out a type, it may not look like the + type specifier that originally appeared in the program. This is + generally not a problem, but it must be taken into consideration + when reading compiler error messages. +\end{itemize} + + +%%\node Member Types, Union Types, Canonicalization, More About Types in Python +\subsection{Member Types} +\cindex{member types} + +The \tindexed{member} type specifier can be used to represent +symbolic'' values, analogous to the enumerated types of Pascal. For +example, the second value of \code{find-symbol} has this type: +\begin{lisp} +(member :internal :external :inherited nil) +\end{lisp} +Member types are very useful for expressing consistency constraints on data +structures, for example: +\begin{lisp} +(defstruct ice-cream + (flavor :vanilla :type (member :vanilla :chocolate :strawberry))) +\end{lisp} +Member types are also useful in type inference, as the number of members can +sometimes be pared down to one, in which case the value is a known constant. + +%%\node Union Types, The Empty Type, Member Types, More About Types in Python +\subsection{Union Types} +\cindex{union (\code{or}) types} +\cindex{or (union) types} + +The \tindexed{or} (union) type specifier is understood, and is +meaningfully applied in many contexts. The use of \code{or} allows +assertions to be made about types in dynamically typed programs. For +example: +\begin{lisp} +(defstruct box + (next nil :type (or box null)) + (top :removed :type (or box-top (member :removed)))) +\end{lisp} +The type assertion on the \code{top} slot ensures that an error will be signaled +when there is an attempt to store an illegal value (such as \kwd{rmoved}.) +Although somewhat weak, these union type assertions provide a useful input into +type inference, allowing the cost of type checking to be reduced. For example, +this loop is safely compiled with no type checks: +\begin{lisp} +(defun find-box-with-top (box) + (declare (type (or box null) box)) + (do ((current box (box-next current))) + ((null current)) + (unless (eq (box-top current) :removed) + (return current)))) +\end{lisp} + +Union types are also useful in type inference for representing types that are +partially constrained. For example, the result of this expression: +\begin{lisp} +(if foo + (logior x y) + (list x y)) +\end{lisp} +can be expressed as \code{\w{(or integer cons)}}. + +%%\node The Empty Type, Function Types, Union Types, More About Types in Python +\subsection{The Empty Type} +\label{empty-type} +\cindex{NIL type} +\cpsubindex{empty type}{the} +\cpsubindex{errors}{result type of} + +The type \false{} is also called the empty type, since no object is of +type \false{}. The union of no types, \code{(or)}, is also empty. +\python{}'s interpretation of an expression whose type is \false{} is +that the expression never yields any value, but rather fails to +terminate, or is thrown out of. For example, the type of a call to +\code{error} or a use of \code{return} is \false{}. When the type of +an expression is empty, compile-time type warnings about its value are +suppressed; presumably somebody else is signaling an error. If a +function is declared to have return type \false{}, but does in fact +return, then (in safe compilation policies) a \code{NIL Function + returned}'' error will be signaled. See also the function +\funref{required-argument}. + +%%\node Function Types, The Values Declaration, The Empty Type, More About Types in Python +\subsection{Function Types} +\label{function-types} +\cpsubindex{function}{types} +\cpsubindex{types}{function} + +\findexed{function} types are understood in the restrictive sense, specifying: +\begin{itemize} + +\item The argument syntax that the function must be called with. This + is information about what argument counts are acceptable, and which + keyword arguments are recognized. In \python, warnings about + argument syntax are a consequence of function type checking. + +\item The types of the argument values that the caller must pass. If + the compiler can prove that some argument to a call is of a type + disallowed by the called function's type, then it will give a + compile-time type warning. In addition to being used for + compile-time type checking, these type assertions are also used as + output type assertions in code generation. For example, if + \code{foo} is declared to have a \code{fixnum} argument, then the + \code{1+} in \w{\code{(foo (1+ x))}} is compiled with knowledge that + the result must be a fixnum. + +\item The types the values that will be bound to argument variables in + the function's definition. Declaring a function's type with + \code{ftype} implicitly declares the types of the arguments in the + definition. \python{} checks for consistency between the definition + and the \code{ftype} declaration. Because of precise type checking, + an error will be signaled when a function is called with an + argument of the wrong type. + +\item The type of return value(s) that the caller can expect. This + information is a useful input to type inference. For example, if a + function is declared to return a \code{fixnum}, then when a call to + that function appears in an expression, the expression will be + compiled with knowledge that the call will return a \code{fixnum}. + +\item The type of return value(s) that the definition must return. + The result type in an \code{ftype} declaration is treated like an + implicit \code{the} wrapped around the body of the definition. If + the definition returns a value of the wrong type, an error will be + signaled. If the compiler can prove that the function returns the + wrong type, then it will give a compile-time warning. +\end{itemize} + +This is consistent with the new interpretation of function types and +the \code{ftype} declaration in the proposed X3J13 +function-type-argument-type-semantics'' cleanup. Note also, that if +you don't explicitly declare the type of a function using a global +\code{ftype} declaration, then \python{} will compute a function type +from the definition, providing a degree of inter-routine type +inference, \pxlref{function-type-inference}. + +%%\node The Values Declaration, Structure Types, Function Types, More About Types in Python +\subsection{The Values Declaration} +\cindex{values declaration} + +\cmucl{} supports the \code{values} declaration as an extension to +\clisp. The syntax is {\code{(values \var{type1} + \var{type2}$\ldots$\var{typen})}}. This declaration is +semantically equivalent to a \code{the} form wrapped around the body +of the special form in which the \code{values} declaration appears. +The advantage of \code{values} over \findexed{the} is purely +syntactic\dash{}it doesn't introduce more indentation. For example: +\begin{example} +(defun foo (x) + (declare (values single-float)) + (ecase x + (:this ...) + (:that ...) + (:the-other ...))) +\end{example} +is equivalent to: +\begin{example} +(defun foo (x) + (the single-float + (ecase x + (:this ...) + (:that ...) + (:the-other ...)))) +\end{example} +and +\begin{example} +(defun floor (number &optional (divisor 1)) + (declare (values integer real)) + ...) +\end{example} +is equivalent to: +\begin{example} +(defun floor (number &optional (divisor 1)) + (the (values integer real) + ...)) +\end{example} +In addition to being recognized by \code{lambda} (and hence by +\code{defun}), the \code{values} declaration is recognized by all the +other special forms with bodies and declarations: \code{let}, +\code{let*}, \code{labels} and \code{flet}. Macros with declarations +usually splice the declarations into one of the above forms, so they +will accept this declaration too, but the exact effect of a +\code{values} declaration will depend on the macro. + +If you declare the types of all arguments to a function, and also +declare the return value types with \code{values}, you have described +the type of the function. \python{} will use this argument and result +type information to derive a function type that will then be applied +to calls of the function (\pxlref{function-types}.) This provides a +way to declare the types of functions that is much less syntactically +awkward than using the \code{ftype} declaration with a \code{function} +type specifier. + +Although the \code{values} declaration is non-standard, it is +relatively harmless to use it in otherwise portable code, since any +warning in non-CMU implementations can be suppressed with the standard +\code{declaration} proclamation. + +%%\node Structure Types, The Freeze-Type Declaration, The Values Declaration, More About Types in Python +\subsection{Structure Types} +\label{structure-types} +\cindex{structure types} +\cindex{defstruct types} +\cpsubindex{types}{structure} + +Because of precise type checking, structure types are much better supported by +Python than by conventional compilers: +\begin{itemize} + +\item The structure argument to structure accessors is precisely + checked\dash{}if you call \code{foo-a} on a \code{bar}, an error + will be signaled. + +\item The types of slot values are precisely checked\dash{}if you pass + the wrong type argument to a constructor or a slot setter, then an + error will be signaled. +\end{itemize} +This error checking is tremendously useful for detecting bugs in +programs that manipulate complex data structures. + +An additional advantage of checking structure types and enforcing slot +types is that the compiler can safely believe slot type declarations. +\python{} effectively moves the type checking from the slot access to +the slot setter or constructor call. This is more efficient since +caller of the setter or constructor often knows the type of the value, +entirely eliminating the need to check the value's type. Consider +this example: +\begin{lisp} +(defstruct coordinate + (x nil :type single-float) + (y nil :type single-float)) + +(defun make-it () + (make-coordinate :x 1.0 :y 1.0)) + +(defun use-it (it) + (declare (type coordinate it)) + (sqrt (expt (coordinate-x it) 2) (expt (coordinate-y it) 2))) +\end{lisp} +\code{make-it} and \code{use-it} are compiled with no checking on the +types of the float slots, yet \code{use-it} can use +\code{single-float} arithmetic with perfect safety. Note that +\code{make-coordinate} must still check the values of \code{x} and +\code{y} unless the call is block compiled or inline expanded +(\pxlref{local-call}.) But even without this advantage, it is almost +always more efficient to check slot values on structure +initialization, since slots are usually written once and read many +times. + +%%\node The Freeze-Type Declaration, Type Restrictions, Structure Types, More About Types in Python +\subsection{The Freeze-Type Declaration} +\cindex{freeze-type declaration} +\label{freeze-type} + +The \code{extensions:freeze-type} declaration is a CMU extension that +enables more efficient compilation of user-defined types by asserting +that the definition is not going to change. This declaration may only +be used globally (with \code{declaim} or \code{proclaim}). Currently +\code{freeze-type} only affects structure type testing done by +\code{typep}, \code{typecase}, etc. Here is an example: +\begin{lisp} +(declaim (freeze-type foo bar)) +\end{lisp} +This asserts that the types \code{foo} and \code{bar} and their +subtypes are not going to change. This allows more efficient type +testing, since the compiler can open-code a test for all possible +subtypes, rather than having to examine the type hierarchy at +run-time. + +%%\node Type Restrictions, Type Style Recommendations, The Freeze-Type Declaration, More About Types in Python +\subsection{Type Restrictions} +\cpsubindex{types}{restrictions on} + +Avoid use of the \code{and}, \code{not} and \code{satisfies} types in +declarations, since type inference has problems with them. When these +types do appear in a declaration, they are still checked precisely, +but the type information is of limited use to the compiler. +\code{and} types are effective as long as the intersection can be +canonicalized to a type that doesn't use \code{and}. For example: +\begin{example} +(and fixnum unsigned-byte) +\end{example} +is fine, since it is the same as: +\begin{example} +(integer 0 \var{most-positive-fixnum}) +\end{example} +but this type: +\begin{example} +(and symbol (not (member :end))) +\end{example} +will not be fully understood by type interference since the \code{and} +can't be removed by canonicalization. + +Using any of these type specifiers in a type test with \code{typep} or +\code{typecase} is fine, since as tests, these types can be translated +into the \code{and} macro, the \code{not} function or a call to the +satisfies predicate. + +%%\node Type Style Recommendations, , Type Restrictions, More About Types in Python +\subsection{Type Style Recommendations} +\cindex{style recommendations} + +Python provides good support for some currently unconventional ways of +using the \clisp{} type system. With \python, it is desirable to make +declarations as precise as possible, but type inference also makes +some declarations unnecessary. Here are some general guidelines for +maximum robustness and efficiency: +\begin{itemize} + +\item Declare the types of all function arguments and structure slots + as precisely as possible (while avoiding \code{not}, \code{and} and + \code{satisfies}). Put these declarations in during initial coding + so that type assertions can find bugs for you during debugging. + +\item Use the \tindexed{member} type specifier where there are a small + number of possible symbol values, for example: \w{\code{(member :red + :blue :green)}}. + +\item Use the \tindexed{or} type specifier in situations where the + type is not certain, but there are only a few possibilities, for + example: \w{\code{(or list vector)}}. + +\item Declare integer types with the tightest bounds that you can, + such as \code{\w{(integer 3 7)}}. + +\item Define \findexed{deftype} or \findexed{defstruct} types before + they are used. Definition after use is legal (producing no + undefined type'' warnings), but type tests and structure + operations will be compiled much less efficiently. + +\item Use the \code{extensions:freeze-type} declaration to speed up + type testing for structure types which won't have new subtypes added + later. \xlref{freeze-type} + +\item In addition to declaring the array element type and simpleness, + also declare the dimensions if they are fixed, for example: + \begin{example} + (simple-array single-float (1024 1024)) + \end{example} + This bounds information allows array indexing for multi-dimensional + arrays to be compiled much more efficiently, and may also allow + array bounds checking to be done at compile time. + \xlref{array-types}. + +\item Avoid use of the \findexed{the} declaration within expressions. + Not only does it clutter the code, but it is also almost worthless + under safe policies. If the need for an output type assertion is + revealed by efficiency notes during tuning, then you can consider + \code{the}, but it is preferable to constrain the argument types + more, allowing the compiler to prove the desired result type. + +\item Don't bother declaring the type of \findexed{let} or other + non-argument variables unless the type is non-obvious. If you + declare function return types and structure slot types, then the + type of a variable is often obvious both to the programmer and to + the compiler. An important case where the type isn't obvious, and a + declaration is appropriate, is when the value for a variable is + pulled out of untyped structure (e.g., the result of \code{car}), or + comes from some weakly typed function, such as \code{read}. + +\item Declarations are sometimes necessary for integer loop variables, + since the compiler can't always prove that the value is of a good + integer type. These declarations are best added during tuning, when + an efficiency note indicates the need. +\end{itemize} + + +%% +%%\node Type Inference, Source Optimization, More About Types in Python, Advanced Compiler Use and Efficiency Hints +\section{Type Inference} +\label{type-inference} +\cindex{type inference} +\cindex{inference of types} +\cindex{derivation of types} + +Type inference is the process by which the compiler tries to figure +out the types of expressions and variables, given an inevitable lack +of complete type information. Although \python{} does much more type +inference than most \llisp{} compilers, remember that the more precise +and comprehensive type declarations are, the more type inference will +be able to do. + +\begin{comment} +* Variable Type Inference:: +* Local Function Type Inference:: +* Global Function Type Inference:: +* Operation Specific Type Inference:: +* Dynamic Type Inference:: +* Type Check Optimization:: +\end{comment} + +%%\node Variable Type Inference, Local Function Type Inference, Type Inference, Type Inference +\subsection{Variable Type Inference} +\label{variable-type-inference} + +The type of a variable is the union of the types of all the +definitions. In the degenerate case of a let, the type of the +variable is the type of the initial value. This inferred type is +intersected with any declared type, and is then propagated to all the +variable's references. The types of \findexed{multiple-value-bind} +variables are similarly inferred from the types of the individual +values of the values form. + +If multiple type declarations apply to a single variable, then all the +declarations must be correct; it is as though all the types were intersected +producing a single \tindexed{and} type specifier. In this example: +\begin{example} +(defmacro my-dotimes ((var count) &body body) + (do ((,var 0 (1+ ,var))) + ((>= ,var ,count)) + (declare (type (integer 0 *) ,var)) + ,@body)) + +(my-dotimes (i ...) + (declare (fixnum i)) + ...) +\end{example} +the two declarations for \code{i} are intersected, so \code{i} is +known to be a non-negative fixnum. + +In practice, this type inference is limited to lets and local +functions, since the compiler can't analyze all the calls to a global +function. But type inference works well enough on local variables so +that it is often unnecessary to declare the type of local variables. +This is especially likely when function result types and structure +slot types are declared. The main areas where type inference breaks +down are: +\begin{itemize} + +\item When the initial value of a variable is a untyped expression, + such as \code{\w{(car x)}}, and + +\item When the type of one of the variable's definitions is a function + of the variable's current value, as in: \code{(setq x (1+ x))} +\end{itemize} + + +%%\node Local Function Type Inference, Global Function Type Inference, Variable Type Inference, Type Inference +\subsection{Local Function Type Inference} +\cpsubindex{local call}{type inference} + +The types of arguments to local functions are inferred in the same was +as any other local variable; the type is the union of the argument +types across all the calls to the function, intersected with the +declared type. If there are any assignments to the argument +variables, the type of the assigned value is unioned in as well. + +The result type of a local function is computed in a special way that +takes tail recursion (\pxlref{tail-recursion}) into consideration. +The result type is the union of all possible return values that aren't +tail-recursive calls. For example, \python{} will infer that the +result type of this function is \code{integer}: +\begin{lisp} +(defun ! (n res) + (declare (integer n res)) + (if (zerop n) + res + (! (1- n) (* n res)))) +\end{lisp} +Although this is a rather obvious result, it becomes somewhat less +trivial in the presence of mutual tail recursion of multiple +functions. Local function result type inference interacts with the +mechanisms for ensuring proper tail recursion mentioned in section +\ref{local-call-return}. + +%%\node Global Function Type Inference, Operation Specific Type Inference, Local Function Type Inference, Type Inference +\subsection{Global Function Type Inference} +\label{function-type-inference} +\cpsubindex{function}{type inference} + +As described in section \ref{function-types}, a global function type +(\tindexed{ftype}) declaration places implicit type assertions on the +call arguments, and also guarantees the type of the return value. So +wherever a call to a declared function appears, there is no doubt as +to the types of the arguments and return value. Furthermore, +\python{} will infer a function type from the function's definition if +there is no \code{ftype} declaration. Any type declarations on the +argument variables are used as the argument types in the derived +function type, and the compiler's best guess for the result type of +the function is used as the result type in the derived function type. + +This method of deriving function types from the definition implicitly assumes +that functions won't be redefined at run-time. Consider this example: +\begin{lisp} +(defun foo-p (x) + (let ((res (and (consp x) (eq (car x) 'foo)))) + (format t "It is ~:[not ~;~]foo." res))) + +(defun frob (it) + (if (foo-p it) + (setf (cadr it) 'yow!) + (1+ it))) +\end{lisp} + +Presumably, the programmer really meant to return \code{res} from +\code{foo-p}, but he seems to have forgotten. When he tries to call +do \code{\w{(frob (list 'foo nil))}}, \code{frob} will flame out when +it tries to add to a \code{cons}. Realizing his error, he fixes +\code{foo-p} and recompiles it. But when he retries his test case, he +is baffled because the error is still there. What happened in this +example is that \python{} proved that the result of \code{foo-p} is +\code{null}, and then proceeded to optimize away the \code{setf} in +\code{frob}. + +Fortunately, in this example, the error is detected at compile time +due to notes about unreachable code (\pxlref{dead-code-notes}.) +Still, some users may not want to worry about this sort of problem +during incremental development, so there is a variable to control +deriving function types. + +\begin{defvar}{extensions:}{derive-function-types} + + If true (the default), argument and result type information derived + from compilation of \code{defun}s is used when compiling calls to + that function. If false, only information from \code{ftype} + proclamations will be used. +\end{defvar} + +%%\node Operation Specific Type Inference, Dynamic Type Inference, Global Function Type Inference, Type Inference +\subsection{Operation Specific Type Inference} +\label{operation-type-inference} +\cindex{operation specific type inference} +\cindex{arithmetic type inference} +\cpsubindex{numeric}{type inference} + +Many of the standard \clisp{} functions have special type inference +procedures that determine the result type as a function of the +argument types. For example, the result type of \code{aref} is the +array element type. Here are some other examples of type inferences: +\begin{lisp} +(logand x #xFF) \result{} (unsigned-byte 8) + +(+ (the (integer 0 12) x) (the (integer 0 1) y)) \result{} (integer 0 13) + +(ash (the (unsigned-byte 16) x) -8) \result{} (unsigned-byte 8) +\end{lisp} + +%%\node Dynamic Type Inference, Type Check Optimization, Operation Specific Type Inference, Type Inference +\subsection{Dynamic Type Inference} +\label{constraint-propagation} +\cindex{dynamic type inference} +\cindex{conditional type inference} +\cpsubindex{type inference}{dynamic} + +Python uses flow analysis to infer types in dynamically typed +programs. For example: +\begin{example} +(ecase x + (list (length x)) + ...) +\end{example} +Here, the compiler knows the argument to \code{length} is a list, +because the call to \code{length} is only done when \code{x} is a +list. The most significant efficiency effect of inference from +assertions is usually in type check optimization. + + +Dynamic type inference has two inputs: explicit conditionals and +implicit or explicit type assertions. Flow analysis propagates these +constraints on variable type to any code that can be executed only +after passing though the constraint. Explicit type constraints come +from \findexed{if}s where the test is either a lexical variable or a +function of lexical variables and constants, where the function is +either a type predicate, a numeric comparison or \code{eq}. + +If there is an \code{eq} (or \code{eql}) test, then the compiler will +actually substitute one argument for the other in the true branch. +For example: +\begin{lisp} +(when (eq x :yow!) (return x)) +\end{lisp} +becomes: +\begin{lisp} +(when (eq x :yow!) (return :yow!)) +\end{lisp} +This substitution is done when one argument is a constant, or one +argument has better type information than the other. This +transformation reveals opportunities for constant folding or +type-specific optimizations. If the test is against a constant, then +the compiler can prove that the variable is not that constant value in +the false branch, or \w{\code{(not (member :yow!))}} in the example +above. This can eliminate redundant tests, for example: +\begin{example} +(if (eq x nil) + ... + (if x a b)) +\end{example} +is transformed to this: +\begin{example} +(if (eq x nil) + ... + a) +\end{example} +Variables appearing as \code{if} tests are interpreted as +\code{\w{(not (eq \var{var} nil))}} tests. The compiler also converts +\code{=} into \code{eql} where possible. It is difficult to do +inference directly on \code{=} since it does implicit coercions. + +When there is an explicit \code{$<$} or \code{$>$} test on +\begin{changebar} + numeric +\end{changebar} +variables, the compiler makes inferences about the ranges the +variables can assume in the true and false branches. This is mainly +useful when it proves that the values are small enough in magnitude to +allow open-coding of arithmetic operations. For example, in many uses +of \code{dotimes} with a \code{fixnum} repeat count, the compiler +proves that fixnum arithmetic can be used. + +Implicit type assertions are quite common, especially if you declare +function argument types. Dynamic inference from implicit type +assertions sometimes helps to disambiguate programs to a useful +degree, but is most noticeable when it detects a dynamic type error. +For example: +\begin{lisp} +(defun foo (x) + (+ (car x) x)) +\end{lisp} +results in this warning: +\begin{example} +In: DEFUN FOO + (+ (CAR X) X) +==> + X +Warning: Result is a LIST, not a NUMBER. +\end{example} + +Note that \llisp{}'s dynamic type checking semantics make dynamic type +inference useful even in programs that aren't really dynamically +typed, for example: +\begin{lisp} +(+ (car x) (length x)) +\end{lisp} +Here, \code{x} presumably always holds a list, but in the absence of a +declaration the compiler cannot assume \code{x} is a list simply +because list-specific operations are sometimes done on it. The +compiler must consider the program to be dynamically typed until it +proves otherwise. Dynamic type inference proves that the argument to +\code{length} is always a list because the call to \code{length} is +only done after the list-specific \code{car} operation. + + +%%\node Type Check Optimization, , Dynamic Type Inference, Type Inference +\subsection{Type Check Optimization} +\label{type-check-optimization} +\cpsubindex{type checking}{optimization} +\cpsubindex{optimization}{type check} + +Python backs up its support for precise type checking by minimizing +the cost of run-time type checking. This is done both through type +inference and though optimizations of type checking itself. + +Type inference often allows the compiler to prove that a value is of +the correct type, and thus no type check is necessary. For example: +\begin{lisp} +(defstruct foo a b c) +(defstruct link + (foo (required-argument) :type foo) + (next nil :type (or link null))) + +(foo-a (link-foo x)) +\end{lisp} +Here, there is no need to check that the result of \code{link-foo} is +a \code{foo}, since it always is. Even when some type checks are +necessary, type inference can often reduce the number: +\begin{example} +(defun test (x) + (let ((a (foo-a x)) + (b (foo-b x)) + (c (foo-c x))) + ...)) +\end{example} +In this example, only one \w{\code{(foo-p x)}} check is needed. This +applies to a lesser degree in list operations, such as: +\begin{lisp} +(if (eql (car x) 3) (cdr x) y) +\end{lisp} +Here, we only have to check that \code{x} is a list once. + +Since \python{} recognizes explicit type tests, code that explicitly +protects itself against type errors has little introduced overhead due +to implicit type checking. For example, this loop compiles with no +implicit checks checks for \code{car} and \code{cdr}: +\begin{lisp} +(defun memq (e l) + (do ((current l (cdr current))) + ((atom current) nil) + (when (eq (car current) e) (return current)))) +\end{lisp} + +\cindex{complemented type checks} +Python reduces the cost of checks that must be done through an +optimization called \var{complementing}. A complemented check for +\var{type} is simply a check that the value is not of the type +\w{\code{(not \var{type})}}. This is only interesting when something +is known about the actual type, in which case we can test for the +complement of \w{\code{(and \var{known-type} (not \var{type}))}}, or +the difference between the known type and the assertion. An example: +\begin{lisp} +(link-foo (link-next x)) +\end{lisp} +Here, we change the type check for \code{link-foo} from a test for +\code{foo} to a test for: +\begin{lisp} +(not (and (or foo null) (not foo))) +\end{lisp} +or more simply \w{\code{(not null)}}. This is probably the most +important use of complementing, since the situation is fairly common, +and a \code{null} test is much cheaper than a structure type test. + +Here is a more complicated example that illustrates the combination of +complementing with dynamic type inference: +\begin{lisp} +(defun find-a (a x) + (declare (type (or link null) x)) + (do ((current x (link-next current))) + ((null current) nil) + (let ((foo (link-foo current))) + (when (eq (foo-a foo) a) (return foo))))) +\end{lisp} +This loop can be compiled with no type checks. The \code{link} test +for \code{link-foo} and \code{link-next} is complemented to +\w{\code{(not null)}}, and then deleted because of the explicit +\code{null} test. As before, no check is necessary for \code{foo-a}, +since the \code{link-foo} is always a \code{foo}. This sort of +situation shows how precise type checking combined with precise +declarations can actually result in reduced type checking. + +%% +%%\node Source Optimization, Tail Recursion, Type Inference, Advanced Compiler Use and Efficiency Hints +\section{Source Optimization} +\label{source-optimization} +\cindex{optimization} + +This section describes source-level transformations that \python{} does on +programs in an attempt to make them more efficient. Although source-level +optimizations can make existing programs more efficient, the biggest advantage +of this sort of optimization is that it makes it easier to write efficient +programs. If a clean, straightforward implementation is can be transformed +into an efficient one, then there is no need for tricky and dangerous hand +optimization. + +\begin{comment} +* Let Optimization:: +* Constant Folding:: +* Unused Expression Elimination:: +* Control Optimization:: +* Unreachable Code Deletion:: +* Multiple Values Optimization:: +* Source to Source Transformation:: +* Style Recommendations:: +\end{comment} + +%%\node Let Optimization, Constant Folding, Source Optimization, Source Optimization +\subsection{Let Optimization} +\label{let-optimization} + +\cindex{let optimization} \cpsubindex{optimization}{let} + +The primary optimization of let variables is to delete them when they +are unnecessary. Whenever the value of a let variable is a constant, +a constant variable or a constant (local or non-notinline) function, +the variable is deleted, and references to the variable are replaced +with references to the constant expression. This is useful primarily +in the expansion of macros or inline functions, where argument values +are often constant in any given call, but are in general non-constant +expressions that must be bound to preserve order of evaluation. Let +variable optimization eliminates the need for macros to carefully +avoid spurious bindings, and also makes inline functions just as +efficient as macros. + +A particularly interesting class of constant is a local function. +Substituting for lexical variables that are bound to a function can +substantially improve the efficiency of functional programming styles, +for example: +\begin{lisp} +(let ((a #'(lambda (x) (zow x)))) + (funcall a 3)) +\end{lisp} +effectively transforms to: +\begin{lisp} +(zow 3) +\end{lisp} +This transformation is done even when the function is a closure, as in: +\begin{lisp} +(let ((a (let ((y (zug))) + #'(lambda (x) (zow x y))))) + (funcall a 3)) +\end{lisp} +becoming: +\begin{lisp} +(zow 3 (zug)) +\end{lisp} + +A constant variable is a lexical variable that is never assigned to, +always keeping its initial value. Whenever possible, avoid setting +lexical variables\dash{}instead bind a new variable to the new value. +Except for loop variables, it is almost always possible to avoid +setting lexical variables. This form: +\begin{example} +(let ((x (f x))) + ...) +\end{example} +is \var{more} efficient than this form: +\begin{example} +(setq x (f x)) +... +\end{example} +Setting variables makes the program more difficult to understand, both +to the compiler and to the programmer. \python{} compiles assignments +at least as efficiently as any other \llisp{} compiler, but most let +optimizations are only done on constant variables. + +Constant variables with only a single use are also optimized away, +even when the initial value is not constant.\footnote{The source + transformation in this example doesn't represent the preservation of + evaluation order implicit in the compiler's internal representation. + Where necessary, the back end will reintroduce temporaries to + preserve the semantics.} For example, this expansion of +\code{incf}: +\begin{lisp} +(let ((#:g3 (+ x 1))) + (setq x #:G3)) +\end{lisp} +becomes: +\begin{lisp} +(setq x (+ x 1)) +\end{lisp} +The type semantics of this transformation are more important than the +elimination of the variable itself. Consider what happens when +\code{x} is declared to be a \code{fixnum}; after the transformation, +the compiler can compile the addition knowing that the result is a +\code{fixnum}, whereas before the transformation the addition would +have to allow for fixnum overflow. + +Another variable optimization deletes any variable that is never read. +This causes the initial value and any assigned values to be unused, +allowing those expressions to be deleted if they have no side-effects. + +Note that a let is actually a degenerate case of local call +(\pxlref{let-calls}), and that let optimization can be done on calls +that weren't created by a let. Also, local call allows an applicative +style of iteration that is totally assignment free. + +%%\node Constant Folding, Unused Expression Elimination, Let Optimization, Source Optimization +\subsection{Constant Folding} +\cindex{constant folding} +\cpsubindex{folding}{constant} + +Constant folding is an optimization that replaces a call of constant +arguments with the constant result of that call. Constant folding is +done on all standard functions for which it is legal. Inline +expansion allows folding of any constant parts of the definition, and +can be done even on functions that have side-effects. + +It is convenient to rely on constant folding when programming, as in this +example: +\begin{example} +(defconstant limit 42) + +(defun foo () + (... (1- limit) ...)) +\end{example} +Constant folding is also helpful when writing macros or inline +functions, since it usually eliminates the need to write a macro that +special-cases constant arguments. + +\cindex{constant-function declaration} Constant folding of a user +defined function is enabled by the \code{extensions:constant-function} +proclamation. In this example: +\begin{example} +(declaim (ext:constant-function myfun)) +(defun myexp (x y) + (declare (single-float x y)) + (exp (* (log x) y))) + + ... (myexp 3.0 1.3) ... +\end{example} +The call to \code{myexp} is constant-folded to \code{4.1711674}. + + +%%\node Unused Expression Elimination, Control Optimization, Constant Folding, Source Optimization +\subsection{Unused Expression Elimination} +\cindex{unused expression elimination} +\cindex{dead code elimination} + +If the value of any expression is not used, and the expression has no +side-effects, then it is deleted. As with constant folding, this +optimization applies most often when cleaning up after inline +expansion and other optimizations. Any function declared an +\code{extensions:constant-function} is also subject to unused +expression elimination. + +Note that \python{} will eliminate parts of unused expressions known +to be side-effect free, even if there are other unknown parts. For +example: +\begin{lisp} +(let ((a (list (foo) (bar)))) + (if t + (zow) + (raz a))) +\end{lisp} +becomes: +\begin{lisp} +(progn (foo) (bar)) +(zow) +\end{lisp} + + +%%\node Control Optimization, Unreachable Code Deletion, Unused Expression Elimination, Source Optimization +\subsection{Control Optimization} +\cindex{control optimization} +\cpsubindex{optimization}{control} + +The most important optimization of control is recognizing when an +\findexed{if} test is known at compile time, then deleting the +\code{if}, the test expression, and the unreachable branch of the +\code{if}. This can be considered a special case of constant folding, +although the test doesn't have to be truly constant as long as it is +definitely not \false. Note also, that type inference propagates the +result of an \code{if} test to the true and false branches, +\pxlref{constraint-propagation}. + +A related \code{if} optimization is this transformation:\footnote{Note + that the code for \code{x} and \code{y} isn't actually replicated.} +\begin{lisp} +(if (if a b c) x y) +\end{lisp} +into: +\begin{lisp} +(if a + (if b x y) + (if c x y)) +\end{lisp} +The opportunity for this sort of optimization usually results from a +conditional macro. For example: +\begin{lisp} +(if (not a) x y) +\end{lisp} +is actually implemented as this: +\begin{lisp} +(if (if a nil t) x y) +\end{lisp} +which is transformed to this: +\begin{lisp} +(if a + (if nil x y) + (if t x y)) +\end{lisp} +which is then optimized to this: +\begin{lisp} +(if a y x) +\end{lisp} +Note that due to \python{}'s internal representations, the +\code{if}\dash{}\code{if} situation will be recognized even if other +forms are wrapped around the inner \code{if}, like: +\begin{example} +(if (let ((g ...)) + (loop + ... + (return (not g)) + ...)) + x y) +\end{example} + +In \python, all the \clisp{} macros really are macros, written in +terms of \code{if}, \code{block} and \code{tagbody}, so user-defined +control macros can be just as efficient as the standard ones. +\python{} emits basic blocks using a heuristic that minimizes the +number of unconditional branches. The code in a \code{tagbody} will +not be emitted in the order it appeared in the source, so there is no +point in arranging the code to make control drop through to the +target. + +%%\node Unreachable Code Deletion, Multiple Values Optimization, Control Optimization, Source Optimization +\subsection{Unreachable Code Deletion} +\label{dead-code-notes} +\cindex{unreachable code deletion} +\cindex{dead code elimination} + +Python will delete code whenever it can prove that the code can never be +executed. Code becomes unreachable when: +\begin{itemize} + +\item +An \code{if} is optimized away, or + +\item +There is an explicit unconditional control transfer such as \code{go} or +\code{return-from}, or + +\item +The last reference to a local function is deleted (or there never was any +reference.) +\end{itemize} + + +When code that appeared in the original source is deleted, the compiler prints +a note to indicate a possible problem (or at least unnecessary code.) For +example: +\begin{lisp} +(defun foo () + (if t + (write-line "True.") + (write-line "False."))) +\end{lisp} +will result in this note: +\begin{example} +In: DEFUN FOO + (WRITE-LINE "False.") +Note: Deleting unreachable code. +\end{example} + +It is important to pay attention to unreachable code notes, since they often +indicate a subtle type error. For example: +\begin{example} +(defstruct foo a b) + +(defun lose (x) + (let ((a (foo-a x)) + (b (if x (foo-b x) :none))) + ...)) +\end{example} +results in this note: +\begin{example} +In: DEFUN LOSE + (IF X (FOO-B X) :NONE) +==> + :NONE +Note: Deleting unreachable code. +\end{example} +The \kwd{none} is unreachable, because type inference knows that the argument +to \code{foo-a} must be a \code{foo}, and thus can't be \false. Presumably the +programmer forgot that \code{x} could be \false{} when he wrote the binding for +\code{a}. + +Here is an example with an incorrect declaration: +\begin{lisp} +(defun count-a (string) + (do ((pos 0 (position #\back{a} string :start (1+ pos))) + (count 0 (1+ count))) + ((null pos) count) + (declare (fixnum pos)))) +\end{lisp} +This time our note is: +\begin{example} +In: DEFUN COUNT-A + (DO ((POS 0 #) (COUNT 0 #)) + ((NULL POS) COUNT) + (DECLARE (FIXNUM POS))) +--> BLOCK LET TAGBODY RETURN-FROM PROGN +==> + COUNT +Note: Deleting unreachable code. +\end{example} +The problem here is that \code{pos} can never be null since it is declared a +\code{fixnum}. + +It takes some experience with unreachable code notes to be able to +tell what they are trying to say. In non-obvious cases, the best +thing to do is to call the function in a way that should cause the +unreachable code to be executed. Either you will get a type error, or +you will find that there truly is no way for the code to be executed. + +Not all unreachable code results in a note: +\begin{itemize} + +\item A note is only given when the unreachable code textually appears + in the original source. This prevents spurious notes due to the + optimization of macros and inline functions, but sometimes also + foregoes a note that would have been useful. + +\item Since accurate source information is not available for non-list + forms, there is an element of heuristic in determining whether or + not to give a note about an atom. Spurious notes may be given when + a macro or inline function defines a variable that is also present + in the calling function. Notes about \false{} and \true{} are never + given, since it is too easy to confuse these constants in expanded + code with ones in the original source. + +\item Notes are only given about code unreachable due to control flow. + There is no note when an expression is deleted because its value is + unused, since this is a common consequence of other optimizations. +\end{itemize} + + +Somewhat spurious unreachable code notes can also result when a macro +inserts multiple copies of its arguments in different contexts, for +example: +\begin{lisp} +(defmacro t-and-f (var form) + (if ,var ,form ,form)) + +(defun foo (x) + (t-and-f x (if x "True." "False."))) +\end{lisp} +results in these notes: +\begin{example} +In: DEFUN FOO + (IF X "True." "False.") +==> + "False." +Note: Deleting unreachable code. + +==> + "True." +Note: Deleting unreachable code. +\end{example} +It seems like it has deleted both branches of the \code{if}, but it has really +deleted one branch in one copy, and the other branch in the other copy. Note +that these messages are only spurious in not satisfying the intent of the rule +that notes are only given when the deleted code appears in the original source; +there is always \var{some} code being deleted when a unreachable code note is +printed. + + +%%\node Multiple Values Optimization, Source to Source Transformation, Unreachable Code Deletion, Source Optimization +\subsection{Multiple Values Optimization} +\cindex{multiple value optimization} +\cpsubindex{optimization}{multiple value} + +Within a function, \python{} implements uses of multiple values +particularly efficiently. Multiple values can be kept in arbitrary +registers, so using multiple values doesn't imply stack manipulation +and representation conversion. For example, this code: +\begin{example} +(let ((a (if x (foo x) u)) + (b (if x (bar x) v))) + ...) +\end{example} +is actually more efficient written this way: +\begin{example} +(multiple-value-bind + (a b) + (if x + (values (foo x) (bar x)) + (values u v)) + ...) +\end{example} + +Also, \pxlref{local-call-return} for information on how local call +provides efficient support for multiple function return values. + + +%%\node Source to Source Transformation, Style Recommendations, Multiple Values Optimization, Source Optimization +\subsection{Source to Source Transformation} +\cindex{source-to-source transformation} +\cpsubindex{transformation}{source-to-source} + +The compiler implements a number of operation-specific optimizations as +source-to-source transformations. You will often see unfamiliar code in error +messages, for example: +\begin{lisp} +(defun my-zerop () (zerop x)) +\end{lisp} +gives this warning: +\begin{example} +In: DEFUN MY-ZEROP + (ZEROP X) +==> + (= X 0) +Warning: Undefined variable: X +\end{example} +The original \code{zerop} has been transformed into a call to +\code{=}. This transformation is indicated with the same \code{==$>$} +used to mark macro and function inline expansion. Although it can be +confusing, display of the transformed source is important, since +warnings are given with respect to the transformed source. This a +more obscure example: +\begin{lisp} +(defun foo (x) (logand 1 x)) +\end{lisp} +gives this efficiency note: +\begin{example} +In: DEFUN FOO + (LOGAND 1 X) +==> + (LOGAND C::Y C::X) +Note: Forced to do static-function Two-arg-and (cost 53). + Unable to do inline fixnum arithmetic (cost 1) because: + The first argument is a INTEGER, not a FIXNUM. + etc. +\end{example} +Here, the compiler commuted the call to \code{logand}, introducing +temporaries. The note complains that the \var{first} argument is not +a \code{fixnum}, when in the original call, it was the second +argument. To make things more confusing, the compiler introduced +temporaries called \code{c::x} and \code{c::y} that are bound to +\code{y} and \code{1}, respectively. + +You will also notice source-to-source optimizations when efficiency +notes are enabled (\pxlref{efficiency-notes}.) When the compiler is +unable to do a transformation that might be possible if there was more +information, then an efficiency note is printed. For example, +\code{my-zerop} above will also give this efficiency note: +\begin{example} +In: DEFUN FOO + (ZEROP X) +==> + (= X 0) +Note: Unable to optimize because: + Operands might not be the same type, so can't open code. +\end{example} + +%%\node Style Recommendations, , Source to Source Transformation, Source Optimization +\subsection{Style Recommendations} +\cindex{style recommendations} + +Source level optimization makes possible a clearer and more relaxed programming +style: +\begin{itemize} + +\item Don't use macros purely to avoid function call. If you want an + inline function, write it as a function and declare it inline. It's + clearer, less error-prone, and works just as well. + +\item Don't write macros that try to optimize'' their expansion in + trivial ways such as avoiding binding variables for simple + expressions. The compiler does these optimizations too, and is less + likely to make a mistake. + +\item Make use of local functions (i.e., \code{labels} or \code{flet}) + and tail-recursion in places where it is clearer. Local function + call is faster than full call. + +\item Avoid setting local variables when possible. Binding a new + \code{let} variable is at least as efficient as setting an existing + variable, and is easier to understand, both for the compiler and the + programmer. + +\item Instead of writing similar code over and over again so that it + can be hand customized for each use, define a macro or inline + function, and let the compiler do the work. +\end{itemize} + + +%% +%%\node Tail Recursion, Local Call, Source Optimization, Advanced Compiler Use and Efficiency Hints +\section{Tail Recursion} +\label{tail-recursion} +\cindex{tail recursion} +\cindex{recursion} + +A call is tail-recursive if nothing has to be done after the the call +returns, i.e. when the call returns, the returned value is immediately +returned from the calling function. In this example, the recursive +call to \code{myfun} is tail-recursive: +\begin{lisp} +(defun myfun (x) + (if (oddp (random x)) + (isqrt x) + (myfun (1- x)))) +\end{lisp} + +Tail recursion is interesting because it is form of recursion that can be +implemented much more efficiently than general recursion. In general, a +recursive call requires the compiler to allocate storage on the stack at +run-time for every call that has not yet returned. This memory consumption +makes recursion unacceptably inefficient for representing repetitive algorithms +having large or unbounded size. Tail recursion is the special case of +recursion that is semantically equivalent to the iteration constructs normally +used to represent repetition in programs. Because tail recursion is equivalent +to iteration, tail-recursive programs can be compiled as efficiently as +iterative programs. + +So why would you want to write a program recursively when you can write it +using a loop? Well, the main answer is that recursion is a more general +mechanism, so it can express some solutions simply that are awkward to write as +a loop. Some programmers also feel that recursion is a stylistically +preferable way to write loops because it avoids assigning variables. +For example, instead of writing: +\begin{lisp} +(defun fun1 (x) + something-that-uses-x) + +(defun fun2 (y) + something-that-uses-y) + +(do ((x something (fun2 (fun1 x)))) + (nil)) +\end{lisp} +You can write: +\begin{lisp} +(defun fun1 (x) + (fun2 something-that-uses-x)) + +(defun fun2 (y) + (fun1 something-that-uses-y)) + +(fun1 something) +\end{lisp} +The tail-recursive definition is actually more efficient, in addition to being +(arguably) clearer. As the number of functions and the complexity of their +call graph increases, the simplicity of using recursion becomes compelling. +Consider the advantages of writing a large finite-state machine with separate +tail-recursive functions instead of using a single huge \code{prog}. + +It helps to understand how to use tail recursion if you think of a +tail-recursive call as a \code{psetq} that assigns the argument values to the +called function's variables, followed by a \code{go} to the start of the called +function. This makes clear an inherent efficiency advantage of tail-recursive +call: in addition to not having to allocate a stack frame, there is no need to +prepare for the call to return (e.g., by computing a return PC.) + +Is there any disadvantage to tail recursion? Other than an increase +in efficiency, the only way you can tell that a call has been compiled +tail-recursively is if you use the debugger. Since a tail-recursive +call has no stack frame, there is no way the debugger can print out +the stack frame representing the call. The effect is that backtrace +will not show some calls that would have been displayed in a +non-tail-recursive implementation. In practice, this is not as bad as +it sounds\dash{}in fact it isn't really clearly worse, just different. +\xlref{debug-tail-recursion} for information about the debugger +implications of tail recursion. + +In order to ensure that tail-recursion is preserved in arbitrarily +complex calling patterns across separately compiled functions, the +compiler must compile any call in a tail-recursive position as a +tail-recursive call. This is done regardless of whether the program +actually exhibits any sort of recursive calling pattern. In this +example, the call to \code{fun2} will always be compiled as a +tail-recursive call: +\begin{lisp} +(defun fun1 (x) + (fun2 x)) +\end{lisp} +So tail recursion doesn't necessarily have anything to do with recursion +as it is normally thought of. \xlref{local-tail-recursion} for more +discussion of using tail recursion to implement loops. + +\begin{comment} +* Tail Recursion Exceptions:: +\end{comment} + +%%\node Tail Recursion Exceptions, , Tail Recursion, Tail Recursion +\subsection{Tail Recursion Exceptions} + +Although \python{} is claimed to be properly'' tail-recursive, some +might dispute this, since there are situations where tail recursion is +inhibited: +\begin{itemize} + +\item When the call is enclosed by a special binding, or + +\item When the call is enclosed by a \code{catch} or + \code{unwind-protect}, or + +\item When the call is enclosed by a \code{block} or \code{tagbody} + and the block name or \code{go} tag has been closed over. +\end{itemize} +These dynamic extent binding forms inhibit tail recursion because they +allocate stack space to represent the binding. Shallow-binding +implementations of dynamic scoping also require cleanup code to be +evaluated when the scope is exited. + +%% +%%\node Local Call, Block Compilation, Tail Recursion, Advanced Compiler Use and Efficiency Hints +\section{Local Call} +\label{local-call} +\cindex{local call} +\cpsubindex{call}{local} +\cpsubindex{function call}{local} + +Python supports two kinds of function call: full call and local call. +Full call is the standard calling convention; its late binding and +generality make \llisp{} what it is, but create unavoidable overheads. +When the compiler can compile the calling function and the called +function simultaneously, it can use local call to avoid some of the +overhead of full call. Local call is really a collection of +compilation strategies. If some aspect of call overhead is not needed +in a particular local call, then it can be omitted. In some cases, +local call can be totally free. Local call provides two main +advantages to the user: +\begin{itemize} + +\item Local call makes the use of the lexical function binding forms + \findexed{flet} and \findexed{labels} much more efficient. A local + call is always faster than a full call, and in many cases is much + faster. + +\item Local call is a natural approach to \i{block compilation}, a + compilation technique that resolves function references at compile + time. Block compilation speeds function call, but increases + compilation times and prevents function redefinition. +\end{itemize} + + +\begin{comment} +* Self-Recursive Calls:: +* Let Calls:: +* Closures:: +* Local Tail Recursion:: +* Return Values:: +\end{comment} + +%%\node Self-Recursive Calls, Let Calls, Local Call, Local Call +\subsection{Self-Recursive Calls} +\cpsubindex{recursion}{self} + +Local call is used when a function defined by \code{defun} calls itself. For +example: +\begin{lisp} +(defun fact (n) + (if (zerop n) + 1 + (* n (fact (1- n))))) +\end{lisp} +This use of local call speeds recursion, but can also complicate +debugging, since \findexed{trace} will only show the first call to +\code{fact}, and not the recursive calls. This is because the +recursive calls directly jump to the start of the function, and don't +indirect through the \code{symbol-function}. Self-recursive local +call is inhibited when the \kwd{block-compile} argument to +\code{compile-file} is \false{} (\pxlref{compile-file-block}.) + +%%\node Let Calls, Closures, Self-Recursive Calls, Local Call +\subsection{Let Calls} +\label{let-calls} +Because local call avoids unnecessary call overheads, the compiler +internally uses local call to implement some macros and special forms +that are not normally thought of as involving a function call. For +example, this \code{let}: +\begin{example} +(let ((a (foo)) + (b (bar))) + ...) +\end{example} +is internally represented as though it was macroexpanded into: +\begin{example} +(funcall #'(lambda (a b) + ...) + (foo) + (bar)) +\end{example} +This implementation is acceptable because the simple cases of local +call (equivalent to a \code{let}) result in good code. This doesn't +make \code{let} any more efficient, but does make local calls that are +semantically the same as \code{let} much more efficient than full +calls. For example, these definitions are all the same as far as the +compiler is concerned: +\begin{example} +(defun foo () + ...some other stuff... + (let ((a something)) + ...some stuff...)) + +(defun foo () + (flet ((localfun (a) + ...some stuff...)) + ...some other stuff... + (localfun something))) + +(defun foo () + (let ((funvar #'(lambda (a) + ...some stuff...))) + ...some other stuff... + (funcall funvar something))) +\end{example} + +Although local call is most efficient when the function is called only +once, a call doesn't have to be equivalent to a \code{let} to be more +efficient than full call. All local calls avoid the overhead of +argument count checking and keyword argument parsing, and there are a +number of other advantages that apply in many common situations. +\xlref{let-optimization} for a discussion of the optimizations done on +let calls. + +%%\node Closures, Local Tail Recursion, Let Calls, Local Call +\subsection{Closures} +\cindex{closures} + +Local call allows for much more efficient use of closures, since the +closure environment doesn't need to be allocated on the heap, or even +stored in memory at all. In this example, there is no penalty for +\code{localfun} referencing \code{a} and \code{b}: +\begin{lisp} +(defun foo (a b) + (flet ((localfun (x) + (1+ (* a b x)))) + (if (= a b) + (localfun (- x)) + (localfun x)))) +\end{lisp} +In local call, the compiler effectively passes closed-over values as +extra arguments, so there is no need for you to optimize'' local +function use by explicitly passing in lexically visible values. +Closures may also be subject to let optimization +(\pxlref{let-optimization}.) + +Note: indirect value cells are currently always allocated on the heap +when a variable is both assigned to (with \code{setq} or \code{setf}) +and closed over, regardless of whether the closure is a local function +or not. This is another reason to avoid setting variables when you +don't have to. + +%%\node Local Tail Recursion, Return Values, Closures, Local Call +\subsection{Local Tail Recursion} +\label{local-tail-recursion} +\cindex{tail recursion} +\cpsubindex{recursion}{tail} + +Tail-recursive local calls are particularly efficient, since they are +in effect an assignment plus a control transfer. Scheme programmers +write loops with tail-recursive local calls, instead of using the +imperative \code{go} and \code{setq}. This has not caught on in the +\clisp{} community, since conventional \llisp{} compilers don't +implement local call. In \python, users can choose to write loops +such as: +\begin{lisp} +(defun ! (n) + (labels ((loop (n total) + (if (zerop n) + total + (loop (1- n) (* n total))))) + (loop n 1))) +\end{lisp} + +\begin{defmac}{extensions:}{iterate}{% + \args{\var{name} (\mstar{(\var{var} \var{initial-value})}) + \mstar{\var{declaration}} \mstar{\var{form}}}} + + This macro provides syntactic sugar for using \findexed{labels} to + do iteration. It creates a local function \var{name} with the + specified \var{var}s as its arguments and the \var{declaration}s and + \var{form}s as its body. This function is then called with the + \var{initial-values}, and the result of the call is return from the + macro. + + Here is our factorial example rewritten using \code{iterate}: + + \begin{lisp} + (defun ! (n) + (iterate loop + ((n n) + (total 1)) + (if (zerop n) + total + (loop (1- n) (* n total))))) + \end{lisp} + + The main advantage of using \code{iterate} over \code{do} is that + \code{iterate} naturally allows stepping to be done differently + depending on conditionals in the body of the loop. \code{iterate} + can also be used to implement algorithms that aren't really + iterative by simply doing a non-tail call. For example, the + standard recursive definition of factorial can be written like this: +\begin{lisp} +(iterate fact + ((n n)) + (if (zerop n) + 1 + (* n (fact (1- n))))) +\end{lisp} +\end{defmac} + +%%\node Return Values, , Local Tail Recursion, Local Call +\subsection{Return Values} +\label{local-call-return} +\cpsubindex{return values}{local call} +\cpsubindex{local call}{return values} + +One of the more subtle costs of full call comes from allowing +arbitrary numbers of return values. This overhead can be avoided in +local calls to functions that always return the same number of values. +For efficiency reasons (as well as stylistic ones), you should write +functions so that they always return the same number of values. This +may require passing extra \false{} arguments to \code{values} in some +cases, but the result is more efficient, not less so. + +When efficiency notes are enabled (\pxlref{efficiency-notes}), and the +compiler wants to use known values return, but can't prove that the +function always returns the same number of values, then it will print +a note like this: +\begin{example} +In: DEFUN GRUE + (DEFUN GRUE (X) (DECLARE (FIXNUM X)) (COND (# #) (# NIL) (T #))) +Note: Return type not fixed values, so can't use known return convention: + (VALUES (OR (INTEGER -536870912 -1) NULL) &REST T) +\end{example} + +In order to implement proper tail recursion in the presence of known +values return (\pxlref{tail-recursion}), the compiler sometimes must +prove that multiple functions all return the same number of values. +When this can't be proven, the compiler will print a note like this: +\begin{example} +In: DEFUN BLUE + (DEFUN BLUE (X) (DECLARE (FIXNUM X)) (COND (# #) (# #) (# #) (T #))) +Note: Return value count mismatch prevents known return from + these functions: + BLUE + SNOO +\end{example} +\xlref{number-local-call} for the interaction between local call +and the representation of numeric types. + +%% +%%\node Block Compilation, Inline Expansion, Local Call, Advanced Compiler Use and Efficiency Hints +\section{Block Compilation} +\label{block-compilation} +\cindex{block compilation} +\cpsubindex{compilation}{block} + +Block compilation allows calls to global functions defined by +\findexed{defun} to be compiled as local calls. The function call +can be in a different top-level form than the \code{defun}, or even in a +different file. + +In addition, block compilation allows the declaration of the \i{entry points} +to the block compiled portion. An entry point is any function that may be +called from outside of the block compilation. If a function is not an entry +point, then it can be compiled more efficiently, since all calls are known at +compile time. In particular, if a function is only called in one place, then +it will be let converted. This effectively inline expands the function, but +without the code duplication that results from defining the function normally +and then declaring it inline. + +The main advantage of block compilation is that it it preserves efficiency in +programs even when (for readability and syntactic convenience) they are broken +up into many small functions. There is absolutely no overhead for calling a +non-entry point function that is defined purely for modularity (i.e. called +only in one place.) + +Block compilation also allows the use of non-descriptor arguments and return +values in non-trivial programs (\pxlref{number-local-call}). + +\begin{comment} +* Block Compilation Semantics:: +* Block Compilation Declarations:: +* Compiler Arguments:: +* Practical Difficulties:: +* Context Declarations:: +* Context Declaration Example:: +\end{comment} + +%%\node Block Compilation Semantics, Block Compilation Declarations, Block Compilation, Block Compilation +\subsection{Block Compilation Semantics} + +The effect of block compilation can be envisioned as the compiler turning all +the \code{defun}s in the block compilation into a single \code{labels} form: +\begin{example} +(declaim (start-block fun1 fun3)) + +(defun fun1 () + ...) + +(defun fun2 () + ... + (fun1) + ...) + +(defun fun3 (x) + (if x + (fun1) + (fun2))) + +(declaim (end-block)) +\end{example} +becomes: +\begin{example} +(labels ((fun1 () + ...) + (fun2 () + ... + (fun1) + ...) + (fun3 (x) + (if x + (fun1) + (fun2)))) + (setf (fdefinition 'fun1) #'fun1) + (setf (fdefinition 'fun3) #'fun3)) +\end{example} +Calls between the block compiled functions are local calls, so changing the +global definition of \code{fun1} will have no effect on what \code{fun2} does; +\code{fun2} will keep calling the old \code{fun1}. + +The entry points \code{fun1} and \code{fun3} are still installed in +the \code{symbol-function} as the global definitions of the functions, +so a full call to an entry point works just as before. However, +\code{fun2} is not an entry point, so it is not globally defined. In +addition, \code{fun2} is only called in one place, so it will be let +converted. + + +%%\node Block Compilation Declarations, Compiler Arguments, Block Compilation Semantics, Block Compilation +\subsection{Block Compilation Declarations} +\cpsubindex{declarations}{block compilation} +\cindex{start-block declaration} +\cindex{end-block declaration} + +The \code{extensions:start-block} and \code{extensions:end-block} +declarations allow fine-grained control of block compilation. These +declarations are only legal as a global declarations (\code{declaim} +or \code{proclaim}). + +\noindent +\vspace{1 em} +The \code{start-block} declaration has this syntax: +\begin{example} +(start-block \mstar{\var{entry-point-name}}) +\end{example} +When processed by the compiler, this declaration marks the start of +block compilation, and specifies the entry points to that block. If +no entry points are specified, then \var{all} functions are made into +entry points. If already block compiling, then the compiler ends the +current block and starts a new one. + +\noindent +\vspace{1 em} +The \code{end-block} declaration has no arguments: +\begin{lisp} +(end-block) +\end{lisp} +The \code{end-block} declaration ends a block compilation unit without +starting a new one. This is useful mainly when only a portion of a file +is worth block compiling. + +%%\node Compiler Arguments, Practical Difficulties, Block Compilation Declarations, Block Compilation +\subsection{Compiler Arguments} +\label{compile-file-block} +\cpsubindex{compile-file}{block compilation arguments} + +The \kwd{block-compile} and \kwd{entry-points} arguments to +\code{extensions:compile-from-stream} and \funref{compile-file} provide overall +control of block compilation, and allow block compilation without requiring +modification of the program source. + +There are three possible values of the \kwd{block-compile} argument: +\begin{Lentry} + +\item[\false{}] Do no compile-time resolution of global function + names, not even for self-recursive calls. This inhibits any + \code{start-block} declarations appearing in the file, allowing all + functions to be incrementally redefined. + +\item[\true{}] Start compiling in block compilation mode. This is + mainly useful for block compiling small files that contain no + \code{start-block} declarations. See also the \kwd{entry-points} + argument. + +\item[\kwd{specified}] Start compiling in form-at-a-time mode, but + exploit \code{start-block} declarations and compile self-recursive + calls as local calls. Normally \kwd{specified} is the default for + this argument (see \varref{block-compile-default}.) +\end{Lentry} + +The \kwd{entry-points} argument can be used in conjunction with +\w{\kwd{block-compile} \true{}} to specify the entry-points to a +block-compiled file. If not specified or \nil, all global functions +will be compiled as entry points. When \kwd{block-compile} is not +\true, this argument is ignored. + +\begin{defvar}{}{block-compile-default} + + This variable determines the default value for the + \kwd{block-compile} argument to \code{compile-file} and + \code{compile-from-stream}. The initial value of this variable is + \kwd{specified}, but \false{} is sometimes useful for totally + inhibiting block compilation. +\end{defvar} + +%%\node Practical Difficulties, Context Declarations, Compiler Arguments, Block Compilation +\subsection{Practical Difficulties} + +The main problem with block compilation is that the compiler uses +large amounts of memory when it is block compiling. This places an +upper limit on the amount of code that can be block compiled as a +unit. To make best use of block compilation, it is necessary to +locate the parts of the program containing many internal calls, and +then add the appropriate \code{start-block} declarations. When writing +new code, it is a good idea to put in block compilation declarations +from the very beginning, since writing block declarations correctly +requires accurate knowledge of the program's function call structure. +If you want to initially develop code with full incremental +redefinition, you can compile with \varref{block-compile-default} set to +\false. + +Note if a \code{defun} appears in a non-null lexical environment, then +calls to it cannot be block compiled. + +Unless files are very small, it is probably impractical to block compile +multiple files as a unit by specifying a list of files to \code{compile-file}. +Semi-inline expansion (\pxlref{semi-inline}) provides another way to +extend block compilation across file boundaries. +%% +%%\node Context Declarations, Context Declaration Example, Practical Difficulties, Block Compilation +\subsection{Context Declarations} +\label{context-declarations} +\cindex{context sensitive declarations} +\cpsubindex{declarations}{context-sensitive} + +\cmucl{} has a context-sensitive declaration mechanism which is useful +because it allows flexible control of the compilation policy in large +systems without requiring changes to the source files. The primary +use of this feature is to allow the exported interfaces of a system to +be compiled more safely than the system internals. The context used +is the name being defined and the kind of definition (function, macro, +etc.) + +The \kwd{context-declarations} option to \macref{with-compilation-unit} has +dynamic scope, affecting all compilation done during the evaluation of the +body. The argument to this option should evaluate to a list of lists of the +form: +\begin{example} +(\var{context-spec} \mplus{\var{declare-form}}) +\end{example} +In the indicated context, the specified declare forms are inserted at +the head of each definition. The declare forms for all contexts that +match are appended together, with earlier declarations getting +precedence over later ones. A simple example: +\begin{example} + :context-declarations + '((:external (declare (optimize (safety 2))))) +\end{example} +This will cause all functions that are named by external symbols to be +compiled with \code{safety 2}. + +The full syntax of context specs is: +\begin{Lentry} + +\item[\kwd{internal}, \kwd{external}] True if the symbol is internal + (external) in its home package. + +\item[\kwd{uninterned}] True if the symbol has no home package. + +\item[\code{\w{(:package \mstar{\var{package-name}})}}] True if the + symbol's home package is in any of the named packages (false if + uninterned.) + +\item[\kwd{anonymous}] True if the function doesn't have any + interesting name (not \code{defmacro}, \code{defun}, \code{labels} + or \code{flet}). + +\item[\kwd{macro}, \kwd{function}] \kwd{macro} is a global + (\code{defmacro}) macro. \kwd{function} is anything else. + +\item[\kwd{local}, \kwd{global}] \kwd{local} is a \code{labels} or + \code{flet}. \kwd{global} is anything else. + +\item[\code{\w{(:or \mstar{\var{context-spec}})}}] True when any + supplied \var{context-spec} is true. + +\item[\code{\w{(:and \mstar{\var{context-spec}})}}] True only when all + supplied \var{context-spec}s are true. + +\item[\code{\w{(:not \mstar{\var{context-spec}})}}] True when + \var{context-spec} is false. + +\item[\code{\w{(:member \mstar{\var{name}})}}] True when the defined + name is one of these names (\code{equal} test.) + +\item[\code{\w{(:match \mstar{\var{pattern}})}}] True when any of the + patterns is a substring of the name. The name is wrapped with + \code{\$}'s, so \code{\$FOO}'' matches names beginning with + \code{FOO}'', etc. +\end{Lentry} + +%%\node Context Declaration Example, , Context Declarations, Block Compilation +\subsection{Context Declaration Example} + +Here is a more complex example of \code{with-compilation-unit} options: +\begin{example} +:optimize '(optimize (speed 2) (space 2) (inhibit-warnings 2) + (debug 1) (safety 0)) +:optimize-interface '(optimize-interface (safety 1) (debug 1)) +:context-declarations +'(((:or :external (:and (:match "\%") (:match "SET"))) + (declare (optimize-interface (safety 2)))) + ((:or (:and :external :macro) + (:match "\$PARSE-"))
+   (declare (optimize (safety 2)))))
+\end{example}
+The \code{optimize} and \code{extensions:optimize-interface}
+declarations (\pxlref{optimize-declaration}) set up the global
+compilation policy.  The bodies of functions are to be compiled
+completely unsafe (\code{safety 0}), but argument count and weakened
+argument type checking is to be done when a function is called
+(\code{speed 2 safety 1}).
+
+The first declaration specifies that all functions that are external
+or whose names contain both \code{\%}'' and \code{SET}'' are to be
+compiled compiled with completely safe interfaces (\code{safety 2}).
+The reason for this particular \kwd{match} rule is that \code{setf}
+inverse functions in this system tend to have both strings in their
+name somewhere.  We want \code{setf} inverses to be safe because they
+are implicitly called by users even though their name is not exported.
+
+The second declaration makes external macros or functions whose names
+start with \code{PARSE-}'' have safe bodies (as well as interfaces).
+This is desirable because a syntax error in a macro may cause a type
+error inside the body.  The \kwd{match} rule is used because macros
+often have auxiliary functions whose names begin with this string.
+
+This particular example is used to build part of the standard \cmucl{}
+system.  Note however, that context declarations must be set up
+according to the needs and coding conventions of a particular system;
+different parts of \cmucl{} are compiled with different context
+declarations, and your system will probably need its own declarations.
+In particular, any use of the \kwd{match} option depends on naming
+conventions used in coding.
+
+%%
+%%\node Inline Expansion, Byte Coded Compilation, Block Compilation, Advanced Compiler Use and Efficiency Hints
+\section{Inline Expansion}
+\label{inline-expansion}
+\cindex{inline expansion}
+\cpsubindex{expansion}{inline}
+\cpsubindex{call}{inline}
+\cpsubindex{function call}{inline}
+\cpsubindex{optimization}{function call}
+
+Python can expand almost any function inline, including functions
+with keyword arguments.  The only restrictions are that keyword
+argument keywords in the call must be constant, and that global
+function definitions (\code{defun}) must be done in a null lexical
+environment (not nested in a \code{let} or other binding form.)  Local
+functions (\code{flet}) can be inline expanded in any environment.
+Combined with \python{}'s source-level optimization, inline expansion
+can be used for things that formerly required macros for efficient
+implementation.  In \python, macros don't have any efficiency
+advantage, so they need only be used where a macro's syntactic
+flexibility is required.
+
+Inline expansion is a compiler optimization technique that reduces
+the overhead of a function call by simply not doing the call:
+instead, the compiler effectively rewrites the program to appear as
+though the definition of the called function was inserted at each
+call site.  In \llisp, this is straightforwardly expressed by
+inserting the \code{lambda} corresponding to the original definition:
+\begin{lisp}
+(proclaim '(inline my-1+))
+(defun my-1+ (x) (+ x 1))
+
+(my-1+ someval) \result{} ((lambda (x) (+ x 1)) someval)
+\end{lisp}
+
+When the function expanded inline is large, the program after inline
+expansion may be substantially larger than the original program.  If
+the program becomes too large, inline expansion hurts speed rather
+than helping it, since hardware resources such as physical memory and
+cache will be exhausted.  Inline expansion is called for:
+\begin{itemize}
+
+\item When profiling has shown that a relatively simple function is
+  called so often that a large amount of time is being wasted in the
+  calling of that function (as opposed to running in that function.)
+  If a function is complex, it will take a long time to run relative
+  the time spent in call, so the speed advantage of inline expansion
+  is diminished at the same time the space cost of inline expansion is
+  increased.  Of course, if a function is rarely called, then the
+  overhead of calling it is also insignificant.
+
+\item With functions so simple that they take less space to inline
+  expand than would be taken to call the function (such as
+  \code{my-1+} above.)  It would require intimate knowledge of the
+  compiler to be certain when inline expansion would reduce space, but
+  it is generally safe to inline expand functions whose definition is
+  a single function call, or a few calls to simple \clisp{} functions.
+\end{itemize}
+
+
+avoidance of the call, inline expansion can also reveal opportunities
+for optimization.  \python{}'s extensive source-level optimization can
+make use of context information from the caller to tremendously
+simplify the code resulting from the inline expansion of a function.
+
+The main form of caller context is local information about the actual
+argument values: what the argument types are and whether the arguments
+are constant.  Knowledge about argument types can eliminate run-time
+type tests (e.g., for generic arithmetic.)  Constant arguments in a
+call provide opportunities for constant folding optimization after
+inline expansion.
+
+A hidden way that constant arguments are often supplied to functions
+is through the defaulting of unsupplied optional or keyword arguments.
+There can be a huge efficiency advantage to inline expanding functions
+that have complex keyword-based interfaces, such as this definition of
+the \code{member} function:
+\begin{lisp}
+(proclaim '(inline member))
+(defun member (item list &key
+                    (key #'identity)
+                    (test #'eql testp)
+                    (test-not nil notp))
+  (do ((list list (cdr list)))
+      ((null list) nil)
+    (let ((car (car list)))
+      (if (cond (testp
+                 (funcall test item (funcall key car)))
+                (notp
+                 (not (funcall test-not item (funcall key car))))
+                (t
+                 (funcall test item (funcall key car))))
+          (return list)))))
+
+\end{lisp}
+After inline expansion, this call is simplified to the obvious code:
+\begin{lisp}
+(member a l :key #'foo-a :test #'char=) \result{}
+
+(do ((list list (cdr list)))
+    ((null list) nil)
+  (let ((car (car list)))
+    (if (char= item (foo-a car))
+        (return list))))
+\end{lisp}
+In this example, there could easily be more than an order of magnitude
+improvement in speed.  In addition to eliminating the original call to
+\code{member}, inline expansion also allows the calls to \code{char=}
+and \code{foo-a} to be open-coded.  We go from a loop with three tests
+and two calls to a loop with one test and no calls.
+
+\xlref{source-optimization} for more discussion of source level
+optimization.
+
+\begin{comment}
+* Inline Expansion Recording::
+* Semi-Inline Expansion::
+* The Maybe-Inline Declaration::
+\end{comment}
+
+%%\node Inline Expansion Recording, Semi-Inline Expansion, Inline Expansion, Inline Expansion
+\subsection{Inline Expansion Recording}
+\cindex{recording of inline expansions}
+
+Inline expansion requires that the source for the inline expanded function to
+be available when calls to the function are compiled.  The compiler doesn't
+remember the inline expansion for every function, since that would take an
+excessive about of space.  Instead, the programmer must tell the compiler to
+record the inline expansion before the definition of the inline expanded
+function is compiled.  This is done by globally declaring the function inline
+before the function is defined, by using the \code{inline} and
+\code{extensions:maybe-inline} (\pxlref{maybe-inline-declaration})
+declarations.
+
+In addition to recording the inline expansion of inline functions at the time
+the function is compiled, \code{compile-file} also puts the inline expansion in
+the output file.  When the output file is loaded, the inline expansion is made
+available for subsequent compilations; there is no need to compile the
+definition again to record the inline expansion.
+
+If a function is declared inline, but no expansion is recorded, then the
+compiler will give an efficiency note like:
+\begin{example}
+Note: MYFUN is declared inline, but has no expansion.
+\end{example}
+When you get this note, check that the \code{inline} declaration and the
+definition appear before the calls that are to be inline expanded.  This note
+will also be given if the inline expansion for a \code{defun} could not be
+recorded because the \code{defun} was in a non-null lexical environment.
+
+%%\node Semi-Inline Expansion, The Maybe-Inline Declaration, Inline Expansion Recording, Inline Expansion
+\subsection{Semi-Inline Expansion}
+\label{semi-inline}
+
+Python supports \var{semi-inline} functions.  Semi-inline expansion
+shares a single copy of a function across all the calls in a component
+by converting the inline expansion into a local function
+(\pxlref{local-call}.)  This takes up less space when there are
+multiple calls, but also provides less opportunity for context
+dependent optimization.  When there is only one call, the result is
+identical to normal inline expansion.  Semi-inline expansion is done
+when the \code{space} optimization quality is \code{0}, and the
+function has been declared \code{extensions:maybe-inline}.
+
+This mechanism of inline expansion combined with local call also
+allows recursive functions to be inline expanded.  If a recursive
+function is declared \code{inline}, calls will actually be compiled
+semi-inline.  Although recursive functions are often so complex that
+there is little advantage to semi-inline expansion, it can still be
+useful in the same sort of cases where normal inline expansion is
+especially advantageous, i.e. functions where the calling context can
+help a lot.
+
+%%\node The Maybe-Inline Declaration,  , Semi-Inline Expansion, Inline Expansion
+\subsection{The Maybe-Inline Declaration}
+\label{maybe-inline-declaration}
+\cindex{maybe-inline declaration}
+
+The \code{extensions:maybe-inline} declaration is a \cmucl{}
+extension.  It is similar to \code{inline}, but indicates that inline
+expansion may sometimes be desirable, rather than saying that inline
+expansion should almost always be done.  When used in a global
+declaration, \code{extensions:maybe-inline} causes the expansion for
+the named functions to be recorded, but the functions aren't actually
+inline expanded unless \code{space} is \code{0} or the function is
+eventually (perhaps locally) declared \code{inline}.
+
+Use of the \code{extensions:maybe-inline} declaration followed by the
+\code{defun} is preferable to the standard idiom of:
+\begin{lisp}
+(proclaim '(inline myfun))
+(defun myfun () ...)
+(proclaim '(notinline myfun))
+
+;;; \i{Any calls to \code{myfun} here are not inline expanded.}
+
+(defun somefun ()
+  (declare (inline myfun))
+  ;;
+  ;; \i{Calls to \code{myfun} here are inline expanded.}
+  ...)
+\end{lisp}
+The problem with using \code{notinline} in this way is that in
+\clisp{} it does more than just suppress inline expansion, it also
+forbids the compiler to use any knowledge of \code{myfun} until a
+later \code{inline} declaration overrides the \code{notinline}.  This
+prevents compiler warnings about incorrect calls to the function, and
+also prevents block compilation.
+
+The \code{extensions:maybe-inline} declaration is used like this:
+\begin{lisp}
+(proclaim '(extensions:maybe-inline myfun))
+(defun myfun () ...)
+
+;;; \i{Any calls to \code{myfun} here are not inline expanded.}
+
+(defun somefun ()
+  (declare (inline myfun))
+  ;;
+  ;; \i{Calls to \code{myfun} here are inline expanded.}
+  ...)
+
+(defun someotherfun ()
+  (declare (optimize (space 0)))
+  ;;
+  ;; \i{Calls to \code{myfun} here are expanded semi-inline.}
+  ...)
+\end{lisp}
+In this example, the use of \code{extensions:maybe-inline} causes the
+expansion to be recorded when the \code{defun} for \code{somefun} is
+compiled, and doesn't waste space through doing inline expansion by
+default.  Unlike \code{notinline}, this declaration still allows the
+compiler to assume that the known definition really is the one that
+will be called when giving compiler warnings, and also allows the
+compiler to do semi-inline expansion when the policy is appropriate.
+
+When the goal is merely to control whether inline expansion is done by
+default, it is preferable to use \code{extensions:maybe-inline} rather
+than \code{notinline}.  The \code{notinline} declaration should be
+reserved for those special occasions when a function may be redefined
+at run-time, so the compiler must be told that the obvious definition
+of a function is not necessarily the one that will be in effect at the
+time of the call.
+
+%%
+%%\node Byte Coded Compilation, Object Representation, Inline Expansion, Advanced Compiler Use and Efficiency Hints
+\section{Byte Coded Compilation}
+\label{byte-compile}
+\cindex{byte coded compilation}
+\cindex{space optimization}
+
+\Python{} supports byte compilation to reduce the size of Lisp
+programs by allowing functions to be compiled more compactly.  Byte
+compilation provides an extreme speed/space tradeoff: byte code is
+typically six times more compact than native code, but runs fifty
+times (or more) slower.  This is about ten times faster than the
+standard interpreter, which is itself considered fast in comparison to
+other \clisp{} interpreters.
+
+Large Lisp systems (such as \cmucl{} itself) often have large amounts
+of user-interface code, compile-time (macro) code, debugging code, or
+rarely executed special-case code.  This code is a good target for
+byte compilation: very little time is spent running in it, but it can
+take up quite a bit of space.  Straight-line code with many function
+calls is much more suitable than inner loops.
+
+When byte-compiling, the compiler compiles about twice as fast, and
+can produce a hardware independent object file (\file{.bytef} type.)
+This file can be loaded like a normal fasl file on any implementation
+of CMU CL with the same byte-ordering (DEC PMAX has \file{.lbytef}
+type.)
+
+The decision to byte compile or native compile can be done on a
+per-file or per-code-object basis.  The \kwd{byte-compile} argument to
+\funref{compile-file} has these possible values:
+\begin{Lentry}
+\item[\false{}] Don't byte compile anything in this file.
+
+\item[\true{}] Byte compile everything in this file and produce a
+  processor-independent \file{.bytef} file.
+
+\item[\kwd{maybe}] Produce a normal fasl file, but byte compile any
+  functions for which the \code{speed} optimization quality is
+  \code{0} and the \code{debug} quality is not greater than \code{1}.
+\end{Lentry}
+
+\begin{defvar}{extensions:}{byte-compile-top-level}
+
+  If this variable is true (the default) and the \kwd{byte-compile}
+  argument to \code{compile-file} is \kwd{maybe}, then byte compile
+  top-level code (code outside of any \code{defun}, \code{defmethod},
+  etc.)
+\end{defvar}
+
+\begin{defvar}{extensions:}{byte-compile-default}
+
+  This variable determines the default value for the
+  \kwd{byte-compile} argument to \code{compile-file}, initially
+  \kwd{maybe}.
+\end{defvar}
+
+%%
+%%\node Object Representation, Numbers, Byte Coded Compilation, Advanced Compiler Use and Efficiency Hints
+\section{Object Representation}
+\label{object-representation}
+\cindex{object representation}
+\cpsubindex{representation}{object}
+\cpsubindex{efficiency}{of objects}
+
+A somewhat subtle aspect of writing efficient \clisp{} programs is
+choosing the correct data structures so that the underlying objects
+can be implemented efficiently.  This is partly because of the need
+for multiple representations for a given value
+(\pxlref{non-descriptor}), but is also due to the sheer number of
+object types that \clisp{} has built in.  The number of possible
+representations complicates the choice of a good representation
+because semantically similar objects may vary in their efficiency
+depending on how the program operates on them.
+
+\begin{comment}
+* Think Before You Use a List::
+* Structure Representation::
+* Arrays::
+* Vectors::
+* Bit-Vectors::
+* Hashtables::
+\end{comment}
+
+%%\node Think Before You Use a List, Structure Representation, Object Representation, Object Representation
+\subsection{Think Before You Use a List}
+\cpsubindex{lists}{efficiency of}
+
+Although Lisp's creator seemed to think that it was for LISt Processing, the
+astute observer may have noticed that the chapter on list manipulation makes up
+less that three percent of \i{Common Lisp: the Language II}.  The language has
+grown since Lisp 1.5\dash{}new data types supersede lists for many purposes.
+
+%%\node Structure Representation, Arrays, Think Before You Use a List, Object Representation
+\subsection{Structure Representation}
+\cpsubindex{structure types}{efficiency of} One of the best ways of
+building complex data structures is to define appropriate structure
+types using \findexed{defstruct}.  In \python, access of structure
+slots is always at least as fast as list or vector access, and is
+usually faster.  In comparison to a list representation of a tuple,
+structures also have a space advantage.
+
+Even if structures weren't more efficient than other representations, structure
+use would still be attractive because programs that use structures in
+appropriate ways are much more maintainable and robust than programs written
+using only lists.  For example:
+\begin{lisp}
+\end{lisp}
+could have been written using structures in this way:
+\begin{lisp}
+(setf (beverage-flavor (astronaut-beverage x)) (beverage-flavor y))
+\end{lisp}
+The second version is more maintainable because it is easier to
+understand what it is doing.  It is more robust because structures
+accesses are type checked.  An \code{astronaut} will never be confused
+with a \code{beverage}, and the result of \code{beverage-flavor} is
+always a flavor.  See sections \ref{structure-types} and
+\xlref{type-inference} for a number of examples that make clear the
+
+Note that the structure definition should be compiled before any uses
+of its accessors or type predicate so that these function calls can be
+efficiently open-coded.
+
+%%\node Arrays, Vectors, Structure Representation, Object Representation
+\subsection{Arrays}
+\label{array-types}
+\cpsubindex{arrays}{efficiency of}
+
+Arrays are often the most efficient representation for collections of objects
+because:
+\begin{itemize}
+
+\item Array representations are often the most compact.  An array is
+  always more compact than a list containing the same number of
+  elements.
+
+\item Arrays allow fast constant-time access.
+
+\item Arrays are easily destructively modified, which can reduce
+  consing.
+
+\item Array element types can be specialized, which reduces both
+  overall size and consing (\pxlref{specialized-array-types}.)
+\end{itemize}
+
+
+Access of arrays that are not of type \code{simple-array} is less
+efficient, so declarations are appropriate when an array is of a
+simple type like \code{simple-string} or \code{simple-bit-vector}.
+Arrays are almost always simple, but the compiler may not be able to
+prove simpleness at every use.  The only way to get a non-simple array
+is to use the \kwd{displaced-to}, \kwd{fill-pointer} or
+\code{adjustable} arguments to \code{make-array}.  If you don't use
+these hairy options, then arrays can always be declared to be simple.
+
+Because of the many specialized array types and the possibility of
+non-simple arrays, array access is much like generic arithmetic
+(\pxlref{generic-arithmetic}).  In order for array accesses to be
+efficiently compiled, the element type and simpleness of the array
+must be known at compile time.  If there is inadequate information,
+the compiler is forced to call a generic array access routine.  You
+can detect inefficient array accesses by enabling efficiency notes,
+\pxlref{efficiency-notes}.
+
+%%\node Vectors, Bit-Vectors, Arrays, Object Representation
+\subsection{Vectors}
+\cpsubindex{vectors}{efficiency of}
+
+Vectors (one dimensional arrays) are particularly useful, since in
+addition to their obvious array-like applications, they are also well
+suited to representing sequences.  In comparison to a list
+representation, vectors are faster to access and take up between two
+and sixty-four times less space (depending on the element type.)  As
+with arbitrary arrays, the compiler needs to know that vectors are not
+complex, so you should use \code{simple-string} in preference to
+\code{string}, etc.
+
+The only advantage that lists have over vectors for representing
+sequences is that it is easy to change the length of a list, add to it
+and remove items from it.  Likely signs of archaic, slow lisp code are
+\code{nth} and \code{nthcdr}.  If you are using these functions you
+should probably be using a vector.
+
+%%\node Bit-Vectors, Hashtables, Vectors, Object Representation
+\subsection{Bit-Vectors}
+\cpsubindex{bit-vectors}{efficiency of}
+
+Another thing that lists have been used for is set manipulation.  In
+applications where there is a known, reasonably small universe of
+items bit-vectors can be used to improve performance.  This is much
+less convenient than using lists, because instead of symbols, each
+element in the universe must be assigned a numeric index into the bit
+vector.  Using a bit-vector will nearly always be faster, and can be
+tremendously faster if the number of elements in the set is not small.
+The logical operations on \code{simple-bit-vector}s are efficient,
+since they operate on a word at a time.
+
+
+%%\node Hashtables,  , Bit-Vectors, Object Representation
+\subsection{Hashtables}
+\cpsubindex{hash-tables}{efficiency of}
+
+Hashtables are an efficient and general mechanism for maintaining associations
+such as the association between an object and its name.  Although hashtables
+are usually the best way to maintain associations, efficiency and style
+considerations sometimes favor the use of an association list (a-list).
+
+\code{assoc} is fairly fast when the \var{test} argument is \code{eq}
+or \code{eql} and there are only a few elements, but the time goes up
+in proportion with the number of elements.  In contrast, the
+hash-table lookup has a somewhat higher overhead, but the speed is
+largely unaffected by the number of entries in the table.  For an
+\code{equal} hash-table or alist, hash-tables have an even greater
+advantage, since the test is more expensive.  Whatever you do, be sure
+to use the most restrictive test function possible.
+
+The style argument observes that although hash-tables and alists
+overlap in function, they do not do all things equally well.
+\begin{itemize}
+
+\item Alists are good for maintaining scoped environments.  They were
+  originally invented to implement scoping in the Lisp interpreter,
+  and are still used for this in \python.  With an alist one can
+  non-destructively change an association simply by consing a new
+  element on the front.  This is something that cannot be done with
+  hash-tables.
+
+\item Hashtables are good for maintaining a global association.  The
+  value associated with an entry can easily be changed with
+  \code{setf}.  With an alist, one has to go through contortions,
+  either \code{rplacd}'ing the cons if the entry exists, or pushing a
+  new one if it doesn't.  The side-effecting nature of hash-table
+  operations is an advantage here.
+\end{itemize}
+
+
+Historically, symbol property lists were often used for global name
+associations.  Property lists provide an awkward and error-prone
+combination of name association and record structure.  If you must use
+the property list, please store all the related values in a single
+structure under a single property, rather than using many properties.
+This makes access more efficient, and also adds a modicum of typing
+and abstraction.  \xlref{advanced-type-stuff} for information on types
+in \cmucl.
+
+%%
+%%\node Numbers, General Efficiency Hints, Object Representation, Advanced Compiler Use and Efficiency Hints
+\section{Numbers}
+\label{numeric-types}
+\cpsubindex{numeric}{types}
+\cpsubindex{types}{numeric}
+
+Numbers are interesting because numbers are one of the few \llisp{} data types
+that have direct support in conventional hardware.  If a number can be
+represented in the way that the hardware expects it, then there is a big
+
+Using hardware representations is problematical in \llisp{} due to
+dynamic typing (where the type of a value may be unknown at compile
+time.)  It is possible to compile code for statically typed portions
+of a \llisp{} program with efficiency comparable to that obtained in
+statically typed languages such as C, but not all \llisp{}
+implementations succeed.  There are two main barriers to efficient
+numerical code in \llisp{}:
+\begin{itemize}
+
+\item The compiler must prove that the numerical expression is in fact
+  statically typed, and
+
+\item The compiler must be able to somehow reconcile the conflicting
+  demands of the hardware mandated number representation with the
+  \llisp{} requirements of dynamic typing and garbage-collecting
+  dynamic storage allocation.
+\end{itemize}
+
+Because of its type inference (\pxlref{type-inference}) and efficiency
+notes (\pxlref{efficiency-notes}), \python{} is better than
+conventional \llisp{} compilers at ensuring that numerical expressions
+are statically typed.  Python also goes somewhat farther than existing
+compilers in the area of allowing native machine number
+representations in the presence of garbage collection.
+
+\begin{comment}
+* Descriptors::
+* Non-Descriptor Representations::
+* Variables::
+* Generic Arithmetic::
+* Fixnums::
+* Word Integers::
+* Floating Point Efficiency::
+* Specialized Arrays::
+* Specialized Structure Slots::
+* Interactions With Local Call::
+* Representation of Characters::
+\end{comment}
+
+%%\node Descriptors, Non-Descriptor Representations, Numbers, Numbers
+\subsection{Descriptors}
+\cpsubindex{descriptors}{object}
+\cindex{object representation}
+\cpsubindex{representation}{object}
+
+\llisp{}'s dynamic typing requires that it be possible to represent
+any value with a fixed length object, known as a \var{descriptor}.
+This fixed-length requirement is implicit in features such as:
+\begin{itemize}
+
+\item Data types (like \code{simple-vector}) that can contain any type
+  of object, and that can be destructively modified to contain
+  different objects (of possibly different types.)
+
+\item Functions that can be called with any type of argument, and that
+  can be redefined at run time.
+\end{itemize}
+
+In order to save space, a descriptor is invariably represented as a
+single word.  Objects that can be directly represented in the
+descriptor itself are said to be \var{immediate}.  Descriptors for
+objects larger than one word are in reality pointers to the memory
+actually containing the object.
+
+Representing objects using pointers has two major disadvantages:
+\begin{itemize}
+
+\item The memory pointed to must be allocated on the heap, so it must
+  eventually be freed by the garbage collector.  Excessive heap
+  allocation of objects (or consing'') is inefficient in several
+  ways.  \xlref{consing}.
+
+\item Representing an object in memory requires the compiler to emit
+  additional instructions to read the actual value in from memory, and
+  then to write the value back after operating on it.
+\end{itemize}
+
+The introduction of garbage collection makes things even worse, since
+the garbage collector must be able to determine whether a descriptor
+is an immediate object or a pointer.  This requires that a few bits in
+each descriptor be dedicated to the garbage collector.  The loss of a
+few bits doesn't seem like much, but it has a major efficiency
+implication\dash{}objects whose natural machine representation is a
+full word (integers and single-floats) cannot have an immediate
+representation.  So the compiler is forced to use an unnatural
+immediate representation (such as \code{fixnum}) or a natural pointer
+representation (with the attendant consing overhead.)
+
+
+%%\node Non-Descriptor Representations, Variables, Descriptors, Numbers
+\subsection{Non-Descriptor Representations}
+\label{non-descriptor}
+\cindex{non-descriptor representations}
+\cindex{stack numbers}
+
+From the discussion above, we can see that the standard descriptor
+representation has many problems, the worst being number consing.
+\llisp{} compilers try to avoid these descriptor efficiency problems by using
+\var{non-descriptor} representations.  A compiler that uses non-descriptor
+representations can compile this function so that it does no number consing:
+\begin{lisp}
+(defun multby (vec n)
+  (declare (type (simple-array single-float (*)) vec)
+           (single-float n))
+  (dotimes (i (length vec))
+    (setf (aref vec i)
+          (* n (aref vec i)))))
+\end{lisp}
+If a descriptor representation were used, each iteration of the loop might
+cons two floats and do three times as many memory references.
+
+As its negative definition suggests, the range of possible non-descriptor
+representations is large.  The performance improvement from non-descriptor
+representation depends upon both the number of types that have non-descriptor
+representations and the number of contexts in which the compiler is forced to
+use a descriptor representation.
+
+Many \llisp{} compilers support non-descriptor representations for
+float types such as \code{single-float} and \code{double-float}
+(section \ref{float-efficiency}.)  \python{} adds support for full
+word integers (\pxlref{word-integers}), characters
+(\pxlref{characters}) and system-area pointers (unconstrained
+pointers, \pxlref{system-area-pointers}.)  Many \llisp{} compilers
+support non-descriptor representations for variables (section
+\ref{ND-variables}) and array elements (section
+non-descriptor arguments and return values in local call
+(\pxlref{number-local-call}) and structure slots (\pxlref{raw-slots}).
+
+%%\node Variables, Generic Arithmetic, Non-Descriptor Representations, Numbers
+\subsection{Variables}
+\label{ND-variables}
+\cpsubindex{variables}{non-descriptor}
+\cpsubindex{type declarations}{variable}
+\cpsubindex{efficiency}{of numeric variables}
+
+In order to use a non-descriptor representation for a variable or
+expression intermediate value, the compiler must be able to prove that
+the value is always of a particular type having a non-descriptor
+representation.  Type inference (\pxlref{type-inference}) often needs
+some help from user-supplied declarations.  The best kind of type
+declaration is a variable type declaration placed at the binding
+point:
+\begin{lisp}
+(let ((x (car l)))
+  (declare (single-float x))
+  ...)
+\end{lisp}
+Use of \code{the}, or of variable declarations not at the binding form
+is insufficient to allow non-descriptor representation of the
+variable\dash{}with these declarations it is not certain that all
+values of the variable are of the right type.  It is sometimes useful
+to introduce a gratuitous binding that allows the compiler to change
+to a non-descriptor representation, like:
+\begin{lisp}
+(etypecase x
+  ((signed-byte 32)
+   (let ((x x))
+     (declare (type (signed-byte 32) x))
+     ...))
+  ...)
+\end{lisp}
+The declaration on the inner \code{x} is necessary here due to a phase
+ordering problem.  Although the compiler will eventually prove that
+the outer \code{x} is a \w{\code{(signed-byte 32)}} within that
+\code{etypecase} branch, the inner \code{x} would have been optimized
+away by that time.  Declaring the type makes let optimization more
+cautious.
+
+Note that storing a value into a global (or \code{special}) variable
+always forces a descriptor representation.  Wherever possible, you
+should operate only on local variables, binding any referenced globals
+to local variables at the beginning of the function, and doing any
+global assignments at the end.
+
+Efficiency notes signal use of inefficient representations, so
+programmer's needn't continuously worry about the details of
+representation selection (\pxlref{representation-eff-note}.)
+
+%%\node Generic Arithmetic, Fixnums, Variables, Numbers
+\subsection{Generic Arithmetic}
+\label{generic-arithmetic}
+\cindex{generic arithmetic}
+\cpsubindex{arithmetic}{generic}
+\cpsubindex{numeric}{operation efficiency}
+
+In \clisp, arithmetic operations are \var{generic}.\footnote{As Steele
+  notes in CLTL II, this is a generic conception of generic, and is
+  not to be confused with the CLOS concept of a generic function.}
+The \code{+} function can be passed \code{fixnum}s, \code{bignum}s,
+\code{ratio}s, and various kinds of \code{float}s and
+\code{complex}es, in any combination.  In addition to the inherent
+complexity of \code{bignum} and \code{ratio} operations, there is also
+a lot of overhead in just figuring out which operation to do and what
+contagion and canonicalization rules apply.  The complexity of generic
+arithmetic is so great that it is inconceivable to open code it.
+Instead, the compiler does a function call to a generic arithmetic
+routine, consuming many instructions before the actual computation
+even starts.
+
+This is ridiculous, since even \llisp{} programs do a lot of
+arithmetic, and the hardware is capable of doing operations on small
+integers and floats with a single instruction.  To get acceptable
+efficiency, the compiler special-cases uses of generic arithmetic that
+are directly implemented in the hardware.  In order to open code
+arithmetic, several constraints must be met:
+\begin{itemize}
+
+\item All the arguments must be known to be a good type of number.
+
+\item The result must be known to be a good type of number.
+
+\item Any intermediate values such as the result of \w{\code{(+ a b)}}
+  in the call \w{\code{(+ a b c)}} must be known to be a good type of
+  number.
+
+\item All the above numbers with good types must be of the \var{same}
+  good type.  Don't try to mix integers and floats or different float
+  formats.
+\end{itemize}
+
+The good types'' are \w{\code{(signed-byte 32)}},
+\w{\code{(unsigned-byte 32)}}, \code{single-float} and
+\code{double-float}.  See sections \ref{fixnums}, \ref{word-integers}
+and \ref{float-efficiency} for more discussion of good numeric types.
+
+\code{float} is not a good type, since it might mean either
+\code{single-float} or \code{double-float}.  \code{integer} is not a
+good type, since it might mean \code{bignum}.  \code{rational} is not
+a good type, since it might mean \code{ratio}.  Note however that
+these types are still useful in declarations, since type inference may
+be able to strengthen a weak declaration into a good one, when it
+would be at a loss if there was no declaration at all
+(\pxlref{type-inference}).  The \code{integer} and
+\code{unsigned-byte} (or non-negative integer) types are especially
+useful in this regard, since they can often be strengthened to a good
+integer type.
+
+Arithmetic with \code{complex} numbers is inefficient in comparison to
+float and integer arithmetic.  Complex numbers are always represented
+with a pointer descriptor (causing consing overhead), and complex
+arithmetic is always closed coded using the general generic arithmetic
+functions.  But arithmetic with complex types such as:
+\begin{lisp}
+(complex float)
+(complex fixnum)
+\end{lisp}
+is still faster than \code{bignum} or \code{ratio} arithmetic, since the
+implementation is much simpler.
+
+Note: don't use \code{/} to divide integers unless you want the
+overhead of rational arithmetic.  Use \code{truncate} even when you
+know that the arguments divide evenly.
+
+You don't need to remember all the rules for how to get open-coded
+arithmetic, since efficiency notes will tell you when and where there
+is a problem\dash{}\pxlref{efficiency-notes}.
+
+
+%%\node Fixnums, Word Integers, Generic Arithmetic, Numbers
+\subsection{Fixnums}
+\label{fixnums}
+\cindex{fixnums}
+\cindex{bignums}
+
+A fixnum is a FIXed precision NUMber''.  In modern \llisp{}
+implementations, fixnums can be represented with an immediate
+descriptor, so operating on fixnums requires no consing or memory
+references.  Clever choice of representations also allows some
+arithmetic operations to be done on fixnums using hardware supported
+word-integer instructions, somewhat reducing the speed penalty for
+using an unnatural integer representation.
+
+It is useful to distinguish the \code{fixnum} type from the fixnum
+representation of integers.  In \python, there is absolutely nothing
+magical about the \code{fixnum} type in comparison to other finite
+integer types.  \code{fixnum} is equivalent to (is defined with
+\code{deftype} to be) \w{\code{(signed-byte 30)}}.  \code{fixnum} is
+simply the largest subset of integers that \i{can be represented}
+using an immediate fixnum descriptor.
+
+Unlike in other \clisp{} compilers, it is in no way desirable to use
+the \code{fixnum} type in declarations in preference to more
+restrictive integer types such as \code{bit}, \w{\code{(integer -43
+    7)}} and \w{\code{(unsigned-byte 8)}}.  Since Python does
+understand these integer types, it is preferable to use the more
+restrictive type, as it allows better type inference
+(\pxlref{operation-type-inference}.)
+
+The small, efficient fixnum is contrasted with bignum, or BIG
+NUMber''.  This is another descriptor representation for integers, but
+this time a pointer representation that allows for arbitrarily large
+integers.  Bignum operations are less efficient than fixnum
+operations, both because of the consing and memory reference overheads
+of a pointer descriptor, and also because of the inherent complexity
+of extended precision arithmetic.  While fixnum operations can often
+be done with a single instruction, bignum operations are so complex
+that they are always done using generic arithmetic.
+
+A crucial point is that the compiler will use generic arithmetic if it
+can't \var{prove} that all the arguments, intermediate values, and
+results are fixnums.  With bounded integer types such as
+\code{fixnum}, the result type proves to be especially problematical,
+since these types are not closed under common arithmetic operations
+such as \code{+}, \code{-}, \code{*} and \code{/}.  For example,
+\w{\code{(1+ (the fixnum x))}} does not necessarily evaluate to a
+\code{fixnum}.  Bignums were added to \llisp{} to get around this
+problem, but they really just transform the correctness problem if
+this add overflows, you will get the wrong answer'' to the efficiency
+problem if this add \var{might} overflow then your program will run
+slowly (because of generic arithmetic.)''
+
+There is just no getting around the fact that the hardware only
+directly supports short integers.  To get the most efficient open
+coding, the compiler must be able to prove that the result is a good
+integer type.  This is an argument in favor of using more restrictive
+integer types: \w{\code{(1+ (the fixnum x))}} may not always be a
+\code{fixnum}, but \w{\code{(1+ (the (unsigned-byte 8) x))}} always
+is.  Of course, you can also assert the result type by putting in lots
+of \code{the} declarations and then compiling with \code{safety}
+\code{0}.
+
+%%\node Word Integers, Floating Point Efficiency, Fixnums, Numbers
+\subsection{Word Integers}
+\label{word-integers}
+\cindex{word integers}
+
+Python is unique in its efficient implementation of arithmetic
+on full-word integers through non-descriptor representations and open coding.
+Arithmetic on any subtype of these types:
+\begin{lisp}
+(signed-byte 32)
+(unsigned-byte 32)
+\end{lisp}
+is reasonably efficient, although subtypes of \code{fixnum} remain
+somewhat more efficient.
+
+If a word integer must be represented as a descriptor, then the
+\code{bignum} representation is used, with its associated consing
+overhead.  The support for word integers in no way changes the
+language semantics, it just makes arithmetic on small bignums vastly
+more efficient.  It is fine to do arithmetic operations with mixed
+\code{fixnum} and word integer operands; just declare the most
+specific integer type you can, and let the compiler decide what
+representation to use.
+
+In fact, to most users, the greatest advantage of word integer
+arithmetic is that it effectively provides a few guard bits on the
+fixnum representation.  If there are missing assertions on
+intermediate values in a fixnum expression, the intermediate results
+can usually be proved to fit in a word.  After the whole expression is
+evaluated, there will often be a fixnum assertion on the final result,
+allowing creation of a fixnum result without even checking for
+overflow.
+
+The remarks in section \ref{fixnums} about fixnum result type also
+apply to word integers; you must be careful to give the compiler
+enough information to prove that the result is still a word integer.
+This time, though, when we blow out of word integers we land in into
+generic bignum arithmetic, which is much worse than sleazing from
+\code{fixnum}s to word integers.  Note that mixing
+\w{\code{(unsigned-byte 32)}} arguments with arguments of any signed
+type (such as \code{fixnum}) is a no-no, since the result might not be
+unsigned.
+
+%%\node Floating Point Efficiency, Specialized Arrays, Word Integers, Numbers
+\subsection{Floating Point Efficiency}
+\label{float-efficiency}
+\cindex{floating point efficiency}
+
+Arithmetic on objects of type \code{single-float} and \code{double-float} is
+efficiently implemented using non-descriptor representations and open coding.
+As for integer arithmetic, the arguments must be known to be of the same float
+type.  Unlike for integer arithmetic, the results and intermediate values
+usually take care of themselves due to the rules of float contagion, i.e.
+\w{\code{(1+ (the single-float x))}} is always a \code{single-float}.
+
+Although they are not specially implemented, \code{short-float} and
+\code{long-float} are also acceptable in declarations, since they are
+synonyms for the \code{single-float} and \code{double-float} types,
+respectively.
+
+\begin{changebar}
+  Some versions of CMU Common Lisp include extra support for floating
+  point arithmetic.  In particular, if \code{*features*} includes
+  \kwd{propagate-float-type}, list-style float type specifiers such as
+  \w{\code{(single-float 0.0 1.0)}} will be used to good effect.
+
+  For example, in this function,
+  \begin{example}
+    (defun square (x)
+      (declare (type (single-float 0f0 10f0)))
+      (* x x))
+  \end{example}
+  \Python{} can deduce that the
+  return type of the function \code{square} is \w{\code{(single-float
+      0f0 100f0)}}.
+
+  Many union types are also supported so that
+  \begin{example}
+    (+ (the (or (integer 1 1) (integer 5 5)) x)
+       (the (or (integer 10 10) (integer 20 20)) y))
+  \end{example}
+  has the inferred type \code{(or (integer 11 11) (integer 15 15)
+    (integer 21 21) (integer 25 25))}.  This also works for
+  floating-point numbers.  Member types, however, are not because in
+  general the member elements do not have to be numbers.  Thus,
+  instead of \code{(member 1 4)}, you should write \code{(or (integer
+    1 1) (integer 4 4))}.
+
+  In addition, if \kwd{propagate-fun-type} is in \code{*features*},
+  \Python{} knows how to infer types for many mathematical functions
+  including square root, exponential and logarithmic functions,
+  trignometric functions and their inverses, and hyperbolic functions
+  and their inverses.  For numeric code, this can greatly enhance
+  efficiency by allowing the compiler to use specialized versions of
+  the functions instead of the generic versions.  The greatest benefit
+  of this type inference is determining that the result of the
+  function is real-valued number instead of possibly being
+  a complex-valued number.
+
+  For example, consider the function
+  \begin{example}
+    (defun fun (x)
+      (declare (type (single-float 0f0 100f0) x))
+      (values (sqrt x) (log x 10f0)))
+  \end{example}
+  With this declaration, the compiler can determine that the argument
+  to \code{sqrt} and \code{log} are always non-negative so that the result
+  is always a \code{single-float}.  In fact, the return type for this
+  function is derived to be \code{(values (single-float 0f0 10f0)
+      (single-float * 2f0))}.
+
+  If the declaration were reduced to just \w{\code{(declare
+      single-float x)}}, the argument to \code{sqrt} and \code{log}
+  could be negative.  This forces the use of the generic versions of
+  these functions because the result could be a complex number.
+
+  Union types are not yet supported for functions.
+
+  We note, however, that proper interval arithmetic is not fully
+  implemented in the compiler so the inferred types may be slightly in
+  error due to round-off errors.  This round-off error could
+  accumulate to cause the compiler to erroneously deduce the result
+  type and cause code to be removed as being
+  unreachable.\footnote{This, however, has not actually happened, but
+    it is a possibility.}%
+  Thus, the declarations should only be precise enough for the
+  compiler to deduce that a real-valued argument to a function would
+  produce a real-valued result.  The efficiency notes
+  (\pxlref{representation-eff-note}) from the compiler will guide you
+  on what declarations might be useful.
+\end{changebar}
+
+When a float must be represented as a descriptor, a pointer representation is
+used, creating consing overhead.  For this reason, you should try to avoid
+situations (such as full call and non-specialized data structures) that force a
+descriptor representation.  See sections \ref{specialized-array-types},
+\ref{raw-slots} and \ref{number-local-call}.
+
+\xlref{ieee-float} for information on the extensions to support IEEE
+floating point.
+
+%%\node Specialized Arrays, Specialized Structure Slots, Floating Point Efficiency, Numbers
+\subsection{Specialized Arrays}
+\label{specialized-array-types}
+\cindex{specialized array types}
+\cpsubindex{array types}{specialized}
+\cpsubindex{types}{specialized array}
+
+\clisp{} supports specialized array element types through the
+\kwd{element-type} argument to \code{make-array}.  When an array has a
+specialized element type, only elements of that type can be stored in
+the array.  From this restriction comes two major efficiency
+\begin{itemize}
+
+\item A specialized array can save space by packing multiple elements
+  into a single word.  For example, a \code{base-char} array can have
+  4 elements per word, and a \code{bit} array can have 32.  This
+  space-efficient representation is possible because it is not
+  necessary to separately indicate the type of each element.
+
+\item The elements in a specialized array can be given the same
+  non-descriptor representation as the one used in registers and on
+  the stack, eliminating the need for representation conversions when
+  reading and writing array elements.  For objects with pointer
+  descriptor representations (such as floats and word integers) there
+  is also a substantial consing reduction because it is not necessary
+  to allocate a new object every time an array element is modified.
+\end{itemize}
+
+
+These are the specialized element types currently supported:
+\begin{lisp}
+bit
+(unsigned-byte 2)
+(unsigned-byte 4)
+(unsigned-byte 8)
+(unsigned-byte 16)
+(unsigned-byte 32)
+base-character
+single-float
+double-float
+\end{lisp}
+\begin{changebar}
+%% New stuff
+Some versions of \cmucl{}\footnote{Currently, this includes the X86
+  and Sparc versions which are compiled with the \kwd{signed-array}
+  feature.} also support the following specialized element types:
+\begin{lisp}
+(signed-byte 8)
+(signed-byte 16)
+(signed-byte 30)
+(signed-byte 32)
+\end{lisp}
+\end{changebar}
+Although a \code{simple-vector} can hold any type of object, \true{}
+should still be considered a specialized array type, since arrays with
+element type \true{} are specialized to hold descriptors.
+
+
+
+When using non-descriptor representations, it is particularly
+important to make sure that array accesses are open-coded, since in
+the array element is converted to a descriptor so that it can be
+passed to (or from) the generic access routine.  You can detect
+inefficient array accesses by enabling efficiency notes,
+\pxlref{efficiency-notes}.  \xlref{array-types}.
+
+%%\node Specialized Structure Slots, Interactions With Local Call, Specialized Arrays, Numbers
+\subsection{Specialized Structure Slots}
+\label{raw-slots}
+\cpsubindex{structure types}{numeric slots}
+\cindex{specialized structure slots}
+
+Structure slots declared by the \kwd{type} \code{defstruct} slot option
+to have certain known numeric types are also given non-descriptor
+representations.  These types (and subtypes of these types) are supported:
+\begin{lisp}
+(unsigned-byte 32)
+single-float
+double-float
+\end{lisp}
+
+The primary advantage of specialized slot representations is a large
+reduction spurious memory allocation and access overhead of programs
+that intensively use these types.
+
+%%\node Interactions With Local Call, Representation of Characters, Specialized Structure Slots, Numbers
+\subsection{Interactions With Local Call}
+\label{number-local-call}
+\cpsubindex{local call}{numeric operands}
+\cpsubindex{call}{numeric operands}
+\cindex{numbers in local call}
+
+Local call has many advantages (\pxlref{local-call}); one relevant to
+our discussion here is that local call extends the usefulness of
+non-descriptor representations.  If the compiler knows from the
+argument type that an argument has a non-descriptor representation,
+then the argument will be passed in that representation.  The easiest
+way to ensure that the argument type is known at compile time is to
+always declare the argument type in the called function, like:
+\begin{lisp}
+(defun 2+f (x)
+  (declare (single-float x))
+  (+ x 2.0))
+\end{lisp}
+The advantages of passing arguments and return values in a non-descriptor
+representation are the same as for non-descriptor representations in general:
+reduced consing and memory access (\pxlref{non-descriptor}.)  This
+extends the applicative programming styles discussed in section
+\ref{local-call} to numeric code.  Also, if source files are kept reasonably
+small, block compilation can be used to reduce number consing to a minimum.
+
+Note that non-descriptor return values can only be used with the known return
+convention (section \ref{local-call-return}.)  If the compiler can't prove that
+a function always returns the same number of values, then it must use the
+unknown values return convention, which requires a descriptor representation.
+Pay attention to the known return efficiency notes to avoid number consing.
+
+%%\node Representation of Characters,  , Interactions With Local Call, Numbers
+\subsection{Representation of Characters}
+\label{characters}
+\cindex{characters}
+\cindex{strings}
+
+Python also uses a non-descriptor representation for characters when
+convenient.  This improves the efficiency of string manipulation, but is
+otherwise pretty invisible; characters have an immediate descriptor
+representation, so there is not a great penalty for converting a character to a
+descriptor.  Nonetheless, it may sometimes be helpful to declare
+character-valued variables as \code{base-character}.
+
+%%
+%%\node General Efficiency Hints, Efficiency Notes, Numbers, Advanced Compiler Use and Efficiency Hints
+\section{General Efficiency Hints}
+\label{general-efficiency}
+\cpsubindex{efficiency}{general hints}
+
+This section is a summary of various implementation costs and ways to get
+around them.  These hints are relatively unrelated to the use of the \python{}
+compiler, and probably also apply to most other \llisp{} implementations.  In
+each section, there are references to related in-depth discussion.
+
+\begin{comment}
+* Avoid Unnecessary Consing::
+* Complex Argument Syntax::
+* Mapping and Iteration::
+* Trace Files and Disassembly::
+\end{comment}
+
+%%\node Compile Your Code, Avoid Unnecessary Consing, General Efficiency Hints, General Efficiency Hints
+\cpsubindex{compilation}{why to}
+
+At this point, the advantages of compiling code relative to running it
+interpreted probably need not be emphasized too much, but remember that
+in \cmucl, compiled code typically runs hundreds of times faster than
+interpreted code.  Also, compiled (\code{fasl}) files load significantly faster
+than source files, so it is worthwhile compiling files which are loaded many
+times, even if the speed of the functions in the file is unimportant.
+
+Even disregarding the efficiency advantages, compiled code is as good or better
+than interpreted code.  Compiled code can be debugged at the source level (see
+chapter \ref{debugger}), and compiled code does more error checking.  For these
+reasons, the interpreter should be regarded mainly as an interactive command
+interpreter, rather than as a programming language implementation.
+
+\b{Do not} be concerned about the performance of your program until you
+see its speed compiled.  Some techniques that make compiled code run
+faster make interpreted code run slower.
+
+%%\node Avoid Unnecessary Consing, Complex Argument Syntax, Compile Your Code, General Efficiency Hints
+\subsection{Avoid Unnecessary Consing}
+\label{consing}
+\cindex{consing}
+\cindex{garbage collection}
+\cindex{memory allocation}
+\cpsubindex{efficiency}{of memory use}
+
+
+Consing is another name for allocation of storage, as done by the
+\code{cons} function (hence its name.)  \code{cons} is by no means the
+only function which conses\dash{}so does \code{make-array} and many
+other functions.  Arithmetic and function call can also have hidden
+consing overheads.  Consing hurts performance in the following ways:
+\begin{itemize}
+
+\item Consing reduces memory access locality, increasing paging
+  activity.
+
+\item Consing takes time just like anything else.
+
+\item Any space allocated eventually needs to be reclaimed, either by
+  garbage collection or by starting a new \code{lisp} process.
+\end{itemize}
+
+
+Consing is not undiluted evil, since programs do things other than
+consing, and appropriate consing can speed up the real work.  It would
+certainly save time to allocate a vector of intermediate results that
+are reused hundreds of times.  Also, if it is necessary to copy a
+large data structure many times, it may be more efficient to update
+the data structure non-destructively; this somewhat increases update
+
+Note that the remarks in section \ref{efficiency-overview} about the
+importance of separating tuning from coding also apply to consing
+overhead.  The majority of consing will be done by a small portion of
+the program.  The consing hot spots are even less predictable than the
+CPU hot spots, so don't waste time and create bugs by doing
+unnecessary consing optimization.  During initial coding, avoid
+unnecessary side-effects and cons where it is convenient.  If
+profiling reveals a consing problem, \var{then} go back and fix the
+hot spots.
+
+\xlref{non-descriptor} for a discussion of how to avoid number consing
+in \python.
+
+
+%%\node Complex Argument Syntax, Mapping and Iteration, Avoid Unnecessary Consing, General Efficiency Hints
+\subsection{Complex Argument Syntax}
+\cpsubindex{argument syntax}{efficiency}
+\cpsubindex{efficiency}{of argument syntax}
+\cindex{keyword argument efficiency}
+\cindex{rest argument efficiency}
+
+Common Lisp has very powerful argument passing mechanisms.  Unfortunately, two
+of the most powerful mechanisms, rest arguments and keyword arguments, have a
+significant performance penalty:
+\begin{itemize}
+
+\item
+With keyword arguments, the called function has to parse the supplied keywords
+by iterating over them and checking them against the desired keywords.
+
+\item
+With rest arguments, the function must cons a list to hold the arguments.  If a
+function is called many times or with many arguments, large amounts of memory
+will be allocated.
+\end{itemize}
+
+Although rest argument consing is worse than keyword parsing, neither problem
+is serious unless thousands of calls are made to such a function.  The use of
+keyword arguments is strongly encouraged in functions with many arguments or
+with interfaces that are likely to be extended, and rest arguments are often
+natural in user interface functions.
+
+Optional arguments have some efficiency advantage over keyword
+arguments, but their syntactic clumsiness and lack of extensibility
+has caused many \clisp{} programmers to abandon use of optionals
+except in functions that have obviously simple and immutable
+interfaces (such as \code{subseq}), or in functions that are only
+called in a few places.  When defining an interface function to be
+used by other programmers or users, use of only required and keyword
+arguments is recommended.
+
+Parsing of \code{defmacro} keyword and rest arguments is done at
+compile time, so a macro can be used to provide a convenient syntax
+with an efficient implementation.  If the macro-expanded form contains
+no keyword or rest arguments, then it is perfectly acceptable in inner
+loops.
+
+Keyword argument parsing overhead can also be avoided by use of inline
+expansion (\pxlref{inline-expansion}) and block compilation (section
+\ref{block-compilation}.)
+
+Note: the compiler open-codes most heavily used system functions which have
+keyword or rest arguments, so that no run-time overhead is involved.
+
+%%\node Mapping and Iteration, Trace Files and Disassembly, Complex Argument Syntax, General Efficiency Hints
+\subsection{Mapping and Iteration}
+\cpsubindex{mapping}{efficiency of}
+
+One of the traditional \llisp{} programming styles is a highly applicative one,
+involving the use of mapping functions and many lists to store intermediate
+results.  To compute the sum of the square-roots of a list of numbers, one
+might say:
+\begin{lisp}
+(apply #'+ (mapcar #'sqrt list-of-numbers))
+\end{lisp}
+
+This programming style is clear and elegant, but unfortunately results
+in slow code.  There are two reasons why:
+\begin{itemize}
+
+\item The creation of lists of intermediate results causes much
+  consing (see \ref{consing}).
+
+\item Each level of application requires another scan down the list.
+  Thus, disregarding other effects, the above code would probably take
+  twice as long as a straightforward iterative version.
+\end{itemize}
+
+
+An example of an iterative version of the same code:
+\begin{lisp}
+(do ((num list-of-numbers (cdr num))
+     (sum 0 (+ (sqrt (car num)) sum)))
+    ((null num) sum))
+\end{lisp}
+
+See sections \ref{variable-type-inference} and \ref{let-optimization}
+for a discussion of the interactions of iteration constructs with type
+inference and variable optimization.  Also, section
+\ref{local-tail-recursion} discusses an applicative style of
+iteration.
+
+%%\node Trace Files and Disassembly,  , Mapping and Iteration, General Efficiency Hints
+\subsection{Trace Files and Disassembly}
+\label{trace-files}
+\cindex{trace files}
+\cindex{assembly listing}
+\cpsubindex{listing files}{trace}
+\cindex{Virtual Machine (VM, or IR2) representation}
+\cindex{implicit continuation representation (IR1)}
+\cpsubindex{continuations}{implicit representation}
+
+In order to write efficient code, you need to know the relative costs
+of different operations.  The main reason why writing efficient
+\llisp{} code is difficult is that there are so many operations, and
+the costs of these operations vary in obscure context-dependent ways.
+Although efficiency notes point out some problem areas, the only way
+to ensure generation of the best code is to look at the assembly code
+output.
+
+The \code{disassemble} function is a convenient way to get the assembly code for a
+function, but it can be very difficult to interpret, since the correspondence
+with the original source code is weak.  A better (but more awkward) option is
+to use the \kwd{trace-file} argument to \code{compile-file} to generate a trace
+file.
+
+A trace file is a dump of the compiler's internal representations,
+including annotated assembly code.  Each component in the program gets
+four pages in the trace file (separated by \code{$\hat{ }L$}''):
+\begin{itemize}
+
+\item The implicit-continuation (or IR1) representation of the
+  optimized source.  This is a dump of the flow graph representation
+  used for source level'' optimizations.  As you will quickly
+  notice, it is not really very close to the source.  This
+  representation is not very useful to even sophisticated users.
+
+\item The Virtual Machine (VM, or IR2) representation of the program.
+  This dump represents the generated code as sequences of Virtual
+  OPerations'' (VOPs.)  This representation is intermediate between
+  the source and the assembly code\dash{}each VOP corresponds fairly
+  directly to some primitive function or construct, but a given VOP
+  also has a fairly predictable instruction sequence.  An operation
+  (such as \code{+}) may have multiple implementations with different
+  cost and applicability.  The choice of a particular VOP such as
+  \code{+/fixnum} or \code{+/single-float} represents this choice of
+  implementation.  Once you are familiar with it, the VM
+  representation is probably the most useful for determining what
+  implementation has been used.
+
+\item An assembly listing, annotated with the VOP responsible for
+  generating the instructions.  This listing is useful for figuring
+  out what a VOP does and how it is implemented in a particular
+  context, but its large size makes it more difficult to read.
+
+\item A disassembly of the generated code, which has all
+  pseudo-operations expanded out, but is not annotated with VOPs.
+\end{itemize}
+
+
+Note that trace file generation takes much space and time, since the trace file
+is tens of times larger than the source file.  To avoid huge confusing trace
+files and much wasted time, it is best to separate the critical program portion
+into its own file and then generate the trace file from this small file.
+
+%%
+%%\node Efficiency Notes, Profiling, General Efficiency Hints, Advanced Compiler Use and Efficiency Hints
+\section{Efficiency Notes}
+\label{efficiency-notes}
+\cindex{efficiency notes}
+\cpsubindex{notes}{efficiency}
+\cindex{tuning}
+
+Efficiency notes are messages that warn the user that the compiler has
+chosen a relatively inefficient implementation for some operation.
+Usually an efficiency note reflects the compiler's desire for more
+type information.  If the type of the values concerned is known to the
+programmer, then additional declarations can be used to get a more
+efficient implementation.
+
+Efficiency notes are controlled by the
+\code{extensions:inhibit-warnings} (\pxlref{optimize-declaration})
+optimization quality. When \code{speed} is greater than
+\code{extensions:inhibit-warnings}, efficiency notes are enabled.
+Note that this implicitly enables efficiency notes whenever
+\code{speed} is increased from its default of \code{1}.
+
+Consider this program with an obscure missing declaration:
+\begin{lisp}
+(defun eff-note (x y z)
+  (declare (fixnum x y z))
+  (the fixnum (+ x y z)))
+\end{lisp}
+If compiled with \code{\w{(speed 3) (safety 0)}}, this note is given:
+\begin{example}
+In: DEFUN EFF-NOTE
+  (+ X Y Z)
+==>
+  (+ (+ X Y) Z)
+Note: Forced to do inline (signed-byte 32) arithmetic (cost 3).
+      Unable to do inline fixnum arithmetic (cost 2) because:
+      The first argument is a (INTEGER -1073741824 1073741822),
+      not a FIXNUM.
+\end{example}
+This efficiency note tells us that the result of the intermediate
+computation \code{\w{(+ x y)}} is not known to be a \code{fixnum}, so
+the addition of the intermediate sum to \code{z} must be done less
+efficiently.  This can be fixed by changing the definition of
+\code{eff-note}:
+\begin{lisp}
+(defun eff-note (x y z)
+  (declare (fixnum x y z))
+  (the fixnum (+ (the fixnum (+ x y)) z)))
+\end{lisp}
+
+\begin{comment}
+* Type Uncertainty::
+* Efficiency Notes and Type Checking::
+* Representation Efficiency Notes::
+* Verbosity Control::
+\end{comment}
+
+%%\node Type Uncertainty, Efficiency Notes and Type Checking, Efficiency Notes, Efficiency Notes
+\subsection{Type Uncertainty}
+\cpsubindex{types}{uncertainty}
+\cindex{uncertainty of types}
+
+The main cause of inefficiency is the compiler's lack of adequate
+information about the types of function argument and result values.
+Many important operations (such as arithmetic) have an inefficient
+general (generic) case, but have efficient implementations that can
+usually be used if there is sufficient argument type information.
+
+Type efficiency notes are given when a value's type is uncertain.
+There is an important distinction between values that are \i{not
+  known} to be of a good type (uncertain) and values that are \i{known
+  not} to be of a good type.  Efficiency notes are given mainly for
+the first case (uncertain types.)  If it is clear to the compiler that
+that there is not an efficient implementation for a particular
+function call, then an efficiency note will only be given if the
+\code{extensions:inhibit-warnings} optimization quality is \code{0}
+(\pxlref{optimize-declaration}.)
+
+In other words, the default efficiency notes only suggest that you add
+declarations, not that you change the semantics of your program so
+that an efficient implementation will apply.  For example, compilation
+of this form will not give an efficiency note:
+\begin{lisp}
+(elt (the list l) i)
+\end{lisp}
+even though a vector access is more efficient than indexing a list.
+
+%%\node Efficiency Notes and Type Checking, Representation Efficiency Notes, Type Uncertainty, Efficiency Notes
+\subsection{Efficiency Notes and Type Checking}
+\cpsubindex{type checking}{efficiency of}
+\cpsubindex{efficiency}{of type checking}
+\cpsubindex{optimization}{type check}
+
+It is important that the \code{eff-note} example above used
+\w{\code{(safety 0)}}.  When type checking is enabled, you may get apparently
+spurious efficiency notes.  With \w{\code{(safety 1)}}, the note has this extra
+line on the end:
+\begin{example}
+The result is a (INTEGER -1610612736 1610612733), not a FIXNUM.
+\end{example}
+This seems strange, since there is a \code{the} declaration on the result of that
+
+In fact, the inefficiency is real, and is a consequence of \python{}'s
+treating declarations as assertions to be verified.  The compiler
+can't assume that the result type declaration is true\dash{}it must
+generate the result and then test whether it is of the appropriate
+type.
+
+In practice, this means that when you are tuning a program to run
+without type checks, you should work from the efficiency notes
+generated by unsafe compilation.  If you want code to run efficiently
+with type checking, then you should pay attention to all the
+efficiency notes that you get during safe compilation.  Since user
+supplied output type assertions (e.g., from \code{the}) are
+disregarded when selecting operation implementations for safe code,
+you must somehow give the compiler information that allows it to prove
+that the result truly must be of a good type.  In our example, it
+could be done by constraining the argument types more:
+\begin{lisp}
+(defun eff-note (x y z)
+  (declare (type (unsigned-byte 18) x y z))
+  (+ x y z))
+\end{lisp}
+Of course, this declaration is acceptable only if the arguments to \code{eff-note}
+always \var{are} \w{\code{(unsigned-byte 18)}} integers.
+
+%%\node Representation Efficiency Notes, Verbosity Control, Efficiency Notes and Type Checking, Efficiency Notes
+\subsection{Representation Efficiency Notes}
+\label{representation-eff-note}
+\cindex{representation efficiency notes}
+\cpsubindex{efficiency notes}{for representation}
+\cindex{object representation efficiency notes}
+\cindex{stack numbers}
+\cindex{non-descriptor representations}
+\cpsubindex{descriptor representations}{forcing of}
+
+When operating on values that have non-descriptor representations
+(\pxlref{non-descriptor}), there can be a substantial time and consing
+penalty for converting to and from descriptor representations.  For
+this reason, the compiler gives an efficiency note whenever it is
+forced to do a representation coercion more expensive than
+\varref{efficiency-note-cost-threshold}.
+
+Inefficient representation coercions may be due to type uncertainty,
+as in this example:
+\begin{lisp}
+(defun set-flo (x)
+  (declare (single-float x))
+  (prog ((var 0.0))
+    (setq var (gorp))
+    (setq var x)
+    (return var)))
+\end{lisp}
+which produces this efficiency note:
+\begin{example}
+In: DEFUN SET-FLO
+  (SETQ VAR X)
+Note: Doing float to pointer coercion (cost 13) from X to VAR.
+\end{example}
+The variable \code{var} is not known to always hold values of type
+\code{single-float}, so a descriptor representation must be used for its value.
+In sort of situation, and adding a declaration will eliminate the inefficiency.
+
+Often inefficient representation conversions are not due to type
+uncertainty\dash{}instead, they result from evaluating a
+non-descriptor expression in a context that requires a descriptor
+result:
+\begin{itemize}
+
+\item Assignment to or initialization of any data structure other than
+  a specialized array (\pxlref{specialized-array-types}), or
+
+\item Assignment to a \code{special} variable, or
+
+\item Passing as an argument or returning as a value in any function
+  call that is not a local call (\pxlref{number-local-call}.)
+\end{itemize}
+
+If such inefficient coercions appear in a hot spot'' in the program, data
+structures redesign or program reorganization may be necessary to improve
+efficiency.  See sections \ref{block-compilation}, \ref{numeric-types} and
+\ref{profiling}.
+
+Because representation selection is done rather late in compilation,
+the source context in these efficiency notes is somewhat vague, making
+interpretation more difficult.  This is a fairly straightforward
+example:
+\begin{lisp}
+(defun cf+ (x y)
+  (declare (single-float x y))
+  (cons (+ x y) t))
+\end{lisp}
+which gives this efficiency note:
+\begin{example}
+In: DEFUN CF+
+  (CONS (+ X Y) T)
+Note: Doing float to pointer coercion (cost 13), for:
+      The first argument of CONS.
+\end{example}
+The source context form is almost always the form that receives the value being
+coerced (as it is in the preceding example), but can also be the source form
+which generates the coerced value.  Compiling this example:
+\begin{lisp}
+(defun if-cf+ (x y)
+  (declare (single-float x y))
+  (cons (if (grue) (+ x y) (snoc)) t))
+\end{lisp}
+produces this note:
+\begin{example}
+In: DEFUN IF-CF+
+  (+ X Y)
+Note: Doing float to pointer coercion (cost 13).
+\end{example}
+
+In either case, the note's text explanation attempts to include
+destination of the coercion.  Here are some example notes:
+\begin{example}
+  (IF (GRUE) X (SNOC))
+Note: Doing float to pointer coercion (cost 13) from X.
+
+  (SETQ VAR X)
+Note: Doing float to pointer coercion (cost 13) from X to VAR.
+\end{example}
+Note that the return value of a function is also a place to which coercions may
+have to be done:
+\begin{example}
+  (DEFUN F+ (X Y) (DECLARE (SINGLE-FLOAT X Y)) (+ X Y))
+Note: Doing float to pointer coercion (cost 13) to "<return value>".
+\end{example}
+Sometimes the compiler is unable to determine a name for the source or
+destination, in which case the source context is the only clue.
+
+
+%%\node Verbosity Control,  , Representation Efficiency Notes, Efficiency Notes
+\subsection{Verbosity Control}
+\cpsubindex{verbosity}{of efficiency notes}
+\cpsubindex{efficiency notes}{verbosity}
+
+These variables control the verbosity of efficiency notes:
+
+\begin{defvar}{}{efficiency-note-cost-threshold}
+
+  Before printing some efficiency notes, the compiler compares the
+  value of this variable to the difference in cost between the chosen
+  implementation and the best potential implementation.  If the
+  difference is not greater than this limit, then no note is printed.
+  The units are implementation dependent; the initial value suppresses
+  notes about trivial'' inefficiencies.  A value of \code{1} will
+  note any inefficiency.
+\end{defvar}
+
+\begin{defvar}{}{efficiency-note-limit}
+
+  When printing some efficiency notes, the compiler reports possible
+  efficient implementations.  The initial value of \code{2} prevents
+  excessively long efficiency notes in the common case where there is
+  no type information, so all implementations are possible.
+\end{defvar}
+
+%%
+%%\node Profiling,  , Efficiency Notes, Advanced Compiler Use and Efficiency Hints
+\section{Profiling}
+
+\cindex{profiling}
+\cindex{timing}
+\cindex{consing}
+\cindex{tuning}
+\label{profiling}
+
+The first step in improving a program's performance is to profile the
+activity of the program to find where it spends its time.  The best
+way to do this is to use the profiling utility found in the
+\code{profile} package.  This package provides a macro \code{profile}
+that encapsulates functions with statistics gathering code.
+
+\begin{comment}
+* Profile Interface::
+* Profiling Techniques::
+* Nested or Recursive Calls::
+* Clock resolution::
+* A Note on Timing::
+* Benchmarking Techniques::
+\end{comment}
+
+%%\node Profile Interface, Profiling Techniques, Profiling, Profiling
+\subsection{Profile Interface}
+
+\begin{defvar}{profile:}{timed-functions}
+
+  This variable holds a list of all functions that are currently being
+  profiled.
+\end{defvar}
+
+\begin{defmac}{profile:}{profile}{%
+    \args{\mstar{\var{name} \mor \kwd{callers} \code{t}}}}
+
+  This macro wraps profiling code around the named functions.  As in
+  \code{trace}, the \var{name}s are not evaluated.  If a function is
+  already profiled, then the function is unprofiled and reprofiled
+  (useful to notice function redefinition.)  A warning is printed for
+  each name that is not a defined function.
+
+  If \kwd{callers \var{t}} is specified, then each function that calls
+  this function is recorded along with the number of calls made.
+\end{defmac}
+
+\begin{defmac}{profile:}{unprofile}{%
+    \args{\mstar{\var{name}}}}
+
+  This macro removes profiling code from the named functions.  If no
+  \var{name}s are supplied, all currently profiled functions are
+  unprofiled.
+\end{defmac}
+
+\begin{changebar}
+  \begin{defmac}{profile:}{profile-all}{%
+      \args{\keys{\kwd{package} \kwd{callers-p}}}}
+
+    This macro in effect calls \code{profile:profile} for each
+    function in the specified package which defaults to
+    \code{*package*}.  \kwd{callers-p} has the same meaning as in
+    \code{profile:profile}.
+  \end{defmac}
+\end{changebar}
+
+\begin{defmac}{profile:}{report-time}{\args{\mstar{\var{name}}}}
+
+  This macro prints a report for each \var{name}d function of the
+  following information:
+  \begin{itemize}
+  \item The total CPU time used in that function for all calls,
+
+  \item the total number of bytes consed in that function for all
+    calls,
+
+  \item the total number of calls,
+
+  \item the average amount of CPU time per call.
+  \end{itemize}
+  Summary totals of the CPU time, consing and calls columns are
+  printed.  An estimate of the profiling overhead is also printed (see
+  below).  If no \var{name}s are supplied, then the times for all
+  currently profiled functions are printed.
+\end{defmac}
+
+\begin{defmac}{}{reset-time}{\args{\mstar{\var{name}}}}
+
+  This macro resets the profiling counters associated with the
+  \var{name}d functions.  If no \var{name}s are supplied, then all
+  currently profiled functions are reset.
+\end{defmac}
+
+
+%%\node Profiling Techniques, Nested or Recursive Calls, Profile Interface, Profiling
+\subsection{Profiling Techniques}
+
+Start by profiling big pieces of a program, then carefully choose which
+functions close to, but not in, the inner loop are to be profiled next.
+Avoid profiling functions that are called by other profiled functions, since
+this opens the possibility of profiling overhead being included in the reported
+times.
+
+If the per-call time reported is less than 1/10 second, then consider the clock
+resolution and profiling overhead before you believe the time.  It may be that
+you will need to run your program many times in order to average out to a
+higher resolution.
+
+
+%%\node Nested or Recursive Calls, Clock resolution, Profiling Techniques, Profiling
+\subsection{Nested or Recursive Calls}
+
+The profiler attempts to compensate for nested or recursive calls.  Time and
+consing overhead will be charged to the dynamically innermost (most recent)
+call to a profiled function.  So profiling a subfunction of a profiled function
+will cause the reported time for the outer function to decrease.  However if an
+inner function has a large number of calls, some of the profiling overhead may
+leak'' into the reported time for the outer function.  In general, be wary of
+profiling short functions that are called many times.
+
+%%\node Clock resolution, Profiling overhead, Nested or Recursive Calls, Profiling
+\subsection{Clock resolution}
+
+Unless you are very lucky, the length of your machine's clock tick'' is
+probably much longer than the time it takes simple function to run.  For
+example, on the IBM RT, the clock resolution is 1/50 second.  This means that
+if a function is only called a few times, then only the first couple decimal
+places are really meaningful.
+
+Note however, that if a function is called many times, then the statistical
+averaging across all calls should result in increased resolution.  For example,
+on the IBM RT, if a function is called a thousand times, then a resolution of
+tens of microseconds can be expected.
+
+
+The added profiling code takes time to run every time that the profiled
+function is called, which can disrupt the attempt to collect timing
+information.  In order to avoid serious inflation of the times for functions
+that take little time to run, an estimate of the overhead due to profiling is
+subtracted from the times reported for each function.
+
+Although this correction works fairly well, it is not totally accurate,
+resulting in times that become increasingly meaningless for functions with
+short runtimes.  This is only a concern when the estimated profiling overhead
+is many times larger than reported total CPU time.
+
+The estimated profiling overhead is not represented in the reported total CPU
+time.  The sum of total CPU time and the estimated profiling overhead should be
+close to the total CPU time for the entire profiling run (as determined by the
+\code{time} macro.)  Time unaccounted for is probably being used by functions that
+you forgot to profile.
+
+
+\begin{defmac}{}{time}{ \args{\var{form}}}
+
+  This macro evaluates \var{form}, prints some timing and memory
+  allocation information to \code{*trace-output*}, and returns any
+  values that \var{form} returns.  The timing information includes
+  real time, user run time, and system run time.  This macro executes
+  a form and reports the time and consing overhead.  If the
+  \code{time} form is not compiled (e.g. it was typed at top-level),
+  then \code{compile} will be called on the form to give more accurate
+  timing information.  If you really want to time interpreted speed,
+  you can say:
+\begin{lisp}
+(time (eval '\var{form}))
+\end{lisp}
+Things that execute fairly quickly should be timed more than once,
+since there may be more paging overhead in the first timing.  To
+increase the accuracy of very short times, you can time multiple
+evaluations:
+\begin{lisp}
+(time (dotimes (i 100) \var{form}))
+\end{lisp}
+\end{defmac}
+
+\begin{defun}{extensions:}{get-bytes-consed}{}
+
+  This function returns the number of bytes allocated since the first
+  time you called it.  The first time it is called it returns zero.
+  The above profiling routines use this to report consing information.
+\end{defun}
+
+\begin{defvar}{extensions:}{gc-run-time}
+
+  This variable accumulates the run-time consumed by garbage
+  collection, in the units returned by
+  \findexed{get-internal-run-time}.
+\end{defvar}
+
+\begin{defconst}{}{internal-time-units-per-second}
+The value of internal-time-units-per-second is 100.
+\end{defconst}
+
+%%\node A Note on Timing, Benchmarking Techniques, Additional Timing Utilities, Profiling
+\subsection{A Note on Timing}
+\cpsubindex{CPU time}{interpretation of}
+\cpsubindex{run time}{interpretation of}
+\cindex{interpretation of run time}
+
+There are two general kinds of timing information provided by the
+\code{time} macro and other profiling utilities: real time and run
+time.  Real time is elapsed, wall clock time.  It will be affected in
+a fairly obvious way by any other activity on the machine.  The more
+other processes contending for CPU and memory, the more real time will
+increase.  This means that real time measurements are difficult to
+replicate, though this is less true on a dedicated workstation.  The
+advantage of real time is that it is real.  It tells you really how
+long the program took to run under the benchmarking conditions.  The
+problem is that you don't know exactly what those conditions were.
+
+Run time is the amount of time that the processor supposedly spent
+running the program, as opposed to waiting for I/O or running other
+processes.  User run time'' and system run time'' are numbers
+reported by the Unix kernel.  They are supposed to be a measure of how
+much time the processor spent running your user'' program (which
+will include GC overhead, etc.), and the amount of time that the
+kernel spent running on your behalf.''
+
+Ideally, user time should be totally unaffected by benchmarking
+conditions; in reality user time does depend on other system activity,
+though in rather non-obvious ways.
+
+System time will clearly depend on benchmarking conditions.  In Lisp
+benchmarking, paging activity increases system run time (but not by as much
+as it increases real time, since the kernel spends some time waiting for
+the disk, and this is not run time, kernel or otherwise.)
+
+In my experience, the biggest trap in interpreting kernel/user run time is
+to look only at user time.  In reality, it seems that the \var{sum} of kernel
+and user time is more reproducible.  The problem is that as system activity
+increases, there is a spurious \var{decrease} in user run time.  In effect, as
+paging, etc., increases, user time leaks into system time.
+
+So, in practice, the only way to get truly reproducible results is to run
+with the same competing activity on the system.  Try to run on a machine
+with nobody else logged in, and check with ps aux'' to see if there are any
+system processes munching large amounts of CPU or memory.  If the ratio
+between real time and the sum of user and system time varies much between
+runs, then you have a problem.
+
+%%\node Benchmarking Techniques,  , A Note on Timing, Profiling
+\subsection{Benchmarking Techniques}
+\cindex{benchmarking techniques}
+
+Given these imperfect timing tools, how do should you do benchmarking?  The
+answer depends on whether you are trying to measure improvements in the
+performance of a single program on the same hardware, or if you are trying to
+compare the performance of different programs and/or different hardware.
+
+For the first use (measuring the effect of program modifications with
+constant hardware), you should look at \var{both} system+user and real time to
+understand what effect the change had on CPU use, and on I/O (including
+paging.)  If you are working on a CPU intensive program, the change in
+system+user time will give you a moderately reproducible measure of
+performance across a fairly wide range of system conditions.  For a CPU
+intensive program, you can think of system+user as how long it would have
+taken to run if I had my own machine.''  So in the case of comparing CPU
+intensive programs, system+user time is relatively real, and reasonable to
+use.
+
+For programs that spend a substantial amount of their time paging, you
+really can't predict elapsed time under a given operating condition without
+benchmarking in that condition.  User or system+user time may be fairly
+reproducible, but it is also relatively meaningless, since in a paging or
+I/O intensive program, the program is spending its time waiting, not
+running, and system time and user time are both measures of run time.
+A change that reduces run time might increase real time by increasing
+paging.
+
+Another common use for benchmarking is comparing the performance of
+the same program on different hardware.  You want to know which
+machine to run your program on.  For comparing different machines
+(operating systems, etc.), the only way to compare that makes sense is
+to set up the machines in \var{exactly} the way that they will
+\var{normally} be run, and then measure \var{real} time.  If the
+program will normally be run along with X, then run X.  If the program
+will normally be run on a dedicated workstation, then be sure nobody
+else is on the benchmarking machine.  If the program will normally be
+run on a machine with three other Lisp jobs, then run three other Lisp
+jobs.  If the program will normally be run on a machine with 8meg of
+memory, then run with 8meg.  Here, normal'' means normal for that
+machine''.  If you the choice of an unloaded RT or a heavily loaded
+PMAX.
+
+If you have a program you believe to be CPU intensive, then you might be
+tempted to compare run'' times across systems, hoping to get a meaningful
+result even if the benchmarking isn't done under the expected running
+condition.  Don't to this, for two reasons:
+\begin{itemize}
+
+\item The operating systems might not compute run time in the same
+  way.
+
+\item Under the real running condition, the program might not be CPU
+  intensive after all.
+\end{itemize}
+
+
+In the end, only real time means anything\dash{}it is the amount of time you
+have to wait for the result.  The only valid uses for run time are:
+\begin{itemize}
+
+\item To develop insight into the program.  For example, if run time
+  is much less than elapsed time, then you are probably spending lots
+  of time paging.
+
+\item To evaluate the relative performance of CPU intensive programs
+  in the same environment.
+\end{itemize}
+
+
+\hide{File:/afs/cs.cmu.edu/project/clisp/hackers/ram/docs/cmu-user/Unix.ms}
+
+
+
+%%\node UNIX Interface, Event Dispatching with SERVE-EVENT, Advanced Compiler Use and Efficiency Hints, Top
+\chapter{UNIX Interface}
+\label{unix-interface}
+\begin{center}
+\b{By Robert MacLachlan, Skef Wholey,}
+\end{center}
+\begin{center}
+\b{Bill Chiles, and William Lott}
+\end{center}
+
+CMU Common Lisp attempts to make the full power of the underlying
+environment available to the Lisp programmer.  This is done using
+combination of hand-coded interfaces and foreign function calls to C
+libraries.  Although the techniques differ, the style of interface is
+similar.  This chapter provides an overview of the facilities
+available and general rules for using them, as well as describing
+specific features in detail.  It is assumed that the reader has a
+working familiarity with Mach, Unix and X, as well as access to the
+standard system documentation.
+
+\begin{comment}
+* Lisp Equivalents for C Routines::
+* Type Translations::
+* System Area Pointers::
+* Unix System Calls::
+* File Descriptor Streams::
+* Making Sense of Mach Return Codes::
+* Unix Interrupts::
+\end{comment}
+
+
+%%\node Reading the Command Line, Useful Variables, UNIX Interface, UNIX Interface
+
+The shell parses the command line with which Lisp is invoked, and
+passes a data structure containing the parsed information to Lisp.
+This information is then extracted from that data structure and put
+into a set of Lisp data structures.
+
+\begin{defvar}{extensions:}{command-line-strings}
+  \defvarx[extensions:]{command-line-utility-name}
+  \defvarx[extensions:]{command-line-words}
+  \defvarx[extensions:]{command-line-switches}
+
+  The value of \code{*command-line-words*} is a list of strings that
+  make up the command line, one word per string.  The first word on
+  the command line, i.e.  the name of the program invoked (usually
+  \code{lisp}) is stored in \code{*command-line-utility-name*}.  The
+  value of \code{*command-line-switches*} is a list of
+  \code{command-line-switch} structures, with a structure for each
+  word on the command line starting with a hyphen.  All the command
+  line words between the program name and the first switch are stored
+  in \code{*command-line-words*}.
+\end{defvar}
+
+The following functions may be used to examine \code{command-line-switch}
+structures.
+\begin{defun}{extensions:}{cmd-switch-name}{\args{\var{switch}}}
+
+  Returns the name of the switch, less the preceding hyphen and
+  trailing equal sign (if any).
+\end{defun}
+\begin{defun}{extensions:}{cmd-switch-value}{\args{\var{switch}}}
+
+  Returns the value designated using an embedded equal sign, if any.
+  If the switch has no equal sign, then this is null.
+\end{defun}
+\begin{defun}{extensions:}{cmd-switch-words}{\args{\var{switch}}}
+
+  Returns a list of the words between this switch and the next switch
+  or the end of the command line.
+\end{defun}
+\begin{defun}{extensions:}{cmd-switch-arg}{\args{\var{switch}}}
+
+  Returns the first non-null value from \code{cmd-switch-value}, the
+  first element in \code{cmd-switch-words}, or the first word in
+  \var{command-line-words}.
+\end{defun}
+
+\begin{defun}{extensions:}{get-command-line-switch}{\args{\var{sname}}}
+
+  This function takes the name of a switch as a string and returns the
+  value of the switch given on the command line.  If no value was
+  specified, then any following words are returned.  If there are no
+  following words, then \true{} is returned.  If the switch was not
+  specified, then \false{} is returned.
+\end{defun}
+
+\begin{defmac}{extensions:}{defswitch}{%
+    \args{\var{name} \ampoptional{} \var{function}}}
+
+  This macro causes \var{function} to be called when the switch
+  \var{name} appears in the command line.  Name is a simple-string
+  that does not begin with a hyphen (unless the switch name really
+  does begin with one.)
+
+  If \var{function} is not supplied, then the switch is parsed into
+  \var{command-line-switches}, but otherwise ignored.  This suppresses
+  the undefined switch warning which would otherwise take place.  THe
+  warning can also be globally suppressed by
+\end{defmac}
+
+%%\node Useful Variables, Lisp Equivalents for C Routines, Reading the Command Line, UNIX Interface
+
+\section{Useful Variables}
+
+\begin{defvar}{system:}{stdin}
+  \defvarx[system:]{stdout} \defvarx[system:]{stderr}
+
+  Streams connected to the standard input, output and error file
+  descriptors.
+\end{defvar}
+
+\begin{defvar}{system:}{tty}
+
+  A stream connected to \file{/dev/tty}.
+\end{defvar}
+
+%%\node Lisp Equivalents for C Routines, Type Translations, Useful Variables, UNIX Interface
+\section{Lisp Equivalents for C Routines}
+
+The UNIX documentation describes the system interface in terms of C
+procedure headers.  The corresponding Lisp function will have a somewhat
+different interface, since Lisp argument passing conventions and
+datatypes are different.
+
+The main difference in the argument passing conventions is that Lisp does not
+support passing values by reference.  In Lisp, all argument and results are
+passed by value.  Interface functions take some fixed number of arguments and
+return some fixed number of values.  A given parameter'' in the C
+specification will appear as an argument, return value, or both, depending on
+whether it is an In parameter, Out parameter, or In/Out parameter.  The basic
+transformation one makes to come up with the Lisp equivalent of a C routine is
+to remove the Out parameters from the call, and treat them as extra return
+values.  In/Out parameters appear both as arguments and return values.  Since
+Out and In/Out parameters are only conventions in C, you must determine the
+usage from the documentation.
+
+
+Thus, the C routine declared as
+\begin{example}
+kern_return_t lookup(servport, portsname, portsid)
+        port        servport;
+        char        *portsname;
+        int        *portsid;        /* out */
+ {
+  ...
+  *portsid = <expression to compute portsid field>
+  return(KERN_SUCCESS);
+ }
+\end{example}
+has as its Lisp equivalent something like
+\begin{lisp}
+(defun lookup (ServPort PortsName)
+  ...
+  (values
+   success
+   <expression to compute portsid field>))
+\end{lisp}
+If there are multiple out or in-out arguments, then there are multiple
+
+Fortunately, CMU Common Lisp programmers rarely have to worry about the
+nuances of this translation process, since the names of the arguments and
+return values are documented in a way so that the \code{describe} function
+(and the \Hemlock{} \code{Describe Function Call} command, invoked with
+\b{C-M-Shift-A}) will list this information.  Since the names of arguments
+and return values are usually descriptive, the information that
+\code{describe} prints is usually all one needs to write a
+call. Most programmers use this on-line documentation nearly
+all of the time, and thereby avoid the need to handle bulky
+manuals and perform the translation from barbarous tongues.
+
+%%\node Type Translations, System Area Pointers, Lisp Equivalents for C Routines, UNIX Interface
+\section{Type Translations}
+\cindex{aliens}
+\cpsubindex{types}{alien}
+\cpsubindex{types}{foreign language}
+
+Lisp data types have very different representations from those used by
+conventional languages such as C.  Since the system interfaces are
+designed for conventional languages, Lisp must translate objects to and
+from the Lisp representations.  Many simple objects have a direct
+translation: integers, characters, strings and floating point numbers
+are translated to the corresponding Lisp object.  A number of types,
+however, are implemented differently in Lisp for reasons of clarity and
+efficiency.
+
+Instances of enumerated types are expressed as keywords in Lisp.
+Records, arrays, and pointer types are implemented with the \Alien{}
+facility (see page \pageref{aliens}.)  Access functions are defined
+for these types which convert fields of records, elements of arrays,
+or data referenced by pointers into Lisp objects (possibly another
+object to be referenced with another access function).
+
+One should dispose of \Alien{} objects created by constructor
+functions or returned from remote procedure calls when they are no
+longer of any use, freeing the virtual memory associated with that
+object.  Since \alien{}s contain pointers to non-Lisp data, the
+garbage collector cannot do this itself.  If the memory
+was obtained from \funref{make-alien} or from a foreign function call
+to a routine that used \code{malloc}, then \funref{free-alien} should
+be used.    If the \alien{} was created
+using MACH memory allocation (e.g.  \code{vm\_allocate}), then the
+storage should be freed using \code{vm\_deallocate}.
+
+%%\node System Area Pointers, Unix System Calls, Type Translations, UNIX Interface
+\section{System Area Pointers}
+\label{system-area-pointers}
+
+\cindex{pointers}\cpsubindex{malloc}{C function}\cpsubindex{free}{C function}
+Note that in some cases an address is represented by a Lisp integer, and in
+other cases it is represented by a real pointer.  Pointers are usually used
+when an object in the current address space is being referred to.  The MACH
+virtual memory manipulation calls must use integers, since in principle the
+address could be in any process, and Lisp cannot abide random pointers.
+Because these types are represented differently in Lisp, one must explicitly
+coerce between these representations.
+
+System Area Pointers (SAPs) provide a mechanism that bypasses the
+\Alien{} type system and accesses virtual memory directly.  A SAP is a
+raw byte pointer into the \code{lisp} process address space.  SAPs are
+represented with a pointer descriptor, so SAP creation can cause
+consing.  However, the compiler uses a non-descriptor representation
+for SAPs when possible, so the consing overhead is generally minimal.
+\xlref{non-descriptor}.
+
+\begin{defun}{system:}{sap-int}{\args{\var{sap}}}
+  \defunx[system:]{int-sap}{\args{\var{int}}}
+
+  The function \code{sap-int} is used to generate an integer
+  corresponding to the system area pointer, suitable for passing to
+  the kernel interfaces (which want all addresses specified as
+  integers).  The function \code{int-sap} is used to do the opposite
+  conversion.  The integer representation of a SAP is the byte offset
+  of the SAP from the start of the address space.
+\end{defun}
+
+\begin{defun}{system:}{sap+}{\args{\var{sap} \var{offset}}}
+
+  This function adds a byte \var{offset} to \var{sap}, returning a new
+  SAP.
+\end{defun}
+
+\begin{defun}{system:}{sap-ref-8}{\args{\var{sap} \var{offset}}}
+  \defunx[system:]{sap-ref-16}{\args{\var{sap} \var{offset}}}
+  \defunx[system:]{sap-ref-32}{\args{\var{sap} \var{offset}}}
+
+  These functions return the 8, 16 or 32 bit unsigned integer at
+  \var{offset} from \var{sap}.  The \var{offset} is always a byte
+  offset, regardless of the number of bits accessed.  \code{setf} may
+  be used with the these functions to deposit values into virtual
+  memory.
+\end{defun}
+
+\begin{defun}{system:}{signed-sap-ref-8}{\args{\var{sap} \var{offset}}}
+  \defunx[system:]{signed-sap-ref-16}{\args{\var{sap} \var{offset}}}
+  \defunx[system:]{signed-sap-ref-32}{\args{\var{sap} \var{offset}}}
+
+  These functions are the same as the above unsigned operations,
+  except that they sign-extend, returning a negative number if the
+  high bit is set.
+\end{defun}
+
+%%\node Unix System Calls, File Descriptor Streams, System Area Pointers, UNIX Interface
+\section{Unix System Calls}
+
+You probably won't have much cause to use them, but all the Unix system
+calls are available.  The Unix system call functions are in the
+\code{Unix} package.  The name of the interface for a particular system
+call is the name of the system call prepended with \code{unix-}.  The
+system usually defines the associated constants without any prefix name.
+To find out how to use a particular system call, try using
+\code{describe} on it.  If that is unhelpful, look at the source in
+\file{syscall.lisp} or consult your system maintainer.
+
+The Unix system calls indicate an error by returning \false{} as the
+first value and the Unix error number as the second value.  If the call
+succeeds, then the first value will always be non-\nil, often \code{t}.
+
+\begin{defun}{Unix:}{get-unix-error-msg}{\args{\var{error}}}
+
+  This function returns a string describing the Unix error number
+  \var{error}.
+\end{defun}
+
+%%\node File Descriptor Streams, Making Sense of Mach Return Codes, Unix System Calls, UNIX Interface
+\section{File Descriptor Streams}
+
+Many of the UNIX system calls return file descriptors.  Instead of using other
+UNIX system calls to perform I/O on them, you can create a stream around them.
+
+\begin{defun}{system:}{make-fd-stream}{%
+    \args{\var{descriptor}} \keys{\kwd{input} \kwd{output}
+      \kwd{element-type}} \morekeys{\kwd{buffering} \kwd{name}
+      \kwd{file} \kwd{original}} \yetmorekeys{\kwd{delete-original}
+      \kwd{auto-close}} \yetmorekeys{\kwd{timeout} \kwd{pathname}}}
+
+  This function creates a file descriptor stream using
+  \var{descriptor}.  If \kwd{input} is non-\nil, input operations are
+  allowed.  If \kwd{output} is non-\nil, output operations are
+  allowed.  The default is input only.  These keywords are defined:
+  \begin{Lentry}
+  \item[\kwd{element-type}] is the type of the unit of transaction for
+    the stream, which defaults to \code{string-char}.  See the Common
+    Lisp description of \code{open} for valid values.
+
+  \item[\kwd{buffering}] is the kind of output buffering desired for
+    the stream.  Legal values are \kwd{none} for no buffering,
+    \kwd{line} for buffering up to each newline, and \kwd{full} for
+    full buffering.
+
+  \item[\kwd{name}] is a simple-string name to use for descriptive
+    purposes when the system prints an fd-stream.  When printing
+    fd-streams, the system prepends the streams name with \code{Stream
+      for }.  If \var{name} is unspecified, it defaults to a string
+    containing \var{file} or \var{descriptor}, in order of preference.
+
+  \item[\kwd{file}, \kwd{original}] \var{file} specifies the defaulted
+    namestring of the associated file when creating a file stream
+    (must be a \code{simple-string}). \var{original} is the
+    \code{simple-string} name of a backup file containing the original
+    contents of \var{file} while writing \var{file}.
+
+    When you abort the stream by passing \true{} to \code{close} as
+    the second argument, if you supplied both \var{file} and
+    \var{original}, \code{close} will rename the \var{original} name
+    to the \var{file} name.  When you \code{close} the stream
+    normally, if you supplied \var{original}, and
+    \var{delete-original} is non-\nil, \code{close} deletes
+    \var{original}.  If \var{auto-close} is true (the default), then
+    \var{descriptor} will be closed when the stream is garbage
+    collected.
+
+  \item[\kwd{pathname}]: The original pathname passed to open and
+    returned by \code{pathname}; not defaulted or translated.
+
+  \item[\kwd{timeout}] if non-null, then \var{timeout} is an integer
+    number of seconds after which an input wait should time out.  If a
+    read does time out, then the \code{system:io-timeout} condition is
+    signalled.
+  \end{Lentry}
+\end{defun}
+
+\begin{defun}{system:}{fd-stream-p}{\args{\var{object}}}
+
+  This function returns \true{} if \var{object} is an fd-stream, and
+  \nil{} if not.  Obsolete: use the portable \code{(typep x
+    'file-stream)}.
+\end{defun}
+
+\begin{defun}{system:}{fd-stream-fd}{\args{\var{stream}}}
+
+  This returns the file descriptor associated with \var{stream}.
+\end{defun}
+
+
+%%\node Making Sense of Mach Return Codes, Unix Interrupts, File Descriptor Streams, UNIX Interface
+\section{Making Sense of Mach Return Codes}
+
+Whenever a remote procedure call returns a Unix error code (such as
+\code{kern\_return\_t}), it is usually prudent to check that code to
+see if the call was successful.  To relieve the programmer of the
+hassle of testing this value himself, and to centralize the
+information about the meaning of non-success return codes, CMU Common
+\funref{get-unix-error-msg}.
+
+\begin{defun}{system:}{gr-error}{%
+    \args{\var{function} \var{gr} \ampoptional{} \var{context}}}
+
+  Signals a Lisp error, printing a message indicating that the call to
+  the specified \var{function} failed, with the return code \var{gr}.
+  If supplied, the \var{context} string is printed after the
+  \var{function} name and before the string associated with the
+  \var{gr}.  For example:
+\begin{example}
+* (gr-error 'nukegarbage 3 "lost big")
+
+Error in function GR-ERROR:
+NUKEGARBAGE lost big, no space.
+Proceed cases:
+Debug  (type H for help)
+(Signal #<Conditions:Simple-Error.5FDE0>)
+0]
+\end{example}
+\end{defun}
+
+\begin{defmac}{system:}{gr-call}{\args{\var{function} \amprest{} \var{args}}}
+  \defmacx[system:]{gr-call*}{\args{\var{function} \amprest{} \var{args}}}
+
+  These macros can be used to call a function and automatically check
+  the GeneralReturn code and signal an appropriate error in case of
+  non-successful return.  \code{gr-call} returns \false{} if no error
+  occurs, while \code{gr-call*} returns the second value of the
+  function called.
+\begin{example}
+NIL
+*
+\end{example}
+\end{defmac}
+
+\begin{defmac}{system:}{gr-bind}{
+    \args{\code{(}\mstar{\var{var}}\code{)}
+      \code{(}\var{function} \mstar{\var{arg}}\code{)}
+      \mstar{\var{form}}}}
+
+  This macro can be used much like \code{multiple-value-bind} to bind
+  the \var{var}s to return values resulting from calling the
+  \var{function} with the given \var{arg}s.  The first return value is
+  not bound to a variable, but is checked as a GeneralReturn code, as
+  in \code{gr-call}.
+\begin{example}
+* (gr-bind (port_list port_list_cnt)
+    (format t "The port count is ~S." port_list_cnt)
+    port_list)
+The port count is 0.
+#<Alien value>
+*
+\end{example}
+\end{defmac}
+
+%%\node Unix Interrupts,  , Making Sense of Mach Return Codes, UNIX Interface
+\section{Unix Interrupts}
+
+\cindex{unix interrupts} \cindex{interrupts}
+CMU Common Lisp allows access to all the Unix signals that can be generated
+under Unix.  It should be noted that if this capability is abused, it is
+possible to completely destroy the running Lisp.  The following macros and
+functions allow access to the Unix interrupt system.  The signal names as
+specified in section 2 of the \i{Unix Programmer's Manual} are exported
+from the Unix package.
+
+\begin{comment}
+* Changing Interrupt Handlers::
+* Examples of Signal Handlers::
+\end{comment}
+
+%%\node Changing Interrupt Handlers, Examples of Signal Handlers, Unix Interrupts, Unix Interrupts
+\subsection{Changing Interrupt Handlers}
+\label{signal-handlers}
+
+\begin{defmac}{system:}{with-enabled-interrupts}{
+    \args{\var{specs} \amprest{} \var{body}}}
+
+  This macro should be called with a list of signal specifications,
+  \var{specs}.  Each element of \var{specs} should be a list of
+  two\hide{ or three} elements: the first should be the Unix signal
+  for which a handler should be established, the second should be a
+  function to be called when the signal is received\hide{, and the
+    third should be an optional character used to generate the signal
+    from the keyboard.  This last item is only useful for the SIGINT,
+    SIGQUIT, and SIGTSTP signals.}  One or more signal handlers can be
+  established in this way.  \code{with-enabled-interrupts} establishes
+  the correct signal handlers and then executes the forms in
+  \var{body}.  The forms are executed in an unwind-protect so that the
+  state of the signal handlers will be restored to what it was before
+  the \code{with-enabled-interrupts} was entered.  A signal handler
+  function specified as NIL will set the Unix signal handler to the
+  default which is normally either to ignore the signal or to cause a
+  core dump depending on the particular signal.
+\end{defmac}
+
+\begin{defmac}{system:}{without-interrupts}{\args{\amprest{} \var{body}}}
+
+  It is sometimes necessary to execute a piece a code that can not be
+  interrupted.  This macro the forms in \var{body} with interrupts
+  disabled.  Note that the Unix interrupts are not actually disabled,
+  rather they are queued until after \var{body} has finished
+  executing.
+\end{defmac}
+
+\begin{defmac}{system:}{with-interrupts}{\args{\amprest{} \var{body}}}
+
+  When executing an interrupt handler, the system disables interrupts,
+  as if the handler was wrapped in in a \code{without-interrupts}.
+  The macro \code{with-interrupts} can be used to enable interrupts
+  while the forms in \var{body} are evaluated.  This is useful if
+  \var{body} is going to enter a break loop or do some long
+  computation that might need to be interrupted.
+\end{defmac}
+
+\begin{defmac}{system:}{without-hemlock}{\args{\amprest{} \var{body}}}
+
+  For some interrupts, such as SIGTSTP (suspend the Lisp process and
+  return to the Unix shell) it is necessary to leave Hemlock and then
+  return to it.  This macro executes the forms in \var{body} after
+  exiting Hemlock.  When \var{body} has been executed, control is
+  returned to Hemlock.
+\end{defmac}
+
+\begin{defun}{system:}{enable-interrupt}{%
+    \args{\var{signal} \var{function}\hide{ \ampoptional{}
+        \var{character}}}}
+
+  This function establishes \var{function} as the handler for
+  \var{signal}.
+  \hide{The optional \var{character} can be specified
+    for the SIGINT, SIGQUIT, and SIGTSTP signals and causes that
+    character to generate the appropriate signal from the keyboard.}
+  Unless you want to establish a global signal handler, you should use
+  the macro \code{with-enabled-interrupts} to temporarily establish a
+  signal handler.  \hide{Without \var{character},}
+  \code{enable-interrupt} returns the old function associated with the
+  signal.  \hide{When \var{character} is specified for SIGINT,
+    SIGQUIT, or SIGTSTP, it returns the old character code.}
+\end{defun}
+
+\begin{defun}{system:}{ignore-interrupt}{\args{\var{signal}}}
+
+  Ignore-interrupt sets the Unix signal mechanism to ignore
+  \var{signal} which means that the Lisp process will never see the
+  signal.  Ignore-interrupt returns the old function associated with
+  the signal or \false{} if none is currently defined.
+\end{defun}
+
+\begin{defun}{system:}{default-interrupt}{\args{\var{signal}}}
+
+  Default-interrupt can be used to tell the Unix signal mechanism to
+  perform the default action for \var{signal}.  For details on what
+  the default action for a signal is, see section 2 of the \i{Unix
+    Programmer's Manual}.  In general, it is likely to ignore the
+  signal or to cause a core dump.
+\end{defun}
+
+%%\node Examples of Signal Handlers,  , Changing Interrupt Handlers, Unix Interrupts
+\subsection{Examples of Signal Handlers}
+
+The following code is the signal handler used by the Lisp system for the
+SIGINT signal.
+\begin{lisp}
+(defun ih-sigint (signal code scp)
+  (declare (ignore signal code scp))
+  (without-hemlock
+   (with-interrupts
+    (break "Software Interrupt" t))))
+\end{lisp}
+The \code{without-hemlock} form is used to make sure that Hemlock is exited before
+a break loop is entered.  The \code{with-interrupts} form is used to enable
+interrupts because the user may want to generate an interrupt while in the
+break loop.  Finally, break is called to enter a break loop, so the user
+can look at the current state of the computation.  If the user proceeds
+from the break loop, the computation will be restarted from where it was
+interrupted.
+
+The following function is the Lisp signal handler for the SIGTSTP signal
+which suspends a process and returns to the Unix shell.
+\begin{lisp}
+(defun ih-sigtstp (signal code scp)
+  (declare (ignore signal code scp))
+  (without-hemlock
+   (Unix:unix-kill (Unix:unix-getpid) Unix:sigstop)))
+\end{lisp}
+Lisp uses this interrupt handler to catch the SIGTSTP signal because it is
+necessary to get out of Hemlock in a clean way before returning to the shell.
+
+To set up these interrupt handlers, the following is recommended:
+\begin{lisp}
+(with-enabled-interrupts ((Unix:SIGINT #'ih-sigint)
+                          (Unix:SIGTSTP #'ih-sigtstp))
+  <user code to execute with the above signal handlers enabled.>
+)
+\end{lisp}
+
+
+\hide{File:/afs/cs.cmu.edu/project/clisp/hackers/ram/docs/cmu-user/server.ms}
+
+%%\node Event Dispatching with SERVE-EVENT, Alien Objects, UNIX Interface, Top
+\chapter{Event Dispatching with SERVE-EVENT}
+\begin{center}
+\b{By Bill Chiles and Robert MacLachlan}
+\end{center}
+
+It is common to have multiple activities simultaneously operating in the same
+Lisp process.  Furthermore, Lisp programmers tend to expect a flexible
+development environment.  It must be possible to load and modify application
+programs without requiring modifications to other running programs.  CMU Common
+Lisp achieves this by having a central scheduling mechanism based on an
+
+An \var{event} is some interesting happening that should cause the Lisp process
+to wake up and do something.  These events include X events and activity on
+Unix file descriptors.  The object-oriented mechanism is only available with
+the first two, and it is optional with X events as described later in this
+chapter.  In an X event, the window ID is the object capability and the X event
+type is the operation code.  The Unix file descriptor input mechanism simply
+consists of an association list of a handler to call when input shows up on a
+particular file descriptor.
+
+
+\begin{comment}
+* Object Sets::
+* The SERVE-EVENT Function::
+* Using SERVE-EVENT with Unix File Descriptors::
+* Using SERVE-EVENT with the CLX Interface to X::
+* A SERVE-EVENT Example::
+\end{comment}
+
+%%\node Object Sets, The SERVE-EVENT Function, Event Dispatching with SERVE-EVENT, Event Dispatching with SERVE-EVENT
+\section{Object Sets}
+\label{object-sets}
+\cindex{object sets}
+An \i{object set} is a collection of objects that have the same implementation
+for each operation.  Externally the object is represented by the object
+capability and the operation is represented by the operation code.  Within
+Lisp, the object is represented by an arbitrary Lisp object, and the
+implementation for the operation is represented by an arbitrary Lisp function.
+The object set mechanism maintains this translation from the external to the
+internal representation.
+
+\begin{defun}{system:}{make-object-set}{%
+    \args{\var{name} \ampoptional{} \var{default-handler}}}
+
+  This function makes a new object set.  \var{Name} is a string used
+  only for purposes of identifying the object set when it is printed.
+  \var{Default-handler} is the function used as a handler when an
+  undefined operation occurs on an object in the set.  You can define
+  operations with the \code{serve-}\var{operation} functions exported
+  the \code{extensions} package for X events
+  (\pxlref{x-serve-mumbles}).  Objects are added with
+  \code{system:add-xwindow-object}.  Initially the object set has no
+  objects and no defined operations.
+\end{defun}
+
+\begin{defun}{system:}{object-set-operation}{%
+    \args{\var{object-set} \var{operation-code}}}
+
+  This function returns the handler function that is the
+  implementation of the operation corresponding to
+  \var{operation-code} in \var{object-set}.  When set with
+  \code{setf}, the setter function establishes the new handler.  The
+  \code{serve-}\var{operation} functions exported from the
+  \code{extensions} package for X events (\pxlref{x-serve-mumbles})
+  call this on behalf of the user when announcing a new operation for
+  an object set.
+\end{defun}
+
+    \args{\var{window} \var{object} \var{object-set}}}
+
+  These functions add \var{port} or \var{window} to \var{object-set}.
+  \var{Object} is an arbitrary Lisp object that is associated with the
+  \var{port} or \var{window} capability.  \var{Window} is a CLX
+  window.  When an event occurs, \code{system:serve-event} passes
+  \var{object} as an argument to the handler function.
+\end{defun}
+
+
+%%\node The SERVE-EVENT Function, Using SERVE-EVENT with Unix File Descriptors, Object Sets, Event Dispatching with SERVE-EVENT
+\section{The SERVE-EVENT Function}
+
+The \code{system:serve-event} function is the standard way for an application
+to wait for something to happen.  For example, the Lisp system calls
+\code{system:serve-event} when it wants input from X or a terminal stream.
+The idea behind \code{system:serve-event} is that it knows the appropriate
+action to take when any interesting event happens.  If an application calls
+\code{system:serve-event} when it is idle, then any other applications with
+pending events can run.  This allows several applications to run at the
+same time'' without interference, even though there is only one thread of
+control.  Note that if an application is waiting for input of any kind,
+then other applications will get events.
+
+\begin{defun}{system:}{serve-event}{\args{\ampoptional{} \var{timeout}}}
+
+  This function waits for an event to happen and then dispatches to
+  the correct handler function.  If specified, \var{timeout} is the
+  number of seconds to wait before timing out.  A time out of zero
+  seconds is legal and causes \code{system:serve-event} to poll for
+  any events immediately available for processing.
+  \code{system:serve-event} returns \true{} if it serviced at least
+  one event, and \nil{} otherwise.  Depending on the application, when
+  \code{system:serve-event} returns \true, you might want to call it
+  repeatedly with a timeout of zero until it returns \nil.
+
+  If input is available on any designated file descriptor, then this
+  calls the appropriate handler function supplied by
+
+  Since events for many different applications may arrive
+  simultaneously, an application waiting for a specific event must
+  loop on \code{system:serve-event} until the desired event happens.
+  Since programs such as \hemlock{} call \code{system:serve-event} for
+  input, applications usually do not need to call
+  \code{system:serve-event} at all; \hemlock{} allows other
+  application's handlers to run when it goes into an input wait.
+\end{defun}
+
+\begin{defun}{system:}{serve-all-events}{\args{\ampoptional{} \var{timeout}}}
+
+  This function is similar to \code{system:serve-event}, except it
+  serves all the pending events rather than just one.  It returns
+  \true{} if it serviced at least one event, and \nil{} otherwise.
+\end{defun}
+
+
+%%\node Using SERVE-EVENT with Unix File Descriptors, Using SERVE-EVENT with the CLX Interface to X, The SERVE-EVENT Function, Event Dispatching with SERVE-EVENT
+\section{Using SERVE-EVENT with Unix File Descriptors}
+Object sets are not available for use with file descriptors, as there are
+only two operations possible on file descriptors: input and output.
+Instead, a handler for either input or output can be registered with
+\code{system:serve-event} for a specific file descriptor.  Whenever any input
+shows up, or output is possible on this file descriptor, the function
+associated with the handler for that descriptor is funcalled with the
+descriptor as it's single argument.
+
+    \args{\var{fd} \var{direction} \var{function}}}
+
+  This function installs and returns a new handler for the file
+  descriptor \var{fd}.  \var{direction} can be either \kwd{input} if
+  the system should invoke the handler when input is available or
+  \kwd{output} if the system should invoke the handler when output is
+  possible.  This returns a unique object representing the handler,
+  and this is a suitable argument for \code{system:remove-fd-handler}
+  \var{function} must take one argument, the file descriptor.
+\end{defun}
+
+\begin{defun}{system:}{remove-fd-handler}{\args{\var{handler}}}
+
+  This function removes \var{handler}, that \code{add-fd-handler} must
+  have previously returned.
+\end{defun}
+
+\begin{defmac}{system:}{with-fd-handler}{%
+    \args{(\var{direction} \var{fd} \var{function})
+      \mstar{\var{form}}}}
+
+  This macro executes the supplied forms with a handler installed
+  using \var{fd}, \var{direction}, and \var{function}.  See
+\end{defmac}
+
+\begin{defun}{system:}{wait-until-fd-usable}{%
+    \args{\var{direction} \var{fd} \ampoptional{} \var{timeout}}}
+
+  This function waits for up to \var{timeout} seconds for \var{fd} to
+  become usable for \var{direction} (either \kwd{input} or
+  \kwd{output}).  If \var{timeout} is \nil{} or unspecified, this
+  waits forever.
+\end{defun}
+
+\begin{defun}{system:}{invalidate-descriptor}{\args{\var{fd}}}
+
+  This function removes all handlers associated with \var{fd}.  This
+  should only be used in drastic cases (such as I/O errors, but not
+  necessarily EOF).  Normally, you should use \code{remove-fd-handler}
+  to remove the specific handler.
+\end{defun}
+
+\begin{comment}
+
+section{Using SERVE-EVENT with Matchmaker Interfaces}
+\label{ipc-serve-mumbles}
+Remember from section \ref{object-sets}, an object set is a collection of
+objects, ports in this case, with some set of operations, message ID's, with
+corresponding implementations, the same handler functions.
+
+Matchmaker uses the object set operations to implement servers.  For
+each server interface \i{XXX}, Matchmaker defines a function,
+\code{serve-}\i{XXX}, of two arguments, an object set and a function.
+The \code{serve-}\i{XXX} function establishes the function as the
+implementation of the \i{XXX} operation in the object set.  Recall
+associates some Lisp object with a port in an object set.  When
+\code{system:serve-event} notices activity on a port, it calls the
+function given to \code{serve-}\i{XXX} with the object given to
+\code{system:add-port-object} and the input parameters specified in
+the message definition.  The return values from the function are used
+as the output parameters for the message, if any.
+\code{serve-}\i{XXX} functions are also generated for each \i{server
+  message} and asynchronous user interface.
+
+To use a Lisp server:
+\begin{itemize}
+
+\item Create an object set.
+
+\item Define some operations on it using the \code{serve-}\i{XXX}
+  functions.
+
+\item Create an object for every port on which you receive requests.
+
+\item Call \code{system:serve-event} to service an RPC request.
+\end{itemize}
+
+
+Object sets allow many servers in the same Lisp to operate without knowing
+about each other.  There can be multiple implementations of the same interface
+with different operation handlers established in distinct object sets.  This
+property is especially useful when handling emergency messages.
+
+\end{comment}
+
+%%\node Using SERVE-EVENT with the CLX Interface to X, A SERVE-EVENT Example, Using SERVE-EVENT with Unix File Descriptors, Event Dispatching with SERVE-EVENT
+\section{Using SERVE-EVENT with the CLX Interface to X}
+\label{x-serve-mumbles}
+Remember from section \ref{object-sets}, an object set is a collection of
+objects, CLX windows in this case, with some set of operations, event keywords,
+with corresponding implementations, the same handler functions.  Since X allows
+multiple display connections from a given process, you can avoid using object
+sets if every window in an application or display connection behaves the same.
+If a particular X application on a single display connection has windows that
+want to handle certain events differently, then using object sets is a
+convenient way to organize this since you need some way to map the window/event
+combination to the appropriate functionality.
+
+The following is a discussion of functions exported from the \code{extensions}
+package that facilitate handling CLX events through \code{system:serve-event}.
+The first two routines are useful regardless of whether you use
+\code{system:serve-event}:
+\begin{defun}{ext:}{open-clx-display}{%
+    \args{\ampoptional{} \var{string}}}
+
+  This function parses \var{string} for an X display specification
+  including display and screen numbers.  \var{String} defaults to the
+  following:
+  \begin{example}
+    (cdr (assoc :display ext:*environment-list* :test #'eq))
+  \end{example}
+  If any field in the display specification is missing, this signals
+  an error.  \code{ext:open-clx-display} returns the CLX display and
+  screen.
+\end{defun}
+
+\begin{defun}{ext:}{flush-display-events}{\args{\var{display}}}
+
+  This function flushes all the events in \var{display}'s event queue
+  including the current event, in case the user calls this from within
+  an event handler.
+\end{defun}
+
+
+\begin{comment}
+* Without Object Sets::
+* With Object Sets::
+\end{comment}
+
+%%\node Without Object Sets, With Object Sets, Using SERVE-EVENT with the CLX Interface to X, Using SERVE-EVENT with the CLX Interface to X
+\subsection{Without Object Sets}
+Since most applications that use CLX, can avoid the complexity of object sets,
+these routines are described in a separate section.  The routines described in
+the next section that use the object set mechanism are based on these
+interfaces.
+
+\begin{defun}{ext:}{enable-clx-event-handling}{%
+    \args{\var{display} \var{handler}}}
+
+  This function causes \code{system:serve-event} to notice when there
+  is input on \var{display}'s connection to the X11 server.  When this
+  happens, \code{system:serve-event} invokes \var{handler} on
+  \var{display} in a dynamic context with an error handler bound that
+  flushes all events from \var{display} and returns.  By returning,
+  the error handler declines to handle the error, but it will have
+  cleared all events; thus, entering the debugger will not result in
+  infinite errors due to streams that wait via
+  \code{system:serve-event} for input.  Calling this repeatedly on the
+  same \var{display} establishes \var{handler} as a new handler,
+  replacing any previous one for \var{display}.
+\end{defun}
+
+\begin{defun}{ext:}{disable-clx-event-handling}{\args{\var{display}}}
+
+  This function undoes the effect of
+  \code{ext:enable-clx-event-handling}.
+\end{defun}
+
+\begin{defmac}{ext:}{with-clx-event-handling}{%
+    \args{(\var{display} \var{handler}) \mstar{form}}}
+
+  This macro evaluates each \var{form} in a context where
+  \code{system:serve-event} invokes \var{handler} on \var{display}
+  whenever there is input on \var{display}'s connection to the X
+  server.  This destroys any previously established handler for
+  \var{display}.
+\end{defmac}
+
+
+%%\node With Object Sets,  , Without Object Sets, Using SERVE-EVENT with the CLX Interface to X
+\subsection{With Object Sets}
+This section discusses the use of object sets and
+\code{system:serve-event} to handle CLX events.  This is necessary
+when a single X application has distinct windows that want to handle
+the same events in different ways.  Basically, you need some way of
+asking for a given window which way you want to handle some event
+because this event is handled differently depending on the window.
+Object sets provide this feature.
+
+For each CLX event-key symbol-name \i{XXX} (for example,
+\var{key-press}), there is a function \code{serve-}\i{XXX} of two
+arguments, an object set and a function.  The \code{serve-}\i{XXX}
+function establishes the function as the handler for the \kwd{XXX}
+event in the object set.  Recall from section \ref{object-sets},
+\code{system:add-xwindow-object} associates some Lisp object with a
+CLX window in an object set.  When \code{system:serve-event} notices
+activity on a window, it calls the function given to
+\code{ext:enable-clx-event-handling}.  If this function is
+\code{ext:object-set-event-handler}, it calls the function given to
+\code{serve-}\i{XXX}, passing the object given to
+\code{system:add-xwindow-object} and the event's slots as well as a
+couple other arguments described below.
+
+To use object sets in this way:
+\begin{itemize}
+
+\item Create an object set.
+
+\item Define some operations on it using the \code{serve-}\i{XXX}
+  functions.
+
+\item Add an object for every window on which you receive requests.
+  This can be the CLX window itself or some structure more meaningful
+
+\item Call \code{system:serve-event} to service an X event.
+\end{itemize}
+
+
+\begin{defun}{ext:}{object-set-event-handler}{%
+    \args{\var{display}}}
+
+  This function is a suitable argument to
+  \code{ext:enable-clx-event-handling}.  The actual event handlers
+  defined for particular events within a given object set must take an
+  argument for every slot in the appropriate event.  In addition to
+  the event slots, \code{ext:object-set-event-handler} passes the
+  following arguments:
+  \begin{itemize}
+  \item The object, as established by
+    \code{system:add-xwindow-object}, on which the event occurred.
+  \item event-key, see \code{xlib:event-case}.
+  \item send-event-p, see \code{xlib:event-case}.
+  \end{itemize}
+
+  Describing any \code{ext:serve-}\var{event-key-name} function, where
+  \var{event-key-name} is an event-key symbol-name (for example,
+  \code{ext:serve-key-press}), indicates exactly what all the
+  arguments are in their correct order.
+
+%%  \begin{comment}
+%%    \code{ext:object-set-event-handler} ignores \kwd{no-exposure}
+%%    events on pixmaps, issuing a warning if one occurs.  It is only
+%%    prepared to dispatch events for windows.
+%%  \end{comment}
+
+  When creating an object set for use with
+  \code{ext:object-set-event-handler}, specify
+  \code{ext:default-clx-event-handler} as the default handler for
+  events in that object set.  If no default handler is specified, and
+  the system invokes the default default handler, it will cause an
+  error since this function takes arguments suitable for handling port
+  messages.
+\end{defun}
+
+
+%%\node A SERVE-EVENT Example,  , Using SERVE-EVENT with the CLX Interface to X, Event Dispatching with SERVE-EVENT
+\section{A SERVE-EVENT Example}
+This section contains two examples using \code{system:serve-event}.  The first
+one does not use object sets, and the second, slightly more complicated one
+does.
+
+
+\begin{comment}
+* Without Object Sets Example::
+* With Object Sets Example::
+\end{comment}
+
+%%\node Without Object Sets Example, With Object Sets Example, A SERVE-EVENT Example, A SERVE-EVENT Example
+\subsection{Without Object Sets Example}
+This example defines an input handler for a CLX display connection.  It only
+recognizes \kwd{key-press} events.  The body of the example loops over
+\code{system:serve-event} to get input.
+
+\begin{lisp}
+(in-package "SERVER-EXAMPLE")
+
+(defun my-input-handler (display)
+  (xlib:event-case (display :timeout 0)
+    (:key-press (event-window code state)
+     (format t "KEY-PRESSED (Window = ~D) = ~S.~%"
+                  (xlib:window-id event-window)
+             ;; See Hemlock Command Implementor's Manual for convenient
+             ;; input mapping function.
+             (ext:translate-character display code state))
+      ;; Make XLIB:EVENT-CASE discard the event.
+      t)))
+\end{lisp}
+\begin{lisp}
+(defun server-example ()
+  "An example of using the SYSTEM:SERVE-EVENT function and object sets to
+   handle CLX events."
+  (let* ((display (ext:open-clx-display))
+         (screen (display-default-screen display))
+         (black (screen-black-pixel screen))
+         (white (screen-white-pixel screen))
+         (window (create-window :parent (screen-root screen)
+                                :x 0 :y 0 :width 200 :height 200
+                                :background white :border black
+                                :border-width 2
+    ;; Wrap code in UNWIND-PROTECT, so we clean up after ourselves.
+    (unwind-protect
+        (progn
+          ;; Enable event handling on the display.
+          (ext:enable-clx-event-handling display #'my-input-handler)
+          ;; Map the windows to the screen.
+          (map-window window)
+          ;; Make sure we send all our requests.
+          (display-force-output display)
+          ;; Call serve-event for 100,000 events or immediate timeouts.
+          (dotimes (i 100000) (system:serve-event)))
+      ;; Disable event handling on this display.
+      (ext:disable-clx-event-handling display)
+      ;; Get rid of the window.
+      (destroy-window window)
+      ;; Pick off any events the X server has already queued for our
+      ;; windows, so we don't choke since SYSTEM:SERVE-EVENT is no longer
+      ;; prepared to handle events for us.
+      (loop
+       (unless (deleting-window-drop-event *display* window)
+        (return)))
+      ;; Close the display.
+      (xlib:close-display display))))
+
+(defun deleting-window-drop-event (display win)
+  "Check for any events on win.  If there is one, remove it from the
+   event queue and return t; otherwise, return nil."
+  (xlib:display-finish-output display)
+  (let ((result nil))
+    (xlib:process-event
+     display :timeout 0
+     :handler #'(lambda (&key event-window &allow-other-keys)
+                  (if (eq event-window win)
+                      (setf result t)
+                      nil)))
+    result))
+\end{lisp}
+
+
+%%\node With Object Sets Example,  , Without Object Sets Example, A SERVE-EVENT Example
+\subsection{With Object Sets Example}
+This example involves more work, but you get a little more for your effort.  It
+defines two objects, \code{input-box} and \code{slider}, and establishes a
+\kwd{key-press} handler for each object, \code{key-pressed} and
+\code{slider-pressed}.  We have two object sets because we handle events on the
+windows manifesting these objects differently, but the events come over the
+same display connection.
+
+\begin{lisp}
+(in-package "SERVER-EXAMPLE")
+
+(defstruct (input-box (:print-function print-input-box)
+                      (:constructor make-input-box (display window)))
+  "Our program knows about input-boxes, and it doesn't care how they
+   are implemented."
+  display        ; The CLX display on which my input-box is displayed.
+  window)        ; The CLX window in which the user types.
+;;;
+(defun print-input-box (object stream n)
+  (declare (ignore n))
+  (format stream "#<Input-Box ~S>" (input-box-display object)))
+
+(defvar *input-box-windows*
+        (system:make-object-set "Input Box Windows"
+                                #'ext:default-clx-event-handler))
+
+(defun key-pressed (input-box event-key event-window root child
+                    same-screen-p x y root-x root-y modifiers time
+                    key-code send-event-p)
+  "This is our :key-press event handler."
+  (declare (ignore event-key root child same-screen-p x y
+                   root-x root-y time send-event-p))
+  (format t "KEY-PRESSED (Window = ~D) = ~S.~%"
+          (xlib:window-id event-window)
+          ;; See Hemlock Command Implementor's Manual for convenient
+          ;; input mapping function.
+          (ext:translate-character (input-box-display input-box)
+                                     key-code modifiers)))
+;;;
+(ext:serve-key-press *input-box-windows* #'key-pressed)
+\end{lisp}
+\begin{lisp}
+(defstruct (slider (:print-function print-slider)
+                   (:include input-box)
+                   (:constructor %make-slider
+                                    (display window window-width max)))
+  "Our program knows about sliders too, and these provide input values
+   zero to max."
+  bits-per-value  ; bits per discrete value up to max.
+  max)            ; End value for slider.
+;;;
+(defun print-slider (object stream n)
+  (declare (ignore n))
+  (format stream "#<Slider ~S  0..~D>"
+          (input-box-display object)
+          (1- (slider-max object))))
+;;;
+(defun make-slider (display window max)
+  (%make-slider display window
+                  (truncate (xlib:drawable-width window) max)
+                max))
+
+(defvar *slider-windows*
+        (system:make-object-set "Slider Windows"
+                                #'ext:default-clx-event-handler))
+
+(defun slider-pressed (slider event-key event-window root child
+                       same-screen-p x y root-x root-y modifiers time
+                       key-code send-event-p)
+  "This is our :key-press event handler for sliders.  Probably this is
+   a mouse thing, but for simplicity here we take a character typed."
+  (declare (ignore event-key root child same-screen-p x y
+                   root-x root-y time send-event-p))
+  (format t "KEY-PRESSED (Window = ~D) = ~S  -->  ~D.~%"
+          (xlib:window-id event-window)
+          ;; See Hemlock Command Implementor's Manual for convenient
+          ;; input mapping function.
+          (ext:translate-character (input-box-display slider)
+                                     key-code modifiers)
+          (truncate x (slider-bits-per-value slider))))
+;;;
+(ext:serve-key-press *slider-windows* #'slider-pressed)
+\end{lisp}
+\begin{lisp}
+(defun server-example ()
+  "An example of using the SYSTEM:SERVE-EVENT function and object sets to
+   handle CLX events."
+  (let* ((display (ext:open-clx-display))
+         (screen (display-default-screen display))
+         (black (screen-black-pixel screen))
+         (white (screen-white-pixel screen))
+         (iwindow (create-window :parent (screen-root screen)
+                                 :x 0 :y 0 :width 200 :height 200
+                                 :background white :border black
+                                 :border-width 2
+         (swindow (create-window :parent (screen-root screen)
+                                 :x 0 :y 300 :width 200 :height 50
+                                 :background white :border black
+                                 :border-width 2
+         (input-box (make-input-box display iwindow))
+         (slider (make-slider display swindow 15)))
+    ;; Wrap code in UNWIND-PROTECT, so we clean up after ourselves.
+    (unwind-protect
+        (progn
+          ;; Enable event handling on the display.
+          (ext:enable-clx-event-handling display
+                                         #'ext:object-set-event-handler)
+          ;; Add the windows to the appropriate object sets.
+                                       *input-box-windows*)
+                                       *slider-windows*)
+          ;; Map the windows to the screen.
+          (map-window iwindow)
+          (map-window swindow)
+          ;; Make sure we send all our requests.
+          (display-force-output display)
+          ;; Call server for 100,000 events or immediate timeouts.
+          (dotimes (i 100000) (system:serve-event)))
+      ;; Disable event handling on this display.
+      (ext:disable-clx-event-handling display)
+      (delete-window iwindow display)
+      (delete-window swindow display)
+      ;; Close the display.
+      (xlib:close-display display))))
+\end{lisp}
+\begin{lisp}
+(defun delete-window (window display)
+  ;; Remove the windows from the object sets before destroying them.
+  (system:remove-xwindow-object window)
+  ;; Destroy the window.
+  (destroy-window window)
+  ;; Pick off any events the X server has already queued for our
+  ;; windows, so we don't choke since SYSTEM:SERVE-EVENT is no longer
+  ;; prepared to handle events for us.
+  (loop
+   (unless (deleting-window-drop-event display window)
+     (return))))
+
+(defun deleting-window-drop-event (display win)
+  "Check for any events on win.  If there is one, remove it from the
+   event queue and return t; otherwise, return nil."
+  (xlib:display-finish-output display)
+  (let ((result nil))
+    (xlib:process-event
+     display :timeout 0
+     :handler #'(lambda (&key event-window &allow-other-keys)
+                  (if (eq event-window win)
+                      (setf result t)
+                      nil)))
+    result))
+\end{lisp}
+
+\hide{File:/afs/cs.cmu.edu/project/clisp/hackers/ram/docs/cmu-user/alien.ms}
+
+%%\node Alien Objects, Interprocess Communication under LISP, Event Dispatching with SERVE-EVENT, Top
+\chapter{Alien Objects}
+\label{aliens}
+\begin{center}
+\b{By Robert MacLachlan and William Lott}
+\end{center}
+\vspace{1 cm}
+
+\begin{comment}
+* Introduction to Aliens::
+* Alien Types::
+* Alien Operations::
+* Alien Variables::
+* Alien Data Structure Example::
+* Alien Function Calls::
+* Step-by-Step Alien Example::
+\end{comment}
+
+%%\node Introduction to Aliens, Alien Types, Alien Objects, Alien Objects
+\section{Introduction to Aliens}
+
+Because of Lisp's emphasis on dynamic memory allocation and garbage
+collection, Lisp implementations use unconventional memory representations
+for objects.  This representation mismatch creates problems when a Lisp
+program must share objects with programs written in another language.  There
+are three different approaches to establishing communication:
+\begin{itemize}
+\item The burden can be placed on the foreign program (and programmer) by
+requiring the use of Lisp object representations.  The main difficulty with
+this approach is that either the foreign program must be written with Lisp
+interaction in mind, or a substantial amount of foreign glue'' code must be
+written to perform the translation.
+
+\item The Lisp system can automatically convert objects back and forth
+between the Lisp and foreign representations.  This is convenient, but
+translation becomes prohibitively slow when large or complex data structures
+must be shared.
+
+\item The Lisp program can directly manipulate foreign objects through the
+use of extensions to the Lisp language.  Most Lisp systems make use of
+this approach, but the language for describing types and expressing
+accesses is often not powerful enough for complex objects to be easily
+manipulated.
+\end{itemize}
+\cmucl{} relies primarily on the automatic conversion and direct manipulation
+approaches: Aliens of simple scalar types are automatically converted,
+while complex types are directly manipulated in their foreign
+representation.  Any foreign objects that can't automatically be
+converted into Lisp values are represented by objects of type
+\code{alien-value}.  Since Lisp is a dynamically typed language, even
+foreign objects must have a run-time type; this type information is
+provided by encapsulating the raw pointer to the foreign data within an
+\code{alien-value} object.
+
+The Alien type language and operations are most similar to those of the
+C language, but Aliens can also be used when communicating with most
+other languages that can be linked with C.
+
+%%
+%%\node Alien Types, Alien Operations, Introduction to Aliens, Alien Objects
+\section{Alien Types}
+
+Alien types have a description language based on nested list structure.  For
+example:
+\begin{example}
+struct foo \{
+    int a;
+    struct foo *b[100];
+\};
+\end{example}
+has the corresponding Alien type:
+\begin{lisp}
+(struct foo
+  (a int)
+  (b (array (* (struct foo)) 100)))
+\end{lisp}
+
+
+\begin{comment}
+* Defining Alien Types::
+* Alien Types and Lisp Types::
+* Alien Type Specifiers::
+* The C-Call Package::
+\end{comment}
+
+%%\node Defining Alien Types, Alien Types and Lisp Types, Alien Types, Alien Types
+\subsection{Defining Alien Types}
+
+Types may be either named or anonymous.  With structure and union
+types, the name is part of the type specifier, allowing recursively
+defined types such as:
+\begin{lisp}
+(struct foo (a (* (struct foo))))
+\end{lisp}
+An anonymous structure or union type is specified by using the name
+\nil.  The \funref{with-alien} macro defines a local scope which
+captures'' any named type definitions.  Other types are not
+inherently named, but can be given named abbreviations using
+\code{def-alien-type}.
+
+\begin{defmac}{alien:}{def-alien-type}{name type}
+
+  This macro globally defines \var{name} as a shorthand for the Alien
+  type \var{type}.  When introducing global structure and union type
+  definitions, \var{name} may be \nil, in which case the name to
+  define is taken from the type's name.
+\end{defmac}
+
+
+%%\node Alien Types and Lisp Types, Alien Type Specifiers, Defining Alien Types, Alien Types
+\subsection{Alien Types and Lisp Types}
+
+The Alien types form a subsystem of the \cmucl{} type system.  An
+\code{alien} type specifier provides a way to use any Alien type as a
+Lisp type specifier.  For example
+\begin{lisp}
+(typep foo '(alien (* int)))
+\end{lisp}
+can be used to determine whether \code{foo} is a pointer to an
+\code{int}.  \code{alien} type specifiers can be used in the same ways
+as ordinary type specifiers (like \code{string}.)  Alien type
+declarations are subject to the same precise type checking as any
+other declaration (section \xlref{precise-type-checks}.)
+
+Note that the Alien type system overlaps with normal Lisp type
+specifiers in some cases.  For example, the type specifier
+\code{(alien single-float)} is identical to \code{single-float}, since
+Alien floats are automatically converted to Lisp floats.  When
+\code{type-of} is called on an Alien value that is not automatically
+converted to a Lisp value, then it will return an \code{alien} type
+specifier.
+
+%%\node Alien Type Specifiers, The C-Call Package, Alien Types and Lisp Types, Alien Types
+\subsection{Alien Type Specifiers}
+
+Some Alien type names are \clisp symbols, but the names are
+still exported from the \code{alien} package, so it is legal to say
+\code{alien:single-float}.  These are the basic Alien type specifiers:
+
+\begin{deftp}{Alien type}{*}{%
+    \args{\var{type}}}
+
+  A pointer to an object of the specified \var{type}.  If \var{type}
+  is \true, then it means a pointer to anything, similar to
+  \code{void *}'' in ANSI C.  Currently, the only way to detect a
+  null pointer is:
+\begin{lisp}
+  (zerop (sap-int (alien-sap \var{ptr})))
+\end{lisp}
+\xlref{system-area-pointers}
+\end{deftp}
+
+\begin{deftp}{Alien type}{array}{\var{type} \mstar{\var{dimension}}}
+
+  An array of the specified \var{dimensions}, holding elements of type
+  \var{type}.  Note that \code{(* int)} and \code{(array int)} are
+  considered to be different types when type checking is done; pointer
+  and array types must be explicitly coerced using \code{cast}.
+
+  Arrays are accessed using \code{deref}, passing the indices as
+  additional arguments.  Elements are stored in column-major order (as
+  in C), so the first dimension determines only the size of the memory
+  block, and not the layout of the higher dimensions.  An array whose
+  first dimension is variable may be specified by using \nil{} as the
+  first dimension.  Fixed-size arrays can be allocated as array
+  elements, structure slots or \code{with-alien} variables.  Dynamic
+  arrays can only be allocated using \funref{make-alien}.
+\end{deftp}
+
+\begin{deftp}{Alien type}{struct}{\var{name}
+    \mstar{(\var{field} \var{type} \mopt{\var{bits}})}}
+
+  A structure type with the specified \var{name} and \var{fields}.
+  Fields are allocated at the same positions used by the
+  implementation's C compiler.  \var{bits} is intended for C-like bit
+  field support, but is currently unused.  If \var{name} is \false,
+  then the type is anonymous.
+
+  If a named Alien \code{struct} specifier is passed to
+  \funref{def-alien-type} or \funref{with-alien}, then this defines,
+  respectively, a new global or local Alien structure type.  If no
+  \var{fields} are specified, then the fields are taken from the
+  current (local or global) Alien structure type definition of
+  \var{name}.
+\end{deftp}
+
+\begin{deftp}{Alien type}{union}{\var{name}
+    \mstar{(\var{field} \var{type} \mopt{\var{bits}})}}
+
+  Similar to \code{struct}, but defines a union type.  All fields are
+  allocated at the same offset, and the size of the union is the size
+  of the largest field.  The programmer must determine which field is
+  active from context.
+\end{deftp}
+
+\begin{deftp}{Alien type}{enum}{\var{name} \mstar{\var{spec}}}
+
+  An enumeration type that maps between integer values and keywords.
+  If \var{name} is \false, then the type is anonymous.  Each
+  \var{spec} is either a keyword, or a list \code{(\var{keyword}
+    \var{value})}.  If \var{integer} is not supplied, then it defaults
+  to one greater than the value for the preceding spec (or to zero if
+  it is the first spec.)
+\end{deftp}
+
+\begin{deftp}{Alien type}{signed}{\mopt{\var{bits}}}
+  A signed integer with the specified number of bits precision.  The
+  upper limit on integer precision is determined by the machine's word
+  size.  If no size is specified, the maximum size will be used.
+\end{deftp}
+
+\begin{deftp}{Alien type}{integer}{\mopt{\var{bits}}}
+  Identical to \code{signed}---the distinction between \code{signed}
+  and \code{integer} is purely stylistic.
+\end{deftp}
+
+\begin{deftp}{Alien type}{unsigned}{\mopt{\var{bits}}}
+  Like \code{signed}, but specifies an unsigned integer.
+\end{deftp}
+
+\begin{deftp}{Alien type}{boolean}{\mopt{\var{bits}}}
+  Similar to an enumeration type that maps \code{0} to \false{} and
+  all other values to \true.  \var{bits} determines the amount of
+  storage allocated to hold the truth value.
+\end{deftp}
+
+\begin{deftp}{Alien type}{single-float}{}
+  A floating-point number in IEEE single format.
+\end{deftp}
+
+\begin{deftp}{Alien type}{double-float}{}
+  A floating-point number in IEEE double format.
+\end{deftp}
+
+\begin{deftp}{Alien type}{function}{\var{result-type} \mstar{\var{arg-type}}}
+  \label{alien-function-types}
+  A Alien function that takes arguments of the specified
+  \var{arg-types} and returns a result of type \var{result-type}.
+  Note that the only context where a \code{function} type is directly
+  specified is in the argument to \code{alien-funcall} (see section
+  \funref{alien-funcall}.)  In all other contexts, functions are
+  represented by function pointer types: \code{(* (function ...))}.
+\end{deftp}
+
+\begin{deftp}{Alien type}{system-area-pointer}{}
+  A pointer which is represented in Lisp as a
+  \code{system-area-pointer} object (\pxlref{system-area-pointers}.)
+\end{deftp}
+
+%%\node The C-Call Package,  , Alien Type Specifiers, Alien Types
+\subsection{The C-Call Package}
+
+The \code{c-call} package exports these type-equivalents to the C type
+of the same name: \code{char}, \code{short}, \code{int}, \code{long},
+\code{unsigned-char}, \code{unsigned-short}, \code{unsigned-int},
+\code{unsigned-long}, \code{float}, \code{double}.  \code{c-call} also
+exports these types:
+
+\begin{deftp}{Alien type}{void}{}
+  This type is used in function types to declare that no useful value
+  is returned.  Evaluation of an \code{alien-funcall} form will return
+  zero values.
+\end{deftp}
+
+\begin{deftp}{Alien type}{c-string}{}
+  This type is similar to \code{(* char)}, but is interpreted as a
+  null-terminated string, and is automatically converted into a Lisp
+  string when accessed.  If the pointer is C \code{NULL} (or 0), then
+  accessing gives Lisp \false.
+
+  Assigning a Lisp string to a \code{c-string} structure field or
+  variable stores the contents of the string to the memory already
+  pointed to by that variable.  When an Alien of type \code{(* char)}
+  is assigned to a \code{c-string}, then the \code{c-string} pointer
+  is assigned to.  This allows \code{c-string} pointers to be
+  initialized.  For example:
+\begin{lisp}
+  (def-alien-type nil (struct foo (str c-string)))
+
+  (defun make-foo (str) (let ((my-foo (make-alien (struct foo))))
+  (setf (slot my-foo 'str) (make-alien char (length str))) (setf (slot
+  my-foo 'str) str) my-foo))
+\end{lisp}
+Storing Lisp \false{} writes C \code{NULL} to the \code{c-string}
+pointer.
+\end{deftp}
+
+%%
+%%\node Alien Operations, Alien Variables, Alien Types, Alien Objects
+\section{Alien Operations}
+
+This section describes the basic operations on Alien values.
+
+\begin{comment}
+* Alien Access Operations::
+* Alien Coercion Operations::
+* Alien Dynamic Allocation::
+\end{comment}
+
+%%\node Alien Access Operations, Alien Coercion Operations, Alien Operations, Alien Operations
+\subsection{Alien Access Operations}
+
+\begin{defun}{alien:}{deref}{\args{\var{pointer-or-array} \amprest \var{indices}}}
+
+  This function returns the value pointed to by an Alien pointer or
+  the value of an Alien array element.  If a pointer, an optional
+  single index can be specified to give the equivalent of C pointer
+  arithmetic; this index is scaled by the size of the type pointed to.
+  If an array, the number of indices must be the same as the number of
+  dimensions in the array type.  \code{deref} can be set with
+  \code{setf} to assign a new value.
+\end{defun}
+
+\begin{defun}{alien:}{slot}{\args{\var{struct-or-union} \var{slot-name}}}
+
+  This function extracts the value of slot \var{slot-name} from the an
+  Alien \code{struct} or \code{union}.  If \var{struct-or-union} is a
+  pointer to a structure or union, then it is automatically
+  dereferenced.  This can be set with \code{setf} to assign a new
+  value.  Note that \var{slot-name} is evaluated, and need not be a
+  compile-time constant (but only constant slot accesses are
+  efficiently compiled.)
+\end{defun}
+
+%%\node Alien Coercion Operations, Alien Dynamic Allocation, Alien Access Operations, Alien Operations
+\subsection{Alien Coercion Operations}
+
+
+  This macro returns a pointer to the location specified by
+  \var{alien-expr}, which must be either an Alien variable, a use of
+  \code{deref}, a use of \code{slot}, or a use of
+  \funref{extern-alien}.
+\end{defmac}
+
+\begin{defmac}{alien:}{cast}{\var{alien} \var{new-type}}
+
+  This macro converts \var{alien} to a new Alien with the specified
+  \var{new-type}.  Both types must be an Alien pointer, array or
+  function type.  Note that the result is not \code{eq} to the
+  argument, but does refer to the same data bits.
+\end{defmac}
+
+\begin{defmac}{alien:}{sap-alien}{\var{sap} \var{type}}
+  \defunx[alien:]{alien-sap}{\var{alien-value}}
+
+  \code{sap-alien} converts \var{sap} (a system area pointer
+  \pxlref{system-area-pointers}) to an Alien value with the specified
+  \var{type}.  \var{type} is not evaluated.
+
+\code{alien-sap} returns the SAP which points to \var{alien-value}'s
+data.
+
+The \var{type} to \code{sap-alien} and the type of the \var{alien-value} to
+\code{alien-sap} must some Alien pointer, array or record type.
+\end{defmac}
+
+%%\node Alien Dynamic Allocation,  , Alien Coercion Operations, Alien Operations
+\subsection{Alien Dynamic Allocation}
+
+Dynamic Aliens are allocated using the \code{malloc} library, so foreign code
+can call \code{free} on the result of \code{make-alien}, and Lisp code can
+call \code{free-alien} on objects allocated by foreign code.
+
+\begin{defmac}{alien:}{make-alien}{\var{type} \mopt{\var{size}}}
+
+  This macro returns a dynamically allocated Alien of the specified
+  \var{type} (which is not evaluated.)  The allocated memory is not
+  initialized, and may contain arbitrary junk.  If supplied,
+  \var{size} is an expression to evaluate to compute the size of the
+  allocated object.  There are two major cases:
+  \begin{itemize}
+  \item When \var{type} is an array type, an array of that type is
+    allocated and a \var{pointer} to it is returned.  Note that you
+    must use \code{deref} to change the result to an array before you
+    can use \code{deref} to read or write elements:
+    \begin{lisp}
+      (defvar *foo* (make-alien (array char 10)))
+
+      (type-of *foo*) \result{} (alien (* (array (signed 8) 10)))
+
+      (setf (deref (deref foo) 0) 10) \result{} 10
+    \end{lisp}
+    If supplied, \var{size} is used as the first dimension for the
+    array.
+
+  \item When \var{type} is any other type, then then an object for
+    that type is allocated, and a \var{pointer} to it is returned.  So
+    \code{(make-alien int)} returns a \code{(* int)}.  If \var{size}
+    is specified, then a block of that many objects is allocated, with
+    the result pointing to the first one.
+  \end{itemize}
+\end{defmac}
+
+\begin{defun}{alien:}{free-alien}{\var{alien}}
+
+  This function frees the storage for \var{alien} (which must have
+  been allocated with \code{make-alien} or \code{malloc}.)
+\end{defun}
+
+
+%%
+%%\node Alien Variables, Alien Data Structure Example, Alien Operations, Alien Objects
+\section{Alien Variables}
+
+Both local (stack allocated) and external (C global) Alien variables are
+supported.
+
+\begin{comment}
+* Local Alien Variables::
+* External Alien Variables::
+\end{comment}
+
+%%\node Local Alien Variables, External Alien Variables, Alien Variables, Alien Variables
+\subsection{Local Alien Variables}
+
+\begin{defmac}{alien:}{with-alien}{\mstar{(\var{name} \var{type}
+      \mopt{\var{initial-value}})} \mstar{form}}
+
+  This macro establishes local alien variables with the specified
+  Alien types and names for dynamic extent of the body.  The variable
+  \var{names} are established as symbol-macros; the bindings have
+  lexical scope, and may be assigned with \code{setq} or \code{setf}.
+  This form is analogous to defining a local variable in C: additional
+  storage is allocated, and the initial value is copied.
+
+  \code{with-alien} also establishes a new scope for named structures
+  and unions.  Any \var{type} specified for a variable may contain
+  name structure or union types with the slots specified.  Within the
+  lexical scope of the binding specifiers and body, a locally defined
+  structure type \var{foo} can be referenced by its name using:
+\begin{lisp}
+  (struct foo)
+\end{lisp}
+\end{defmac}
+
+%%\node External Alien Variables,  , Local Alien Variables, Alien Variables
+\subsection{External Alien Variables}
+\label{external-aliens}
+
+External Alien names are strings, and Lisp names are symbols.  When an
+external Alien is represented using a Lisp variable, there must be a
+way to convert from one name syntax into the other.  The macros
+\code{extern-alien}, \code{def-alien-variable} and
+\funref{def-alien-routine} use this conversion heuristic:
+\begin{itemize}
+\item Alien names are converted to Lisp names by uppercasing and
+  replacing underscores with hyphens.
+
+\item Conversely, Lisp names are converted to Alien names by
+  lowercasing and replacing hyphens with underscores.
+
+\item Both the Lisp symbol and Alien string names may be separately
+  specified by using a list of the form:
+\begin{lisp}
+  (\var{alien-string} \var{lisp-symbol})
+\end{lisp}
+\end{itemize}
+
+\begin{defmac}{alien:}{def-alien-variable}{\var{name} \var{type}}
+
+  This macro defines \var{name} as an external Alien variable of the
+  specified Alien \var{type}.  \var{name} and \var{type} are not
+  evaluated.  The Lisp name of the variable (see above) becomes a
+  global Alien variable in the Lisp namespace.  Global Alien variables
+  are effectively global symbol macros''; a reference to the
+  variable fetches the contents of the external variable.  Similarly,
+  setting the variable stores new contents---the new contents must be
+  of the declared \var{type}.
+
+  For example, it is often necessary to read the global C variable
+  \code{errno} to determine why a particular function call failed.  It
+  is possible to define errno and make it accessible from Lisp by the
+  following:
+\begin{lisp}
+(def-alien-variable "errno" int)
+
+;; Now it is possible to get the value of the C variable errno simply by
+;; referencing that Lisp variable:
+;;
+(print errno)
+\end{lisp}
+\end{defmac}
+
+\begin{defmac}{alien:}{extern-alien}{\var{name} \var{type}}
+
+  This macro returns an Alien with the specified \var{type} which
+  points to an externally defined value.  \var{name} is not evaluated,
+  and may be specified either as a string or a symbol.  \var{type} is
+  an unevaluated Alien type specifier.
+\end{defmac}
+
+%%
+%%\node Alien Data Structure Example, Loading Unix Object Files, Alien Variables, Alien Objects
+\section{Alien Data Structure Example}
+
+Now that we have Alien types, operations and variables, we can manipulate
+foreign data structures.  This C declaration can be translated into the
+following Alien type:
+\begin{lisp}
+struct foo \{
+    int a;
+    struct foo *b[100];
+\};
+
+ \myequiv
+
+(def-alien-type nil
+  (struct foo
+    (a int)
+    (b (array (* (struct foo)) 100))))
+\end{lisp}
+
+With this definition, the following C expression can be translated in this way:
+\begin{example}
+struct foo f;
+f.b[7].a
+
+ \myequiv
+
+(with-alien ((f (struct foo)))
+  (slot (deref (slot f 'b) 7) 'a)
+  ;;
+  ;; Do something with f...
+  )
+\end{example}
+
+
+Or consider this example of an external C variable and some accesses:
+\begin{example}
+struct c_struct \{
+        short x, y;
+        char a, b;
+        int z;
+        c_struct *n;
+\};
+
+extern struct c_struct *my_struct;
+
+my_struct->x++;
+my_struct->a = 5;
+my_struct = my_struct->n;
+\end{example}
+which can be made be manipulated in Lisp like this:
+\begin{lisp}
+(def-alien-type nil
+  (struct c-struct
+          (x short)
+          (y short)
+          (a char)
+          (b char)
+          (z int)
+          (n (* c-struct))))
+
+(def-alien-variable "my_struct" (* c-struct))
+
+(incf (slot my-struct 'x))
+(setf (slot my-struct 'a) 5)
+(setq my-struct (slot my-struct 'n))
+\end{lisp}
+
+
+%%
+%%\node Loading Unix Object Files, Alien Function Calls, Alien Data Structure Example, Alien Objects
+
+Foreign object files are loaded into the running Lisp process by
+libraries, creating an absolute Unix object file.  This object file is
+then loaded into into the currently running Lisp.  The external
+symbols defining routines and variables are made available for future
+external references (e.g.  by \code{extern-alien}.)
+\code{load-foreign} must be run before any of the defined symbols are
+referenced.
+
+Note that if a Lisp core image is saved (using \funref{save-lisp}), all
+loaded foreign code is lost when the image is restarted.
+
+    \args{\var{files} \keys{\kwd{libraries} \kwd{base-file} \kwd{env}}}}
+
+  \var{files} is a \code{simple-string} or list of
+  \code{simple-string}s specifying the names of the object files.
+  \var{libraries} is a list of \code{simple-string}s specifying
+  libraries in a format that \code{ld}, the Unix linker, expects.  The
+  default value for \var{libraries} is \code{("-lc")} (i.e., the
+  standard C library).  \var{base-file} is the file to use for the
+  initial symbol table information.  The default is the Lisp start up
+  code: \file{path:lisp}.  \var{env} should be a list of simple
+  strings in the format of Unix environment variables (i.e.,
+  \code{\var{A}=\var{B}}, where \var{A} is an environment variable and
+  \var{B} is its value).  The default value for \var{env} is the
+  environment information available at the time Lisp was invoked.
+  Unless you are certain that you want to change this, you should just
+  use the default.
+\end{defun}
+
+%%
+%%\node Alien Function Calls, Step-by-Step Alien Example, Loading Unix Object Files, Alien Objects
+\section{Alien Function Calls}
+
+The foreign function call interface allows a Lisp program to call functions
+written in other languages.  The current implementation of the foreign
+function call interface assumes a C calling convention and thus routines
+written in any language that adheres to this convention may be called from
+Lisp.
+
+Lisp sets up various interrupt handling routines and other environment
+information when it first starts up, and expects these to be in place at all
+times.  The C functions called by Lisp should either not change the
+environment, especially the interrupt entry points, or should make sure
+that these entry points are restored when the C function returns to Lisp.
+If a C function makes changes without restoring things to the way they were
+when the C function was entered, there is no telling what will happen.
+
+\begin{comment}
+* alien-funcall::               The alien-funcall Primitive
+* def-alien-routine::           The def-alien-routine Macro
+* def-alien-routine Example::
+* Calling Lisp from C::
+\end{comment}
+
+%%\node alien-funcall, def-alien-routine, Alien Function Calls, Alien Function Calls
+\subsection{The alien-funcall Primitive}
+
+\begin{defun}{alien:}{alien-funcall}{%
+    \args{\var{alien-function} \amprest{} \var{arguments}}}
+
+  This function is the foreign function call primitive:
+  \var{alien-function} is called with the supplied \var{arguments} and
+  its value is returned.  The \var{alien-function} is an arbitrary
+  run-time expression; to call a constant function, use
+  \funref{extern-alien} or \code{def-alien-routine}.
+
+  The type of \var{alien-function} must be \code{(alien (function
+    ...))} or \code{(alien (* (function ...)))},
+  \xlref{alien-function-types}.  The function type is used to
+  determine how to call the function (as though it was declared with
+  a prototype.)  The type need not be known at compile time, but only
+  known-type calls are efficiently compiled.  Limitations:
+  \begin{itemize}
+  \item Structure type return values are not implemented.
+  \item Passing of structures by value is not implemented.
+  \end{itemize}
+\end{defun}
+
+Here is an example which allocates a \code{(struct foo)}, calls a foreign
+function to initialize it, then returns a Lisp vector of all the
+\code{(* (struct foo))} objects filled in by the foreign call:
+\begin{lisp}
+;;
+;; Allocate a foo on the stack.
+(with-alien ((f (struct foo)))
+  ;;
+  ;; Call some C function to fill in foo fields.
+  (alien-funcall (extern-alien "mangle_foo" (function void (* foo)))
+  ;;
+  ;; Find how many foos to use by getting the A field.
+  (let* ((num (slot f 'a))
+         (result (make-array num)))
+    ;;
+    ;; Get a pointer to the array so that we don't have to keep extracting it:
+    (with-alien ((a (* (array (* (struct foo)) 100)) (addr (slot f 'b))))
+      ;;
+      ;; Loop over the first N elements and stash them in the result vector.
+      (dotimes (i num)
+        (setf (svref result i) (deref (deref a) i)))
+      result)))
+\end{lisp}
+
+%%\node def-alien-routine, def-alien-routine Example, alien-funcall, Alien Function Calls
+\subsection{The def-alien-routine Macro}
+
+
+\begin{defmac}{alien:}{def-alien-routine}{\var{name} \var{result-type}
+    \mstar{(\var{aname} \var{atype} \mopt{style})}}
+
+  This macro is a convenience for automatically generating Lisp
+  interfaces to simple foreign functions.  The primary feature is the
+  parameter style specification, which translates the C
+  pass-by-reference idiom into additional return values.
+
+  \var{name} is usually a string external symbol, but may also be a
+  symbol Lisp name or a list of the foreign name and the Lisp name.
+  If only one name is specified, the other is automatically derived,
+  (\pxlref{external-aliens}.)
+
+  \var{result-type} is the Alien type of the return value.  Each
+  remaining subform specifies an argument to the foreign function.
+  \var{aname} is the symbol name of the argument to the constructed
+  function (for documentation) and \var{atype} is the Alien type of
+  corresponding foreign argument.  The semantics of the actual call
+  are the same as for \funref{alien-funcall}.  \var{style} should be
+  one of the following:
+  \begin{Lentry}
+  \item[\kwd{in}] specifies that the argument is passed by value.
+    This is the default.  \kwd{in} arguments have no corresponding
+    return value from the Lisp function.
+
+  \item[\kwd{out}] specifies a pass-by-reference output value.  The
+    type of the argument must be a pointer to a fixed sized object
+    (such as an integer or pointer).  \kwd{out} and \kwd{in-out}
+    cannot be used with pointers to arrays, records or functions.  An
+    object of the correct size is allocated, and its address is passed
+    to the foreign function.  When the function returns, the contents
+    of this location are returned as one of the values of the Lisp
+    function.
+
+  \item[\kwd{copy}] is similar to \kwd{in}, but the argument is copied
+    to a pre-allocated object and a pointer to this object is passed
+    to the foreign routine.
+
+  \item[\kwd{in-out}] is a combination of \kwd{copy} and \kwd{out}.
+    The argument is copied to a pre-allocated object and a pointer to
+    this object is passed to the foreign routine.  On return, the
+    contents of this location is returned as an additional value.
+  \end{Lentry}
+  Any efficiency-critical foreign interface function should be inline
+  expanded by preceding \code{def-alien-routine} with:
+  \begin{lisp}
+    (declaim (inline \var{lisp-name}))
+  \end{lisp}
+  pointers, word-integers and floats to be passed using non-descriptor
+  representations, avoiding consing (\pxlref{non-descriptor}.)
+\end{defmac}
+
+%%\node def-alien-routine Example, Calling Lisp from C, def-alien-routine, Alien Function Calls
+\subsection{def-alien-routine Example}
+
+Consider the C function \code{cfoo} with the following calling convention:
+\begin{example}
+cfoo (str, a, i)
+    char *str;
+    char *a; /* update */
+    int *i; /* out */
+\{
+/* Body of cfoo. */
+\}
+\end{example}
+which can be described by the following call to \code{def-alien-routine}:
+\begin{lisp}
+(def-alien-routine "cfoo" void
+  (str c-string)
+  (a char :in-out)
+  (i int :out))
+\end{lisp}
+The Lisp function \code{cfoo} will have two arguments (\var{str} and \var{a})
+and two return values (\var{a} and \var{i}).
+
+%%\node Calling Lisp from C,  , def-alien-routine Example, Alien Function Calls
+\subsection{Calling Lisp from C}
+
+Calling Lisp functions from C is sometimes possible, but is rather hackish.
+See \code{funcall0} ... \code{funcall3} in the \file{lisp/arch.h}.  The
+arguments must be valid CMU CL object descriptors (e.g.  fixnums must be
+left-shifted by 2.)  See \file{compiler/generic/objdef.lisp} or the derived
+file \file{lisp/internals.h} for details of the object representation.
+\file{lisp/internals.h} is mechanically generated, and is not part of the
+source distribution.  It is distributed in the \file{docs/} directory of the
+binary distribution.
+
+Note that the garbage collector moves objects, and won't be able to fix up any
+references in C variables, so either turn GC off or don't keep Lisp pointers
+in C data unless they are to statically allocated objects.  You can use
+\funref{purify} to place live data structures in static space so that they
+won't move during GC.
+
+\begin{changebar}
+\subsection{Accessing Lisp Arrays}
+
+Due to the way \cmucl{} manages memory, the amount of memory that can
+be dynamically allocated by \code{malloc} or \funref{make-alien} is
+limited\footnote{\cmucl{} mmaps a large piece of memory for it's own
+  use and this memory is typically about 8 MB above the start of the C
+  heap.  Thus, only about 8 MB of memory can be dynamically
+  allocated.}.
+
+To overcome this limitation, it is possible to access the content of
+Lisp arrays which are limited only by the amount of physical memory
+and swap space available.  However, this technique is only useful if
+the foreign function takes pointers to memory instead of allocating
+memory for itself.  In latter case, you will have to modify the
+foreign functions.
+
+This technique takes advantage of the fact that \cmucl{} has
+specialized array types (\pxlref{specialized-array-types}) that match
+a typical C array.  For example, a \code{(simple-array double-float
+  (100))} is stored in memory in essentially the same way as the C
+array \code{double x[100]} would be.  The following function allows us
+to get the physical address of such a Lisp array:
+\begin{example}
+  "Return the physical address of where the actual data of an array is
+stored.
+
+ARRAY must be a specialized array type in CMU Lisp.  This means ARRAY
+must be an array of one of the following types:
+
+                  double-float
+                  single-float
+                  (unsigned-byte 32)
+                  (unsigned-byte 16)
+                  (unsigned-byte  8)
+                  (signed-byte 32)
+                  (signed-byte 16)
+                  (signed-byte  8)
+"
+  (declare (type (or #+signed-array (array (signed-byte 8))
+                     #+signed-array (array (signed-byte 16))
+                     #+signed-array (array (signed-byte 32))
+                     (array (unsigned-byte 8))
+                     (array (unsigned-byte 16))
+                     (array (unsigned-byte 32))
+                     (array single-float)
+                     (array double-float))
+                 array)
+           (optimize (speed 3) (safety 0))
+           (ext:optimize-interface (safety 3)))
+  ;; with-array-data will get us to the actual data.  However, because
+  ;; the array could have been displaced, we need to know where the
+  ;; data starts.
+  (lisp::with-array-data ((data array)
+                          (start)
+                          (end))
+    (declare (ignore end))
+    ;; DATA is a specialized simple-array.  Memory is laid out like this:
+    ;;
+    ;;   byte offset    Value
+    ;;        0         type code (should be 70 for double-float vector)
+    ;;        4         4 * number of elements in vector
+    ;;        8         1st element of vector
+    ;;      ...         ...
+    ;;
+          (type-size (let ((type (array-element-type data)))
+                       (cond ((or (equal type '(signed-byte 8))
+                                  (equal type '(unsigned-byte 8)))
+                              1)
+                             ((or (equal type '(signed-byte 16))
+                                  (equal type '(unsigned-byte 16)))
+                              2)
+                             ((or (equal type '(signed-byte 32))
+                                  (equal type '(unsigned-byte 32)))
+                              4)
+                             ((equal type 'single-float)
+                              4)
+                             ((equal type 'double-float)
+                              8)
+                             (t
+                              (error "Unknown specialized array element type"))))))
+      (declare (type (unsigned-byte 32) addr)
+               (optimize (speed 3) (safety 0) (ext:inhibit-warnings 3)))
+      (system:int-sap (the (unsigned-byte 32)
+                        (+ addr (* type-size start)))))))
+\end{example}
+
+Assume we have the C function below that we wish to use:
+\begin{example}
+  double dotprod(double* x, double* y, int n)
+  \{
+    int k;
+    double sum = 0;
+
+    for (k = 0; k < n; ++k) \{
+      sum += x[k] * y[k];
+    \}
+  \}
+\end{example}
+The following example generates two large arrays in Lisp, and calls the C
+function to do the desired computation.  This would not have been
+possible using \code{malloc} or \code{make-alien} since we need about
+16 MB of memory to hold the two arrays.
+\begin{example}
+  (def-alien-routine "dotprod" double
+    (x (* double-float) :in)
+    (y (* double-float) :in)
+    (n int :in))
+
+  (let ((x (make-array 1000000 :element-type 'double-float))
+        (y (make-array 1000000 :element-type 'double-float)))
+    ;; Initialize X and Y somehow
+\end{example}
+In this example, it may be useful to wrap the inner \code{let}
+expression in an \code{unwind-protect} that first turns off garbage
+collection and then turns garbage collection on afterwards.  This will
+prevent garbage collection from moving \code{x} and \code{y} after we
+have obtained the (now erroneous) addresses but before the call to
+
+\end{changebar}
+%%
+%%\node Step-by-Step Alien Example,  , Alien Function Calls, Alien Objects
+\section{Step-by-Step Alien Example}
+
+This section presents a complete example of an interface to a somewhat
+complicated C function.  This example should give a fairly good idea
+of how to get the effect you want for almost any kind of C function.
+Suppose you have the following C function which you want to be able to
+call from Lisp in the file \file{test.c}:
+\begin{verbatim}
+struct c_struct
+{
+  int x;
+  char *s;
+};
+
+struct c_struct *c_function (i, s, r, a)
+    int i;
+    char *s;
+    struct c_struct *r;
+    int a[10];
+{
+  int j;
+  struct c_struct *r2;
+
+  printf("i = %d\n", i);
+  printf("s = %s\n", s);
+  printf("r->x = %d\n", r->x);
+  printf("r->s = %s\n", r->s);
+  for (j = 0; j < 10; j++) printf("a[%d] = %d.\n", j, a[j]);
+  r2 = (struct c_struct *) malloc (sizeof(struct c_struct));
+  r2->x = i + 5;
+  r2->s = "A C string";
+  return(r2);
+};
+\end{verbatim}
+It is possible to call this function from Lisp using the file \file{test.lisp}
+whose contents is:
+\begin{lisp}
+;;; -*- Package: test-c-call -*-
+(in-package "TEST-C-CALL")
+(use-package "ALIEN")
+(use-package "C-CALL")
+
+;;; Define the record c-struct in Lisp.
+(def-alien-type nil
+    (struct c-struct
+            (x int)
+            (s c-string)))
+
+;;; Define the Lisp function interface to the C routine.  It returns a
+;;; pointer to a record of type c-struct.  It accepts four parameters:
+;;; i, an int; s, a pointer to a string; r, a pointer to a c-struct
+;;; record; and a, a pointer to the array of 10 ints.
+;;;
+;;; The INLINE declaration eliminates some efficiency notes about heap
+;;; allocation of Alien values.
+(declaim (inline c-function))
+(def-alien-routine c-function
+    (* (struct c-struct))
+  (i int)
+  (s c-string)
+  (r (* (struct c-struct)))
+  (a (array int 10)))
+
+;;; A function which sets up the parameters to the C function and
+;;; actually calls it.
+(defun call-cfun ()
+  (with-alien ((ar (array int 10))
+               (c-struct (struct c-struct)))
+    (dotimes (i 10)                     ; Fill array.
+      (setf (deref ar i) i))
+    (setf (slot c-struct 'x) 20)
+    (setf (slot c-struct 's) "A Lisp String")
+
+    (with-alien ((res (* (struct c-struct))
+                      (c-function 5 "Another Lisp String" (addr c-struct) ar)))
+      (format t "Returned from C function.~%")
+      (multiple-value-prog1
+          (values (slot res 'x)
+                  (slot res 's))
+        ;;
+        ;; Deallocate result \i{after} we are done using it.
+        (free-alien res)))))
+\end{lisp}
+To execute the above example, it is necessary to compile the C routine as
+follows:
+\begin{example}
+cc -c test.c
+\end{example}
+\begin{example}
+cc -G 0 -c test.c
+\end{example}
+Once the C code has been compiled, you can start up Lisp and load it in:
+\begin{example}
+%lisp
+;;; Lisp should start up with its normal prompt.
+
+;;; Compile the Lisp file.  This step can be done separately.  You don't have
+;;; to recompile every time.
+* (compile-file "test.lisp")
+
+;;; Load the foreign object file to define the necessary symbols.  This must
+;;; be done before loading any code that refers to these symbols.  next block
+;;; will give different warnings, but some warning about redefining the code
+;;; size is typical.
+
+;;; Parsing symbol table...
+Warning:  "_gp" moved from #x00C082C0 to #x00C08460.
+
+Warning:  "end" moved from #x00C00340 to #x00C004E0.
+
+;;; o.k. now load the compiled Lisp object file.
+
+;;; Now we can call the routine that sets up the parameters and calls the C
+;;; function.
+* (test-c-call::call-cfun)
+
+;;; The C routine prints the following information to standard output.
+i = 5
+s = Another Lisp string
+r->x = 20
+r->s = A Lisp string
+a[0] = 0.
+a[1] = 1.
+a[2] = 2.
+a[3] = 3.
+a[4] = 4.
+a[5] = 5.
+a[6] = 6.
+a[7] = 7.
+a[8] = 8.
+a[9] = 9.
+;;; Lisp prints out the following information.
+Returned from C function.
+;;; Return values from the call to test-c-call::call-cfun.
+10
+"A C string"
+*
+\end{example}
+
+If any of the foreign functions do output, they should not be called from
+within Hemlock.  Depending on the situation, various strange behavior occurs.
+Under X, the output goes to the window in which Lisp was started; on a
+terminal, the output will overwrite the Hemlock screen image; in a Hemlock
+slave, standard output is \file{/dev/null} by default, so any output is
+
+\hide{File:/afs/cs.cmu.edu/project/clisp/hackers/ram/docs/cmu-user/ipc.ms}
+
+%%\node Interprocess Communication under LISP, Debugger Programmer's Interface, Alien Objects, Top
+\chapter{Interprocess Communication under LISP}
+\begin{center}
+\b{Written by William Lott and Bill Chiles}
+\end{center}
+\label{remote}
+
+CMU Common Lisp offers a facility for interprocess communication (IPC)
+on top of using Unix system calls and the complications of that level
+of IPC.  There is a simple remote-procedure-call (RPC) package build
+on top of TCP/IP sockets.
+
+
+\begin{comment}
+* The REMOTE Package::
+* The WIRE Package::
+* Out-Of-Band Data::
+\end{comment}
+
+%%\node The REMOTE Package, The WIRE Package, Interprocess Communication under LISP, Interprocess Communication under LISP
+\section{The REMOTE Package}
+The \code{remote} package provides simple RPC facility including
+interfaces for creating servers, connecting to already existing
+servers, and calling functions in other Lisp processes.  The routines
+for establishing a connection between two processes,
+\code{create-request-server} and \code{connect-to-remote-server},
+return \var{wire} structures.  A wire maintains the current state of
+a connection, and all the RPC forms require a wire to indicate where
+to send requests.
+
+
+\begin{comment}
+* Connecting Servers and Clients::
+* Remote Evaluations::
+* Remote Objects::
+\end{comment}
+
+%%\node Connecting Servers and Clients, Remote Evaluations, The REMOTE Package, The REMOTE Package
+\subsection{Connecting Servers and Clients}
+
+Before a client can connect to a server, it must know the network address on
+which the server accepts connections.  Network addresses consist of a host
+address or name, and a port number.  Host addresses are either a string of the
+form \code{VANCOUVER.SLISP.CS.CMU.EDU} or a 32 bit unsigned integer.  Port
+numbers are 16 bit unsigned integers.  Note: \var{port} in this context has
+nothing to do with Mach ports and message passing.
+
+When a process wants to receive connection requests (that is, become a
+server), it first picks an integer to use as the port.  Only one server
+(Lisp or otherwise) can use a given port number on a given machine at
+any particular time.  This can be an iterative process to find a free
+port: picking an integer and calling \code{create-request-server}.  This
+function signals an error if the chosen port is unusable.  You will
+probably want to write a loop using \code{handler-case}, catching
+conditions of type error, since this function does not signal more
+specific conditions.
+
+\begin{defun}{wire:}{create-request-server}{%
+    \args{\var{port} \ampoptional{} \var{on-connect}}}
+
+  \code{create-request-server} sets up the current Lisp to accept
+  connections on the given port.  If port is unavailable for any
+  reason, this signals an error.  When a client connects to this port,
+  the acceptance mechanism makes a wire structure and invokes the
+  \var{on-connect} function.  Invoking this function has a couple
+  purposes, and \var{on-connect} may be \nil{} in which case the
+  system foregoes invoking any function at connect time.
+
+  The \var{on-connect} function is both a hook that allows you access
+  to the wire created by the acceptance mechanism, and it confirms the
+  connection.  This function takes two arguments, the wire and the
+  host address of the connecting process.  See the section on host
+  addresses below.  When \var{on-connect} is \nil, the request server
+  allows all connections.  When it is non-\nil, the function returns
+  two values, whether to accept the connection and a function the
+  system should call when the connection terminates.  Either value may
+  be \nil, but when the first value is \nil, the acceptance mechanism
+  destroys the wire.
+
+  \code{create-request-server} returns an object that
+  \code{destroy-request-server} uses to terminate a connection.
+\end{defun}
+
+\begin{defun}{wire:}{destroy-request-server}{\args{\var{server}}}
+
+  \code{destroy-request-server} takes the result of
+  \code{create-request-server} and terminates that server.  Any
+  existing connections remain intact, but all additional connection
+  attempts will fail.
+\end{defun}
+
+\begin{defun}{wire:}{connect-to-remote-server}{%
+    \args{\var{host} \var{port} \ampoptional{} \var{on-death}}}
+
+  \code{connect-to-remote-server} attempts to connect to a remote
+  server at the given \var{port} on \var{host} and returns a wire
+  structure if it is successful.  If \var{on-death} is non-\nil, it is
+  a function the system invokes when this connection terminates.
+\end{defun}
+
+
+%%\node Remote Evaluations, Remote Objects, Connecting Servers and Clients, The REMOTE Package
+\subsection{Remote Evaluations}
+After the server and client have connected, they each have a wire
+allowing function evaluation in the other process.  This RPC mechanism
+has three flavors: for side-effect only, for a single value, and for
+multiple values.
+
+Only a limited number of data types can be sent across wires as
+arguments for remote function calls and as return values: integers
+inclusively less than 32 bits in length, symbols, lists, and
+\var{remote-objects} (\pxlref{remote-objs}).  The system sends symbols
+as two strings, the package name and the symbol name, and if the
+package doesn't exist remotely, the remote process signals an error.
+The system ignores other slots of symbols.  Lists may be any tree of
+the above valid data types.  To send other data types you must
+represent them in terms of these supported types.  For example, you
+could use \code{prin1-to-string} locally, send the string, and use
+
+\begin{defmac}{wire:}{remote}{%
+    \args{\var{wire} \mstar{call-specs}}}
+
+  The \code{remote} macro arranges for the process at the other end of
+  \var{wire} to invoke each of the functions in the \var{call-specs}.
+  To make sure the system sends the remote evaluation requests over
+  the wire, you must call \code{wire-force-output}.
+
+  Each of \var{call-specs} looks like a function call textually, but
+  it has some odd constraints and semantics.  The function position of
+  the form must be the symbolic name of a function.  \code{remote}
+  evaluates each of the argument subforms for each of the
+  \var{call-specs} locally in the current context, sending these
+  values as the arguments for the functions.
+
+  Consider the following example:
+\begin{verbatim}
+(defun write-remote-string (str)
+  (declare (simple-string str))
+  (wire:remote wire
+    (write-string str)))
+\end{verbatim}
+  The value of \code{str} in the local process is passed over the wire
+  with a request to invoke \code{write-string} on the value.  The
+  system does not expect to remotely evaluate \code{str} for a value
+  in the remote process.
+\end{defmac}
+
+\begin{defun}{wire:}{wire-force-output}{\args{\var{wire}}}
+
+  \code{wire-force-output} flushes all internal buffers associated
+  with \var{wire}, sending the remote requests.  This is necessary
+  after a call to \code{remote}.
+\end{defun}
+
+\begin{defmac}{wire:}{remote-value}{\args{\var{wire} \var{call-spec}}}
+
+  The \code{remote-value} macro is similar to the \code{remote} macro.
+  \code{remote-value} only takes one \var{call-spec}, and it returns
+  the value returned by the function call in the remote process.  The
+  value must be a valid type the system can send over a wire, and
+  there is no need to call \code{wire-force-output} in conjunction
+  with this interface.
+
+  If client unwinds past the call to \code{remote-value}, the server
+  continues running, but the system ignores the value the server sends
+  back.
+
+  If the server unwinds past the remotely requested call, instead of
+  returning normally, \code{remote-value} returns two values, \nil{}
+  and \true.  Otherwise this returns the result of the remote
+  evaluation and \nil.
+\end{defmac}
+
+\begin{defmac}{wire:}{remote-value-bind}{%
+    \args{\var{wire} (\mstar{variable}) remote-form
+      \mstar{local-forms}}}
+
+  \code{remote-value-bind} is similar to \code{multiple-value-bind}
+  except the values bound come from \var{remote-form}'s evaluation in
+  the remote process.  The \var{local-forms} execute in an implicit
+  \code{progn}.
+
+  If the client unwinds past the call to \code{remote-value-bind}, the
+  server continues running, but the system ignores the values the
+  server sends back.
+
+  If the server unwinds past the remotely requested call, instead of
+  returning normally, the \var{local-forms} never execute, and
+  \code{remote-value-bind} returns \nil.
+\end{defmac}
+
+
+%%\node Remote Objects, Host Addresses, Remote Evaluations, The REMOTE Package
+\subsection{Remote Objects}
+\label{remote-objs}
+
+The wire mechanism only directly supports a limited number of data
+types for transmission as arguments for remote function calls and as
+return values: integers inclusively less than 32 bits in length,
+symbols, lists.  Sometimes it is useful to allow remote processes to
+refer to local data structures without allowing the remote process
+to operate on the data.  We have \var{remote-objects} to support
+this without the need to represent the data structure in terms of
+the above data types, to send the representation to the remote
+process, to decode the representation, to later encode it again, and
+to send it back along the wire.
+
+You can convert any Lisp object into a remote-object.  When you send
+a remote-object along a wire, the system simply sends a unique token
+for it.  In the remote process, the system looks up the token and
+returns a remote-object for the token.  When the remote process
+needs to refer to the original Lisp object as an argument to a
+remote call back or as a return value, it uses the remote-object it
+has which the system converts to the unique token, sending that
+along the wire to the originating process.  Upon receipt in the
+first process, the system converts the token back to the same
+(\code{eq}) remote-object.
+
+\begin{defun}{wire:}{make-remote-object}{\args{\var{object}}}
+
+  \code{make-remote-object} returns a remote-object that has
+  \var{object} as its value.  The remote-object can be passed across
+  wires just like the directly supported wire data types.
+\end{defun}
+
+\begin{defun}{wire:}{remote-object-p}{\args{\var{object}}}
+
+  The function \code{remote-object-p} returns \true{} if \var{object}
+  is a remote object and \nil{} otherwise.
+\end{defun}
+
+\begin{defun}{wire:}{remote-object-local-p}{\args{\var{remote}}}
+
+  The function \code{remote-object-local-p} returns \true{} if
+  \var{remote} refers to an object in the local process.  This is can
+  only occur if the local process created \var{remote} with
+  \code{make-remote-object}.
+\end{defun}
+
+\begin{defun}{wire:}{remote-object-eq}{\args{\var{obj1} \var{obj2}}}
+
+  The function \code{remote-object-eq} returns \true{} if \var{obj1} and
+  \var{obj2} refer to the same (\code{eq}) lisp object, regardless of
+  which process created the remote-objects.
+\end{defun}
+
+\begin{defun}{wire:}{remote-object-value}{\args{\var{remote}}}
+
+  This function returns the original object used to create the given
+  remote object.  It is an error if some other process originally
+  created the remote-object.
+\end{defun}
+
+\begin{defun}{wire:}{forget-remote-translation}{\args{\var{object}}}
+
+  This function removes the information and storage necessary to
+  translate remote-objects back into \var{object}, so the next
+  \code{gc} can reclaim the memory.  You should use this when you no
+  longer expect to receive references to \var{object}.  If some remote
+  process does send a reference to \var{object},
+  \code{remote-object-value} signals an error.
+\end{defun}
+
+
+%%\node Host Addresses,  , Remote Objects, The REMOTE Package
+The operating system maintains a database of all the valid host
+addresses.  You can use this database to convert between host names
+
+\begin{defun}{ext:}{lookup-host-entry}{\args{\var{host}}}
+
+  \code{lookup-host-entry} searches the database for the given
+  \var{host} and returns a host-entry structure for it.  If it fails
+  to find \var{host} in the database, it returns \nil.  \var{Host} is
+  either the address (as an integer) or the name (as a string) of the
+  desired host.
+\end{defun}
+
+\begin{defun}{ext:}{host-entry-name}{\args{\var{host-entry}}}
+  \defunx[ext:]{host-entry-aliases}{\args{\var{host-entry}}}
+
+  \code{host-entry-name}, \code{host-entry-aliases}, and
+  \code{host-entry-addr-list} each return the indicated slot from the
+  host-entry structure.  \code{host-entry-addr} returns the primary
+  (first) address from the list returned by
+\end{defun}
+
+
+%%\node The WIRE Package, Out-Of-Band Data, The REMOTE Package, Interprocess Communication under LISP
+\section{The WIRE Package}
+
+The \code{wire} package provides for sending data along wires.  The
+\code{remote} package sits on top of this package.  All data sent
+with a given output routine must be read in the remote process with
+the complementary fetching routine.  For example, if you send so a
+string with \code{wire-output-string}, the remote process must know
+to use \code{wire-get-string}.  To avoid rigid data transfers and
+complicated code, the interface supports sending
+\var{tagged} data.  With tagged data, the system sends a tag
+announcing the type of the next data, and the remote system takes
+care of fetching the appropriate type.
+
+When using interfaces at the wire level instead of the RPC level,
+the remote process must read everything sent by these routines.  If
+the remote process leaves any input on the wire, it will later
+mistake the data for an RPC request causing unknown lossage.
+
+\begin{comment}
+* Untagged Data::
+* Tagged Data::
+\end{comment}
+
+%%\node Untagged Data, Tagged Data, The WIRE Package, The WIRE Package
+\subsection{Untagged Data}
+When using these routines both ends of the wire know exactly what types are
+coming and going and in what order. This data is restricted to the following
+types:
+\begin{itemize}
+
+\item
+8 bit unsigned bytes.
+
+\item
+32 bit unsigned bytes.
+
+\item
+32 bit integers.
+
+\item
+simple-strings less than 65535 in length.
+\end{itemize}
+
+
+\begin{defun}{wire:}{wire-output-byte}{\args{\var{wire} \var{byte}}}
+  \defunx[wire:]{wire-get-byte}{\args{\var{wire}}}
+  \defunx[wire:]{wire-output-number}{\args{\var{wire} \var{number}}}
+  \defunx[wire:]{wire-get-number}{\args{\var{wire} \ampoptional{}
+      \var{signed}}}
+  \defunx[wire:]{wire-output-string}{\args{\var{wire} \var{string}}}
+  \defunx[wire:]{wire-get-string}{\args{\var{wire}}}
+
+  These functions either output or input an object of the specified
+  data type.  When you use any of these output routines to send data
+  across the wire, you must use the corresponding input routine
+  interpret the data.
+\end{defun}
+
+
+%%\node Tagged Data, Making Your Own Wires, Untagged Data, The WIRE Package
+\subsection{Tagged Data}
+When using these routines, the system automatically transmits and interprets
+the tags for you, so both ends can figure out what kind of data transfers
+occur.  Sending tagged data allows a greater variety of data types: integers
+inclusively less than 32 bits in length, symbols, lists, and \var{remote-objects}
+(\pxlref{remote-objs}).  The system sends symbols as two strings, the
+package name and the symbol name, and if the package doesn't exist remotely,
+the remote process signals an error.  The system ignores other slots of
+symbols.  Lists may be any tree of the above valid data types.  To send other
+data types you must represent them in terms of these supported types.  For
+example, you could use \code{prin1-to-string} locally, send the string, and use
+
+\begin{defun}{wire:}{wire-output-object}{%
+    \args{\var{wire} \var{object} \ampoptional{} \var{cache-it}}}
+  \defunx[wire:]{wire-get-object}{\args{\var{wire}}}
+
+  The function \code{wire-output-object} sends \var{object} over
+  \var{wire} preceded by a tag indicating its type.
+
+  If \var{cache-it} is non-\nil, this function only sends \var{object}
+  the first time it gets \var{object}.  Each end of the wire
+  associates a token with \var{object}, similar to remote-objects,
+  allowing you to send the object more efficiently on successive
+  transmissions.  \var{cache-it} defaults to \true{} for symbols and
+  \nil{} for other types.  Since the RPC level requires function
+  names, a high-level protocol based on a set of function calls saves
+  time in sending the functions' names repeatedly.
+
+  The function \code{wire-get-object} reads the results of
+  \code{wire-output-object} and returns that object.
+\end{defun}
+
+
+%%\node Making Your Own Wires,  , Tagged Data, The WIRE Package
+You can create wires manually in addition to the \code{remote} package's
+interface creating them for you.  To create a wire, you need a Unix \i{file
+descriptor}.  If you are unfamiliar with Unix file descriptors, see section 2 of
+the Unix manual pages.
+
+\begin{defun}{wire:}{make-wire}{\args{\var{descriptor}}}
+
+  The function \code{make-wire} creates a new wire when supplied with
+  the file descriptor to use for the underlying I/O operations.
+\end{defun}
+
+\begin{defun}{wire:}{wire-p}{\args{\var{object}}}
+
+  This function returns \true{} if \var{object} is indeed a wire,
+  \nil{} otherwise.
+\end{defun}
+
+\begin{defun}{wire:}{wire-fd}{\args{\var{wire}}}
+
+  This function returns the file descriptor used by the \var{wire}.
+\end{defun}
+
+
+%%\node Out-Of-Band Data,  , The WIRE Package, Interprocess Communication under LISP
+\section{Out-Of-Band Data}
+
+The TCP/IP protocol allows users to send data asynchronously, otherwise
+known as \var{out-of-band} data.  When using this feature, the operating
+system interrupts the receiving process if this process has chosen to be
+without affecting any information currently queued on the socket.
+Therefore, you can use this without interfering with any current
+activity due to other wire and remote interfaces.
+
+Unfortunately, most implementations of TCP/IP are broken, so use of
+out-of-band data is limited for safety reasons.  You can only reliably
+send one character at a time.
+
+This routines in this section provide a mechanism for establishing
+handlers for out-of-band characters and for sending them out-of-band.
+These all take a Unix file descriptor instead of a wire, but you can
+fetch a wire's file descriptor with \code{wire-fd}.
+
+
+  The function \code{add-oob-handler} arranges for \var{handler} to be
+  called whenever \var{char} shows up as out-of-band data on the file
+  descriptor \var{fd}.
+\end{defun}
+
+\begin{defun}{wire:}{remove-oob-handler}{\args{\var{fd} \var{char}}}
+
+  This function removes the handler for the character \var{char} on
+  the file descriptor \var{fd}.
+\end{defun}
+
+\begin{defun}{wire:}{remove-all-oob-handlers}{\args{\var{fd}}}
+
+  This function removes all handlers for the file descriptor \var{fd}.
+\end{defun}
+
+\begin{defun}{wire:}{send-character-out-of-band}{\args{\var{fd} \var{char}}}
+
+  This function Sends the character \var{char} down the file
+  descriptor \var{fd} out-of-band.
+\end{defun}
+
+%%
+\hide{File:debug-int.tex}
+%%\node Debugger Programmer's Interface, Function Index, Interprocess Communication under LISP, Top
+\chapter{Debugger Programmer's Interface}
+\label{debug-internals}
+
+The debugger programmers interface is exported from from the
+\code{"DEBUG-INTERNALS"} or \code{"DI"} package.  This is a CMU
+extension that allows debugging tools to be written without detailed
+knowledge of the compiler or run-time system.
+
+Some of the interface routines take a code-location as an argument.  As
+described in the section on code-locations, some code-locations are
+unknown.  When a function calls for a \var{basic-code-location}, it
+takes either type, but when it specifically names the argument
+\var{code-location}, the routine will signal an error if you give it an
+unknown code-location.
+
+\begin{comment}
+* DI Exceptional Conditions::
+* Debug-variables::
+* Frames::
+* Debug-functions::
+* Debug-blocks::
+* Breakpoints::
+* Code-locations::
+* Debug-sources::
+* Source Translation Utilities::
+\end{comment}
+
+%%
+%%\node DI Exceptional Conditions, Debug-variables, Debugger Programmer's Interface, Debugger Programmer's Interface
+\section{DI Exceptional Conditions}
+
+Some of these operations fail depending on the availability debugging
+information.  In the most severe case, when someone saved a Lisp image
+stripping all debugging data structures, no operations are valid.  In
+this case, even backtracing and finding frames is impossible.  Some
+interfaces can simply return values indicating the lack of information,
+or their return values are naturally meaningful in light missing data.
+Other routines, as documented below, will signal
+\code{serious-condition}s when they discover awkward situations.  This
+interface does not provide for programs to detect these situations other
+than by calling a routine that detects them and signals a condition.
+These are serious-conditions because the program using the interface
+must handle them before it can correctly continue execution.  These
+debugging conditions are not errors since it is no fault of the
+programmers that the conditions occur.
+
+\begin{comment}
+* Debug-conditions::
+* Debug-errors::
+\end{comment}
+
+%%\node Debug-conditions, Debug-errors, DI Exceptional Conditions, DI Exceptional Conditions
+\subsection{Debug-conditions}
+
+The debug internals interface signals conditions when it can't adhere
+to its contract.  These are serious-conditions because the program
+using the interface must handle them before it can correctly continue
+execution.  These debugging conditions are not errors since it is no
+fault of the programmers that the conditions occur.  The interface
+does not provide for programs to detect these situations other than
+calling a routine that detects them and signals a condition.
+
+
+\begin{deftp}{Condition}{debug-condition}{}
+
+This condition inherits from serious-condition, and all debug-conditions
+inherit from this.  These must be handled, but they are not programmer errors.
+\end{deftp}
+
+
+\begin{deftp}{Condition}{no-debug-info}{}
+
+This condition indicates there is absolutely no debugging information
+available.
+\end{deftp}
+
+
+\begin{deftp}{Condition}{no-debug-function-returns}{}
+
+This condition indicates the system cannot return values from a frame since
+its debug-function lacks debug information details about returning values.
+\end{deftp}
+
+
+\begin{deftp}{Condition}{no-debug-blocks}{}
+This condition indicates that a function was not compiled with debug-block
+information, but this information is necessary necessary for some requested
+operation.
+\end{deftp}
+
+\begin{deftp}{Condition}{no-debug-variables}{}
+Similar to \code{no-debug-blocks}, except that variable information was
+requested.
+\end{deftp}
+
+\begin{deftp}{Condition}{lambda-list-unavailable}{}
+Similar to \code{no-debug-blocks}, except that lambda list information was
+requested.
+\end{deftp}
+
+\begin{deftp}{Condition}{invalid-value}{}
+
+This condition indicates a debug-variable has \kwd{invalid} or \kwd{unknown}
+value in a particular frame.
+\end{deftp}
+
+
+\begin{deftp}{Condition}{ambiguous-variable-name}{}
+
+This condition indicates a user supplied debug-variable name identifies more
+than one valid variable in a particular frame.
+\end{deftp}
+
+
+%%\node Debug-errors,  , Debug-conditions, DI Exceptional Conditions
+\subsection{Debug-errors}
+
+These are programmer errors resulting from misuse of the debugging tools'
+programmers' interface.  You could have avoided an occurrence of one of these
+by using some routine to check the use of the routine generating the error.
+
+
+\begin{deftp}{Condition}{debug-error}{}
+This condition inherits from error, and all user programming errors inherit
+from this condition.
+\end{deftp}
+
+
+\begin{deftp}{Condition}{unhandled-condition}{}
+This error results from a signalled \code{debug-condition} occurring
+without anyone handling it.
+\end{deftp}
+
+
+\begin{deftp}{Condition}{unknown-code-location}{}
+This error indicates the invalid use of an unknown-code-location.
+\end{deftp}
+
+
+\begin{deftp}{Condition}{unknown-debug-variable}{}
+
+This error indicates an attempt to use a debug-variable in conjunction with an
+inappropriate debug-function; for example, checking the variable's validity
+using a code-location in the wrong debug-function will signal this error.
+\end{deftp}
+
+
+\begin{deftp}{Condition}{frame-function-mismatch}{}
+
+This error indicates you called a function returned by
+\code{preprocess-for-eval}
+on a frame other than the one for which the function had been prepared.
+\end{deftp}
+
+
+%%
+%%\node Debug-variables, Frames, DI Exceptional Conditions, Debugger Programmer's Interface
+\section{Debug-variables}
+
+Debug-variables represent the constant information about where the system
+stores argument and local variable values.  The system uniquely identifies with
+an integer every instance of a variable with a particular name and package.  To
+access a value, you must supply the frame along with the debug-variable since
+these are particular to a function, not every instance of a variable on the
+stack.
+
+\begin{defun}{}{debug-variable-name}{\args{\var{debug-variable}}}
+
+  This function returns the name of the \var{debug-variable}.  The
+  name is the name of the symbol used as an identifier when writing
+  the code.
+\end{defun}
+
+
+\begin{defun}{}{debug-variable-package}{\args{\var{debug-variable}}}
+
+  This function returns the package name of the \var{debug-variable}.
+  This is the package name of the symbol used as an identifier when
+  writing the code.
+\end{defun}
+
+
+\begin{defun}{}{debug-variable-symbol}{\args{\var{debug-variable}}}
+
+  This function returns the symbol from interning
+  \code{debug-variable-name} in the package named by
+  \code{debug-variable-package}.
+\end{defun}
+
+
+\begin{defun}{}{debug-variable-id}{\args{\var{debug-variable}}}
+
+  This function returns the integer that makes \var{debug-variable}'s
+  name and package name unique with respect to other
+  \var{debug-variable}'s in the same function.
+\end{defun}
+
+
+\begin{defun}{}{debug-variable-validity}{%
+    \args{\var{debug-variable} \var{basic-code-location}}}
+
+  This function returns three values reflecting the validity of
+  \var{debug-variable}'s value at \var{basic-code-location}:
+  \begin{Lentry}
+  \item[\kwd{valid}] The value is known to be available.
+  \item[\kwd{invalid}] The value is known to be unavailable.
+  \item[\kwd{unknown}] The value's availability is unknown.
+  \end{Lentry}
+\end{defun}
+
+
+\begin{defun}{}{debug-variable-value}{\args{\var{debug-variable}
+      \var{frame}}}
+
+  This function returns the value stored for \var{debug-variable} in
+  \var{frame}.  The value may be invalid.  This is \code{SETF}'able.
+\end{defun}
+
+
+\begin{defun}{}{debug-variable-valid-value}{%
+    \args{\var{debug-variable} \var{frame}}}
+
+  This function returns the value stored for \var{debug-variable} in
+  \var{frame}.  If the value is not \kwd{valid}, then this signals an
+  \code{invalid-value} error.
+\end{defun}
+
+
+%%
+%%\node Frames, Debug-functions, Debug-variables, Debugger Programmer's Interface
+\section{Frames}
+
+Frames describe a particular call on the stack for a particular thread.  This
+is the environment for name resolution, getting arguments and locals, and
+returning values.  The stack conceptually grows up, so the top of the stack is
+the most recently called function.
+
+\code{top-frame}, \code{frame-down}, \code{frame-up}, and
+\code{frame-debug-function} can only fail when there is absolutely no
+debug information available.  This can only happen when someone saved a
+Lisp image specifying that the system dump all debugging data.
+
+
+\begin{defun}{}{top-frame}{}
+
+  This function never returns the frame for itself, always the frame
+  before calling \code{top-frame}.
+\end{defun}
+
+
+\begin{defun}{}{frame-down}{\args{\var{frame}}}
+
+  This returns the frame immediately below \var{frame} on the stack.
+  When \var{frame} is the bottom of the stack, this returns \nil.
+\end{defun}
+
+
+\begin{defun}{}{frame-up}{\args{\var{frame}}}
+
+  This returns the frame immediately above \var{frame} on the stack.
+  When \var{frame} is the top of the stack, this returns \nil.
+\end{defun}
+
+
+\begin{defun}{}{frame-debug-function}{\args{\var{frame}}}
+
+  This function returns the debug-function for the function whose call
+  \var{frame} represents.
+\end{defun}
+
+
+\begin{defun}{}{frame-code-location}{\args{\var{frame}}}
+
+  This function returns the code-location where \var{frame}'s
+  debug-function will continue running when program execution returns
+  to \var{frame}.  If someone interrupted this frame, the result could
+  be an unknown code-location.
+\end{defun}
+
+
+\begin{defun}{}{frame-catches}{\args{\var{frame}}}
+
+  This function returns an a-list for all active catches in
+  \var{frame} mapping catch tags to the code-locations at which the
+  catch re-enters.
+\end{defun}
+
+
+\begin{defun}{}{eval-in-frame}{\args{\var{frame} \var{form}}}
+
+  This evaluates \var{form} in \var{frame}'s environment.  This can
+  signal several different debug-conditions since its success relies
+  on a variety of inexact debug information: \code{invalid-value},
+  \code{ambiguous-variable-name}, \code{frame-function-mismatch}.  See
+  also \funref{preprocess-for-eval}.
+\end{defun}
+
+\begin{comment}
+  \begin{defun}{}{return-from-frame}{\args{\var{frame} \var{values}}}
+
+    This returns the elements in the list \var{values} as multiple
+    values from \var{frame} as if the function \var{frame} represents
+    returned these values.  This signals a
+    \code{no-debug-function-returns} condition when \var{frame}'s
+    debug-function lacks information on returning values.
+
+    \i{Not Yet Implemented}
+  \end{defun}
+\end{comment}
+
+%%
+%%\node Debug-functions, Debug-blocks, Frames, Debugger Programmer's Interface
+\section {Debug-functions}
+
+Debug-functions represent the static information about a function determined at
+compile time---argument and variable storage, their lifetime information,
+etc.  The debug-function also contains all the debug-blocks representing
+basic-blocks of code, and these contains information about specific
+code-locations in a debug-function.
+
+\begin{defmac}{}{do-debug-function-blocks}{%
+    \args{(\var{block-var} \var{debug-function} \mopt{result-form})
+      \mstar{form}}}
+
+  This executes the forms in a context with \var{block-var} bound to
+  each debug-block in \var{debug-function} successively.
+  \var{Result-form} is an optional form to execute for a return value,
+  and \code{do-debug-function-blocks} returns \nil if there is no
+  \var{result-form}.  This signals a \code{no-debug-blocks} condition
+  when the \var{debug-function} lacks debug-block information.
+\end{defmac}
+
+
+\begin{defun}{}{debug-function-lambda-list}{\args{\var{debug-function}}}
+
+  This function returns a list representing the lambda-list for
+  \var{debug-function}.  The list has the following structure:
+  \begin{example}
+    (required-var1 required-var2
+    ...
+    (:optional var3 suppliedp-var4)
+    (:optional var5)
+    ...
+    (:rest var6) (:rest var7)
+    ...
+    (:keyword keyword-symbol var8 suppliedp-var9)
+    (:keyword keyword-symbol var10)
+    ...
+    )
+  \end{example}
+  Each \code{var}\var{n} is a debug-variable; however, the symbol
+  \kwd{deleted} appears instead whenever the argument remains
+  unreferenced throughout \var{debug-function}.
+
+  If there is no lambda-list information, this signals a
+  \code{lambda-list-unavailable} condition.
+\end{defun}
+
+
+\begin{defmac}{}{do-debug-function-variables}{%
+    \args{(\var{var} \var{debug-function} \mopt{result})
+      \mstar{form}}}
+
+  This macro executes each \var{form} in a context with \var{var}
+  bound to each debug-variable in \var{debug-function}.  This returns
+  the value of executing \var{result} (defaults to \nil).  This may
+  iterate over only some of \var{debug-function}'s variables or none
+  depending on debug policy; for example, possibly the compilation
+  only preserved argument information.
+\end{defmac}
+
+
+\begin{defun}{}{debug-variable-info-available}{\args{\var{debug-function}}}
+
+  This function returns whether there is any variable information for
+  \var{debug-function}.  This is useful for distinguishing whether
+  there were no locals in a function or whether there was no variable
+  information.  For example, if \code{do-debug-function-variables}
+  executes its forms zero times, then you can use this function to
+  determine the reason.
+\end{defun}
+
+
+\begin{defun}{}{debug-function-symbol-variables}{%
+    \args{\var{debug-function} \var{symbol}}}
+
+  This function returns a list of debug-variables in
+  \var{debug-function} having the same name and package as
+  \var{symbol}.  If \var{symbol} is uninterned, then this returns a
+  list of debug-variables without package names and with the same name
+  as \var{symbol}.  The result of this function is limited to the
+  availability of variable information in \var{debug-function}; for
+  example, possibly \var{debug-function} only knows about its
+  arguments.
+\end{defun}
+
+
+\begin{defun}{}{ambiguous-debug-variables}{%
+    \args{\var{debug-function} \var{name-prefix-string}}}
+
+  This function returns a list of debug-variables in
+  \var{debug-function} whose names contain \var{name-prefix-string} as
+  an initial substring.  The result of this function is limited to the
+  availability of variable information in \var{debug-function}; for
+  example, possibly \var{debug-function} only knows about its
+  arguments.
+\end{defun}
+
+
+\begin{defun}{}{preprocess-for-eval}{%
+    \args{\var{form} \var{basic-code-location}}}
+
+  This function returns a function of one argument that evaluates
+  \var{form} in the lexical context of \var{basic-code-location}.
+  This allows efficient repeated evaluation of \var{form} at a certain
+  place in a function which could be useful for conditional breaking.
+  This signals a \code{no-debug-variables} condition when the
+  code-location's debug-function has no debug-variable information
+  available.  The returned function takes a frame as an argument.  See
+  also \funref{eval-in-frame}.
+\end{defun}
+
+
+\begin{defun}{}{function-debug-function}{\args{\var{function}}}
+
+  This function returns a debug-function that represents debug
+  information for \var{function}.
+\end{defun}
+
+
+\begin{defun}{}{debug-function-kind}{\args{\var{debug-function}}}
+
+  This function returns the kind of function \var{debug-function}
+  represents.  The value is one of the following:
+  \begin{Lentry}
+  \item[\kwd{optional}] This kind of function is an entry point to an
+    ordinary function.  It handles optional defaulting, parsing
+    keywords, etc.
+  \item[\kwd{external}] This kind of function is an entry point to an
+    ordinary function.  It checks argument values and count and calls
+    the defined function.
+  \item[\kwd{top-level}] This kind of function executes one or more
+    random top-level forms from a file.
+  \item[\kwd{cleanup}] This kind of function represents the cleanup
+    forms in an \code{unwind-protect}.
+  \item[\nil] This kind of function is not one of the above; that is,
+    it is not specially marked in any way.
+  \end{Lentry}
+\end{defun}
+
+
+\begin{defun}{}{debug-function-function}{\args{\var{debug-function}}}
+
+  This function returns the Common Lisp function associated with the
+  \var{debug-function}.  This returns \nil{} if the function is
+  unavailable or is non-existent as a user callable function object.
+\end{defun}
+
+
+\begin{defun}{}{debug-function-name}{\args{\var{debug-function}}}
+
+  This function returns the name of the function represented by
+  \var{debug-function}.  This may be a string or a cons; do not assume
+  it is a symbol.
+\end{defun}
+
+
+%%
+%%\node Debug-blocks, Breakpoints, Debug-functions, Debugger Programmer's Interface
+\section{Debug-blocks}
+
+Debug-blocks contain information pertinent to a specific range of code in a
+debug-function.
+
+\begin{defmac}{}{do-debug-block-locations}{%
+    \args{(\var{code-var} \var{debug-block} \mopt{result})
+      \mstar{form}}}
+
+  This macro executes each \var{form} in a context with \var{code-var}
+  bound to each code-location in \var{debug-block}.  This returns the
+  value of executing \var{result} (defaults to \nil).
+\end{defmac}
+
+
+\begin{defun}{}{debug-block-successors}{\args{\var{debug-block}}}
+
+  This function returns the list of possible code-locations where
+  execution may continue when the basic-block represented by
+  \var{debug-block} completes its execution.
+\end{defun}
+
+
+\begin{defun}{}{debug-block-elsewhere-p}{\args{\var{debug-block}}}
+
+  This function returns whether \var{debug-block} represents elsewhere
+  code.  This is code the compiler has moved out of a function's code
+  sequence for optimization reasons.  Code-locations in these blocks
+  are unsuitable for stepping tools, and the first code-location has
+  nothing to do with a normal starting location for the block.
+\end{defun}
+
+
+%%
+%%\node Breakpoints, Code-locations, Debug-blocks, Debugger Programmer's Interface
+\section{Breakpoints}
+
+A breakpoint represents a function the system calls with the current frame when
+execution passes a certain code-location.  A break point is active or inactive
+independent of its existence.  They also have an extra slot for users to tag
+the breakpoint with information.
+
+\begin{defun}{}{make-breakpoint}{%
+    \args{\var{hook-function} \var{what} \keys{\kwd{kind} \kwd{info}
+
+  This function creates and returns a breakpoint.  When program
+  execution encounters the breakpoint, the system calls
+  \var{hook-function}.  \var{hook-function} takes the current frame
+  for the function in which the program is running and the breakpoint
+  object.
+
+  \var{what} and \var{kind} determine where in a function the system
+  invokes \var{hook-function}.  \var{what} is either a code-location
+  or a debug-function.  \var{kind} is one of \kwd{code-location},
+  \kwd{function-start}, or \kwd{function-end}.  Since the starts and
+  ends of functions may not have code-locations representing them,
+  designate these places by supplying \var{what} as a debug-function
+  and \var{kind} indicating the \kwd{function-start} or
+  \kwd{function-end}.  When \var{what} is a debug-function and
+  \var{kind} is \kwd{function-end}, then hook-function must take two
+  additional arguments, a list of values returned by the function and
+
+  \var{info} is information supplied by and used by the user.
+
+  \var{function-end-cookie} is a function.  To implement function-end
+  breakpoints, the system uses starter breakpoints to establish the
+  function-end breakpoint for each invocation of the function.  Upon
+  each entry, the system creates a unique cookie to identify the
+  invocation, and when the user supplies a function for this argument,
+  the system invokes it on the cookie.  The system later invokes the
+  function-end breakpoint hook on the same cookie.  The user may save
+  comparison in the hook function.
+
+  This signals an error if \var{what} is an unknown code-location.
+
+  \i{Note: Breakpoints in interpreted code or byte-compiled code are
+    not implemented.  Function-end breakpoints are not implemented for
+    compiled functions that use the known local return convention
+    (e.g. for block-compiled or self-recursive functions.)}
+
+\end{defun}
+
+
+\begin{defun}{}{activate-breakpoint}{\args{\var{breakpoint}}}
+
+  This function causes the system to invoke the \var{breakpoint}'s
+  hook-function until the next call to \code{deactivate-breakpoint} or
+  \code{delete-breakpoint}.  The system invokes breakpoint hook
+  functions in the opposite order that you activate them.
+\end{defun}
+
+
+\begin{defun}{}{deactivate-breakpoint}{\args{\var{breakpoint}}}
+
+  This function stops the system from invoking the \var{breakpoint}'s
+  hook-function.
+\end{defun}
+
+
+\begin{defun}{}{breakpoint-active-p}{\args{\var{breakpoint}}}
+
+  This returns whether \var{breakpoint} is currently active.
+\end{defun}
+
+
+\begin{defun}{}{breakpoint-hook-function}{\args{\var{breakpoint}}}
+
+  This function returns the \var{breakpoint}'s function the system
+  calls when execution encounters \var{breakpoint}, and it is active.
+  This is \code{SETF}'able.
+\end{defun}
+
+
+\begin{defun}{}{breakpoint-info}{\args{\var{breakpoint}}}
+
+  This function returns \var{breakpoint}'s information supplied by the
+  user.  This is \code{SETF}'able.
+\end{defun}
+
+
+\begin{defun}{}{breakpoint-kind}{\args{\var{breakpoint}}}
+
+  This function returns the \var{breakpoint}'s kind specification.
+\end{defun}
+
+
+\begin{defun}{}{breakpoint-what}{\args{\var{breakpoint}}}
+
+  This function returns the \var{breakpoint}'s what specification.
+\end{defun}
+
+
+\begin{defun}{}{delete-breakpoint}{\args{\var{breakpoint}}}
+
+  This function frees system storage and removes computational
+  overhead associated with \var{breakpoint}.  After calling this,
+  \var{breakpoint} is useless and can never become active again.
+\end{defun}
+
+
+%%
+%%\node Code-locations, Debug-sources, Breakpoints, Debugger Programmer's Interface
+\section{Code-locations}
+
+Code-locations represent places in functions where the system has correct
+information about the function's environment and where interesting operations
+can occur---asking for a local variable's value, setting breakpoints,
+evaluating forms within the function's environment, etc.
+
+Sometimes the interface returns unknown code-locations.  These
+represent places in functions, but there is no debug information
+associated with them.  Some operations accept these since they may
+succeed even with missing debug data.  These operations' argument is
+named \var{basic-code-location} indicating they take known and unknown
+code-locations.  If an operation names its argument
+\var{code-location}, and you supply an unknown one, it will signal an
+error.  For example, \code{frame-code-location} may return an unknown
+code-location if someone interrupted Lisp in the given frame.  The
+system knows where execution will continue, but this place in the code
+may not be a place for which the compiler dumped debug information.
+
+\begin{defun}{}{code-location-debug-function}{\args{\var{basic-code-location}}}
+
+  This function returns the debug-function representing information
+  about the function corresponding to the code-location.
+\end{defun}
+
+
+\begin{defun}{}{code-location-debug-block}{\args{\var{basic-code-location}}}
+
+  This function returns the debug-block containing code-location if it
+  is available.  Some debug policies inhibit debug-block information,
+  and if none is available, then this signals a \code{no-debug-blocks}
+  condition.
+\end{defun}
+
+
+\begin{defun}{}{code-location-top-level-form-offset}{%
+    \args{\var{code-location}}}
+
+  This function returns the number of top-level forms before the one
+  containing \var{code-location} as seen by the compiler in some
+  compilation unit.  A compilation unit is not necessarily a single
+  file, see the section on debug-sources.
+\end{defun}
+
+
+\begin{defun}{}{code-location-form-number}{\args{\var{code-location}}}
+
+  This function returns the number of the form corresponding to
+  \var{code-location}.  The form number is derived by walking the
+  subforms of a top-level form in depth-first order.  While walking
+  the top-level form, count one in depth-first order for each subform
+  that is a cons.  See \funref{form-number-translations}.
+\end{defun}
+
+
+\begin{defun}{}{code-location-debug-source}{\args{\var{code-location}}}
+
+  This function returns \var{code-location}'s debug-source.
+\end{defun}
+
+
+\begin{defun}{}{code-location-unknown-p}{\args{\var{basic-code-location}}}
+
+  This function returns whether \var{basic-code-location} is unknown.
+  It returns \nil when the code-location is known.
+\end{defun}
+
+
+\begin{defun}{}{code-location=}{\args{\var{code-location1}
+      \var{code-location2}}}
+
+  This function returns whether the two code-locations are the same.
+\end{defun}
+
+
+%%
+%%\node Debug-sources, Source Translation Utilities, Code-locations, Debugger Programmer's Interface
+\section{Debug-sources}
+
+Debug-sources represent how to get back the source for some code.  The
+source is either a file (\code{compile-file} or \code{load}), a
+lambda-expression (\code{compile}, \code{defun}, \code{defmacro}), or
+a stream (something particular to CMU Common Lisp,
+\code{compile-from-stream}).
+
+When compiling a source, the compiler counts each top-level form it
+processes, but when the compiler handles multiple files as one block
+compilation, the top-level form count continues past file boundaries.
+Therefore \code{code-location-top-level-form-offset} returns an offset
+that does not always start at zero for the code-location's
+debug-source.  The offset into a particular source is
+\code{code-location-top-level-form-offset} minus
+\code{debug-source-root-number}.
+
+Inside a top-level form, a code-location's form number indicates the
+subform corresponding to the code-location.
+
+\begin{defun}{}{debug-source-from}{\args{\var{debug-source}}}
+
+  This function returns an indication of the type of source.  The
+  following are the possible values:
+  \begin{Lentry}
+  \item[\kwd{file}] from a file (obtained by \code{compile-file} if
+    compiled).
+  \item[\kwd{lisp}] from Lisp (obtained by \code{compile} if
+    compiled).
+  \item[\kwd{stream}] from a non-file stream (CMU Common Lisp supports
+    \code{compile-from-stream}).
+  \end{Lentry}
+\end{defun}
+
+
+\begin{defun}{}{debug-source-name}{\args{\var{debug-source}}}
+
+  This function returns the actual source in some sense represented by
+  debug-source, which is related to \code{debug-source-from}:
+  \begin{Lentry}
+  \item[\kwd{file}] the pathname of the file.
+  \item[\kwd{lisp}] a lambda-expression.
+  \item[\kwd{stream}] some descriptive string that's otherwise
+    useless.
+\end{Lentry}
+\end{defun}
+
+
+\begin{defun}{}{debug-source-created}{\args{\var{debug-source}}}
+
+  This function returns the universal time someone created the source.
+  This may be \nil{} if it is unavailable.
+\end{defun}
+
+
+\begin{defun}{}{debug-source-compiled}{\args{\var{debug-source}}}
+
+  This function returns the time someone compiled the source.  This is
+  \nil if the source is uncompiled.
+\end{defun}
+
+
+\begin{defun}{}{debug-source-root-number}{\args{\var{debug-source}}}
+
+  This returns the number of top-level forms processed by the compiler
+  before compiling this source.  If this source is uncompiled, this is
+  zero.  This may be zero even if the source is compiled since the
+  first form in the first file compiled in one compilation, for
+  example, must have a root number of zero---the compiler saw no other
+  top-level forms before it.
+\end{defun}
+
+
+%%\node Source Translation Utilities,  , Debug-sources, Debugger Programmer's Interface
+\section{Source Translation Utilities}
+
+These two functions provide a mechanism for converting the rather
+obscure (but highly compact) representation of source locations into an
+actual source form:
+
+\begin{defun}{}{debug-source-start-positions}{\args{\var{debug-source}}}
+
+  This function returns the file position of each top-level form a
+  vector if \var{debug-source} is from a \kwd{file}.  If
+  \code{debug-source-from} is \kwd{lisp} or \kwd{stream}, or the file
+  is byte-compiled, then the result is \false.
+\end{defun}
+
+
+\begin{defun}{}{form-number-translations}{\args{\var{form}
+      \var{tlf-number}}}
+
+  This function returns a table mapping form numbers (see
+  \code{code-location-form-number}) to source-paths.  A source-path
+  indicates a descent into the top-level-form \var{form}, going
+  directly to the subform corresponding to a form number.
+  \var{tlf-number} is the top-level-form number of \var{form}.
+\end{defun}
+
+
+\begin{defun}{}{source-path-context}{%
+    \args{\var{form} \var{path} \var{context}}}
+
+  This function returns the subform of \var{form} indicated by the
+  source-path.  \var{Form} is a top-level form, and \var{path} is a
+  source-path into it.  \var{Context} is the number of enclosing forms
+  to return instead of directly returning the source-path form.  When
+  \var{context} is non-zero, the form returned contains a marker,
+  \code{\#:****HERE****}, immediately before the form indicated by
+  \var{path}.
+\end{defun}
+
+
+%%
+\twocolumn
+%%\node Function Index, Variable Index, Debugger Programmer's Interface, Top
+%%\unnumbered{Function Index}
+\cindex{Function Index}
+
+%%\printindex{fn}
+\printindex[funs]
+
+\twocolumn
+%%\node Variable Index, Type Index, Function Index, Top
+%%\unnumbered{Variable Index}
+\cindex{Variable Index}
+
+%%\printindex{vr}
+\printindex[vars]
+
+\twocolumn
+%%\node Type Index, Concept Index, Variable Index, Top
+%%\unnumbered{Type Index}
+\cindex{Type Index}
+
+%%\printindex{tp}
+\printindex[types]
+
+%%\node Concept Index,  , Type Index, Top
+%%\unnumbered{Concept Index}
+\cindex{Concept Index}
+
+%%\printindex{cp}
+\onecolumn
+\printindex[concept]
+\end{document}