/usr/share/doc/cmucl-docs/cmu-user.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>
<TITLE>CMUCL User's Manual
</TITLE>

<META http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<META name="GENERATOR" content="hevea 1.10">
<STYLE type="text/css">
.li-itemize{margin:1ex 0ex;}
.li-enumerate{margin:1ex 0ex;}
.dd-description{margin:0ex 0ex 1ex 4ex;}
.dt-description{margin:0ex;}
.toc{list-style:none;}
.thefootnotes{text-align:left;margin:0ex;}
.dt-thefootnotes{margin:0em;}
.dd-thefootnotes{margin:0em 0em 0em 2em;}
.footnoterule{margin:1em auto 1em 0px;width:50%;}
.caption{padding-left:2ex; padding-right:2ex; margin-left:auto; margin-right:auto}
.title{margin:2ex auto;text-align:center}
.center{text-align:center;margin-left:auto;margin-right:auto;}
.flushleft{text-align:left;margin-left:0ex;margin-right:auto;}
.flushright{text-align:right;margin-left:auto;margin-right:0ex;}
DIV TABLE{margin-left:inherit;margin-right:inherit;}
PRE{text-align:left;margin-left:0ex;margin-right:auto;}
BLOCKQUOTE{margin-left:4ex;margin-right:4ex;text-align:left;}
TD P{margin:0px;}
.boxed{border:1px solid black}
.textboxed{border:1px solid black}
.vbar{border:none;width:2px;background-color:black;}
.hbar{border:none;height:2px;width:100%;background-color:black;}
.hfill{border:none;height:1px;width:200%;background-color:black;}
.vdisplay{border-collapse:separate;border-spacing:2px;width:auto; empty-cells:show; border:2px solid red;}
.vdcell{white-space:nowrap;padding:0px;width:auto; border:2px solid green;}
.display{border-collapse:separate;border-spacing:2px;width:auto; border:none;}
.dcell{white-space:nowrap;padding:0px;width:auto; border:none;}
.dcenter{margin:0ex auto;}
.vdcenter{border:solid #FF8000 2px; margin:0ex auto;}
.minipage{text-align:left; margin-left:0em; margin-right:auto;}
.marginpar{border:solid thin black; width:20%; text-align:left;}
.marginparleft{float:left; margin-left:0ex; margin-right:1ex;}
.marginparright{float:right; margin-left:1ex; margin-right:0ex;}
.theorem{text-align:left;margin:1ex auto 1ex 0ex;}
.part{margin:2ex auto;text-align:center}
BODY{background:white;}
.title{padding:1ex;background:#00B200;}
.titlemain{padding:1ex;background:#00B200;}
.titlerest{padding:1ex;background:#00B200;}
.part{padding:1ex;background:#FFFFCE;}
.section{padding:.5ex;background:#FFFFD3;}
.subsection{padding:0.3ex;background:#FFFFE2;}
.subsubsection{padding:0.5ex;background:#FFFFED;}
.chapter{padding:0.5ex;background:#FFFFBC;}
.fmarginpar{border:solid thin #FFFFE2; width:20%; text-align:left;}
.ffootnoterule{border:none;margin:1em auto 1em 0px;width:50%;background:#FFFFCE;}
.ftoc1{list-style:none;margin:0ex 1ex;padding:0ex 1ex;border-left:1ex solid #FFFFCE;}
.ftoc2{list-style:none;margin:1ex 1ex;padding:0ex 1ex;border-left:1ex solid #FFFFBC;}
.ftoc3{list-style:none;margin:0ex 1ex;padding:0ex 1ex;border-left:1ex solid #FFFFD3;}
.ftoc4{list-style:none;margin:0ex 1ex;padding:0ex 1ex;border-left:1ex solid #FFFFE2;}
.ftoc5{list-style:none;margin:0ex 1ex;padding:0ex 1ex;border-left:1ex solid #FFFFED;}
.ftoc6{list-style:none;margin:0ex 1ex;padding:0ex 1ex;border-left:1ex solid #CCFFCC;}
</STYLE>

<link rel="stylesheet" href="cmucl.css" type="text/css">
<meta http-equiv="Content-Language" content="en">
</HEAD>
<BODY >
<!--HEVEA command line is: /usr/bin/hevea -fix cmu-user.hva cmu-user.tex -->
<!--PREFIX <ARG >CMUCL User&#X2019;s Manual: </ARG>-->
<!--CUT DEF chapter 10 --><P>
<BR>
<BR>
<BR>
<BR>
<BR>
<BR>

</P><DIV CLASS="center">
<HR SIZE=2>
<BR>
<BR>
<BR>

<FONT SIZE=7>CMUCL User&#X2019;s Manual</FONT><P>
<BR>
<BR>
<BR>
<BR>

</P><TABLE CELLSPACING=6 CELLPADDING=0><TR><TD ALIGN=center NOWRAP><FONT SIZE=4> Robert A. MacLachlan, </FONT><FONT SIZE=4><I>Editor</I></FONT></TD></TR>
</TABLE><P>
<BR>
<BR>

<FONT SIZE=4>November 2011<BR>
20c</FONT></P><P>
<BR>
<BR>

</P><HR SIZE=2></DIV><BLOCKQUOTE CLASS="quotation">
CMUCL is a free, high-performance implementation of the Common Lisp
programming language, which runs on most major Unix platforms. It
mainly conforms to the ANSI Common Lisp Standard. CMUCL features a
sophisticated native-code compiler, a foreign function interface, a
graphical source-level debugger, an interface to the X11 Window
System, and an Emacs-like editor.<P><BR>
<B>Keywords</B>: lisp, Common Lisp, manual, compiler, programming
language implementation, programming environment</P></BLOCKQUOTE><P><BR>
<BR>
<BR>
<BR>
<BR>
<BR>
<BR>
<BR>
<BR>
<BR>
<BR>
<BR>
<BR>
<BR>
</P><P>This manual is based on CMU Technical Report CMU-CS-92-161, edited by
Robert A. MacLachlan, dated July 1992.</P><P>
/Author (Robert A. MacLachlan, ed)
/Title (CMUCL User&#X2019;s Manual)
/Keywords (lisp, Common Lisp, manual, compiler, programming
language implementation, programming environment)


</P><!--TOC chapter Contents-->
<H1 CLASS="chapter"><!--SEC ANCHOR -->Contents</H1><!--SEC END --><UL CLASS="ftoc1"><LI CLASS="li-toc">
<A HREF="#htoc1">Chapter&#XA0;1&#XA0;&#XA0;Introduction</A>
<UL CLASS="ftoc2"><LI CLASS="li-toc">
<A HREF="#htoc2">1.1&#XA0;&#XA0;Distribution and Support</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc3">1.2&#XA0;&#XA0;Command Line Options</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc4">1.3&#XA0;&#XA0;Credits</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc5">Chapter&#XA0;2&#XA0;&#XA0;Design Choices and Extensions</A>
<UL CLASS="ftoc2"><LI CLASS="li-toc">
<A HREF="#htoc6">2.1&#XA0;&#XA0;Data Types</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc7">2.1.1&#XA0;&#XA0;Integers</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc8">2.1.2&#XA0;&#XA0;Floats</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc9">2.1.3&#XA0;&#XA0;Extended Floats</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc10">2.1.4&#XA0;&#XA0;Characters</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc11">2.1.5&#XA0;&#XA0;Array Initialization</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc12">2.1.6&#XA0;&#XA0;Hash tables</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc13">2.2&#XA0;&#XA0;Default Interrupts for Lisp</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc14">2.3&#XA0;&#XA0;Implementation-Specific Packages</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc15">2.4&#XA0;&#XA0;Hierarchical Packages</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc16">2.4.1&#XA0;&#XA0;Introduction</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc17">2.4.2&#XA0;&#XA0;Relative Package Names</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc18">2.4.3&#XA0;&#XA0;Compatibility with ANSI Common Lisp</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc19">2.5&#XA0;&#XA0;Package Locks</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc20">2.5.1&#XA0;&#XA0;Rationale</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc21">2.5.2&#XA0;&#XA0;Disabling package locks</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc22">2.6&#XA0;&#XA0;The Editor</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc23">2.7&#XA0;&#XA0;Garbage Collection</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc24">2.7.1&#XA0;&#XA0;GC Parameters</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc25">2.7.2&#XA0;&#XA0;Generational GC</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc26">2.7.3&#XA0;&#XA0;Weak Pointers</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc27">2.7.4&#XA0;&#XA0;Finalization</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc28">2.8&#XA0;&#XA0;Describe</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc29">2.9&#XA0;&#XA0;The Inspector</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc30">2.9.1&#XA0;&#XA0;The Graphical Interface</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc31">2.9.2&#XA0;&#XA0;The TTY Inspector</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc32">2.10&#XA0;&#XA0;Load</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc33">2.11&#XA0;&#XA0;The Reader</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc34">2.11.1&#XA0;&#XA0;Reader Extensions</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc35">2.11.2&#XA0;&#XA0;Reader Parameters</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc36">2.12&#XA0;&#XA0;Stream Extensions</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc37">2.13&#XA0;&#XA0;Simple Streams</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc38">2.14&#XA0;&#XA0;Running Programs from Lisp</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc39">2.14.1&#XA0;&#XA0;Process Accessors</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc40">2.15&#XA0;&#XA0;Saving a Core Image</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc41">2.16&#XA0;&#XA0;Pathnames</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc42">2.16.1&#XA0;&#XA0;Unix Pathnames</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc43">2.16.2&#XA0;&#XA0;Wildcard Pathnames</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc44">2.16.3&#XA0;&#XA0;Logical Pathnames</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc45">2.16.4&#XA0;&#XA0;Search Lists</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc46">2.16.5&#XA0;&#XA0;Predefined Search-Lists</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc47">2.16.6&#XA0;&#XA0;Search-List Operations</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc48">2.16.7&#XA0;&#XA0;Search List Example</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc49">2.17&#XA0;&#XA0;Filesystem Operations</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc50">2.17.1&#XA0;&#XA0;Wildcard Matching</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc51">2.17.2&#XA0;&#XA0;File Name Completion</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc52">2.17.3&#XA0;&#XA0;Miscellaneous Filesystem Operations</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc53">2.18&#XA0;&#XA0;Time Parsing and Formatting</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc54">2.19&#XA0;&#XA0;Random Number Generation</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc55">2.19.1&#XA0;&#XA0;MT-19937 Generator</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc56">2.20&#XA0;&#XA0;Lisp Threads</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc57">2.21&#XA0;&#XA0;Lisp Library</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc58">2.22&#XA0;&#XA0;Generalized Function Names</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc59">2.23&#XA0;&#XA0;CLOS</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc60">2.23.1&#XA0;&#XA0;Primary Method Errors</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc61">2.23.2&#XA0;&#XA0;Slot Type Checking</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc62">2.23.3&#XA0;&#XA0;Slot Access Optimization</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc63">2.23.4&#XA0;&#XA0;Inlining Methods in Effective Methods</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc64">2.23.5&#XA0;&#XA0;Effective Method Precomputation</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc65">2.23.6&#XA0;&#XA0;Sealing</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc66">2.23.7&#XA0;&#XA0;Method Tracing and Profiling</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc67">2.23.8&#XA0;&#XA0;Misc</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc68">2.24&#XA0;&#XA0;Differences from ANSI Common Lisp</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc69">2.24.1&#XA0;&#XA0;Extensions</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc70">2.25&#XA0;&#XA0;Function Wrappers</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc71">2.26&#XA0;&#XA0;Dynamic-Extent Declarations</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc72">2.26.1&#XA0;&#XA0;<TT class=code>&amp;rest</TT> argument lists</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc73">2.26.2&#XA0;&#XA0;Closures</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc74">2.26.3&#XA0;&#XA0;<TT class=code>list</TT>, <TT class=code>list*</TT>, and <TT class=code>cons</TT></A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc75">2.27&#XA0;&#XA0;Modular Arithmetic</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc76">2.28&#XA0;&#XA0;Extension to REQUIRE</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc77">2.29&#XA0;&#XA0;Localization</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc78">2.29.1&#XA0;&#XA0;Dictionary</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc79">2.29.2&#XA0;&#XA0;Example Usage</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc80">2.30&#XA0;&#XA0;Static Arrays</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc81">Chapter&#XA0;3&#XA0;&#XA0;The Debugger</A>
<UL CLASS="ftoc2"><LI CLASS="li-toc">
<A HREF="#htoc82">3.1&#XA0;&#XA0;Debugger Introduction</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc83">3.2&#XA0;&#XA0;The Command Loop</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc84">3.3&#XA0;&#XA0;Stack Frames</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc85">3.3.1&#XA0;&#XA0;Stack Motion</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc86">3.3.2&#XA0;&#XA0;How Arguments are Printed</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc87">3.3.3&#XA0;&#XA0;Function Names</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc88">3.3.4&#XA0;&#XA0;Funny Frames</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc89">3.3.5&#XA0;&#XA0;Debug Tail Recursion</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc90">3.3.6&#XA0;&#XA0;Unknown Locations and Interrupts</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc91">3.4&#XA0;&#XA0;Variable Access</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc92">3.4.1&#XA0;&#XA0;Variable Value Availability</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc93">3.4.2&#XA0;&#XA0;Note On Lexical Variable Access</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc94">3.5&#XA0;&#XA0;Source Location Printing</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc95">3.5.1&#XA0;&#XA0;How the Source is Found</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc96">3.5.2&#XA0;&#XA0;Source Location Availability</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc97">3.6&#XA0;&#XA0;Compiler Policy Control</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc98">3.7&#XA0;&#XA0;Exiting Commands</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc99">3.8&#XA0;&#XA0;Information Commands</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc100">3.9&#XA0;&#XA0;Breakpoint Commands</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc101">3.9.1&#XA0;&#XA0;Breakpoint Example</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc102">3.10&#XA0;&#XA0;Function Tracing</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc103">3.10.1&#XA0;&#XA0;Encapsulation Functions</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc104">3.10.2&#XA0;&#XA0;Tracing Examples</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc105">3.11&#XA0;&#XA0;Specials</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc106">Chapter&#XA0;4&#XA0;&#XA0;The Compiler</A>
<UL CLASS="ftoc2"><LI CLASS="li-toc">
<A HREF="#htoc107">4.1&#XA0;&#XA0;Compiler Introduction</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc108">4.2&#XA0;&#XA0;Calling the Compiler</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc109">4.3&#XA0;&#XA0;Compilation Units</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc110">4.3.1&#XA0;&#XA0;Undefined Warnings</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc111">4.4&#XA0;&#XA0;Interpreting Error Messages</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc112">4.4.1&#XA0;&#XA0;The Parts of the Error Message</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc113">4.4.2&#XA0;&#XA0;The Original and Actual Source</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc114">4.4.3&#XA0;&#XA0;The Processing Path</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc115">4.4.4&#XA0;&#XA0;Error Severity</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc116">4.4.5&#XA0;&#XA0;Errors During Macroexpansion</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc117">4.4.6&#XA0;&#XA0;Read Errors</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc118">4.4.7&#XA0;&#XA0;Error Message Parameterization</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc119">4.5&#XA0;&#XA0;Types in Python</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc120">4.5.1&#XA0;&#XA0;Compile Time Type Errors</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc121">4.5.2&#XA0;&#XA0;Precise Type Checking</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc122">4.5.3&#XA0;&#XA0;Weakened Type Checking</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc123">4.6&#XA0;&#XA0;Getting Existing Programs to Run</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc124">4.7&#XA0;&#XA0;Compiler Policy</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc125">4.7.1&#XA0;&#XA0;The Optimize Declaration</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc126">4.7.2&#XA0;&#XA0;The Optimize-Interface Declaration</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc127">4.8&#XA0;&#XA0;Open Coding and Inline Expansion</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc128">Chapter&#XA0;5&#XA0;&#XA0;Advanced Compiler Use and Efficiency Hints</A>
<UL CLASS="ftoc2"><LI CLASS="li-toc">
<A HREF="#htoc129">5.1&#XA0;&#XA0;Advanced Compiler Introduction</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc130">5.1.1&#XA0;&#XA0;Types</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc131">5.1.2&#XA0;&#XA0;Optimization</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc132">5.1.3&#XA0;&#XA0;Function Call</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc133">5.1.4&#XA0;&#XA0;Representation of Objects</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc134">5.1.5&#XA0;&#XA0;Writing Efficient Code</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc135">5.2&#XA0;&#XA0;More About Types in Python</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc136">5.2.1&#XA0;&#XA0;More Types Meaningful</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc137">5.2.2&#XA0;&#XA0;Canonicalization</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc138">5.2.3&#XA0;&#XA0;Member Types</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc139">5.2.4&#XA0;&#XA0;Union Types</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc140">5.2.5&#XA0;&#XA0;The Empty Type</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc141">5.2.6&#XA0;&#XA0;Function Types</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc142">5.2.7&#XA0;&#XA0;The Values Declaration</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc143">5.2.8&#XA0;&#XA0;Structure Types</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc144">5.2.9&#XA0;&#XA0;The Freeze-Type Declaration</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc145">5.2.10&#XA0;&#XA0;Type Restrictions</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc146">5.2.11&#XA0;&#XA0;Type Style Recommendations</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc147">5.3&#XA0;&#XA0;Type Inference</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc148">5.3.1&#XA0;&#XA0;Variable Type Inference</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc149">5.3.2&#XA0;&#XA0;Local Function Type Inference</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc150">5.3.3&#XA0;&#XA0;Global Function Type Inference</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc151">5.3.4&#XA0;&#XA0;Operation Specific Type Inference</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc152">5.3.5&#XA0;&#XA0;Dynamic Type Inference</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc153">5.3.6&#XA0;&#XA0;Type Check Optimization</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc154">5.4&#XA0;&#XA0;Source Optimization</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc155">5.4.1&#XA0;&#XA0;Let Optimization</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc156">5.4.2&#XA0;&#XA0;Constant Folding</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc157">5.4.3&#XA0;&#XA0;Unused Expression Elimination</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc158">5.4.4&#XA0;&#XA0;Control Optimization</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc159">5.4.5&#XA0;&#XA0;Unreachable Code Deletion</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc160">5.4.6&#XA0;&#XA0;Multiple Values Optimization</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc161">5.4.7&#XA0;&#XA0;Source to Source Transformation</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc162">5.4.8&#XA0;&#XA0;Style Recommendations</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc163">5.5&#XA0;&#XA0;Tail Recursion</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc164">5.5.1&#XA0;&#XA0;Tail Recursion Exceptions</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc165">5.6&#XA0;&#XA0;Local Call</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc166">5.6.1&#XA0;&#XA0;Self-Recursive Calls</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc167">5.6.2&#XA0;&#XA0;Let Calls</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc168">5.6.3&#XA0;&#XA0;Closures</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc169">5.6.4&#XA0;&#XA0;Local Tail Recursion</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc170">5.6.5&#XA0;&#XA0;Return Values</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc171">5.7&#XA0;&#XA0;Block Compilation</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc172">5.7.1&#XA0;&#XA0;Block Compilation Semantics</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc173">5.7.2&#XA0;&#XA0;Block Compilation Declarations</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc174">5.7.3&#XA0;&#XA0;Compiler Arguments</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc175">5.7.4&#XA0;&#XA0;Practical Difficulties</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc176">5.7.5&#XA0;&#XA0;Context Declarations</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc177">5.7.6&#XA0;&#XA0;Context Declaration Example</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc178">5.8&#XA0;&#XA0;Inline Expansion</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc179">5.8.1&#XA0;&#XA0;Inline Expansion Recording</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc180">5.8.2&#XA0;&#XA0;Semi-Inline Expansion</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc181">5.8.3&#XA0;&#XA0;The Maybe-Inline Declaration</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc182">5.9&#XA0;&#XA0;Byte Coded Compilation</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc183">5.10&#XA0;&#XA0;Object Representation</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc184">5.10.1&#XA0;&#XA0;Think Before You Use a List</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc185">5.10.2&#XA0;&#XA0;Structure Representation</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc186">5.10.3&#XA0;&#XA0;Arrays</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc187">5.10.4&#XA0;&#XA0;Vectors</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc188">5.10.5&#XA0;&#XA0;Bit-Vectors</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc189">5.10.6&#XA0;&#XA0;Hashtables</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc190">5.11&#XA0;&#XA0;Numbers</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc191">5.11.1&#XA0;&#XA0;Descriptors</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc192">5.11.2&#XA0;&#XA0;Non-Descriptor Representations</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc193">5.11.3&#XA0;&#XA0;Variables</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc194">5.11.4&#XA0;&#XA0;Generic Arithmetic</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc195">5.11.5&#XA0;&#XA0;Fixnums</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc196">5.11.6&#XA0;&#XA0;Word Integers</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc197">5.11.7&#XA0;&#XA0;Floating Point Efficiency</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc198">5.11.8&#XA0;&#XA0;Specialized Arrays</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc199">5.11.9&#XA0;&#XA0;Specialized Structure Slots</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc200">5.11.10&#XA0;&#XA0;Interactions With Local Call</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc201">5.11.11&#XA0;&#XA0;Representation of Characters</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc202">5.12&#XA0;&#XA0;General Efficiency Hints</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc203">5.12.1&#XA0;&#XA0;Compile Your Code</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc204">5.12.2&#XA0;&#XA0;Avoid Unnecessary Consing</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc205">5.12.3&#XA0;&#XA0;Complex Argument Syntax</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc206">5.12.4&#XA0;&#XA0;Mapping and Iteration</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc207">5.12.5&#XA0;&#XA0;Trace Files and Disassembly</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc208">5.13&#XA0;&#XA0;Efficiency Notes</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc209">5.13.1&#XA0;&#XA0;Type Uncertainty</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc210">5.13.2&#XA0;&#XA0;Efficiency Notes and Type Checking</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc211">5.13.3&#XA0;&#XA0;Representation Efficiency Notes</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc212">5.13.4&#XA0;&#XA0;Verbosity Control</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc213">5.14&#XA0;&#XA0;Profiling</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc214">5.14.1&#XA0;&#XA0;Profile Interface</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc215">5.14.2&#XA0;&#XA0;Profiling Techniques</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc216">5.14.3&#XA0;&#XA0;Nested or Recursive Calls</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc217">5.14.4&#XA0;&#XA0;Clock resolution</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc218">5.14.5&#XA0;&#XA0;Profiling overhead</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc219">5.14.6&#XA0;&#XA0;Additional Timing Utilities</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc220">5.14.7&#XA0;&#XA0;A Note on Timing</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc221">5.14.8&#XA0;&#XA0;Benchmarking Techniques</A>
</LI></UL>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc222">Chapter&#XA0;6&#XA0;&#XA0;UNIX Interface</A>
<UL CLASS="ftoc2"><LI CLASS="li-toc">
<A HREF="#htoc223">6.1&#XA0;&#XA0;Reading the Command Line</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc224">6.2&#XA0;&#XA0;Useful Variables</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc225">6.3&#XA0;&#XA0;Lisp Equivalents for C Routines</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc226">6.4&#XA0;&#XA0;Type Translations</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc227">6.5&#XA0;&#XA0;System Area Pointers</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc228">6.6&#XA0;&#XA0;Unix System Calls</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc229">6.7&#XA0;&#XA0;File Descriptor Streams</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc230">6.8&#XA0;&#XA0;Unix Signals</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc231">6.8.1&#XA0;&#XA0;Changing Signal Handlers</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc232">6.8.2&#XA0;&#XA0;Examples of Signal Handlers</A>
</LI></UL>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc233">Chapter&#XA0;7&#XA0;&#XA0;Event Dispatching with SERVE-EVENT</A>
<UL CLASS="ftoc2"><LI CLASS="li-toc">
<A HREF="#htoc234">7.1&#XA0;&#XA0;Object Sets</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc235">7.2&#XA0;&#XA0;The SERVE-EVENT Function</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc236">7.3&#XA0;&#XA0;Using SERVE-EVENT with Unix File Descriptors</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc237">7.4&#XA0;&#XA0;Using SERVE-EVENT with the CLX Interface to X</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc238">7.4.1&#XA0;&#XA0;Without Object Sets</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc239">7.4.2&#XA0;&#XA0;With Object Sets</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc240">7.5&#XA0;&#XA0;A SERVE-EVENT Example</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc241">7.5.1&#XA0;&#XA0;Without Object Sets Example</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc242">7.5.2&#XA0;&#XA0;With Object Sets Example</A>
</LI></UL>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc243">Chapter&#XA0;8&#XA0;&#XA0;Alien Objects</A>
<UL CLASS="ftoc2"><LI CLASS="li-toc">
<A HREF="#htoc244">8.1&#XA0;&#XA0;Introduction to Aliens</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc245">8.2&#XA0;&#XA0;Alien Types</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc246">8.2.1&#XA0;&#XA0;Defining Alien Types</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc247">8.2.2&#XA0;&#XA0;Alien Types and Lisp Types</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc248">8.2.3&#XA0;&#XA0;Alien Type Specifiers</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc249">8.2.4&#XA0;&#XA0;The C-Call Package</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc250">8.3&#XA0;&#XA0;Alien Operations</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc251">8.3.1&#XA0;&#XA0;Alien Access Operations</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc252">8.3.2&#XA0;&#XA0;Alien Coercion Operations</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc253">8.3.3&#XA0;&#XA0;Alien Dynamic Allocation</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc254">8.4&#XA0;&#XA0;Alien Variables</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc255">8.4.1&#XA0;&#XA0;Local Alien Variables</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc256">8.4.2&#XA0;&#XA0;External Alien Variables</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc257">8.5&#XA0;&#XA0;Alien Data Structure Example</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc258">8.6&#XA0;&#XA0;Loading Unix Object Files</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc259">8.7&#XA0;&#XA0;Alien Function Calls</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc260">8.7.1&#XA0;&#XA0;The alien-funcall Primitive</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc261">8.7.2&#XA0;&#XA0;The def-alien-routine Macro</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc262">8.7.3&#XA0;&#XA0;def-alien-routine Example</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc263">8.7.4&#XA0;&#XA0;Calling Lisp from C</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc264">8.7.5&#XA0;&#XA0;Callback Example</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc265">8.7.6&#XA0;&#XA0;Accessing Lisp Arrays</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc266">8.8&#XA0;&#XA0;Step-by-Step Alien Example</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc267">Chapter&#XA0;9&#XA0;&#XA0;Interprocess Communication under LISP</A>
<UL CLASS="ftoc2"><LI CLASS="li-toc">
<A HREF="#htoc268">9.1&#XA0;&#XA0;The REMOTE Package</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc269">9.1.1&#XA0;&#XA0;Connecting Servers and Clients</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc270">9.1.2&#XA0;&#XA0;Remote Evaluations</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc271">9.1.3&#XA0;&#XA0;Remote Objects</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc272">9.2&#XA0;&#XA0;The WIRE Package</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc273">9.2.1&#XA0;&#XA0;Untagged Data</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc274">9.2.2&#XA0;&#XA0;Tagged Data</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc275">9.2.3&#XA0;&#XA0;Making Your Own Wires</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc276">9.3&#XA0;&#XA0;Out-Of-Band Data</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc277">Chapter&#XA0;10&#XA0;&#XA0;Networking Support</A>
<UL CLASS="ftoc2"><LI CLASS="li-toc">
<A HREF="#htoc278">10.1&#XA0;&#XA0;Byte Order Converters</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc279">10.2&#XA0;&#XA0;Domain Name Services (DNS)</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc280">10.3&#XA0;&#XA0;Binding to Interfaces</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc281">10.4&#XA0;&#XA0;Accepting Connections</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc282">10.5&#XA0;&#XA0;Connecting</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc283">10.6&#XA0;&#XA0;Out-of-Band Data</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc284">10.7&#XA0;&#XA0;Unbound Sockets, Socket Options, and Closing Sockets</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc285">10.8&#XA0;&#XA0;Unix Datagrams</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc286">10.9&#XA0;&#XA0;Errors</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc287">Chapter&#XA0;11&#XA0;&#XA0;Debugger Programmer&#X2019;s Interface</A>
<UL CLASS="ftoc2"><LI CLASS="li-toc">
<A HREF="#htoc288">11.1&#XA0;&#XA0;DI Exceptional Conditions</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc289">11.1.1&#XA0;&#XA0;Debug-conditions</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc290">11.1.2&#XA0;&#XA0;Debug-errors</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc291">11.2&#XA0;&#XA0;Debug-variables</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc292">11.3&#XA0;&#XA0;Frames</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc293">11.4&#XA0;&#XA0;Debug-functions</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc294">11.5&#XA0;&#XA0;Debug-blocks</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc295">11.6&#XA0;&#XA0;Breakpoints</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc296">11.7&#XA0;&#XA0;Code-locations</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc297">11.8&#XA0;&#XA0;Debug-sources</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc298">11.9&#XA0;&#XA0;Source Translation Utilities</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc299">Chapter&#XA0;12&#XA0;&#XA0;Cross-Referencing Facility</A>
<UL CLASS="ftoc2"><LI CLASS="li-toc">
<A HREF="#htoc300">12.1&#XA0;&#XA0;Populating the cross-reference database</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc301">12.2&#XA0;&#XA0;Querying the cross-reference database</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc302">12.3&#XA0;&#XA0;Example usage</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc303">12.4&#XA0;&#XA0;Limitations of the cross-referencing facility</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc304">Chapter&#XA0;13&#XA0;&#XA0;Internationalization</A>
<UL CLASS="ftoc2"><LI CLASS="li-toc">
<A HREF="#htoc305">13.1&#XA0;&#XA0;Changes</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc306">13.1.1&#XA0;&#XA0;Design Choices</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc307">13.1.2&#XA0;&#XA0;Characters</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc308">13.1.3&#XA0;&#XA0;Strings</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc309">13.2&#XA0;&#XA0;External Formats</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc310">13.2.1&#XA0;&#XA0;Available External Formats</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc311">13.2.2&#XA0;&#XA0;Composing External Formats</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc312">13.3&#XA0;&#XA0;Dictionary</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc313">13.3.1&#XA0;&#XA0;Variables</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc314">13.3.2&#XA0;&#XA0;Characters</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc315">13.3.3&#XA0;&#XA0;Strings</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc316">13.3.4&#XA0;&#XA0;Sequences</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc317">13.3.5&#XA0;&#XA0;Reader</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc318">13.3.6&#XA0;&#XA0;Printer</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc319">13.3.7&#XA0;&#XA0;Miscellaneous</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc320">13.4&#XA0;&#XA0;Writing External Formats</A>
<UL CLASS="ftoc3"><LI CLASS="li-toc">
<A HREF="#htoc321">13.4.1&#XA0;&#XA0;External Formats</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc322">13.4.2&#XA0;&#XA0;Composing External Formats</A>
</LI></UL>
</LI></UL>
</LI></UL><!--NAME cmu-user.htoc.html-->
<!--TOC chapter Introduction-->
<H1 CLASS="chapter"><!--SEC ANCHOR --><A NAME="htoc1">Chapter&#XA0;1</A>&#XA0;&#XA0;Introduction</H1><!--SEC END --><P>CMUCL is a free, high-performance implementation of the Common Lisp
programming language which runs on most major Unix platforms. It
mainly conforms to the ANSI Common Lisp standard. Here is a summary of
its main features:</P><UL CLASS="itemize"><LI CLASS="li-itemize">
a <EM>sophisticated native-code compiler</EM> which is capable of
powerful type inferences, and generates code competitive in speed with
C compilers.</LI><LI CLASS="li-itemize">generational garbage collection and multiprocessing
capability on the x86 ports.</LI><LI CLASS="li-itemize">a foreign function interface which allows interfacing with C code and
system libraries, including shared libraries on most platforms, and
direct access to Unix system calls.</LI><LI CLASS="li-itemize">support for interprocess communication and remote procedure
calls.</LI><LI CLASS="li-itemize">an implementation of CLOS, the Common Lisp Object System, which
includes multimethods and a metaobject protocol.</LI><LI CLASS="li-itemize">a graphical source-level debugger using a Motif interface, and a
code profiler.</LI><LI CLASS="li-itemize">an interface to the X11 Window System (CLX), and a sophisticated
graphical widget library (Garnet).</LI><LI CLASS="li-itemize">programmer-extensible input and output streams.</LI><LI CLASS="li-itemize">an Emacs-like editor implemented in Common Lisp.</LI><LI CLASS="li-itemize">public domain: free, with full source code and no
strings attached (and no warranty). Like GNU/Linux and the *BSD
operating systems, CMUCL is maintained and improved by a team of
volunteers collaborating over the Internet.
</LI></UL><P>This user&#X2019;s manual contains only implementation-specific information
about CMUCL. Users will also need a separate manual describing the
Common Lisp standard, for example, the
<A HREF="http://www.lispworks.com/documentation/HyperSpec/Front/index.htm">Hyperspec</A>.</P><P>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&#X2019;s Manual</I>, and the <I>Hemlock Command Implementor&#X2019;s Manual</I>.</P><!--TOC section Distribution and Support-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc2">1.1</A>&#XA0;&#XA0;Distribution and Support</H2><!--SEC END --><P>CMUCL is developed and maintained by a group of volunteers who
collaborate over the internet. Sources and binary releases for the
various supported platforms can be obtained from
<A HREF="http://www.cons.org/cmucl/">www.cons.org/cmucl</A>. These pages
describe how to download by FTP or CVS.</P><P>A number of mailing lists are available for users and developers;
please see the web site for more information. </P><!--TOC section Command Line Options-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc3">1.2</A>&#XA0;&#XA0;Command Line Options</H2><!--SEC END --><P>
<A NAME="@concept0"></A>
<A NAME="command-line-options"></A></P><P>The command line syntax and environment is described in the
<CODE>lisp(1)</CODE> man page in the man/man1 directory of the distribution.
See also <CODE>cmucl(1)</CODE>. Currently CMUCL accepts the following
switches:</P><DL CLASS="list"><DT CLASS="dt-list">

<TT class=code>&#X2013;help</TT><BR>
</DT><DD CLASS="dd-list"> Same as <TT class=code>-help</TT>.</DD><DT CLASS="dt-list"><TT class=code>-help</TT><BR>
</DT><DD CLASS="dd-list"> Print ou the command line options and exit.</DD><DT CLASS="dt-list"><TT class=code>-batch</TT><BR>
</DT><DD CLASS="dd-list"> 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.</DD><DT CLASS="dt-list"><TT class=code>-quiet</TT><BR>
</DT><DD CLASS="dd-list"> enters quiet mode. This implies setting the
variables <TT class=code>*load-verbose*</TT>, <TT class=code>*compile-verbose*</TT>,
<TT class=code>*compile-print*</TT>, <TT class=code>*compile-progress*</TT>,
<TT class=code>*require-verbose*</TT> and <TT class=code>*gc-verbose*</TT> to NIL, and
disables the printing of the startup banner.</DD><DT CLASS="dt-list"><TT class=code>-core</TT><BR>
</DT><DD CLASS="dd-list"> requires an argument that should be the name of a
core file. Rather than using the default core file, which is searched
in a number of places, according to the initial value of the
<TT class=code>library:</TT> search-list, the specified core file is loaded. This
switch overrides the value of the <TT class=code>CMUCLCORE</TT> environment variable,
if present.</DD><DT CLASS="dt-list"><TT class=code>-lib</TT><BR>
</DT><DD CLASS="dd-list"> requires an argument that should be the path to the
CMUCL library directory, which is going to be used to initialize the
<TT class=code>library:</TT> search-list, among other things. This switch overrides
the value of the <TT class=code>CMUCLLIB</TT> environment variable, if present.</DD><DT CLASS="dt-list"><TT class=code>-dynamic-space-size</TT><BR>
</DT><DD CLASS="dd-list"> requires an argument that should be
the number of megabytes (1048576 bytes) that should be allocated to
the heap. If not specified, a platform-specific default is used.
The actual maximum allowed heap size is platform-specific.<P>Currently, this option is only available for the x86 and sparc
platforms. </P></DD><DT CLASS="dt-list"><TT class=code>-edit</TT><BR>
</DT><DD CLASS="dd-list"> specifies to enter Hemlock. A file to edit may be
specified by placing the name of the file between the program name
(usually <TT class=filename>lisp</TT>) and the first switch.</DD><DT CLASS="dt-list"><TT class=code>-eval</TT><BR>
</DT><DD CLASS="dd-list"> 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.</DD><DT CLASS="dt-list"><TT class=code>-hinit</TT><BR>
</DT><DD CLASS="dd-list"> accepts an argument that should be the name of
the hemlock init file to load the first time the function
<A NAME="@funs0"></A><TT class=code>ed</TT> is invoked. The default is to load
<TT class=filename>hemlock-init.<TT class=variable>object-type</TT></TT>, or if that does not exist,
<TT class=filename>hemlock-init.lisp</TT> from the user&#X2019;s home directory. If the
file is not in the user&#X2019;s home directory, the full path must be
specified.</DD><DT CLASS="dt-list"><TT class=code>-init</TT><BR>
</DT><DD CLASS="dd-list"> 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 <TT class=filename>init.<TT class=variable>object-type</TT></TT> or, if that does not exist,
<TT class=filename>init.lisp</TT> from the user&#X2019;s home directory. If neither exists,
CMUCLtries <TT class=filename>.cmucl-init.<TT class=variable>object-type</TT></TT> and then
<TT class=filename>.cmucl-init.lisp</TT>. If the file is not
in the user&#X2019;s home directory, the full path must be specified. If
the file does not exist, CMUCLsilently ignores it.</DD><DT CLASS="dt-list"><TT class=code>-noinit</TT><BR>
</DT><DD CLASS="dd-list"> 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 <TT class=code>-edit</TT> switch.</DD><DT CLASS="dt-list"><TT class=code>-nositeinit</TT><BR>
</DT><DD CLASS="dd-list"> accepts no arguments and specifies that the
site init file should not be loaded during the normal start up
sequence. </DD><DT CLASS="dt-list"><TT class=code>-load</TT><BR>
</DT><DD CLASS="dd-list"> accepts an argument which should be the name of a
file to load into Lisp before entering Lisp&#X2019;s read-eval-print loop.</DD><DT CLASS="dt-list"><TT class=code>-slave</TT><BR>
</DT><DD CLASS="dd-list"> specifies that Lisp should start up as a
islave Lisp and try to connect to an editor Lisp. The name of
the editor to connect to must be specified&#X2014;to find the
editor&#X2019;s name, use the Hemlock &#X201C;<TT class=code>Accept Slave
Connections</TT>&#X201D; command. The name for the editor Lisp is of the
form:
<BLOCKQUOTE class=example><PRE>
    <TT class=variable>machine-name</TT><TT class=code>:</TT><TT class=variable>socket</TT>
  </PRE></BLOCKQUOTE>
where <TT class=variable>machine-name</TT> is the internet host name for the machine
and <TT class=variable>socket</TT> is the decimal number of the socket to connect to.</DD><DT CLASS="dt-list"><TT class=code>-fpu</TT><BR>
</DT><DD CLASS="dd-list"> specifies what fpu should be used for x87 machines.
The possible values are &#X201C;<TT class=code>x87</TT>&#X201D;, &#X201C;<TT class=code>sse2</TT>&#X201D;, or
&#X201C;<TT class=code>auto</TT>&#X201D;, which is the default. By default, CMUCLwill
detect if the chip supports the SSE2 instruction set or not. If so
or if <TT class=code>-fpu sse2</TT> is specified, the SSE2 core will be loaded
that uses SSE2 for floating-point arithmetic. If SSE2 is not
available or if <TT class=code>-fpu x87</TT> is given, the legacy x87 core is
loaded.</DD><DT CLASS="dt-list"><TT class=code>&#X2013;</TT><BR>
</DT><DD CLASS="dd-list"> indicates that everything after &#X201C;<TT class=code>&#X2013;</TT>&#X201D; is not
subject to CMUCL&#X2019;s command line parsing. Everything after
&#X201C;<TT class=code>&#X2013;</TT>&#X201D; is placed in the variable
<TT class=code>ext:*command-line-application-arguments*</TT>.
</DD></DL><P>For more details on the use of the </P><TT class=code>-edit</TT><P> and </P><TT class=code>-slave</TT><P>
switches, see the <I>Hemlock User&#X2019;s Manual</I>.</P><P>Arguments to the above switches can be specified in one of two ways:
</P><TT class=variable>switch</TT><TT class=code>=</TT><TT class=variable>value</TT><P> or
</P><TT class=variable>switch</TT><P>&lt;</P><TT class=variable>space</TT><P>&gt;</P><TT class=variable>value</TT><P>. For example, to start up
the saved core file mylisp.core use either of the following two
commands:</P><BLOCKQUOTE class=example><PRE>
   lisp -core=mylisp.core
   lisp -core mylisp.core
</PRE></BLOCKQUOTE><!--TOC section Credits-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc4">1.3</A>&#XA0;&#XA0;Credits</H2><!--SEC END --><P>CMUCL was developed at the Computer Science Department of Carnegie
Mellon University. The work was a small autonomous part within the
Mach microkernel-based operating system project, and started more as a
tool development effort than a research project. The project started
out as Spice Lisp, which provided a modern Lisp implementation for use
in the CMU community. CMUCL has been under continual development since
the early 1980&#X2019;s (concurrent with the Common Lisp standardization
effort). Most of the CMU Common Lisp implementors went on to work on
the Gwydion environment for Dylan. The CMU team was lead by Scott E.
Fahlman, the Python compiler was written by Robert MacLachlan.</P><P>CMUCL&#X2019;s CLOS implementation is derived from the PCL reference
implementation written at Xerox PARC:
</P><BLOCKQUOTE CLASS="quotation">
Copyright (c) 1985, 1986, 1987, 1988, 1989, 1990 Xerox
Corporation.<BR>
All rights reserved.<P><BR>

Use and copying of this software and preparation of
derivative works based upon this software are permitted. Any
distribution of this software or derivative works must comply with all
applicable United States export control laws.</P><P><BR>

This software is made available AS IS, and Xerox Corporation
makes no warranty about the software, its performance or its
conformity to any specification.
</P></BLOCKQUOTE><P>
Its implementation of the LOOP macro was derived from code from
Symbolics, which was derived from code written at MIT:
</P><BLOCKQUOTE CLASS="quotation">
Portions of LOOP are Copyright (c) 1986 by the Massachusetts
Institute of Technology.<BR>
All Rights Reserved.<P><BR>

Permission to use, copy, modify and distribute this software
and its documentation for any purpose and without fee is hereby granted,
provided that the M.I.T. copyright notice appear in all copies and that
both that copyright notice and this permission notice appear in
supporting documentation. The names "M.I.T." and "Massachusetts
Institute of Technology" may not be used in advertising or publicity
pertaining to distribution of the software without specific, written
prior permission. Notice must be given in supporting documentation that
copying distribution is by permission of M.I.T. M.I.T. makes no
representations about the suitability of this software for any purpose.
It is provided "as is" without express or implied warranty.</P><P><BR>
<BR>
<BR>

Portions of LOOP are Copyright (c) 1989, 1990, 1991, 1992 by
Symbolics, Inc.<BR>
All Rights Reserved.</P><P><BR>

Permission to use, copy, modify and distribute this software
and its documentation for any purpose and without fee is hereby
granted, provided that the Symbolics copyright notice appear in all
copies and that both that copyright notice and this permission notice
appear in supporting documentation. The name "Symbolics" may not be
used in advertising or publicity pertaining to distribution of the
software without specific, written prior permission. Notice must be
given in supporting documentation that copying distribution is by
permission of Symbolics. Symbolics makes no representations about the
suitability of this software for any purpose. It is provided "as is"
without express or implied warranty.</P><P><BR>

Symbolics, CLOE Runtime, and Minima are trademarks, and
CLOE, Genera, and Zetalisp are registered trademarks of Symbolics,
Inc.
</P></BLOCKQUOTE><P>
The CLX code is copyrighted by Texas Instruments Incorporated:
</P><BLOCKQUOTE CLASS="quotation">
Copyright (C) 1987 Texas Instruments Incorporated.<P><BR>

Permission is granted to any individual or institution to
use, copy, modify, and distribute this software, provided that this
complete copyright and permission notice is maintained, intact, in all
copies and supporting documentation.</P><P><BR>

Texas Instruments Incorporated provides this software "as
is" without express or implied warranty.
</P></BLOCKQUOTE><P>CMUCL was funded by DARPA under CMU&#X2019;s "Research on Parallel Computing"
contract. Rather than doing pure research on programming languages and
environments, the emphasis was on developing practical programming
tools. Sometimes this required new technology, but much of the work
was in creating a Common Lisp environment that incorporates
state-of-the-art features from existing systems (both Lisp and
non-Lisp). Archives of the project are available online.</P><P>The project funding stopped in 1994, so support at Carnegie Mellon
University has been discontinued. All code and documentation developed
at CMU was released into the public domain. The project continues as a
group of users and developers collaborating over the Internet. The
current and previous maintainers include:</P><UL CLASS="itemize"><LI CLASS="li-itemize">
Marco Antoniotti
</LI><LI CLASS="li-itemize">Martin Cracauer
</LI><LI CLASS="li-itemize">Fred Gilham
</LI><LI CLASS="li-itemize">Alex Goncharov
</LI><LI CLASS="li-itemize">Rob MacLachlan
</LI><LI CLASS="li-itemize">Pierre Mai
</LI><LI CLASS="li-itemize">Eric Marsden
</LI><LI CLASS="li-itemize">Gerd Moellman
</LI><LI CLASS="li-itemize">Tim Moore
</LI><LI CLASS="li-itemize">Carl Shapiro 
</LI><LI CLASS="li-itemize">Robert Swindells
</LI><LI CLASS="li-itemize">Raymond Toy
</LI><LI CLASS="li-itemize">Peter Van Eynde
</LI><LI CLASS="li-itemize">Paul Werkowski
</LI></UL><P>In particular, Paul Werkowski and Douglas Crosher completed the port
for the x86 architecture for FreeBSD. Peter VanEnyde took the FreeBSD
port and created a Linux version. Other people who have contributed to
the development of CMUCL since 1981 are</P><UL CLASS="itemize"><LI CLASS="li-itemize">
David Axmark
</LI><LI CLASS="li-itemize">Miles Bader
</LI><LI CLASS="li-itemize">Rick Busdiecker
</LI><LI CLASS="li-itemize">Bill Chiles
</LI><LI CLASS="li-itemize">Douglas Thomas Crosher
</LI><LI CLASS="li-itemize">Casper Dik
</LI><LI CLASS="li-itemize">Ted Dunning
</LI><LI CLASS="li-itemize">Scott Fahlman
</LI><LI CLASS="li-itemize">Mike Garland
</LI><LI CLASS="li-itemize">Paul Gleichauf
</LI><LI CLASS="li-itemize">Sean Hallgren
</LI><LI CLASS="li-itemize">Richard Harris
</LI><LI CLASS="li-itemize">Joerg-Cyril Hoehl
</LI><LI CLASS="li-itemize">Chris Hoover
</LI><LI CLASS="li-itemize">John Kolojejchick
</LI><LI CLASS="li-itemize">Todd Kaufmann
</LI><LI CLASS="li-itemize">Simon Leinen
</LI><LI CLASS="li-itemize">Sandra Loosemore
</LI><LI CLASS="li-itemize">William Lott
</LI><LI CLASS="li-itemize">Dave McDonald
</LI><LI CLASS="li-itemize">Tim Moore
</LI><LI CLASS="li-itemize">Skef Wholey
</LI><LI CLASS="li-itemize">Paul Foley
</LI><LI CLASS="li-itemize">Helmut Eller
</LI><LI CLASS="li-itemize">Jan Rychter
</LI></UL><P>Countless others have contributed to the project by sending in bug
reports, bug fixes, and new features.</P><P>This manual is based on CMU Technical Report CMU-CS-92-161, edited by
Robert A. MacLachlan, dated July 1992. Other contributors include
Raymond Toy, Paul Werkowski and Eric Marsden. The Hierarchical
Packages chapter is based on documentation written by Franz. Inc, and
is used with permission. The remainder of the document is in the
public domain.
</P><!--NAME introduction.html-->
<!--TOC chapter Design Choices and Extensions-->
<H1 CLASS="chapter"><!--SEC ANCHOR --><A NAME="htoc5">Chapter&#XA0;2</A>&#XA0;&#XA0;Design Choices and Extensions</H1><!--SEC END --><P>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.</P><!--TOC section Data Types-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc6">2.1</A>&#XA0;&#XA0;Data Types</H2><!--SEC END --><!--TOC subsection Integers-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc7">2.1.1</A>&#XA0;&#XA0;Integers</H3><!--SEC END --><P>The <A NAME="@types0"></A></P><TT class=code>fixnum</TT><P> type is equivalent to </P><TT class=code>(signed-byte 30)</TT><P>.
Integers outside this range are represented as a <A NAME="@types1"></A></P><TT class=code>bignum</TT><P> or
a word integer (see section&#XA0;<A HREF="#word-integers">5.11.6</A>.) Almost all integers that
appear in programs can be represented as a </P><TT class=code>fixnum</TT><P>, so integer
number consing is rare.</P><!--TOC subsection Floats-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc8">2.1.2</A>&#XA0;&#XA0;Floats</H3><!--SEC END --><P>
<A NAME="ieee-float"></A></P><P>CMUCL supports three floating point formats:
<A NAME="@types2"></A></P><TT class=code>single-float</TT><P>, <A NAME="@types3"></A></P><TT class=code>double-float</TT><P> and
<A NAME="@types4"></A></P><TT class=code>double-double-float</TT><P>. The first two are implemented with
IEEE single and double float arithmetic, respectively. The last is an
extension; see section&#XA0;<A HREF="#extended-float">2.1.3</A> for more information.
</P><TT class=code>short-float</TT><P> is a synonym for </P><TT class=code>single-float</TT><P>, and
</P><TT class=code>long-float</TT><P> is a synonym for </P><TT class=code>double-float</TT><P>. The initial
value of <A NAME="@vars0"></A></P><TT class=code>*read-default-float-format*</TT><P> is </P><TT class=code>single-float</TT><P>.</P><P>Both </P><TT class=code>single-float</TT><P> and </P><TT class=code>double-float</TT><P> 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 (see section&#XA0;<A HREF="#numeric-types">5.11</A>.)</P><!--TOC subsubsection IEEE Special Values-->
<H4 CLASS="subsubsection"><!--SEC ANCHOR -->2.1.2.1&#XA0;&#XA0;IEEE Special Values</H4><!--SEC END --><P>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 (see section&#XA0;<A HREF="#float-traps">2.1.2.4</A>), so users of
the default configuration need not concern themselves with special
values.</P><P><BR>
</P><DIV align=left>
[Constant]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>short-float-positive-infinity</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
<DIV align=left>
[Constant]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>short-float-negative-infinity</TT>  &nbsp;&nbsp;&nbsp;
</DIV>
<DIV align=left>
[Constant]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>single-float-positive-infinity</TT>  &nbsp;&nbsp;&nbsp;
</DIV>
<DIV align=left>
[Constant]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>single-float-negative-infinity</TT>  &nbsp;&nbsp;&nbsp;
</DIV>
<DIV align=left>
[Constant]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>double-float-positive-infinity</TT>  &nbsp;&nbsp;&nbsp;
</DIV>
<DIV align=left>
[Constant]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>double-float-negative-infinity</TT>  &nbsp;&nbsp;&nbsp;
</DIV>
<DIV align=left>
[Constant]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>long-float-positive-infinity</TT>  &nbsp;&nbsp;&nbsp;
</DIV>
<DIV align=left>
[Constant]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>long-float-negative-infinity</TT>  &nbsp;&nbsp;&nbsp;
</DIV><P>The values of these constants are the IEEE positive and negative
infinity objects for each float format.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs1"></A><A NAME="FN:float-infinity-p"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>float-infinity-p</TT> <TT class=variable>x</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns true if </P><TT class=variable>x</TT><P> is an IEEE float infinity (of
either sign.) </P><TT class=variable>x</TT><P> must be a float.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs2"></A><A NAME="FN:float-nan-p"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>float-nan-p</TT> <TT class=variable>x</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
<P><A NAME="@funs3"></A><A NAME="FN:float-trapping-nan-p"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>float-trapping-nan-p</TT> <TT class=variable>x</TT> &nbsp;&nbsp;&nbsp;
</DIV><TT class=code>float-nan-p</TT><P> returns true if </P><TT class=variable>x</TT><P> is an IEEE NaN (Not A
Number) object. </P><TT class=code>float-trapping-nan-p</TT><P> returns true only if
</P><TT class=variable>x</TT><P> is a trapping NaN. With either function, </P><TT class=variable>x</TT><P> must be a
float.
</P></BLOCKQUOTE><!--TOC subsubsection Negative Zero-->
<H4 CLASS="subsubsection"><!--SEC ANCHOR -->2.1.2.2&#XA0;&#XA0;Negative Zero</H4><!--SEC END --><P>The IEEE float format provides for distinct positive and negative
zeros. To test the sign on zero (or any other float), use the
Common Lisp <A NAME="@funs4"></A></P><TT class=code>float-sign</TT><P> function. Negative zero prints as
</P><TT class=code>-0.0f0</TT><P> or </P><TT class=code>-0.0d0</TT><P>.</P><!--TOC subsubsection Denormalized Floats-->
<H4 CLASS="subsubsection"><!--SEC ANCHOR -->2.1.2.3&#XA0;&#XA0;Denormalized Floats</H4><!--SEC END --><P>CMUCL supports IEEE denormalized floats. Denormalized floats
provide a mechanism for gradual underflow. The Common Lisp
<A NAME="@funs5"></A></P><TT class=code>float-precision</TT><P> function returns the actual precision of a
denormalized float, which will be less than <A NAME="@funs6"></A></P><TT class=code>float-digits</TT><P>.
Note that in order to generate (or even print) denormalized floats,
trapping must be disabled for the underflow exception
(see section&#XA0;<A HREF="#float-traps">2.1.2.4</A>.) The Common Lisp
</P><TT class=code>least-positive-</TT><TT class=variable>format</TT><P>-</P><TT class=code>float</TT><P> constants are
denormalized.</P><P><BR>
<A NAME="@funs7"></A><A NAME="FN:float-denormalized-p"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>float-denormalized-p</TT> <TT class=variable>x</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns true if </P><TT class=variable>x</TT><P> is a denormalized float.
</P><TT class=variable>x</TT><P> must be a float.
</P></BLOCKQUOTE><!--TOC subsubsection Floating Point Exceptions-->
<H4 CLASS="subsubsection"><!--SEC ANCHOR -->2.1.2.4&#XA0;&#XA0;Floating Point Exceptions</H4><!--SEC END --><P>
<A NAME="float-traps"></A></P><P>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:

</P><DL CLASS="list"><DT CLASS="dt-list">
<TT class=code>:underflow</TT><BR>
</DT><DD CLASS="dd-list"> 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
<A NAME="@types5"></A><TT class=code>floating-point-underflow</TT> condition is signalled.
Otherwise, the operation results in a denormalized float or zero.</DD><DT CLASS="dt-list"><TT class=code>:overflow</TT><BR>
</DT><DD CLASS="dd-list"> 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 <A NAME="@types6"></A><TT class=code>floating-point-overflow</TT>
exception is signalled. Otherwise, the operation results in the
appropriate infinity.</DD><DT CLASS="dt-list"><TT class=code>:inexact</TT><BR>
</DT><DD CLASS="dd-list"> 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 <TT class=code>extensions:floating-point-inexact</TT>
condition is signalled. Otherwise, the rounded result is returned.</DD><DT CLASS="dt-list"><TT class=code>:invalid</TT><BR>
</DT><DD CLASS="dd-list"> This exception occurs when the result of an
operation is ill-defined, such as <TT class=code>(/ 0.0 0.0)</TT>. If
trapping is enabled, the <TT class=code>extensions:floating-point-invalid</TT>
condition is signalled. Otherwise, a quiet NaN is returned.</DD><DT CLASS="dt-list"><TT class=code>:divide-by-zero</TT><BR>
</DT><DD CLASS="dd-list"> This exception occurs when a float is
divided by zero. If trapping is enabled, the
<A NAME="@types7"></A><TT class=code>divide-by-zero</TT> condition is signalled. Otherwise, the
appropriate infinity is returned.
</DD></DL><!--TOC subsubsection Floating Point Rounding Mode-->
<H4 CLASS="subsubsection"><!--SEC ANCHOR -->2.1.2.5&#XA0;&#XA0;Floating Point Rounding Mode</H4><!--SEC END --><P>
<A NAME="float-rounding-modes"></A></P><P>IEEE floating point specifies four possible rounding modes:

</P><DL CLASS="list"><DT CLASS="dt-list">
<TT class=code>:nearest</TT><BR>
</DT><DD CLASS="dd-list"> 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 &#X201C;round to even&#X201D;, and is the form
of rounding specified for the Common Lisp <A NAME="@funs8"></A><TT class=code>round</TT> function.</DD><DT CLASS="dt-list"><TT class=code>:positive-infinity</TT><BR>
</DT><DD CLASS="dd-list"> This mode rounds inexact results to the
possible value closer to positive infinity. This is analogous to
the Common Lisp <A NAME="@funs9"></A><TT class=code>ceiling</TT> function.</DD><DT CLASS="dt-list"><TT class=code>:negative-infinity</TT><BR>
</DT><DD CLASS="dd-list"> This mode rounds inexact results to the
possible value closer to negative infinity. This is analogous to
the Common Lisp <A NAME="@funs10"></A><TT class=code>floor</TT> function.</DD><DT CLASS="dt-list"><TT class=code>:zero</TT><BR>
</DT><DD CLASS="dd-list"> This mode rounds inexact results to the possible
value closer to zero. This is analogous to the Common Lisp
<A NAME="@funs11"></A><TT class=code>truncate</TT> function.
</DD></DL><!--TOC paragraph Warning:-->
<H5 CLASS="paragraph"><!--SEC ANCHOR -->Warning:</H5><!--SEC END --><P>Although the rounding mode can be changed with
</P><TT class=code>set-floating-point-modes</TT><P>, use of any value other than the
default (</P><TT class=code>:nearest</TT><P>) can cause unusual behavior, since it will
affect rounding done by Common Lisp system code as well as rounding in
user code. In particular, the unary </P><TT class=code>round</TT><P> function will stop
doing round-to-nearest on floats, and instead do the selected form of
rounding.</P><!--TOC subsubsection Accessing the Floating Point Modes-->
<H4 CLASS="subsubsection"><!--SEC ANCHOR -->2.1.2.6&#XA0;&#XA0;Accessing the Floating Point Modes</H4><!--SEC END --><P>These functions can be used to modify or read the floating point modes:</P><P><BR>
<A NAME="@funs12"></A><A NAME="FN:set-floating-point-modes"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>set-floating-point-modes</TT> <TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=code>:traps</TT> <TT class=code>:rounding-mode</TT></SPAN><BR>
 <TT class=code>:fast-mode</TT> <TT class=code>:accrued-exceptions</TT><BR>
 <TT class=code>:current-exceptions</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
<P><A NAME="@funs13"></A><A NAME="FN:get-floating-point-modes"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>get-floating-point-modes</TT>  &nbsp;&nbsp;&nbsp;
</DIV><P>The keyword arguments to </P><TT class=code>set-floating-point-modes</TT><P> set various
modes controlling how floating point arithmetic is done:

</P><DL CLASS="list"><DT CLASS="dt-list">
<TT class=code>:traps</TT><BR>
</DT><DD CLASS="dd-list"> A list of the exception conditions that should
cause traps. Possible exceptions are <TT class=code>:underflow</TT>,
<TT class=code>:overflow</TT>, <TT class=code>:inexact</TT>, <TT class=code>:invalid</TT> and
<TT class=code>:divide-by-zero</TT>. Initially all traps except <TT class=code>:inexact</TT>
are enabled. See section&#XA0;<A HREF="#float-traps">2.1.2.4</A>.</DD><DT CLASS="dt-list"><TT class=code>:rounding-mode</TT><BR>
</DT><DD CLASS="dd-list"> The rounding mode to use when the result
is not exact. Possible values are <TT class=code>:nearest</TT>,
<TT class=code>:positive-infinity</TT>, <TT class=code>:negative-infinity</TT> and <TT class=code>:zero</TT>.
Initially, the rounding mode is <TT class=code>:nearest</TT>. See the warning in
section <A HREF="#float-rounding-modes">2.1.2.5</A> about use of other rounding
modes.</DD><DT CLASS="dt-list"><TT class=code>:current-exceptions</TT>, <TT class=code>:accrued-exceptions</TT><BR>
</DT><DD CLASS="dd-list"> Lists of
exception keywords used to set the exception flags. The
<TT class=variable>current-exceptions</TT> are the exceptions for the previous
operation, so setting it is not very useful. The
<TT class=variable>accrued-exceptions</TT> are a cumulative record of the exceptions
that occurred since the last time these flags were cleared.
Specifying <TT class=code>()</TT> will clear any accrued exceptions.</DD><DT CLASS="dt-list"><TT class=code>:fast-mode</TT><BR>
</DT><DD CLASS="dd-list"> Set the hardware&#X2019;s &#X201C;fast mode&#X201D; 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 <TT class=code>nil</TT>. Sparc platforms support a fast mode where
denormal numbers are silently truncated to zero.
</DD></DL><P>
If a keyword argument is not supplied, then the associated state is
not changed.</P><TT class=code>get-floating-point-modes</TT><P> returns a list representing the
state of the floating point modes. The list is in the same format
as the keyword arguments to </P><TT class=code>set-floating-point-modes</TT><P>, so
</P><TT class=code>apply</TT><P> could be used with </P><TT class=code>set-floating-point-modes</TT><P> to
restore the modes in effect at the time of the call to
</P><TT class=code>get-floating-point-modes</TT><P>.
</P></BLOCKQUOTE><P>To make handling control of floating-point exceptions, the following
macro is useful.</P><P><BR>
<A NAME="@funs14"></A><A NAME="FN:with-float-traps-masked"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>ext:</TT><TT class=function-name>with-float-traps-masked</TT> traps <TT class=code>&amp;body</TT> body &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
<TT class=code>body</TT> is executed with the selected floating-point exceptions
given by <TT class=code>traps</TT> masked out (disabled). <TT class=code>traps</TT> should be
a list of possible floating-point exceptions that should be ignored.
Possible values are <TT class=code>:underflow</TT>, <TT class=code>:overflow</TT>, <TT class=code>:inexact</TT>,
<TT class=code>:invalid</TT> and <TT class=code>:divide-by-zero</TT>.<P>This is equivalent to saving the current traps from
</P><TT class=code>get-floating-point-modes</TT><P>, setting the floating-point modes to
the desired exceptions, running the </P><TT class=code>body</TT><P>, and restoring the
saved floating-point modes. The advantage of this macro is that it
causes less consing to occur.</P><P>Some points about the with-float-traps-masked:</P><UL CLASS="itemize"><LI CLASS="li-itemize">
Two approaches are available for detecting FP exceptions:
<OL CLASS="enumerate" type=1><LI CLASS="li-enumerate">
enabling the traps and handling the exceptions
</LI><LI CLASS="li-enumerate">disabling the traps and either handling the return values or
checking the accrued exceptions.
</LI></OL>
Of these the latter is the most portable because on the alpha port
it is not possible to enable some traps at run-time.</LI><LI CLASS="li-itemize">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.</LI><LI CLASS="li-itemize">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.</LI><LI CLASS="li-itemize">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.</LI><LI CLASS="li-itemize">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.</LI><LI CLASS="li-itemize">On the x86, and, perhaps, the hppa, the FP exceptions may be
delivered at the next FP instruction which requires a FP
<TT class=code>wait</TT> instruction (<TT class=code>x86::float-wait</TT>) if using the lisp
conditions to catch trap within a <TT class=code>handler-bind</TT>. The
<TT class=code>handler-bind</TT> 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.</LI><LI CLASS="li-itemize">The setting of the FP flags uses the
<TT class=code>(floating-point-modes)</TT> and the <TT class=code>(set
(floating-point-modes)&#X2026;)</TT> VOPs. These VOPs blindly update
the flags which may include other state. We assume this state
hasn&#X2019;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
<TT class=code>with-float-traps-masked</TT> macro keeps the intervening code to
a minimum and uses only integer operations.
</LI></UL></BLOCKQUOTE><!--TOC subsection Extended Floats-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc9">2.1.3</A>&#XA0;&#XA0;Extended Floats</H3><!--SEC END --><P>
<A NAME="extended-float"></A></P><P>CMUCL also has an extension to support </P><TT class=code>double-double-float</TT><P>
type. This float format provides extended precision of about 31
decimal digits, with the same exponent range as </P><TT class=code>double-float</TT><P>.
It is completely integrated into CMUCL, and can be used just like
any other floating-point object, including arrays, complex
</P><TT class=code>double-double-float</TT><P>&#X2019;s, and special functions. With appropriate
declarations, no boxing is needed, just like </P><TT class=code>single-float</TT><P> and
</P><TT class=code>double-float</TT><P>. </P><P>The exponent marker for a double-double float number is &#X201C;W&#X201D;, so
&#X201C;1.234w0&#X201D; is a double-double float number.</P><P>Note that there are a few shortcomings with
</P><TT class=code>double-double-float</TT><P>&#X2019;s:
</P><UL CLASS="itemize"><LI CLASS="li-itemize">
There are no equivalents to <TT class=code>most-positive-double-float</TT>,
<TT class=code>double-float-positive-infinity</TT>, <I>etc</I>. This is because
these are not really well defined for <TT class=code>double-double-float</TT>&#X2019;s.
</LI><LI CLASS="li-itemize">Underflow and overflow may be prematurely signaled. This is
due to how <TT class=code>double-double-float</TT>&#X2019;s are implemented.
</LI><LI CLASS="li-itemize">Basic arithmetic operations are inlined, so the code size is
fairly large.
</LI><LI CLASS="li-itemize"><TT class=code>double-double-float</TT> arithmetic is quite a bit slower
than <TT class=code>double-float</TT> since there is no hardware support for
this type.
</LI><LI CLASS="li-itemize">The constant <TT class=code>pi</TT> is still a <TT class=code>double-float</TT> instead
of a <TT class=code>double-double-float</TT>. Use <TT class=code>ext:dd-pi</TT> if you
want a <TT class=code>double-double-float</TT> value for &#X3C0;.
</LI></UL><P><BR>
<BR>
<A NAME="@types8"></A></P><DIV align=left>
[float]<BR>
 <TT class=function-name>extensions:double-double-float</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
The <TT class=code>double-double-float</TT> type. It is in the <TT class=code>EXTENSIONS</TT>
package.
</BLOCKQUOTE><P><BR>
</P><DIV align=left>
[Constant]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>dd-pi</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
A <TT class=code>double-double-float</TT> approximation to &#X3C0;.
</BLOCKQUOTE><!--TOC subsection Characters-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc10">2.1.4</A>&#XA0;&#XA0;Characters</H3><!--SEC END --><P>CMUCL implements characters according to <I>Common Lisp: The Language II</I>. 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.
<A NAME="@types9"></A></P><TT class=code>base-character</TT><P> is the new equivalent of the old
<A NAME="@types10"></A></P><TT class=code>string-char</TT><P>. In this implementation, all characters are
base characters (there are no extended characters.) Character codes
range between </P><TT class=code>0</TT><P> and </P><TT class=code>255</TT><P>, using the ASCII encoding.
Table&#XA0;<A HREF="#tbl:chars">2.1</A>&#XA0;tbl:chars shows characters recognized
by CMUCL.</P><BLOCKQUOTE CLASS="table"><DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV>
<DIV CLASS="center">
<TABLE BORDER=1 CELLSPACING=0 CELLPADDING=1><TR><TD ALIGN=center NOWRAP COLSPAN=2>ASCII</TD><TD ALIGN=center NOWRAP>Lisp</TD><TD ALIGN=center NOWRAP COLSPAN=3>&nbsp;</TD></TR>
<TR><TD ALIGN=center NOWRAP> Name</TD><TD ALIGN=center NOWRAP>Code</TD><TD ALIGN=center NOWRAP>Name</TD><TD ALIGN=center NOWRAP COLSPAN=3>1.5exAlternatives</TD></TR>
<TR><TD ALIGN=center NOWRAP> <TT class=code>nul</TT></TD><TD ALIGN=center NOWRAP>0</TD><TD ALIGN=left NOWRAP><TT class=code>#\NULL</TT></TD><TD ALIGN=left NOWRAP><TT class=code>#\NUL</TT></TD><TD ALIGN=left NOWRAP>&nbsp;</TD><TD ALIGN=left NOWRAP>&nbsp;</TD></TR>
<TR><TD ALIGN=center NOWRAP> <TT class=code>bel</TT></TD><TD ALIGN=center NOWRAP>7</TD><TD ALIGN=left NOWRAP><TT class=code>#\BELL</TT></TD><TD ALIGN=left NOWRAP>&nbsp;</TD><TD ALIGN=left NOWRAP>&nbsp;</TD><TD ALIGN=left NOWRAP>&nbsp;</TD></TR>
<TR><TD ALIGN=center NOWRAP> <TT class=code>bs</TT></TD><TD ALIGN=center NOWRAP>8</TD><TD ALIGN=left NOWRAP><TT class=code>#\BACKSPACE</TT></TD><TD ALIGN=left NOWRAP><TT class=code>#\BS</TT></TD><TD ALIGN=left NOWRAP>&nbsp;</TD><TD ALIGN=left NOWRAP>&nbsp;</TD></TR>
<TR><TD ALIGN=center NOWRAP> <TT class=code>tab</TT></TD><TD ALIGN=center NOWRAP>9</TD><TD ALIGN=left NOWRAP><TT class=code>#\TAB</TT></TD><TD ALIGN=left NOWRAP>&nbsp;</TD><TD ALIGN=left NOWRAP>&nbsp;</TD><TD ALIGN=left NOWRAP>&nbsp;</TD></TR>
<TR><TD ALIGN=center NOWRAP> <TT class=code>lf</TT></TD><TD ALIGN=center NOWRAP>10</TD><TD ALIGN=left NOWRAP><TT class=code>#\NEWLINE</TT></TD><TD ALIGN=left NOWRAP><TT class=code>#\NL</TT></TD><TD ALIGN=left NOWRAP><TT class=code>#\LINEFEED</TT></TD><TD ALIGN=left NOWRAP><TT class=code>#\LF</TT></TD></TR>
<TR><TD ALIGN=center NOWRAP> <TT class=code>ff</TT></TD><TD ALIGN=center NOWRAP>11</TD><TD ALIGN=left NOWRAP><TT class=code>#\VT</TT></TD><TD ALIGN=left NOWRAP><TT class=code>#\PAGE</TT></TD><TD ALIGN=left NOWRAP><TT class=code>#\FORM</TT></TD><TD ALIGN=left NOWRAP>&nbsp;</TD></TR>
<TR><TD ALIGN=center NOWRAP> <TT class=code>cr</TT></TD><TD ALIGN=center NOWRAP>13</TD><TD ALIGN=left NOWRAP><TT class=code>#\RETURN</TT></TD><TD ALIGN=left NOWRAP><TT class=code>#\CR</TT></TD><TD ALIGN=left NOWRAP>&nbsp;</TD><TD ALIGN=left NOWRAP>&nbsp;</TD></TR>
<TR><TD ALIGN=center NOWRAP> <TT class=code>esc</TT></TD><TD ALIGN=center NOWRAP>27</TD><TD ALIGN=left NOWRAP><TT class=code>#\ESCAPE</TT></TD><TD ALIGN=left NOWRAP><TT class=code>#\ESC</TT></TD><TD ALIGN=left NOWRAP><TT class=code>#\ALTMODE</TT></TD><TD ALIGN=left NOWRAP><TT class=code>#\ALT</TT></TD></TR>
<TR><TD ALIGN=center NOWRAP> <TT class=code>sp</TT></TD><TD ALIGN=center NOWRAP>32</TD><TD ALIGN=left NOWRAP><TT class=code>#\SPACE</TT></TD><TD ALIGN=left NOWRAP><TT class=code>#\SP</TT></TD><TD ALIGN=left NOWRAP>&nbsp;</TD><TD ALIGN=left NOWRAP>&nbsp;</TD></TR>
<TR><TD ALIGN=center NOWRAP> <TT class=code>del</TT></TD><TD ALIGN=center NOWRAP>127</TD><TD ALIGN=left NOWRAP><TT class=code>#\DELETE</TT></TD><TD ALIGN=left NOWRAP><TT class=code>#\RUBOUT</TT></TD><TD ALIGN=left NOWRAP>&nbsp;</TD><TD ALIGN=left NOWRAP>&nbsp;</TD></TR>
</TABLE>
<DIV CLASS="caption"><TABLE CELLSPACING=6 CELLPADDING=0><TR><TD VALIGN=top ALIGN=left>Table 2.1: Characters recognized by CMUCL</TD></TR>
</TABLE></DIV>
<A NAME="tbl:chars"></A>
</DIV>
<DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV></BLOCKQUOTE><!--TOC subsection Array Initialization-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc11">2.1.5</A>&#XA0;&#XA0;Array Initialization</H3><!--SEC END --><P>If no </P><TT class=code>:initial-value</TT><P> is specified, arrays are initialized to zero.</P><!--TOC subsection Hash tables-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc12">2.1.6</A>&#XA0;&#XA0;Hash tables</H3><!--SEC END --><P>The <A NAME="@types11"></A></P><TT class=code>hash-tables</TT><P> defined by Common Lisp have limited utility because they
are limited to testing their keys using the equality predicates
provided by (pre-CLOS) Common Lisp. CMUCL overcomes this limitation
by allowing its users to specify new hash table tests and hashing
methods. The hashing method must also be specified, since the
compiler is unable to determine a good hashing function for an
arbitrary equality (equivalence) predicate.</P><P><BR>
<A NAME="@funs15"></A><A NAME="FN:define-hash-table-test"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>define-hash-table-test</TT> <TT class=variable>hash-table-test-name</TT> <TT class=variable>test-function</TT> <TT class=variable>hash-function</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>The </P><TT class=variable>hash-table-test-name</TT><P> must be a symbol.
The </P><TT class=variable>test-function</TT><P> takes two objects and returns true
iff they are the same. The </P><TT class=variable>hash-function</TT><P> takes one object and
returns two values: the (positive fixnum) hash value and true if
the hashing depends on pointer values and will have to be redone
if the object moves.</P><P>To create a hash-table using this new &#X201C;test&#X201D; (really, a
test/hash-function pair), use
</P><TT class=code>(<A NAME="@funs16"></A>make-hash-table :test
<TT class=variable>hash-table-test-name</TT> &#X2026;)</TT><P>.</P><P>Note that it is the </P><TT class=variable>hash-table-test-name</TT><P> that will be
returned by the function <A NAME="@funs17"></A></P><TT class=code>hash-table-test</TT><P>, when applied to
a hash-table created using this function.</P><P>This function updates <A NAME="@vars1"></A></P><TT class=code>*hash-table-tests*</TT><P>, which is now
internal. 
</P></BLOCKQUOTE><P>CMUCL also supports a number of weak hash tables. These weak
tables are created using the </P><TT class=code>:weak-p</TT><P> argument to
</P><TT class=code>make-hash-table</TT><P>. Normally, a reference to an object as either
the key or value of the hash-table will prevent that object from being
garbage-collected. However, in a weak table, if the only reference is
the hash-table, the object can be collected.</P><P>The possible values for </P><TT class=code>:weak-p</TT><P> are listed below. An entry in
the table remains if the condition holds

</P><DL CLASS="list"><DT CLASS="dt-list">

<TT class=code>:key</TT><BR>
</DT><DD CLASS="dd-list"> The key is referenced elsewhere
</DD><DT CLASS="dt-list"><TT class=code>:value</TT><BR>
</DT><DD CLASS="dd-list"> The value is referenced elsewhere
</DD><DT CLASS="dt-list"><TT class=code>:key-and-value</TT><BR>
</DT><DD CLASS="dd-list"> Both the key and value are referenced elsewhere
</DD><DT CLASS="dt-list"><TT class=code>:key-or-value</TT><BR>
</DT><DD CLASS="dd-list"> Either the key or value are referenced elsewhere
</DD><DT CLASS="dt-list">T<BR>
</DT><DD CLASS="dd-list"> For backward compatibility, this means the same as <TT class=code>:key</TT>.
</DD></DL><P>
If the condition does not hold, the object can be removed from the
hash table. </P><P>Weak hash tables can only be created if the test is </P><TT class=code>eq</TT><P> or
</P><TT class=code>eql</TT><P>. An error is signaled if this is not the case.</P><P><BR>
<A NAME="@funs18"></A><A NAME="FN:make-hash-table"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>make-hash-table</TT> <TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=code>:test</TT> <TT class=code>:size</TT> <TT class=code>:rehash-size</TT> <TT class=code>:rehash-threshold</TT> <TT class=code>:weak-p</TT></SPAN> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Creates a hash-table with the specified properties.
</BLOCKQUOTE><!--TOC section Default Interrupts for Lisp-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc13">2.2</A>&#XA0;&#XA0;Default Interrupts for Lisp</H2><!--SEC END --><P>CMUCL has several interrupt handlers defined when it starts up,
as follows:

</P><DL CLASS="list"><DT CLASS="dt-list">
<TT class=code>SIGINT</TT> (<TT class=code>Ctrl-c</TT>)<BR>
</DT><DD CLASS="dd-list"> 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.</DD><DT CLASS="dt-list"><TT class=code>SIGQUIT</TT> (<TT class=code>Ctrl-L</TT>)<BR>
</DT><DD CLASS="dd-list"> 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.</DD><DT CLASS="dt-list"><TT class=code>SIGTSTP</TT> (<TT class=code>Ctrl-z</TT>)<BR>
</DT><DD CLASS="dd-list"> 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.</DD><DT CLASS="dt-list"><TT class=code>SIGILL</TT>, <TT class=code>SIGBUS</TT>, <TT class=code>SIGSEGV</TT>, and <TT class=code>SIGFPE</TT><BR>
</DT><DD CLASS="dd-list">
cause Lisp to signal an error.
</DD></DL><P>
For keyboard interrupt signals, the standard interrupt character is in
parentheses. Your </P><TT class=filename>.login</TT><P> 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. See section&#XA0;<A HREF="#signal-handlers">6.8.1</A> to define
your own signal handlers.</P><!--TOC section Implementation-Specific Packages-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc14">2.3</A>&#XA0;&#XA0;Implementation-Specific Packages</H2><!--SEC END --><P>When CMUCL is first started up, the default package is the
</P><TT class=code>common-lisp-user</TT><P> package. The </P><TT class=code>common-lisp-user</TT><P> package
uses the </P><TT class=code>common-lisp</TT><P> and </P><TT class=code>extensions</TT><P> 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.</P><DL CLASS="list"><DT CLASS="dt-list">

<TT class=code>alien</TT>, <TT class=code>c-call</TT><BR>
</DT><DD CLASS="dd-list"> Export the features of the Alien
foreign data structure facility (see section&#XA0;<A HREF="#aliens">8</A>.)</DD><DT CLASS="dt-list"><TT class=code>pcl</TT><BR>
</DT><DD CLASS="dd-list"> 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 <I>Common Lisp: The Language II</I>.</DD><DT CLASS="dt-list"><TT class=code>clos-mop (mop)</TT><BR>
</DT><DD CLASS="dd-list"> This package contains an implementation
of the CLOS Metaobject Protocol, as per the book <I>The Art of
the Metaobject Protocol</I>.</DD><DT CLASS="dt-list"><TT class=code>debug</TT><BR>
</DT><DD CLASS="dd-list"> The <TT class=code>debug</TT> package contains the command-line
oriented debugger. It exports utility various functions and
switches.</DD><DT CLASS="dt-list"><TT class=code>debug-internals</TT><BR>
</DT><DD CLASS="dd-list"> The <TT class=code>debug-internals</TT> package
exports the primitives used to write debuggers.
See section&#XA0;<A HREF="#debug-internals">11</A>.</DD><DT CLASS="dt-list"><TT class=code>extensions (ext)</TT><BR>
</DT><DD CLASS="dd-list"> The <TT class=code>extensions</TT> packages exports
local extensions to Common Lisp that are documented in this manual.
Examples include the <TT class=code>save-lisp</TT> function and time parsing.</DD><DT CLASS="dt-list"><TT class=code>hemlock (ed)</TT><BR>
</DT><DD CLASS="dd-list"> The <TT class=code>hemlock</TT> package contains all the
code to implement Hemlock commands. The <TT class=code>hemlock</TT> package
currently exports no symbols.</DD><DT CLASS="dt-list"><TT class=code>hemlock-internals (hi)</TT><BR>
</DT><DD CLASS="dd-list"> The <TT class=code>hemlock-internals</TT>
package contains code that implements low level primitives and
exports those symbols used to write Hemlock commands.</DD><DT CLASS="dt-list"><TT class=code>keyword</TT><BR>
</DT><DD CLASS="dd-list"> The <TT class=code>keyword</TT> package contains keywords
(e.g., <TT class=code>:start</TT>). All symbols in the <TT class=code>keyword</TT> package are
exported and evaluate to themselves (i.e., the value of the symbol
is the symbol itself).</DD><DT CLASS="dt-list"><TT class=code>profile</TT><BR>
</DT><DD CLASS="dd-list"> The <TT class=code>profile</TT> package exports a simple
run-time profiling facility (see section&#XA0;<A HREF="#profiling">5.14</A>).</DD><DT CLASS="dt-list"><TT class=code>common-lisp (cl)</TT><BR>
</DT><DD CLASS="dd-list"> The <TT class=code>common-lisp</TT> package
exports all the symbols defined by <I>Common Lisp: The Language</I> and only those symbols.
Strictly portable Lisp code will depend only on the symbols exported
from the <TT class=code>common-lisp</TT> package.</DD><DT CLASS="dt-list"><TT class=code>unix</TT><BR>
</DT><DD CLASS="dd-list"> This package exports system call
interfaces to Unix (see section&#XA0;<A HREF="#unix-interface">6</A>).</DD><DT CLASS="dt-list"><TT class=code>system (sys)</TT><BR>
</DT><DD CLASS="dd-list"> The <TT class=code>system</TT> package contains
functions and information necessary for system interfacing. This
package is used by the <TT class=code>lisp</TT> package and exports several
symbols that are necessary to interface to system code.</DD><DT CLASS="dt-list"><TT class=code>xlib</TT><BR>
</DT><DD CLASS="dd-list"> The <TT class=code>xlib</TT> 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.</DD><DT CLASS="dt-list"><TT class=code>wire</TT><BR>
</DT><DD CLASS="dd-list"> The <TT class=code>wire</TT> package exports a remote procedure
call facility (see section&#XA0;<A HREF="#remote">9</A>).</DD><DT CLASS="dt-list"><TT class=code>stream</TT><BR>
</DT><DD CLASS="dd-list"> The <TT class=code>stream</TT> package exports the public
interface to the simple-streams implementation (see section&#XA0;<A HREF="#simple-streams">2.13</A>).</DD><DT CLASS="dt-list"><TT class=code>xref</TT><BR>
</DT><DD CLASS="dd-list"> The <TT class=code>xref</TT> package exports the public
interface to the cross-referencing utility (see section&#XA0;<A HREF="#xref">12</A>).</DD></DL><!--TOC section Hierarchical Packages-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc15">2.4</A>&#XA0;&#XA0;Hierarchical Packages</H2><!--SEC END --><P>
<A NAME="@concept1"></A></P><!--TOC subsection Introduction-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc16">2.4.1</A>&#XA0;&#XA0;Introduction</H3><!--SEC END --><P>The Common Lisp package system, designed and standardized several years
ago, is not hierarchical. Since Common Lisp was standardized, other
languages, including Java and Perl, have evolved namespaces which are
hierarchical. This document describes a hierarchical package naming
scheme for Common Lisp. The scheme was proposed by Franz Inc and
implemented in their <I>Allegro Common Lisp</I> product; a
compatible implementation of the naming scheme is implemented in
CMUCL. This documentation is based on the Franz Inc. documentation,
and is included with permission.</P><P>The goals of hierarchical packages in Common Lisp are:</P><UL CLASS="itemize"><LI CLASS="li-itemize">
Reduce collisions with user-defined packages: it is a well-known
problem that package names used by the Lisp implementation and those
defined by users can easily conflict. The intent of hierarchical
packages is to reduce such conflicts to a minimum.</LI><LI CLASS="li-itemize">Improve modularity: the current organization of packages in various
implementations has grown over the years and appears somewhat random.
Organizing future packages into a hierarchy will help make the
intention of the implementation more clear.</LI><LI CLASS="li-itemize">Foster growth in Common Lisp programs, or modules, available to the CL
community: the Perl and Java communities are able to contribute code
to repositories, with minimal fear of collision, because of the
hierarchical nature of the name spaces used by the contributed code.
We want the Lisp community to benefit from shared modules in the same
way.
</LI></UL><P>In a nutshell, a dot (<CODE>.</CODE>) is used to separate levels in package
names, and a leading dot signifies a relative package name. The choice
of dot follows Java. Perl, another language with hierarchical
packages, uses a colon (<CODE>:</CODE>) as a delimiter, but the colon is
already reserved in Common Lisp. Absolute package names require no
modifications to the underlying Common Lisp implementation. Relative
package names require only small and simple modifications.</P><!--TOC subsection Relative Package Names-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc17">2.4.2</A>&#XA0;&#XA0;Relative Package Names</H3><!--SEC END --><P>Relative package names are needed for the same reason as relative
pathnames, for brevity and to reduce the brittleness of absolute
names. A relative package name is one that begins with one or more
dots. A single dot means the current package, two dots mean the parent
of the current package, and so on.</P><P>Table&#XA0;<A HREF="#tbl:hierarchical-packages">2.2</A> presents a number of examples,
assuming that the packages named <CODE>foo</CODE>, <CODE>foo.bar</CODE>,
<CODE>mypack</CODE>, <CODE>mypack.foo</CODE>, <CODE>mypack.foo.bar</CODE>,
<CODE>mypack.foo.baz</CODE>, <CODE>mypack.bar</CODE>, and <CODE>mypack.bar.baz</CODE>,
have all been created.</P><BLOCKQUOTE CLASS="table"><DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV>
<DIV CLASS="center">
<TABLE BORDER=1 CELLSPACING=0 CELLPADDING=1><TR><TD ALIGN=left NOWRAP>relative name</TD><TD ALIGN=left NOWRAP>current package</TD><TD ALIGN=left NOWRAP>absolute name of referenced package</TD></TR>
<TR><TD ALIGN=left NOWRAP>foo</TD><TD ALIGN=left NOWRAP>any</TD><TD ALIGN=left NOWRAP>foo</TD></TR>
<TR><TD ALIGN=left NOWRAP>foo.bar</TD><TD ALIGN=left NOWRAP>any</TD><TD ALIGN=left NOWRAP>foo.bar</TD></TR>
<TR><TD ALIGN=left NOWRAP>.foo</TD><TD ALIGN=left NOWRAP>mypack</TD><TD ALIGN=left NOWRAP>mypack.foo</TD></TR>
<TR><TD ALIGN=left NOWRAP> .foo.bar</TD><TD ALIGN=left NOWRAP>mypack</TD><TD ALIGN=left NOWRAP>mypack.foo.bar</TD></TR>
<TR><TD ALIGN=left NOWRAP> ..foo</TD><TD ALIGN=left NOWRAP>mypack.bar</TD><TD ALIGN=left NOWRAP>mypack.foo</TD></TR>
<TR><TD ALIGN=left NOWRAP> ..foo.baz</TD><TD ALIGN=left NOWRAP>mypack.bar</TD><TD ALIGN=left NOWRAP>mypack.foo.baz</TD></TR>
<TR><TD ALIGN=left NOWRAP> ...foo</TD><TD ALIGN=left NOWRAP>mypack.bar.baz</TD><TD ALIGN=left NOWRAP>mypack.foo</TD></TR>
<TR><TD ALIGN=left NOWRAP> .</TD><TD ALIGN=left NOWRAP>mypack.bar.baz</TD><TD ALIGN=left NOWRAP>mypack.bar.baz</TD></TR>
<TR><TD ALIGN=left NOWRAP> ..</TD><TD ALIGN=left NOWRAP>mypack.bar.baz</TD><TD ALIGN=left NOWRAP>mypack.bar</TD></TR>
<TR><TD ALIGN=left NOWRAP> ...</TD><TD ALIGN=left NOWRAP>mypack.bar.baz</TD><TD ALIGN=left NOWRAP>mypack</TD></TR>
</TABLE>
</DIV>
<DIV CLASS="caption"><TABLE CELLSPACING=6 CELLPADDING=0><TR><TD VALIGN=top ALIGN=left>Table 2.2: Examples of hierarchical packages</TD></TR>
</TABLE></DIV>
<A NAME="tbl:hierarchical-packages"></A>
<DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV></BLOCKQUOTE><P>Additional notes:</P><OL CLASS="enumerate" type=1><LI CLASS="li-enumerate">
All packages in the hierarchy must exist.</LI><LI CLASS="li-enumerate"><B>Warning about nicknames</B>: Unless you provide nicknames for
your hierarchical packages (and we recommend against doing so because
the number gets quite large), you can only use the names supplied. You
cannot mix in nicknames or alternate names. <TT class=code>cl-user</TT>
is nickname of the <TT class=code>common-lisp-user</TT> package.
Consider the following:<PRE CLASS="verbatim">   (defpackage :cl-user.foo)
</PRE><P>When the current package (the value of the variable </P><TT class=code>*package*</TT><P>)
is </P><TT class=code>common-lisp-user</TT><P>, you might expect <CODE>.foo</CODE> to refer to
<CODE>cl-user.foo</CODE>, but it does not. It actually refers to the non-existent
package <CODE>common-lisp-user.foo</CODE>. Note that the purpose of
nicknames is to provide shorter names in place of the longer names
that are designed to be fully descriptive. The hope is that
hierarchical packages makes longer names unnecessary and thus makes
nicknames unnecessary.</P></LI><LI CLASS="li-enumerate">Multiple dots can only appear at the beginning of a package name. For
example, <CODE>foo.bar..baz</CODE> does not mean <CODE>foo.baz</CODE> &#X2013; it is
invalid. (Of course, it is perfectly legal to name a package
<CODE>foo.bar..baz</CODE>, but <TT class=code>cl:find-package</TT> will not process such
a name to find <CODE>foo.baz</CODE> in the package hierarchy.)
</LI></OL><!--TOC subsection Compatibility with ANSI Common Lisp-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc18">2.4.3</A>&#XA0;&#XA0;Compatibility with ANSI Common Lisp</H3><!--SEC END --><P>The implementation of hierarchical packages modifies the
</P><TT class=code>cl:find-package</TT><P> function, and provides certain auxiliary
functions, </P><TT class=code>package-parent</TT><P>, </P><TT class=code>package-children</TT><P>, and
</P><TT class=code>relative-package-name-to-package</TT><P>, as described in this section.
The function </P><TT class=code>defpackage</TT><P> itself requires no modification.</P><P>While the changes to </P><TT class=code>cl:find-package</TT><P> are small and described
below, it is an important consideration for authors who would like
their programs to run on a variety of implementations that using
hierarchical packages will work in an implementation without the
modifications discussed in this document. We show why after
describing the changes to </P><TT class=code>cl:find-package</TT><P>.</P><P>Absolute hierarchical package names require no changes in the
underlying Common Lisp implementation.</P><!--TOC subsubsection Changes to <TT class=code>cl:find-package</TT>-->
<H4 CLASS="subsubsection"><!--SEC ANCHOR -->2.4.3.1&#XA0;&#XA0;Changes to <TT class=code>cl:find-package</TT></H4><!--SEC END --><P>Using relative hierarchical package names requires a simple
modification of </P><TT class=code>cl:find-package</TT><P>.</P><P>In ANSI Common Lisp, </P><TT class=code>cl:find-package</TT><P>, if passed a package object,
returns it; if passed a string, </P><TT class=code>cl:find-package</TT><P> looks for a
package with that string as its name or nickname, and returns the
package if it finds one, or returns nil if it does not; if passed a
symbol, the symbol name (a string) is extracted and
</P><TT class=code>cl:find-package</TT><P> proceeds as it does with a string.</P><P>For implementing hierarchical packages, the behavior when the argument
is a package object (return it) does not change. But when the argument
is a string starting with one or more dots not directly naming a
package, </P><TT class=code>cl:find-package</TT><P> will, instead of returning nil, check
whether the string can be resolved as naming a relative package, and
if so, return the associated absolute package object. (If the argument
is a symbol, the symbol name is extracted and </P><TT class=code>cl:find-package</TT><P>
proceeds as it does with a string argument.)</P><P>Note that you should not use leading dots in package names when using
hierarchical packages.</P><!--TOC subsubsection Using Hierarchical Packages without Modifying cl:find-package-->
<H4 CLASS="subsubsection"><!--SEC ANCHOR -->2.4.3.2&#XA0;&#XA0;Using Hierarchical Packages without Modifying cl:find-package</H4><!--SEC END --><P>Even without the modifications to </P><TT class=code>cl:find-package</TT><P>, authors need
not avoid using relative package names, but the ability to reuse
relative package names is restricted. Consider for example a module
<I>foo</I> which is composed of the <CODE>my.foo.bar</CODE> and
<CODE>my.foo.baz</CODE> packages. In the code for each of the these packages
there are relative package references, <CODE>..bar</CODE> and <CODE>..baz</CODE>.</P><P>Implementations that have the new </P><TT class=code>cl:find-package</TT><P> would have
<CODE>:relative-package-names</CODE> on their </P><TT class=code>*features*</TT><P>
list (this is the case of CMUCL releases starting from 18d). Then,
in the <I>foo</I> module, there would be definitions of the
<CODE>my.foo.bar</CODE> and <CODE>my.foo.baz</CODE> packages like so:</P><PRE CLASS="verbatim">   (defpackage :my.foo.bar
     #-relative-package-names (:nicknames #:..bar)
     ...)

   (defpackage :my.foo.baz
     #-relative-package-names (:nicknames #:..baz)
     ...)
</PRE><P>Then, in a <CODE>#-relative-package-names</CODE> implementation, the symbol
<CODE>my.foo.bar:blam</CODE> would be visible from <CODE>my.foo.baz</CODE> as
<CODE>..bar:blam</CODE>, just as it would from a
<CODE>#+relative-package-names</CODE> implementation.</P><P>So, even without the implementation of the augmented
</P><TT class=code>cl:find-package</TT><P>, one can still write Common Lisp code that will
work in both types of implementations, but <CODE>..bar</CODE> and
<CODE>..baz</CODE> are now used, so you cannot also have
<CODE>otherpack.foo.bar</CODE> and <CODE>otherpack.foo.baz</CODE> and use
<CODE>..bar</CODE> and <CODE>..baz</CODE> as relative names. (The point of
hierarchical packages, of course, is to allow reusing relative package
names.)</P><!--NAME hierarchical-packages.html-->
<!--TOC section Package Locks-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc19">2.5</A>&#XA0;&#XA0;Package Locks</H2><!--SEC END --><P>
<A NAME="@concept2"></A></P><P>CMUCL provides two types of package locks, as an extension to the
ANSI Common Lisp standard. The package-lock protects a package from
changes in its structure (the set of exported symbols, its use list,
etc). The package-definition-lock protects the symbols in the package
from being redefined due to the execution of a </P><TT class=code>defun</TT><P>,
</P><TT class=code>defmacro</TT><P>, </P><TT class=code>defstruct</TT><P>, </P><TT class=code>deftype</TT><P> or </P><TT class=code>defclass</TT><P>
form.</P><!--TOC subsection Rationale-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc20">2.5.1</A>&#XA0;&#XA0;Rationale</H3><!--SEC END --><P>Package locks are an aid to program development, by helping to detect
inadvertent name collisions and function redefinitions. They are
consistent with the principle that a package &#X201C;belongs to&#X201D; its
implementor, and that noone other than the package&#X2019;s developer should
be making or modifying definitions on symbols in that package. Package
locks are compatible with the ANSI Common Lisp standard, which states
that the consequences of redefining functions in the
</P><TT class=code>COMMON-LISP</TT><P> package are undefined.</P><P>Violation of a package lock leads to a continuable error of type
</P><TT class=code>lisp::package-locked-error</TT><P> being signaled. The user may choose
to ignore the lock and proceed, or to abort the computation. Two other
restarts are available, one which disables all locks on all packages,
and one to disable only the package-lock or package-definition-lock
that was tripped.</P><P>The following transcript illustrates the behaviour seen when
attempting to redefine a standard macro in the </P><TT class=code>COMMON-LISP</TT><P>
package, or to redefine a function in one of CMUCL&#X2019;s
implementation-defined packages:</P><PRE CLASS="verbatim">CL-USER&gt; (defmacro 1+ (x) (* x 2))
Attempt to modify the locked package COMMON-LISP, by defining macro 1+
   [Condition of type LISP::PACKAGE-LOCKED-ERROR]

Restarts:
  0: [continue      ] Ignore the lock and continue
  1: [unlock-package] Disable the package's definition-lock then continue
  2: [unlock-all    ] Unlock all packages, then continue
  3: [abort         ] Return to Top-Level.

CL-USER&gt; (defun ext:gc () t)
Attempt to modify the locked package EXTENSIONS, by redefining function GC
   [Condition of type LISP::PACKAGE-LOCKED-ERROR]

Restarts:
  0: [continue      ] Ignore the lock and continue
  1: [unlock-package] Disable package's definition-lock, then continue
  2: [unlock-all    ] Disable all package locks, then continue
  3: [abort         ] Return to Top-Level.
</PRE><P>The following transcript illustrates the behaviour seen when an
attempt to modify the structure of a package is made:</P><PRE CLASS="verbatim">CL-USER&gt; (unexport 'load-foreign :ext)
Attempt to modify the locked package EXTENSIONS, by unexporting symbols LOAD-FOREIGN
   [Condition of type lisp::package-locked-error]

Restarts:
  0: [continue      ] Ignore the lock and continue
  1: [unlock-package] Disable package's lock then continue
  2: [unlock-all    ] Unlock all packages, then continue
  3: [abort         ] Return to Top-Level.
</PRE><P>The </P><TT class=code>COMMON-LISP</TT><P> package and the CMUCL-specific
implementation packages are locked on startup. Users can lock their
own packages by using the </P><TT class=code>ext:package-lock</TT><P> and
</P><TT class=code>ext:package-definition-lock</TT><P> accessors.</P><!--TOC subsection Disabling package locks-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc21">2.5.2</A>&#XA0;&#XA0;Disabling package locks</H3><!--SEC END --><P>A package&#X2019;s locks can be enabled or disabled by using the
</P><TT class=code>ext:package-lock</TT><P> and </P><TT class=code>ext:package-definition-lock</TT><P>
accessors, as follows:</P><BLOCKQUOTE CLASS=lisp> <PRE>
   (setf (ext:package-lock (find-package "UNIX")) nil)
   (setf (ext:package-definition-lock (find-package "UNIX")) nil)
</PRE></BLOCKQUOTE><P><BR>
<A NAME="@funs19"></A><A NAME="FN:package-lock"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>ext:</TT><TT class=function-name>package-lock</TT> <TT class=variable>package</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
This function is an accessor for a package&#X2019;s structural lock, which
protects it against modifications to its list of exported symbols.
</BLOCKQUOTE><P><BR>
<A NAME="@funs20"></A><A NAME="FN:package-definition-lock"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>ext:</TT><TT class=function-name>package-definition-lock</TT> <TT class=variable>package</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
This function is an accessor for a package&#X2019;s definition-lock, which
protects symbols in that package from redefinition. As well as
protecting the symbol&#X2019;s fdefinition from change, attempts to change
the symbol&#X2019;s definition using <TT class=code>defstruct</TT>, <TT class=code>defclass</TT> or
<TT class=code>deftype</TT> will be trapped.
</BLOCKQUOTE><P><BR>
<A NAME="@funs21"></A><A NAME="FN:without-package-locks"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>ext:</TT><TT class=function-name>without-package-locks</TT> <TT class=code>&amp;rest</TT> <TT class=variable>body</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
This macro can be used to execute forms with all package locks (both
structure and definition locks) disabled. 
</BLOCKQUOTE><P><BR>
<A NAME="@funs22"></A><A NAME="FN:unlock-all-packages"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>ext:</TT><TT class=function-name>unlock-all-packages</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
This function disables both structure and definition locks on all
currently defined packages. Note that package locks are reset when
CMUCL is restarted, so the effect of this function is limited to
the current session. 
</BLOCKQUOTE><!--NAME package-locks.html-->
<!--TOC section The Editor-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc22">2.6</A>&#XA0;&#XA0;The Editor</H2><!--SEC END --><P>The </P><TT class=code>ed</TT><P> function invokes the Hemlock editor which is described
in <I>Hemlock User&#X2019;s Manual</I> and <I>Hemlock Command Implementor&#X2019;s
Manual</I>. Most users at CMU prefer to use Hemlock&#X2019;s slave Common Lisp
mechanism which provides an interactive buffer for the
</P><TT class=code>read-eval-print</TT><P> loop and editor commands for evaluating and
compiling text from a buffer into the slave Common Lisp. Since the editor
runs in the Common Lisp, using slaves keeps users from trashing their
editor by developing in the same Common Lisp with Hemlock.</P><!--TOC section Garbage Collection-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc23">2.7</A>&#XA0;&#XA0;Garbage Collection</H2><!--SEC END --><P>CMUCL uses either a stop-and-copy garbage collector or a
generational, mostly copying garbage collector. Which collector is
available depends on the platform and the features of the platform.
The stop-and-copy GC is available on all RISC platforms. The x86
platform supports a conservative stop-and-copy collector, which is now
rarely used, and a generational conservative collector. On the Sparc
platform, both the stop-and-copy GC and the generational GC are
available, but the stop-and-copy GC is deprecated in favor of the
generational GC. </P><P>The generational GC is available if </P><TT class=variable>*features*</TT><P> contains
</P><TT class=code>:gencgc</TT><P>.</P><P>The following functions invoke the garbage collector or control whether
automatic garbage collection is in effect:</P><P><BR>
<A NAME="@funs23"></A><A NAME="FN:-"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>[</TT><TT class=function-name>-</TT> c &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">heney]extensions:gc<TT class=code>&amp;optional</TT> <TT class=variable>verbose-p</TT><P>This function runs the garbage collector. If
</P><TT class=code>ext:*gc-verbose*</TT><P> is non-</P><TT class=code>nil</TT><P>, then it invokes
</P><TT class=code>ext:*gc-notify-before*</TT><P> before GC&#X2019;ing and
</P><TT class=code>ext:*gc-notify-after*</TT><P> afterwards.</P><TT class=code>verbose-p</TT><P> indicates whether GC statistics are printed or
not. </P></BLOCKQUOTE><P><BR>
<A NAME="@funs24"></A><A NAME="FN:gc-off"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>gc-off</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function inhibits automatic garbage collection. After calling
it, the system will not GC unless you call </P><TT class=code>ext:gc</TT><P> or
</P><TT class=code>ext:gc-on</TT><P>.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs25"></A><A NAME="FN:gc-on"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>gc-on</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function reinstates automatic garbage collection. If the
system would have GC&#X2019;ed while automatic GC was inhibited, then this
will call </P><TT class=code>ext:gc</TT><P>.
</P></BLOCKQUOTE><!--TOC subsection GC Parameters-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc24">2.7.1</A>&#XA0;&#XA0;GC Parameters</H3><!--SEC END --><P>The following variables control the behavior of the garbage collector:</P><P><BR>
<A NAME="@vars2"></A><A NAME="VR:bytes-consed-between-gcs"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>*bytes-consed-between-gcs*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>CMUCL automatically GC&#X2019;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 </P><TT class=code>ext:*bytes-consed-between-gcs*</TT><P>. The default
value is 2000000.
</P></BLOCKQUOTE><P><BR>
<A NAME="@vars3"></A><A NAME="VR:gc-verbose"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>*gc-verbose*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This variable controls whether </P><TT class=code>ext:gc</TT><P> invokes the functions
in </P><TT class=code>ext:*gc-notify-before*</TT><P> and
</P><TT class=code>ext:*gc-notify-after*</TT><P>. If </P><TT class=code>*gc-verbose*</TT><P> is </P><TT class=code>nil</TT><P>,
</P><TT class=code>ext:gc</TT><P> foregoes printing any messages. The default value is
</P><TT class=code>T</TT><P>.
</P></BLOCKQUOTE><P><BR>
<A NAME="@vars4"></A><A NAME="VR:gc-notify-before"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>*gc-notify-before*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This variable&#X2019;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:
</P><PRE CLASS="verbatim">   [GC threshold exceeded with 2,107,124 bytes in use.  Commencing GC.]
</PRE></BLOCKQUOTE><P><BR>
<A NAME="@vars5"></A><A NAME="VR:gc-notify-after"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>*gc-notify-after*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This variable&#X2019;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:
</P><PRE CLASS="verbatim">    [GC completed with 25,680 bytes retained and 2,096,808 bytes freed.]
    [GC will next occur when at least 2,025,680 bytes are in use.]
  </PRE></BLOCKQUOTE><P>Note that a garbage collection will not happen at exactly the new
threshold printed by the default </P><TT class=code>ext:*gc-notify-after*</TT><P>
function. The system periodically checks whether this threshold has
been exceeded, and only then does a garbage collection.</P><P><BR>
<A NAME="@vars6"></A><A NAME="VR:gc-inhibit-hook"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>*gc-inhibit-hook*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This variable&#X2019;s value is either a function of one argument or </P><TT class=code>nil</TT><P>.
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 </P><TT class=code>nil</TT><P>, then the GC occurs; otherwise, the system inhibits
automatic GC as if you had called </P><TT class=code>ext:gc-off</TT><P>. 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
</P><TT class=code>ext:gc-on</TT><P>. The default value of this variable is </P><TT class=code>nil</TT><P>.
</P></BLOCKQUOTE><P><BR>
<A NAME="@vars7"></A><A NAME="VR:before-gc-hooks"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>*before-gc-hooks*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
<P><A NAME="@vars8"></A><A NAME="VR:after-gc-hooks"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>*after-gc-hooks*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><P>These variables&#X2019; 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.
</P></BLOCKQUOTE><!--TOC subsection Generational GC-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc25">2.7.2</A>&#XA0;&#XA0;Generational GC</H3><!--SEC END --><P>
Generational GC also supports some additional functions and variables
to control it.</P><P><BR>
<A NAME="@funs26"></A><A NAME="FN:-"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>[</TT><TT class=function-name>-</TT> g &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">encgc]extensions:gc<TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=code>:verbose</TT> <TT class=code>:gen</TT> <TT class=code>:full</TT></SPAN><P>This function runs the garbage collector. If
</P><TT class=code>ext:*gc-verbose*</TT><P> is non-</P><TT class=code>nil</TT><P>, then it invokes
</P><TT class=code>ext:*gc-notify-before*</TT><P> before GC&#X2019;ing and
</P><TT class=code>ext:*gc-notify-after*</TT><P> afterwards.</P><DL CLASS="list"><DT CLASS="dt-list">

<TT class=code>verbose</TT><BR>
</DT><DD CLASS="dd-list"> Print GC statistics if non-<TT class=code>NIL</TT>.
</DD><DT CLASS="dt-list"><TT class=code>gen</TT><BR>
</DT><DD CLASS="dd-list"> The number of generations to be collected.
</DD><DT CLASS="dt-list"><TT class=code>full</TT><BR>
</DT><DD CLASS="dd-list"> If non-<TT class=code>NIL</TT>, a full collection of all
generations is performed.
</DD></DL></BLOCKQUOTE><P><BR>
<A NAME="@funs27"></A><A NAME="FN:gencgc-stats"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>lisp::</TT><TT class=function-name>gencgc-stats</TT> <TT class=variable>generation</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Returns statistics about the generation, as multiple values:
<OL CLASS="enumerate" type=1><LI CLASS="li-enumerate">
Bytes allocated in this generation
</LI><LI CLASS="li-enumerate">The GC trigger for this generation. When this many bytes have
been allocated, a GC is started automatically.
</LI><LI CLASS="li-enumerate">The number of bytes consed between GCs.
</LI><LI CLASS="li-enumerate">The number of GCs that have been done on this generation.
This is reset to zero when the generation is raised.
</LI><LI CLASS="li-enumerate">The trigger age, which is the maximum number of GCs to perform
before this generation is raised.
</LI><LI CLASS="li-enumerate">The total number of bytes allocated to this generation.
</LI><LI CLASS="li-enumerate">Average age of the objects in this generations. The average
age is the cumulative bytes allocated divided by current number of
bytes allocated.
</LI></OL>
</BLOCKQUOTE><P><BR>
<A NAME="@funs28"></A><A NAME="FN:set-gc-trigger"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>lisp::</TT><TT class=function-name>set-gc-trigger</TT> <TT class=variable>gen</TT> <TT class=variable>trigger</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Sets the GC trigger value for the specified generation.
</BLOCKQUOTE><P><BR>
<A NAME="@funs29"></A><A NAME="FN:set-trigger-age"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>lisp::</TT><TT class=function-name>set-trigger-age</TT> <TT class=variable>gen</TT> <TT class=variable>trigger-age</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Sets the GC trigger age for the specified generation.
</BLOCKQUOTE><P><BR>
<A NAME="@funs30"></A><A NAME="FN:set-min-mem-age"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>lisp::</TT><TT class=function-name>set-min-mem-age</TT> <TT class=variable>gen</TT> <TT class=variable>min-mem-age</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Sets the minimum average memory age for the specified generation.
If the computed memory age is below this, GC is not performed, which
helps prevent a GC when a large number of new live objects have been
added in which case a GC would usually be a waste of time.
</BLOCKQUOTE><!--TOC subsection Weak Pointers-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc26">2.7.3</A>&#XA0;&#XA0;Weak Pointers</H3><!--SEC END --><P>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.</P><P><BR>
<A NAME="@funs31"></A><A NAME="FN:make-weak-pointer"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>make-weak-pointer</TT> <TT class=variable>object</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
<P><A NAME="@funs32"></A><A NAME="FN:weak-pointer-value"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>weak-pointer-value</TT> <TT class=variable>weak-pointer</TT> &nbsp;&nbsp;&nbsp;
</DIV><TT class=code>make-weak-pointer</TT><P> returns a weak pointer to an object.
</P><TT class=code>weak-pointer-value</TT><P> follows a weak pointer, returning the two
values: the object pointed to (or </P><TT class=code>nil</TT><P> if broken) and a boolean
value which is </P><TT class=code>nil</TT><P> if the pointer has been broken, and true
otherwise.
</P></BLOCKQUOTE><!--TOC subsection Finalization-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc27">2.7.4</A>&#XA0;&#XA0;Finalization</H3><!--SEC END --><P>Finalization provides a &#X201C;hook&#X201D; 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.</P><P><BR>
<A NAME="@funs33"></A><A NAME="FN:finalize"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>finalize</TT> <TT class=variable>object</TT> <TT class=variable>function</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function registers </P><TT class=variable>object</TT><P> for finalization.
</P><TT class=variable>function</TT><P> is called with no arguments when </P><TT class=variable>object</TT><P> is
reclaimed. Normally </P><TT class=variable>function</TT><P> 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 </P><TT class=variable>function</TT><P> must not
close over </P><TT class=variable>object</TT><P> itself, as this prevents the object from
ever becoming garbage.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs34"></A><A NAME="FN:cancel-finalization"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>cancel-finalization</TT> <TT class=variable>object</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function cancel any finalization request for </P><TT class=variable>object</TT><P>.
</P></BLOCKQUOTE><!--TOC section Describe-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc28">2.8</A>&#XA0;&#XA0;Describe</H2><!--SEC END --><P><BR>
<A NAME="@funs35"></A><A NAME="FN:describe"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>describe</TT>  <TT class=variable>object</TT> &amp;optional <TT class=variable>stream</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>The </P><TT class=code>describe</TT><P> function prints useful information about
</P><TT class=variable>object</TT><P> on </P><TT class=variable>stream</TT><P>, which defaults to
</P><TT class=code>*standard-output*</TT><P>. For any object, </P><TT class=code>describe</TT><P> will
print out the type. Then it prints other information based on the
type of </P><TT class=variable>object</TT><P>. The types which are presently handled are:</P><DL CLASS="list"><DT CLASS="dt-list">
<A NAME="@types12"></A><TT class=code>hash-table</TT><BR>
</DT><DD CLASS="dd-list"> <TT class=code>describe</TT> prints the number of
entries currently in the hash table and the number of buckets
currently allocated.</DD><DT CLASS="dt-list"><A NAME="@types13"></A><TT class=code>function</TT><BR>
</DT><DD CLASS="dd-list"> <TT class=code>describe</TT> prints a list of the
function&#X2019;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.</DD><DT CLASS="dt-list"><A NAME="@types14"></A><TT class=code>fixnum</TT><BR>
</DT><DD CLASS="dd-list"> <TT class=code>describe</TT> prints whether the integer
is prime or not.</DD><DT CLASS="dt-list"><A NAME="@types15"></A><TT class=code>symbol</TT><BR>
</DT><DD CLASS="dd-list"> The symbol&#X2019;s value, properties, and
documentation are printed. If the symbol has a function
definition, then the function is described.
</DD></DL><P>
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.
</P></BLOCKQUOTE><P>A number of switches can be used to control </P><TT class=code>describe</TT><P>&#X2019;s behavior.</P><P><BR>
<A NAME="@vars9"></A><A NAME="VR:describe-level"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>*describe-level*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>The maximum level of recursive description allowed. Initially two.
</P></BLOCKQUOTE><P><BR>
<A NAME="@vars10"></A><A NAME="VR:describe-indentation"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>*describe-indentation*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>The number of spaces to indent for each level of recursive
description, initially three.
</P></BLOCKQUOTE><P><BR>
<A NAME="@vars11"></A><A NAME="VR:describe-print-level"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>*describe-print-level*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
<P><A NAME="@vars12"></A><A NAME="VR:describe-print-length"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>*describe-print-length*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><P>The values of </P><TT class=code>*print-level*</TT><P> and </P><TT class=code>*print-length*</TT><P> during
description. Initially two and five.
</P></BLOCKQUOTE><!--TOC section The Inspector-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc29">2.9</A>&#XA0;&#XA0;The Inspector</H2><!--SEC END --><P>CMUCL has both a graphical inspector that uses the X Window System,
and a simple terminal-based inspector.</P><P><BR>
<A NAME="@funs36"></A><A NAME="FN:inspect"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>inspect</TT>  <TT class=code>&amp;optional</TT> <TT class=variable>object</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><TT class=code>inspect</TT><P> calls the inspector on the optional argument
</P><TT class=variable>object</TT><P>. If </P><TT class=variable>object</TT><P> is unsupplied, </P><TT class=code>inspect</TT><P>
immediately returns </P><TT class=code>nil</TT><P>. Otherwise, the behavior of inspect
depends on whether Lisp is running under X. When </P><TT class=code>inspect</TT><P> is
eventually exited, it returns some selected Lisp object.
</P></BLOCKQUOTE><!--TOC subsection The Graphical Interface-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc30">2.9.1</A>&#XA0;&#XA0;The Graphical Interface</H3><!--SEC END --><P>
<A NAME="motif-interface"></A></P><P>CMUCL has an interface to Motif which is functionally similar to
CLM, but works better in CMUCL. This interface is documented in
separate manuals <I>CMUCL Motif Toolkit</I> and <I>Design Notes
on the Motif Toolkit</I>, which are distributed with CMUCL.</P><P>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 </P><TT class=code>interface</TT><P> and </P><TT class=code>toolkit</TT><P> packages.</P><P><BR>
<A NAME="@funs37"></A><A NAME="FN:lisp-control-panel"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>interface:</TT><TT class=function-name>lisp-control-panel</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function creates a control panel for the Lisp process.
</P></BLOCKQUOTE><P><BR>
<A NAME="@vars13"></A><A NAME="VR:interface-style"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>interface:</TT><TT class=function-name>*interface-style*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>When the graphical interface is loaded, this variable controls
whether it is used by </P><TT class=code>inspect</TT><P> and the error system. If the
value is </P><TT class=code>:graphics</TT><P> (the default) and the </P><TT class=code>DISPLAY</TT><P>
environment variable is defined, the graphical inspector and
debugger will be invoked by <A NAME="@funs38"></A></P><TT class=code>inspect</TT><P> or when an error is
signalled. Possible values are </P><TT class=code>:graphics</TT><P> and tty. If the
value is </P><TT class=code>:graphics</TT><P>, but there is no X display, then we quietly
use the TTY interface.
</P></BLOCKQUOTE><!--TOC subsection The TTY Inspector-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc31">2.9.2</A>&#XA0;&#XA0;The TTY Inspector</H3><!--SEC END --><P>If X is unavailable, a terminal inspector is invoked. The TTY inspector
is a crude interface to </P><TT class=code>describe</TT><P> 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
</P><TT class=code>read</TT><P>&#X2013;</P><TT class=code>eval</TT><P>&#X2013;</P><TT class=code>print</TT><P> loop, but an integer </P><TT class=variable>n</TT><P>
descends into the </P><TT class=variable>n</TT><P>&#X2019;th component of the current object, and
symbols with these special names are interpreted as commands:</P><DL CLASS="list"><DT CLASS="dt-list">

U<BR>
</DT><DD CLASS="dd-list"> 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.</DD><DT CLASS="dt-list">Q, E<BR>
</DT><DD CLASS="dd-list"> Return the current object from <TT class=code>inspect</TT>.</DD><DT CLASS="dt-list">R<BR>
</DT><DD CLASS="dd-list"> Recompute object display, and print again. Useful if the
object may have changed.</DD><DT CLASS="dt-list">D<BR>
</DT><DD CLASS="dd-list"> Display again without recomputing.</DD><DT CLASS="dt-list">H, ?<BR>
</DT><DD CLASS="dd-list"> Show help message.
</DD></DL><!--TOC section Load-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc32">2.10</A>&#XA0;&#XA0;Load</H2><!--SEC END --><P><BR>
<A NAME="@funs39"></A><A NAME="FN:load"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>load</TT> <TT class=variable>filename</TT>
<TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=code>:verbose</TT> <TT class=code>:print</TT> <TT class=code>:if-does-not-exist</TT></SPAN><BR>
 <TT class=code>:if-source-newer</TT> <TT class=code>:contents</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>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 </P><TT class=code>load</TT><P> to conveniently support a variety of
program file organizations. </P><TT class=variable>filename</TT><P> may be a wildcard
pathname such as </P><TT class=filename>*.lisp</TT><P>, in which case all matching files are
loaded.</P><P>If </P><TT class=variable>filename</TT><P> has a </P><TT class=code>pathname-type</TT><P> (or extension), then
that exact file is loaded. If the file has no extension, then this
tells </P><TT class=code>load</TT><P> to use a heuristic to load the &#X201C;right&#X201D; file.
The </P><TT class=code>*load-source-types*</TT><P> and </P><TT class=code>*load-object-types*</TT><P>
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
</P><TT class=variable>if-source-newer</TT><P> 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:

</P><DL CLASS="list"><DT CLASS="dt-list">

<TT class=code>:load-object</TT><BR>
</DT><DD CLASS="dd-list"> The object file is loaded even though the
source file is newer.</DD><DT CLASS="dt-list"><TT class=code>:load-source</TT><BR>
</DT><DD CLASS="dd-list"> The source file is loaded instead of the
older object file.</DD><DT CLASS="dt-list"><TT class=code>:compile</TT><BR>
</DT><DD CLASS="dd-list"> The source file is compiled and then the new
object file is loaded.</DD><DT CLASS="dt-list"><TT class=code>:query</TT><BR>
</DT><DD CLASS="dd-list"> The user is asked a yes or no question to
determine whether the source or object file is loaded.
</DD></DL><P>
This argument defaults to the value of
</P><TT class=code>ext:*load-if-source-newer*</TT><P> (initially </P><TT class=code>:load-object</TT><P>.)</P><P>The </P><TT class=variable>contents</TT><P> 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 </P><TT class=code>:source</TT><P> or </P><TT class=code>:binary</TT><P>, which forces
loading in source and binary mode, respectively. You really
shouldn&#X2019;t ever need to use this argument.
</P></BLOCKQUOTE><P><BR>
<A NAME="@vars14"></A><A NAME="VR:load-source-types"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>*load-source-types*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
<P><A NAME="@vars15"></A><A NAME="VR:load-object-types"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>*load-object-types*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><P>These variables are lists of possible </P><TT class=code>pathname-type</TT><P> values
for source and object files to be passed to </P><TT class=code>load</TT><P>. These
variables are only used when the file passed to </P><TT class=code>load</TT><P> 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.
</P></BLOCKQUOTE><P><BR>
<A NAME="@vars16"></A><A NAME="VR:load-if-source-newer"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>*load-if-source-newer*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This variable determines the default value of the
</P><TT class=variable>if-source-newer</TT><P> argument to </P><TT class=code>load</TT><P>. Its initial value is
</P><TT class=code>:load-object</TT><P>.
</P></BLOCKQUOTE><!--TOC section The Reader-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc33">2.11</A>&#XA0;&#XA0;The Reader</H2><!--SEC END --><!--TOC subsection Reader Extensions-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc34">2.11.1</A>&#XA0;&#XA0;Reader Extensions</H3><!--SEC END --><P>
CMUCL supports an ANSI-compatible extension to enable reading of
specialized arrays. Thus
</P><BLOCKQUOTE class=example><PRE>
  * (setf *print-readably* nil)
  NIL
  * (make-array &#X2019;(2 2) :element-type &#X2019;(signed-byte 8))
  #2A((0 0) (0 0))
  * (setf *print-readably* t)
  T
  * (make-array &#X2019;(2 2) :element-type &#X2019;(signed-byte 8))
  #A((SIGNED-BYTE 8) (2 2) ((0 0) (0 0)))
  * (type-of (read-from-string "#A((SIGNED-BYTE 8) (2 2) ((0 0) (0 0)))"))
  (SIMPLE-ARRAY (SIGNED-BYTE 8) (2 2))
  * (setf *print-readably* nil)
  NIL
  * (type-of (read-from-string "#A((SIGNED-BYTE 8) (2 2) ((0 0) (0 0)))"))
  (SIMPLE-ARRAY (SIGNED-BYTE 8) (2 2))
</PRE></BLOCKQUOTE><!--TOC subsection Reader Parameters-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc35">2.11.2</A>&#XA0;&#XA0;Reader Parameters</H3><!--SEC END --><P><BR>
<A NAME="@vars17"></A><A NAME="VR:ignore-extra-close-parentheses"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>*ignore-extra-close-parentheses*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>If this variable is </P><TT class=code>t</TT><P> (the default), then the reader merely
prints a warning when an extra close parenthesis is detected
(instead of signalling an error.)
</P></BLOCKQUOTE><!--TOC section Stream Extensions-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc36">2.12</A>&#XA0;&#XA0;Stream Extensions</H2><!--SEC END --><P><BR>
<A NAME="@funs40"></A><A NAME="FN:read-n-bytes"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>sys:</TT><TT class=function-name>read-n-bytes</TT> <TT class=variable>stream buffer start numbytes</TT> 
<TT class=code>&amp;optional</TT> <TT class=variable>eof-error-p</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>On streams that support it, this function reads multiple bytes of
data into a buffer. The buffer must be a </P><TT class=code>simple-string</TT><P> or
</P><TT class=code>(simple-array (unsigned-byte 8) (*))</TT><P>. The argument
</P><TT class=variable>nbytes</TT><P> specifies the desired number of bytes, and the return
value is the number of bytes actually read.
</P><UL CLASS="itemize"><LI CLASS="li-itemize">
If <TT class=variable>eof-error-p</TT> is true, an <A NAME="@types16"></A><TT class=code>end-of-file</TT>
condition is signalled if end-of-file is encountered before
<TT class=variable>count</TT> bytes have been read.</LI><LI CLASS="li-itemize">If <TT class=variable>eof-error-p</TT> is false, <TT class=code>read-n-bytes reads</TT> 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 <TT class=variable>count</TT> and
eof has not been hit. See also <A NAME="@funs41"></A><TT class=code>make-fd-stream</TT>.
</LI></UL></BLOCKQUOTE><!--TOC section Simple Streams-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc37">2.13</A>&#XA0;&#XA0;Simple Streams</H2><!--SEC END --><P>
<A NAME="@concept3"></A>
<A NAME="simple-streams"></A></P><P>CMUCL includes a partial implementation of <EM>Simple Streams</EM>, a
protocol that allows user-extensible streams<SUP><A NAME="text1" HREF="#note1">1</A></SUP>. The protocol was proposed
by Franz, Inc. and is intended to replace the <EM>Gray Streams</EM>
method of extending streams. Simple streams are distributed as a
CMUCL subsystem, that can be loaded into the image by saying</P><BLOCKQUOTE CLASS=lisp> <PRE>
   (require :simple-streams)
</PRE></BLOCKQUOTE><P>Note that CMUCL&#X2019;s implementation of simple streams is incomplete, and
in particular is currently missing support for the functions
</P><TT class=code>read-sequence</TT><P> and </P><TT class=code>write-sequence</TT><P>. Please consult the
<I>Allegro Common Lisp</I> documentation for more information on
simple streams.</P><!--NAME simple-streams.html-->
<!--TOC section Running Programs from Lisp-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc38">2.14</A>&#XA0;&#XA0;Running Programs from Lisp</H2><!--SEC END --><P>It is possible to run programs from Lisp by using the following function.</P><P><BR>
<A NAME="@funs42"></A><A NAME="FN:run-program"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>run-program</TT> <TT class=variable>program</TT> <TT class=variable>args</TT>
<TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=code>:env</TT> <TT class=code>:wait</TT> <TT class=code>:pty</TT> <TT class=code>:input</TT></SPAN><BR>
 <TT class=code>:if-input-does-not-exist</TT><BR>
 <TT class=code>:output</TT> <TT class=code>:if-output-exists</TT><BR>
 <TT class=code>:error</TT> <TT class=code>:if-error-exists</TT><BR>
 <TT class=code>:status-hook</TT> <TT class=code>:before-execve</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><TT class=code>run-program</TT><P> runs </P><TT class=variable>program</TT><P> in a child process.
</P><TT class=variable>Program</TT><P> should be a pathname or string naming the program.
</P><TT class=variable>Args</TT><P> should be a list of strings which this passes to
</P><TT class=variable>program</TT><P> as normal Unix parameters. For no arguments, specify
</P><TT class=variable>args</TT><P> as </P><TT class=code>nil</TT><P>. The value returned is either a process
structure or </P><TT class=code>nil</TT><P>. The process interface follows the description of
</P><TT class=code>run-program</TT><P>. If </P><TT class=code>run-program</TT><P> fails to fork the child
process, it returns </P><TT class=code>nil</TT><P>.</P><P>Except for sharing file descriptors as explained in keyword argument
descriptions, </P><TT class=code>run-program</TT><P> closes all file descriptors in the
child process before running the program. When you are done using a
process, call </P><TT class=code>process-close</TT><P> to reclaim system resources. You
only need to do this when you supply </P><TT class=code>:stream</TT><P> for one of
</P><TT class=code>:input</TT><P>, </P><TT class=code>:output</TT><P>, or </P><TT class=code>:error</TT><P>, or you supply </P><TT class=code>:pty</TT><P>
non-</P><TT class=code>nil</TT><P>. You can call </P><TT class=code>process-close</TT><P> regardless of whether
you must to reclaim resources without penalty if you feel safer.</P><TT class=code>run-program</TT><P> accepts the following keyword arguments:</P><DL CLASS="list"><DT CLASS="dt-list">
 
<TT class=code>:env</TT><BR>
</DT><DD CLASS="dd-list"> This is an a-list mapping keywords and
simple-strings. The default is <TT class=code>ext:*environment-list*</TT>. If
<TT class=code>:env</TT> is specified, <TT class=code>run-program</TT> uses the value given
and does not combine the environment passed to Lisp with the one
specified.</DD><DT CLASS="dt-list"><TT class=code>:wait</TT><BR>
</DT><DD CLASS="dd-list"> If non-<TT class=code>nil</TT> (the default), wait until the child
process terminates. If <TT class=code>nil</TT>, continue running Lisp while the
child process runs.</DD><DT CLASS="dt-list"><TT class=code>:pty</TT><BR>
</DT><DD CLASS="dd-list"> This should be one of <TT class=code>t</TT>, <TT class=code>nil</TT>, or a stream. If
specified non-<TT class=code>nil</TT>, the subprocess executes under a Unix PTY.
If specified as a stream, the system collects all output to this
pty and writes it to this stream. If specified as <TT class=code>t</TT>, the
<TT class=code>process-pty</TT> slot contains a stream from which you can read
the program&#X2019;s output and to which you can write input for the
program. The default is <TT class=code>nil</TT>.</DD><DT CLASS="dt-list"><TT class=code>:input</TT><BR>
</DT><DD CLASS="dd-list"> 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. <TT class=code>run-program</TT> opens the file as
standard input. If specified as <TT class=code>nil</TT> (the default), then
standard input is the file <TT class=filename>/dev/null</TT>. If specified as
<TT class=code>t</TT>, the program uses the current standard input. This may
cause some confusion if <TT class=code>:wait</TT> is <TT class=code>nil</TT> since two processes
may use the terminal at the same time. If specified as
<TT class=code>:stream</TT>, then the <TT class=code>process-input</TT> slot contains an
output stream. Anything written to this stream goes to the
program as input. <TT class=code>:input</TT> may also be an input stream that
already contains all the input for the process. In this case
<TT class=code>run-program</TT> reads all the input from this stream before
returning, so this cannot be used to interact with the process.</DD><DT CLASS="dt-list"><TT class=code>:if-input-does-not-exist</TT><BR>
</DT><DD CLASS="dd-list"> This specifies what to do if
the input file does not exist. The following values are valid:
<TT class=code>nil</TT> (the default) causes <TT class=code>run-program</TT> to return <TT class=code>nil</TT>
without doing anything; <TT class=code>:create</TT> creates the named file; and
<TT class=code>:error</TT> signals an error.</DD><DT CLASS="dt-list"><TT class=code>:output</TT><BR>
</DT><DD CLASS="dd-list"> This specifies what happens with the program&#X2019;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 <TT class=code>nil</TT> (the default), all output goes to
<TT class=filename>/dev/null</TT>. If specified as <TT class=code>t</TT>, the program writes to
the Lisp process&#X2019;s standard output. This may cause confusion if
<TT class=code>:wait</TT> is <TT class=code>nil</TT> since two processes may write to the terminal
at the same time. If specified as <TT class=code>:stream</TT>, then the
<TT class=code>process-output</TT> slot contains an input stream from which you
can read the program&#X2019;s output. <TT class=code>:output</TT> can also be a stream
in which case all output from the process is written to this
stream. </DD><DT CLASS="dt-list"><TT class=code>:if-output-exists</TT><BR>
</DT><DD CLASS="dd-list"> This specifies what to do if the
output file already exists. The following values are valid:
<TT class=code>nil</TT> causes <TT class=code>run-program</TT> to return <TT class=code>nil</TT> without doing
anything; <TT class=code>:error</TT> (the default) signals an error;
<TT class=code>:supersede</TT> overwrites the current file; and <TT class=code>:append</TT>
appends all output to the file.</DD><DT CLASS="dt-list"><TT class=code>:error</TT><BR>
</DT><DD CLASS="dd-list"> This is similar to <TT class=code>:output</TT>, except the file
becomes the program&#X2019;s standard error. Additionally, <TT class=code>:error</TT>
can be <TT class=code>:output</TT> in which case the program&#X2019;s error output is
routed to the same place specified for <TT class=code>:output</TT>. If specified
as <TT class=code>:stream</TT>, the <TT class=code>process-error</TT> contains a stream
similar to the <TT class=code>process-output</TT> slot when specifying the
<TT class=code>:output</TT> argument.</DD><DT CLASS="dt-list"><TT class=code>:if-error-exists</TT><BR>
</DT><DD CLASS="dd-list"> This specifies what to do if the error
output file already exists. It accepts the same values as
<TT class=code>:if-output-exists</TT>.</DD><DT CLASS="dt-list"><TT class=code>:status-hook</TT><BR>
</DT><DD CLASS="dd-list"> This specifies a function to call whenever
the process changes status. This is especially useful when
specifying <TT class=code>:wait</TT> as <TT class=code>nil</TT>. The function takes the process as
a required argument.</DD></DL></BLOCKQUOTE><!--TOC subsection Process Accessors-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc39">2.14.1</A>&#XA0;&#XA0;Process Accessors</H3><!--SEC END --><P>The following functions interface the process returned by </P><TT class=code>run-program</TT><P>:</P><P><BR>
<A NAME="@funs43"></A><A NAME="FN:process-p"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>process-p</TT> <TT class=variable>thing</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns </P><TT class=code>t</TT><P> if </P><TT class=variable>thing</TT><P> is a process.
Otherwise it returns </P><TT class=code>nil</TT></BLOCKQUOTE><P><BR>
<A NAME="@funs44"></A><A NAME="FN:process-pid"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>process-pid</TT> <TT class=variable>process</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns the process ID, an integer, for the
</P><TT class=variable>process</TT><P>.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs45"></A><A NAME="FN:process-status"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>process-status</TT> <TT class=variable>process</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns the current status of </P><TT class=variable>process</TT><P>, which is
one of </P><TT class=code>:running</TT><P>, </P><TT class=code>:stopped</TT><P>, </P><TT class=code>:exited</TT><P>, or
</P><TT class=code>:signaled</TT><P>.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs46"></A><A NAME="FN:process-exit-code"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>process-exit-code</TT> <TT class=variable>process</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns either the exit code for </P><TT class=variable>process</TT><P>, if it
is </P><TT class=code>:exited</TT><P>, or the termination signal </P><TT class=variable>process</TT><P> if it is
</P><TT class=code>:signaled</TT><P>. The result is undefined for processes that are
still alive.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs47"></A><A NAME="FN:process-core-dumped"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>process-core-dumped</TT> <TT class=variable>process</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns </P><TT class=code>t</TT><P> if someone used a Unix signal to
terminate the </P><TT class=variable>process</TT><P> and caused it to dump a Unix core image.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs48"></A><A NAME="FN:process-pty"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>process-pty</TT> <TT class=variable>process</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns either the two-way stream connected to
</P><TT class=variable>process</TT><P>&#X2019;s Unix PTY connection or </P><TT class=code>nil</TT><P> if there is none.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs49"></A><A NAME="FN:process-input"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>process-input</TT> <TT class=variable>process</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
<P><A NAME="@funs50"></A><A NAME="FN:process-output"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>process-output</TT> <TT class=variable>process</TT> &nbsp;&nbsp;&nbsp;
</DIV><P><A NAME="@funs51"></A><A NAME="FN:process-error"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>process-error</TT> <TT class=variable>process</TT> &nbsp;&nbsp;&nbsp;
</DIV><P>If the corresponding stream was created, these functions return the
input, output or error fd-stream. </P><TT class=code>nil</TT><P> is returned if there
is no stream.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs52"></A><A NAME="FN:process-status-hook"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>process-status-hook</TT> <TT class=variable>process</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns the current function to call whenever
</P><TT class=variable>process</TT><P>&#X2019;s status changes. This function takes the
</P><TT class=variable>process</TT><P> as a required argument. </P><TT class=code>process-status-hook</TT><P> is
</P><TT class=code>setf</TT><P>&#X2019;able.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs53"></A><A NAME="FN:process-plist"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>process-plist</TT> <TT class=variable>process</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns annotations supplied by users, and it is
</P><TT class=code>setf</TT><P>&#X2019;able. This is available solely for users to associate
information with </P><TT class=variable>process</TT><P> without having to build a-lists or
hash tables of process structures.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs54"></A><A NAME="FN:process-wait"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>process-wait</TT> 
<TT class=variable>process</TT> <TT class=code>&amp;optional</TT> <TT class=variable>check-for-stopped</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function waits for </P><TT class=variable>process</TT><P> to finish. If
</P><TT class=variable>check-for-stopped</TT><P> is non-</P><TT class=code>nil</TT><P>, this also returns when
</P><TT class=variable>process</TT><P> stops.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs55"></A><A NAME="FN:process-kill"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>process-kill</TT> <TT class=variable>process</TT> <TT class=variable>signal</TT> <TT class=code>&amp;optional</TT> <TT class=variable>whom</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function sends the Unix </P><TT class=variable>signal</TT><P> to </P><TT class=variable>process</TT><P>.
</P><TT class=variable>Signal</TT><P> should be the number of the signal or a keyword with
the Unix name (for example, </P><TT class=code>:sigsegv</TT><P>). </P><TT class=variable>Whom</TT><P> should be
one of the following:

</P><DL CLASS="list"><DT CLASS="dt-list">
<TT class=code>:pid</TT><BR>
</DT><DD CLASS="dd-list"> This is the default, and it indicates sending the
signal to <TT class=variable>process</TT> only.</DD><DT CLASS="dt-list"><TT class=code>:process-group</TT><BR>
</DT><DD CLASS="dd-list"> This indicates sending the signal to
<TT class=variable>process</TT>&#X2019;s group.</DD><DT CLASS="dt-list"><TT class=code>:pty-process-group</TT><BR>
</DT><DD CLASS="dd-list"> This indicates sending the signal to
the process group currently in the foreground on the Unix PTY
connected to <TT class=variable>process</TT>. 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
<TT class=code>process-pty</TT> of <TT class=variable>process</TT> is <TT class=code>nil</TT>, using this option is
an error.
</DD></DL></BLOCKQUOTE><P><BR>
<A NAME="@funs56"></A><A NAME="FN:process-alive-p"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>process-alive-p</TT> <TT class=variable>process</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns </P><TT class=code>t</TT><P> if </P><TT class=variable>process</TT><P>&#X2019;s status is either
</P><TT class=code>:running</TT><P> or </P><TT class=code>:stopped</TT><P>.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs57"></A><A NAME="FN:process-close"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>process-close</TT> <TT class=variable>process</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function closes all the streams associated with </P><TT class=variable>process</TT><P>.
When you are done using a process, call this to reclaim system
resources.
</P></BLOCKQUOTE><!--TOC section Saving a Core Image-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc40">2.15</A>&#XA0;&#XA0;Saving a Core Image</H2><!--SEC END --><P>A mechanism has been provided to save a running Lisp core image and to
later restore it. This is convenient if you don&#X2019;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.</P><P><BR>
<A NAME="@funs58"></A><A NAME="FN:save-lisp"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>save-lisp</TT> <TT class=variable>file</TT>
<TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=code>:purify</TT> <TT class=code>:root-structures</TT> <TT class=code>:init-function</TT></SPAN><BR>
 <TT class=code>:load-init-file</TT> <TT class=code>:print-herald</TT> <TT class=code>:site-init</TT><BR>
 <TT class=code>:process-command-line</TT> <TT class=code>:batch-mode</TT> <TT class=code>:executable</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>The </P><TT class=code>save-lisp</TT><P> function saves the state of the currently
running Lisp core image in </P><TT class=variable>file</TT><P>. The keyword arguments have
the following meaning:

</P><DL CLASS="list"><DT CLASS="dt-list">
<TT class=code>:purify</TT><BR>
</DT><DD CLASS="dd-list"> If non-<TT class=code>nil</TT> (the default), the core image is
purified before it is saved (see <A NAME="@funs59"></A><TT class=code>purify</TT>.) 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.</DD><DT CLASS="dt-list"><TT class=code>:root-structures</TT><BR>
</DT><DD CLASS="dd-list">
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
<TT class=code>:purify</TT> is <TT class=code>nil</TT>. See <A NAME="@funs60"></A><TT class=code>purify</TT>.</DD><DT CLASS="dt-list"><TT class=code>:init-function</TT><BR>
</DT><DD CLASS="dd-list"> 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.</DD><DT CLASS="dt-list"><TT class=code>:load-init-file</TT><BR>
</DT><DD CLASS="dd-list"> If non-NIL, then load an init file;
either the one specified on the command line or
&#X201C;<TT class=filename>init.</TT><TT class=variable>fasl-type</TT>&#X201D;, or, if
&#X201C;<TT class=filename>init.</TT><TT class=variable>fasl-type</TT>&#X201D; does not exist,
<TT class=code>init.lisp</TT> from the user&#X2019;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.</DD><DT CLASS="dt-list"><TT class=code>:site-init</TT><BR>
</DT><DD CLASS="dd-list"> If non-NIL, the name of the site init file to
quietly load. The default is <TT class=filename>library:site-init</TT>. No error
is signalled if the file does not exist.</DD><DT CLASS="dt-list"><TT class=code>:print-herald</TT><BR>
</DT><DD CLASS="dd-list"> If non-NIL (the default), then print out
the standard Lisp herald when starting.</DD><DT CLASS="dt-list"><TT class=code>:process-command-line</TT><BR>
</DT><DD CLASS="dd-list"> If non-NIL (the default),
processes the command line switches and performs the appropriate
actions.</DD><DT CLASS="dt-list"><TT class=code>:batch-mode</TT><BR>
</DT><DD CLASS="dd-list"> If NIL (the default), then the presence of
the -batch command-line switch will invoke batch-mode processing
upon resuming the saved core. If non-NIL, the produced core will
always be in batch-mode, regardless of any command-line switches.</DD><DT CLASS="dt-list"><TT class=code>:executable</TT><BR>
</DT><DD CLASS="dd-list"> If non-NIL, an executable image is created.
Normally, CMUCL consists of the C runtime along with a core
file image. When <TT class=code>:executable</TT> is non-NIL, the core file is
incorporated into the C runtime, so one (large) executable is
created instead of a new separate core file.<P>This feature is only available on some platforms, as indicated by
having the feature </P><TT class=code>:executable</TT><P>. Currently only x86 ports and
the solaris/sparc port have this feature.
</P></DD></DL></BLOCKQUOTE><P>To resume a saved file, type:
</P><BLOCKQUOTE class=example><PRE>
lisp -core file
</PRE></BLOCKQUOTE><P>
However, if the </P><TT class=code>:executable</TT><P> option was specified, you can just
use
</P><BLOCKQUOTE class=example><PRE>
  file
</PRE></BLOCKQUOTE><P>
since the executable contains the core file within the executable.</P><P><BR>
<A NAME="@funs61"></A><A NAME="FN:purify"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>purify</TT> 
<TT class=variable>file</TT>
<TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=code>:root-structures</TT> <TT class=code>:environment-name</TT></SPAN> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>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.</P><DL CLASS="list"><DT CLASS="dt-list">

<TT class=code>:root-structures</TT><BR>
</DT><DD CLASS="dd-list"> 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.<TT class=variable>defstruct</TT><P> structures defined with the </P><TT class=code>(:pure t)</TT><P>
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.</P></DD><DT CLASS="dt-list"><TT class=code>:environment-name</TT><BR>
</DT><DD CLASS="dd-list"> is gratuitous documentation for the
compacted version of the current global environment (as seen in
<TT class=code>c::*info-environment*</TT>.) If <TT class=code>nil</TT> is supplied, then
environment compaction is inhibited.
</DD></DL></BLOCKQUOTE><!--TOC section Pathnames-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc41">2.16</A>&#XA0;&#XA0;Pathnames</H2><!--SEC END --><P>In Common Lisp quite a few aspects of <A NAME="@types17"></A></P><TT class=code>pathname</TT><P> semantics are left to
the implementation. </P><!--TOC subsection Unix Pathnames-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc42">2.16.1</A>&#XA0;&#XA0;Unix Pathnames</H3><!--SEC END --><P>
<A NAME="@concept4"></A></P><P>Unix pathnames are always parsed with a </P><TT class=code>unix-host</TT><P> object as the host and
</P><TT class=code>nil</TT><P> as the device. The last two dots (</P><TT class=code>.</TT><P>) 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 </P><TT class=code>nil</TT><P> and the version
defaults to </P><TT class=code>:newest</TT><P>.</P><BLOCKQUOTE class=example><PRE>
(defun parse (x)
  (values (pathname-name x) (pathname-type x) (pathname-version x)))

(parse "foo") ==&gt; "foo", NIL, NIL
(parse "foo.bar") ==&gt; "foo", "bar", NIL
(parse ".foo") ==&gt; ".foo", NIL, NIL
(parse ".foo.bar") ==&gt; ".foo", "bar", NIL
(parse "..") ==&gt; NIL, NIL, NIL
(parse "foo.") ==&gt; "foo", "", NIL
(parse "foo.bar.~1~") ==&gt; "foo", "bar", 1
(parse "foo.bar.baz") ==&gt; "foo.bar", "baz", NIL
</PRE></BLOCKQUOTE><P>The directory of pathnames beginning with a slash (or a search-list,
see section&#XA0;<A HREF="#search-lists">2.16.4</A>) is starts </P><TT class=code>:absolute</TT><P>, others start with
</P><TT class=code>:relative</TT><P>. The </P><TT class=code>..</TT><P> directory is parsed as </P><TT class=code>:up</TT><P>; there is no
namestring for </P><TT class=code>:back</TT><P>:</P><BLOCKQUOTE class=example><PRE>
(pathname-directory "/usr/foo/bar.baz") ==&gt; (:ABSOLUTE "usr" "foo")
(pathname-directory "../foo/bar.baz") ==&gt; (:RELATIVE :UP "foo")
</PRE></BLOCKQUOTE><!--TOC subsection Wildcard Pathnames-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc43">2.16.2</A>&#XA0;&#XA0;Wildcard Pathnames</H3><!--SEC END --><P>Wildcards are supported in Unix pathnames. If &#X2018;</P><TT class=code>*</TT><P>&#X2019; is specified for a
part of a pathname, that is parsed as </P><TT class=code>:wild</TT><P>. &#X2018;</P><TT class=code>**</TT><P>&#X2019; can be used as a
directory name to indicate </P><TT class=code>:wild-inferiors</TT><P>. Filesystem operations
treat </P><TT class=code>:wild-inferiors</TT><P> the same as </P><TT class=code>:wild</TT><P>, but pathname pattern
matching (e.g. for logical pathname translation, see section&#XA0;<A HREF="#logical-pathnames">2.16.3</A>)
matches any number of directory parts with &#X2018;</P><TT class=code>**</TT><P>&#X2019; (see
see section&#XA0;<A HREF="#wildcard-matching">2.17.1</A>.)</P><P>&#X2018;</P><TT class=code>*</TT><P>&#X2019; embedded in a pathname part matches any number of characters.
Similarly, &#X2018;</P><TT class=code>?</TT><P>&#X2019; matches exactly one character, and &#X2018;</P><TT class=code>[a,b]</TT><P>&#X2019;
matches the characters &#X2018;</P><TT class=code>a</TT><P>&#X2019; or &#X2018;</P><TT class=code>b</TT><P>&#X2019;. These pathname parts are
parsed as </P><TT class=code>pattern</TT><P> objects.</P><P>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:</P><BLOCKQUOTE class=example><PRE>
(pathname-name "foo\\*bar") =&gt; "foo*bar"
</PRE></BLOCKQUOTE><!--TOC subsection Logical Pathnames-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc44">2.16.3</A>&#XA0;&#XA0;Logical Pathnames</H3><!--SEC END --><P>
<A NAME="@concept5"></A>
<A NAME="logical-pathnames"></A></P><P>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 &#X2018;</P><TT class=code>*</TT><P>&#X2019; and &#X2018;</P><TT class=code>**</TT><P>&#X2019; wildcards are implemented.
<A NAME="@funs62"></A></P><TT class=code>load-logical-pathname-translations</TT><P> on </P><TT class=variable>name</TT><P> looks for a
logical host definition file in
</P><TT class=filename>library:<TT class=variable>name</TT>.translations</TT><P>. Note that </P><TT class=filename>library:</TT><P>
designates the search list (see section&#XA0;<A HREF="#search-lists">2.16.4</A>) initialized to the
CMUCL </P><TT class=filename>lib/</TT><P> directory, not a logical pathname. The format of
the file is a single list of two-lists of the from and to patterns:</P><BLOCKQUOTE class=example><PRE>
(("foo;*.text" "/usr/ram/foo/*.txt")
 ("foo;*.lisp" "/usr/ram/foo/*.l"))
</PRE></BLOCKQUOTE><!--TOC subsection Search Lists-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc45">2.16.4</A>&#XA0;&#XA0;Search Lists</H3><!--SEC END --><P>
<A NAME="@concept6"></A>
<A NAME="search-lists"></A></P><P>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:
</P><UL CLASS="itemize"><LI CLASS="li-itemize">
They provide a convenient shorthand for commonly used directory names,
and</LI><LI CLASS="li-itemize">They allow the abstract (directory structure independent) specification
of file locations in program pathname constants (similar to logical pathnames.)
</LI></UL><P>
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 &#X201C;</P><TT class=variable>slist</TT><TT class=code>:</TT><P>&#X201D;, indicating that the
pathname is relative to the search list </P><TT class=variable>slist</TT><P> (instead of to the current
working directory.) Once qualified with a search list, the pathname is no
longer considered to be relative.</P><P>When a search list qualified pathname is passed to a file-system operation such
as </P><TT class=code>open</TT><P>, </P><TT class=code>load</TT><P> or </P><TT class=code>truename</TT><P>, 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.</P><!--TOC subsection Predefined Search-Lists-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc46">2.16.5</A>&#XA0;&#XA0;Predefined Search-Lists</H3><!--SEC END --><P>These search-lists are initialized from the Unix environment or when Lisp was
built:

</P><DL CLASS="list"><DT CLASS="dt-list">

<TT class=code>default:</TT><BR>
</DT><DD CLASS="dd-list"> The current directory at startup.</DD><DT CLASS="dt-list"><TT class=code>home:</TT><BR>
</DT><DD CLASS="dd-list"> The user&#X2019;s home directory.</DD><DT CLASS="dt-list"><TT class=code>library:</TT><BR>
</DT><DD CLASS="dd-list"> The CMUCL <TT class=filename>lib/</TT> directory (<TT class=code>CMUCLLIB</TT> environment
variable).</DD><DT CLASS="dt-list"><TT class=code>path:</TT><BR>
</DT><DD CLASS="dd-list"> The Unix command path (<TT class=code>PATH</TT> environment variable).
</DD><DT CLASS="dt-list"><TT class=code>ld-library-path:</TT><BR>
</DT><DD CLASS="dd-list"> The Unix <TT class=code>LD_LIBRARY_PATH</TT>
environment variable.
</DD><DT CLASS="dt-list"><TT class=code>target:</TT><BR>
</DT><DD CLASS="dd-list"> The root of the tree where CMUCL was compiled.
</DD><DT CLASS="dt-list"><TT class=code>modules:</TT><BR>
</DT><DD CLASS="dd-list"> The list of directories where CMUCL&#X2019;s
modules can be found.
</DD><DT CLASS="dt-list"><TT class=code>ext-formats:</TT><BR>
</DT><DD CLASS="dd-list"> The list of directories where CMUCL can
find the implementation of external formats. 
</DD></DL><P>
It can be useful to redefine these search-lists, for example, </P><TT class=filename>library:</TT><P>
can be augmented to allow logical pathname translations to be located, and
</P><TT class=filename>target:</TT><P> can be redefined to point to where CMUCL system sources are
locally installed. </P><!--TOC subsection Search-List Operations-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc47">2.16.6</A>&#XA0;&#XA0;Search-List Operations</H3><!--SEC END --><P>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.</P><P><BR>
<A NAME="@funs63"></A><A NAME="FN:search-list"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>search-list</TT> <TT class=variable>name</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns the list of directories associated with the
search list </P><TT class=variable>name</TT><P>. If </P><TT class=variable>name</TT><P> is not a defined search list,
then an error is signaled. When set with </P><TT class=code>setf</TT><P>, 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.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs64"></A><A NAME="FN:search-list-defined-p"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>search-list-defined-p</TT> <TT class=variable>name</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
<P><A NAME="@funs65"></A><A NAME="FN:clear-search-list"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>clear-search-list</TT> <TT class=variable>name</TT> &nbsp;&nbsp;&nbsp;
</DIV><TT class=code>search-list-defined-p</TT><P> returns </P><TT class=code>t</TT><P> if </P><TT class=variable>name</TT><P> is a
defined search list name, </P><TT class=code>nil</TT><P> otherwise.
</P><TT class=code>clear-search-list</TT><P> make the search list </P><TT class=variable>name</TT><P> undefined.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs66"></A><A NAME="FN:enumerate-search-list"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>enumerate-search-list</TT> (<TT class=variable>var</TT> <TT class=variable>pathname</TT> <TT class=code>{result}</TT>) <TT class=code>{form}</TT><SUP>*</SUP> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This macro provides an interface to search list resolution. The
body </P><TT class=variable>forms</TT><P> are executed with </P><TT class=variable>var</TT><P> bound to each
successive possible expansion for </P><TT class=variable>name</TT><P>. If </P><TT class=variable>name</TT><P> does
not contain a search-list, then the body is executed exactly once.
Everything is wrapped in a block named </P><TT class=code>nil</TT><P>, so </P><TT class=code>return</TT><P> can be
used to terminate early. The </P><TT class=variable>result</TT><P> form (default </P><TT class=code>nil</TT><P>) is
evaluated to determine the result of the iteration.
</P></BLOCKQUOTE><!--TOC subsection Search List Example-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc48">2.16.7</A>&#XA0;&#XA0;Search List Example</H3><!--SEC END --><P>The search list </P><TT class=code>code:</TT><P> can be defined as follows:
</P><BLOCKQUOTE class=example><PRE>
(setf (ext:search-list "code:") &#X2019;("/usr/lisp/code/"))
</PRE></BLOCKQUOTE><P>
It is now possible to use </P><TT class=code>code:</TT><P> as an abbreviation for the directory
</P><TT class=filename>/usr/lisp/code/</TT><P> in all file operations. For example, you can now specify
</P><TT class=code>code:eval.lisp</TT><P> to refer to the file </P><TT class=filename>/usr/lisp/code/eval.lisp</TT><P>.</P><P>To obtain the value of a search-list name, use the function search-list
as follows:
</P><BLOCKQUOTE class=example><PRE>
(ext:search-list <TT class=variable>name</TT>)
</PRE></BLOCKQUOTE><P>
Where </P><TT class=variable>name</TT><P> is the name of a search list as described above. For example,
calling </P><TT class=code>ext:search-list</TT><P> on </P><TT class=code>code:</TT><P> as follows:
</P><BLOCKQUOTE class=example><PRE>
(ext:search-list "code:")
</PRE></BLOCKQUOTE><P>
returns the list </P><TT class=code>("/usr/lisp/code/")</TT><P>.</P><!--TOC section Filesystem Operations-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc49">2.17</A>&#XA0;&#XA0;Filesystem Operations</H2><!--SEC END --><P>CMUCL provides a number of extensions and optional features beyond those
required by the Common Lisp specification.</P><!--TOC subsection Wildcard Matching-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc50">2.17.1</A>&#XA0;&#XA0;Wildcard Matching</H3><!--SEC END --><P>
<A NAME="wildcard-matching"></A></P><P>Unix filesystem operations such as </P><TT class=code>open</TT><P> will accept wildcard pathnames
that match a single file (of course, </P><TT class=code>directory</TT><P> allows any number of
matches.) Filesystem operations treat </P><TT class=code>:wild-inferiors</TT><P> the same as
</P><TT class=code>:wild</TT><P>.</P><P><BR>
<A NAME="@funs67"></A><A NAME="FN:directory"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>directory</TT> <TT class=variable>wildname</TT> <TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=code>:all</TT> <TT class=code>:check-for-subdirs</TT></SPAN>
<TT class=code>:truenamep</TT><BR>
 <TT class=code>:follow-links</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>The keyword arguments to this Common Lisp function are a CMUCL extension.
The arguments (all default to </P><TT class=code>t</TT><P>) have the following
functions:

</P><DL CLASS="list"><DT CLASS="dt-list">

<TT class=code>:all</TT><BR>
</DT><DD CLASS="dd-list"> Include files beginning with dot such as
<TT class=filename>.login</TT>, similar to &#X201C;<TT class=code>ls -a</TT>&#X201D;.</DD><DT CLASS="dt-list"><TT class=code>:check-for-subdirs</TT><BR>
</DT><DD CLASS="dd-list"> Test whether files are directories,
similar to &#X201C;<TT class=code>ls -F</TT>&#X201D;.</DD><DT CLASS="dt-list"><TT class=code>:truenamep</TT><BR>
</DT><DD CLASS="dd-list"> Call <TT class=code>truename</TT> 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 <TT class=variable>wildname</TT> argument.</DD><DT CLASS="dt-list"><TT class=code>:follow-links</TT><BR>
</DT><DD CLASS="dd-list"> Follow symbolic links when searching for
matching directories.
</DD></DL></BLOCKQUOTE><P><BR>
<A NAME="@funs68"></A><A NAME="FN:print-directory"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>print-directory</TT> <TT class=variable>wildname</TT>
<TT class=code>&amp;optional</TT> <TT class=variable>stream</TT>
<TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=code>:all</TT> <TT class=code>:verbose</TT></SPAN><BR>
 <TT class=code>:return-list</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>Print a directory of </P><TT class=variable>wildname</TT><P> listing to </P><TT class=variable>stream</TT><P> (default
</P><TT class=code>*standard-output*</TT><P>.) </P><TT class=code>:all</TT><P> and </P><TT class=code>:verbose</TT><P> both default
to </P><TT class=code>nil</TT><P> and correspond to the &#X201C;</P><TT class=code>-a</TT><P>&#X201D; and &#X201C;</P><TT class=code>-l</TT><P>&#X201D;
options of </P><TT class=filename>ls</TT><P>. Normally this function returns </P><TT class=code>nil</TT><P>, but
if </P><TT class=code>:return-list</TT><P> is true, a list of the matched pathnames are
returned.
</P></BLOCKQUOTE><!--TOC subsection File Name Completion-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc51">2.17.2</A>&#XA0;&#XA0;File Name Completion</H3><!--SEC END --><P><BR>
<A NAME="@funs69"></A><A NAME="FN:complete-file"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>complete-file</TT> <TT class=variable>pathname</TT>
<TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=code>:defaults</TT> <TT class=code>:ignore-types</TT></SPAN> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>Attempt to complete a file name to the longest unambiguous prefix.
If supplied, directory from </P><TT class=code>:defaults</TT><P> is used as the &#X201C;working
directory&#X201D; when doing completion. </P><TT class=code>:ignore-types</TT><P> is a list of
strings of the pathname types (a.k.a. extensions) that should be
disregarded as possible matches (binary file names, etc.)
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs70"></A><A NAME="FN:ambiguous-files"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>ambiguous-files</TT> <TT class=variable>pathname</TT>
<TT class=code>&amp;optional</TT> <TT class=variable>defaults</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>Return a list of pathnames for all the possible completions of
</P><TT class=variable>pathname</TT><P> with respect to </P><TT class=variable>defaults</TT><P>.
</P></BLOCKQUOTE><!--TOC subsection Miscellaneous Filesystem Operations-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc52">2.17.3</A>&#XA0;&#XA0;Miscellaneous Filesystem Operations</H3><!--SEC END --><P><BR>
<A NAME="@funs71"></A><A NAME="FN:default-directory"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>default-directory</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>Return the current working directory as a pathname. If set with
</P><TT class=code>setf</TT><P>, set the working directory.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs72"></A><A NAME="FN:file-writable"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>file-writable</TT> <TT class=variable>name</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function accepts a pathname and returns </P><TT class=code>t</TT><P> if the current
process can write it, and </P><TT class=code>nil</TT><P> otherwise.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs73"></A><A NAME="FN:unix-namestring"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>unix-namestring</TT> <TT class=variable>pathname</TT>
<TT class=code>&amp;optional</TT> <TT class=variable>for-input</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function converts </P><TT class=variable>pathname</TT><P> into a string that can be used
with UNIX system calls. Search-lists and wildcards are expanded.
</P><TT class=variable>for-input</TT><P> 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.
</P></BLOCKQUOTE><!--TOC section Time Parsing and Formatting-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc53">2.18</A>&#XA0;&#XA0;Time Parsing and Formatting</H2><!--SEC END --><P><A NAME="@concept7"></A> <A NAME="@concept8"></A>
Functions are provided to allow parsing strings containing time information
and printing time in various formats are available.</P><P><BR>
<A NAME="@funs74"></A><A NAME="FN:parse-time"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>parse-time</TT> <TT class=variable>time-string</TT>
<TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=code>:error-on-mismatch</TT> <TT class=code>:default-seconds</TT></SPAN><BR>
 <TT class=code>:default-minutes</TT> <TT class=code>:default-hours</TT><BR>
 <TT class=code>:default-day</TT> <TT class=code>:default-month</TT><BR>
 <TT class=code>:default-year</TT> <TT class=code>:default-zone</TT><BR>
 <TT class=code>:default-weekday</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><TT class=code>parse-time</TT><P> accepts a string containing a time (e.g.,
"</P><TT class=code>Jan 12, 1952</TT><P>") and returns the universal time if it is
successful. If it is unsuccessful and the keyword argument
</P><TT class=code>:error-on-mismatch</TT><P> is non-</P><TT class=code>nil</TT><P>, it signals an error.
Otherwise it returns </P><TT class=code>nil</TT><P>. The other keyword arguments have the
following meaning:</P><DL CLASS="list"><DT CLASS="dt-list">

<TT class=code>:default-seconds</TT><BR>
</DT><DD CLASS="dd-list"> specifies the default value for the
seconds value if one is not provided by <TT class=variable>time-string</TT>. The
default value is 0.</DD><DT CLASS="dt-list"><TT class=code>:default-minutes</TT><BR>
</DT><DD CLASS="dd-list"> specifies the default value for the
minutes value if one is not provided by <TT class=variable>time-string</TT>. The
default value is 0.</DD><DT CLASS="dt-list"><TT class=code>:default-hours</TT><BR>
</DT><DD CLASS="dd-list"> specifies the default value for the hours
value if one is not provided by <TT class=variable>time-string</TT>. The default
value is 0.</DD><DT CLASS="dt-list"><TT class=code>:default-day</TT><BR>
</DT><DD CLASS="dd-list"> specifies the default value for the day
value if one is not provided by <TT class=variable>time-string</TT>. The default
value is the current day.</DD><DT CLASS="dt-list"><TT class=code>:default-month</TT><BR>
</DT><DD CLASS="dd-list"> specifies the default value for the month
value if one is not provided by <TT class=variable>time-string</TT>. The default
value is the current month.</DD><DT CLASS="dt-list"><TT class=code>:default-year</TT><BR>
</DT><DD CLASS="dd-list"> specifies the default value for the year
value if one is not provided by <TT class=variable>time-string</TT>. The default
value is the current year.</DD><DT CLASS="dt-list"><TT class=code>:default-zone</TT><BR>
</DT><DD CLASS="dd-list"> specifies the default value for the time
zone value if one is not provided by <TT class=variable>time-string</TT>. The
default value is the current time zone.</DD><DT CLASS="dt-list"><TT class=code>:default-weekday</TT><BR>
</DT><DD CLASS="dd-list"> specifies the default value for the day
of the week if one is not provided by <TT class=variable>time-string</TT>. The
default value is the current day of the week.
</DD></DL><P>
Any of the above keywords can be given the value </P><TT class=code>:current</TT><P> which
means to use the current value as determined by a call to the
operating system.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs75"></A><A NAME="FN:format-universal-time"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>format-universal-time</TT> 
<TT class=variable>dest</TT> <TT class=variable>universal-time</TT><BR>
 <TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=code>:timezone</TT></SPAN><BR>
 <TT class=code>:style</TT> <TT class=code>:date-first</TT><BR>
 <TT class=code>:print-seconds</TT> <TT class=code>:print-meridian</TT><BR>
 <TT class=code>:print-timezone</TT> <TT class=code>:print-weekday</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
<P><A NAME="@funs76"></A><A NAME="FN:format-decoded-time"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>format-decoded-time</TT> 
<TT class=variable>dest</TT> <TT class=variable>seconds</TT> <TT class=variable>minutes</TT> <TT class=variable>hours</TT> <TT class=variable>day</TT> <TT class=variable>month</TT> <TT class=variable>year</TT><BR>
 <TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=code>:timezone</TT></SPAN><BR>
 <TT class=code>:style</TT> <TT class=code>:date-first</TT><BR>
 <TT class=code>:print-seconds</TT> <TT class=code>:print-meridian</TT><BR>
 <TT class=code>:print-timezone</TT> <TT class=code>:print-weekday</TT> &nbsp;&nbsp;&nbsp;
</DIV><TT class=code>format-universal-time</TT><P> formats the time specified by
</P><TT class=variable>universal-time</TT><P>. </P><TT class=code>format-decoded-time</TT><P> formats the time
specified by </P><TT class=variable>seconds</TT><P>, </P><TT class=variable>minutes</TT><P>, </P><TT class=variable>hours</TT><P>, </P><TT class=variable>day</TT><P>,
</P><TT class=variable>month</TT><P>, and </P><TT class=variable>year</TT><P>. </P><TT class=variable>Dest</TT><P> is any destination
accepted by the </P><TT class=code>format</TT><P> function. The keyword arguments have
the following meaning:

</P><DL CLASS="list"><DT CLASS="dt-list">
<TT class=code>:timezone</TT><BR>
</DT><DD CLASS="dd-list"> is an integer specifying the hours west of
Greenwich. <TT class=code>:timezone</TT> defaults to the current time zone.</DD><DT CLASS="dt-list"><TT class=code>:style</TT><BR>
</DT><DD CLASS="dd-list"> specifies the style to use in formatting the
time. The legal values are:

<DL CLASS="list"><DT CLASS="dt-list">
<TT class=code>:short</TT><BR>
</DT><DD CLASS="dd-list"> specifies to use a numeric date.</DD><DT CLASS="dt-list"><TT class=code>:long</TT><BR>
</DT><DD CLASS="dd-list"> specifies to format months and weekdays as
words instead of numbers.</DD><DT CLASS="dt-list"><TT class=code>:abbreviated</TT><BR>
</DT><DD CLASS="dd-list"> is similar to long except the words are
abbreviated.</DD><DT CLASS="dt-list"><TT class=code>:government</TT><BR>
</DT><DD CLASS="dd-list"> is similar to abbreviated, except the
date is of the form &#X201C;day month year&#X201D; instead of &#X201C;month day,
year&#X201D;.
</DD></DL></DD><DT CLASS="dt-list"><TT class=code>:date-first</TT><BR>
</DT><DD CLASS="dd-list"> if non-<TT class=code>nil</TT> (default) will place the
date first. Otherwise, the time is placed first.</DD><DT CLASS="dt-list"><TT class=code>:print-seconds</TT><BR>
</DT><DD CLASS="dd-list"> if non-<TT class=code>nil</TT> (default) will format
the seconds as part of the time. Otherwise, the seconds will be
omitted.</DD><DT CLASS="dt-list"><TT class=code>:print-meridian</TT><BR>
</DT><DD CLASS="dd-list"> if non-<TT class=code>nil</TT> (default) will format
&#X201C;AM&#X201D; or &#X201C;PM&#X201D; as part of the time. Otherwise, the &#X201C;AM&#X201D; or
&#X201C;PM&#X201D; will be omitted.</DD><DT CLASS="dt-list"><TT class=code>:print-timezone</TT><BR>
</DT><DD CLASS="dd-list"> if non-<TT class=code>nil</TT> (default) will format
the time zone as part of the time. Otherwise, the time zone will
be omitted.</DD><DT CLASS="dt-list"><TT class=code>:print-weekday</TT><BR>
</DT><DD CLASS="dd-list"> if non-<TT class=code>nil</TT> (default) will format
the weekday as part of date. Otherwise, the weekday will be
omitted.
</DD></DL></BLOCKQUOTE><!--TOC section Random Number Generation-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc54">2.19</A>&#XA0;&#XA0;Random Number Generation</H2><!--SEC END --><P>
<A NAME="@concept9"></A></P><P>Common Lisp includes a random number generator as a standard part of the
language; however, the implementation of the generator is not
specified.</P><!--TOC subsection MT-19937 Generator-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc55">2.19.1</A>&#XA0;&#XA0;MT-19937 Generator</H3><!--SEC END --><P>
<A NAME="@concept10"></A>
On all platforms, the random number is </P><TT class=code>MT-19937</TT><P> generator as indicated by
</P><TT class=code>:rand-mt19937</TT><P> being in </P><TT class=code>*features*</TT><P>. This is a Lisp
implementation of the MT-19937 generator of Makoto Matsumoto and
T. Nishimura. We refer the reader to their paper<SUP><A NAME="text2" HREF="#note2">2</A></SUP> or to
their
<A HREF="http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html">website</A>.
</P><P>When CMUCL starts up, </P><TT class=code>*random-state*</TT><P> is initialized by
reading 627 words from </P><TT class=code>/dev/urandom</TT><P>, when available. If
</P><TT class=code>/dev/urandom</TT><P> is not available, the universal time is used to
initialize </P><TT class=code>*random-state*</TT><P>. The initialization is done as given
in Matsumoto&#X2019;s paper.</P><!--TOC section Lisp Threads-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc56">2.20</A>&#XA0;&#XA0;Lisp Threads</H2><!--SEC END --><P>
<A NAME="@concept11"></A></P><P>CMUCL supports Lisp threads for the x86 platform.</P><!--TOC section Lisp Library-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc57">2.21</A>&#XA0;&#XA0;Lisp Library</H2><!--SEC END --><P>
<A NAME="lisp-lib"></A></P><P>The CMUCL project maintains a collection of useful or interesting
programs written by users of our system. The library is in
</P><TT class=filename>lib/contrib/</TT><P>. Two files there that users should read are:

</P><DL CLASS="list"><DT CLASS="dt-list">
CATALOG.TXT<BR>
</DT><DD CLASS="dd-list">
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.</DD><DT CLASS="dt-list">READ-ME.TXT<BR>
</DT><DD CLASS="dd-list">
This file describes the library&#X2019;s organization and all the
possible pieces of information an entry&#X2019;s catalog description could contain.
</DD></DL><P>Hemlock has a command </P><TT class=code>Library Entry</TT><P> 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.</P><!--TOC section Generalized Function Names-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc58">2.22</A>&#XA0;&#XA0;Generalized Function Names</H2><!--SEC END --><P><BR>
<A NAME="@funs77"></A><A NAME="FN:define-function-name-syntax"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>ext:</TT><TT class=function-name>define-function-name-syntax</TT> name (var) <TT class=code>&amp;body</TT> body &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Define lists starting with the symbol <TT class=code>name</TT> as a new extended
function name syntax.<TT class=code>body</TT><P> is executed with </P><TT class=code>var</TT><P> bound to an actual function
name of that form, and should return two values:</P><UL CLASS="itemize"><LI CLASS="li-itemize">
A generalized boolean that is true if <TT class=code>var</TT> is a valid
function name.
</LI><LI CLASS="li-itemize">A symbol that can be used as a <TT class=code>block</TT> name in functions
whose name is <TT class=code>var</TT>. (For some sorts of function names it
might make sense to return <TT class=code>nil</TT> for the block name, or just
return one value.)
</LI></UL><P>Users should not define function names starting with a symbol that
CMUCL might be using internally. It is therefore advisable to
only define new function names starting with a symbol from a
user-defined package.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs78"></A><A NAME="FN:valid-function-name-p"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>ext:</TT><TT class=function-name>valid-function-name-p</TT> name &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Returns two values:<UL CLASS="itemize"><LI CLASS="li-itemize">
True if <TT class=code>name</TT> is a valid function name.
</LI><LI CLASS="li-itemize">A symbol that can be used as a <TT class=code>block</TT> name in
functions whose name is <TT class=code>name</TT>. This can be <TT class=code>nil</TT>
for some function names.
</LI></UL></BLOCKQUOTE><!--TOC section CLOS-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc59">2.23</A>&#XA0;&#XA0;CLOS</H2><!--SEC END --><!--TOC subsection Primary Method Errors-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc60">2.23.1</A>&#XA0;&#XA0;Primary Method Errors</H3><!--SEC END --><P>
<A NAME="@concept12"></A></P><P>The standard requires that an error is signaled when a generic
function is called and</P><UL CLASS="itemize"><LI CLASS="li-itemize">
no primary method is applicable to the generic function&#X2019;s actual
arguments, and
</LI><LI CLASS="li-itemize">the generic function&#X2019;s method combination is either the standard
method combination or a method combination defined with the short
form of <TT class=code>define-method-combination</TT>. The latter includes the
standardized method combinations like <TT class=code>progn</TT>, <TT class=code>and</TT>, etc.
</LI></UL><P><BR>
<A NAME="@funs79"></A><A NAME="FN:no-primary-method-generic-generic"></A></P><DIV align=left>
[Generic Function]<BR>
 <TT class=function-name>pcl:</TT><TT class=function-name>no-primary-method</TT> gf &amp;rest args &nbsp;&nbsp;&nbsp;
</DIV><P>

In CMUCL, this generic function is called in the above erroneous
cases. The parameter </P><TT class=code>gf</TT><P> is the generic function being
called, and </P><TT class=code>args</TT><P> is a list of actual arguments in the generic
function call.
</P><P><BR>
<A NAME="@funs80"></A><A NAME="FN:no-primary-method-method-standard"></A></P><DIV align=left>
[Method]<BR>
 <TT class=function-name>pcl:</TT><TT class=function-name>no-primary-method</TT> (gf standard-generic-function) &amp;rest args &nbsp;&nbsp;&nbsp;
</DIV><P>

This method signals a continuable error of type
</P><TT class=code>pcl:no-primary-method-error</TT><P>.
</P><!--TOC subsection Slot Type Checking-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc61">2.23.2</A>&#XA0;&#XA0;Slot Type Checking</H3><!--SEC END --><P>
<A NAME="@concept13"></A></P><P>Declared slot types are used when </P><UL CLASS="itemize"><LI CLASS="li-itemize">
reading slot values with <TT class=code>slot-value</TT> in methods, or</LI><LI CLASS="li-itemize">setting slots with <TT class=code>(setf slot-value)</TT> in methods, or </LI><LI CLASS="li-itemize">creating instances with <TT class=code>make-instance</TT>, when slots are
initialized from initforms. This currently depends on PCL being
able to use its internal <TT class=code>make-instance</TT> optimization, which it
usually can.
</LI></UL><P>Example:</P><BLOCKQUOTE class=example><PRE>
(defclass foo ()
  ((a :type fixnum)))

(defmethod bar ((object foo) value)
  (with-slots (a) object
    (setf a value)))

(defmethod baz ((object foo))
  (&lt; (slot-value object &#X2019;a) 10))
</PRE></BLOCKQUOTE><P>In method </P><TT class=code>bar</TT><P>, and with a suitable safety setting, a type error
will occur if </P><TT class=code>value</TT><P> is not a </P><TT class=code>fixnum</TT><P>. In method
</P><TT class=code>baz</TT><P>, a </P><TT class=code>fixnum</TT><P> comparison can be used by the compiler.</P><P><BR>
<A NAME="@vars18"></A><A NAME="VR:use-slot-types-p"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>pcl::</TT><TT class=function-name>*use-slot-types-p*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Slot type checking can be turned off by setting this variable to
<TT class=code>nil</TT>, which can be useful for compiling code containing incorrect
slot type declarations.
</BLOCKQUOTE><!--TOC subsection Slot Access Optimization-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc62">2.23.3</A>&#XA0;&#XA0;Slot Access Optimization</H3><!--SEC END --><P>
<A NAME="@concept14"></A>
<A NAME="@concept15"></A></P><P>The declaration </P><TT class=code>ext:slots</TT><P> is used for optimizing slot access in
methods.</P><BLOCKQUOTE class=example><PRE>
declare (ext:slots specifier*)

specifier   ::= (quality class-entry*)
quality     ::= SLOT-BOUNDP | INLINE
class-entry ::= class | (class slot-name*)
class       ::= the name of a class
slot-name   ::= the name of a slot
</PRE></BLOCKQUOTE><P>The </P><TT class=code>slot-boundp</TT><P> quality specifies that all or some slots of a
class are always bound.</P><P>The </P><TT class=code>inline</TT><P> quality specifies that access to all or some slots
of a class should be inlined, using compile-time knowledge of class
layouts.</P><!--TOC subsubsection <TT class=code>slot-boundp</TT> Declaration-->
<H4 CLASS="subsubsection"><!--SEC ANCHOR -->2.23.3.1&#XA0;&#XA0;<TT class=code>slot-boundp</TT> Declaration</H4><!--SEC END --><P>
<A NAME="@concept16"></A></P><P>Example:</P><BLOCKQUOTE class=example><PRE>
(defclass foo ()
  (a b))

(defmethod bar ((x foo))
  (declare (ext:slots (slot-boundp foo)))
  (list (slot-value x &#X2019;a) (slot-value x &#X2019;b)))
</PRE></BLOCKQUOTE><P>The </P><TT class=code>slot-boundp</TT><P> declaration in method </P><TT class=code>bar</TT><P> specifies that
the slots </P><TT class=code>a</TT><P> and </P><TT class=code>b</TT><P> accessed through parameter </P><TT class=code>x</TT><P> in
the scope of the declaration are always bound, because parameter
</P><TT class=code>x</TT><P> is specialized on class </P><TT class=code>foo</TT><P> to which the
</P><TT class=code>slot-boundp</TT><P> declaration applies. The PCL-generated code for
the </P><TT class=code>slot-value</TT><P> forms will thus not contain tests for the slots
being bound or not. The consequences are undefined should one of the
accessed slots not be bound.</P><!--TOC subsubsection <TT class=code>inline</TT> Declaration-->
<H4 CLASS="subsubsection"><!--SEC ANCHOR -->2.23.3.2&#XA0;&#XA0;<TT class=code>inline</TT> Declaration</H4><!--SEC END --><P>
<A NAME="@concept17"></A></P><P>Example:</P><BLOCKQUOTE class=example><PRE>
(defclass foo ()
  (a b))

(defmethod bar ((x foo))
  (declare (ext:slots (inline (foo a))))
  (list (slot-value x &#X2019;a) (slot-value x &#X2019;b)))
</PRE></BLOCKQUOTE><P>The </P><TT class=code>inline</TT><P> declaration in method </P><TT class=code>bar</TT><P> tells PCL to use
compile-time knowledge of slot locations for accessing slot </P><TT class=code>a</TT><P>
of class </P><TT class=code>foo</TT><P>, in the scope of the declaration.</P><P>Class </P><TT class=code>foo</TT><P> must be known at compile time for this optimization
to be possible. PCL prints a warning and uses normal slot access If
the class is not defined at compile time.</P><P>If a class is </P><TT class=code>proclaim</TT><P>ed to use inline slot access before it is
defined, the class is defined at compile time. Example:</P><BLOCKQUOTE class=example><PRE>
(declaim (ext:slots (inline (foo slot-a))))
(defclass foo () ...)
(defclass bar (foo) ...)
</PRE></BLOCKQUOTE><P>Class </P><TT class=code>foo</TT><P> will be defined at compile time because it is
declared to use inline slot access; methods accessing slot
</P><TT class=code>slot-a</TT><P> of </P><TT class=code>foo</TT><P> will use inline slot access if otherwise
possible. Class </P><TT class=code>bar</TT><P> will be defined at compile time because
its superclass </P><TT class=code>foo</TT><P> is declared to use inline slot access. PCL
uses compile-time information from subclasses to warn about situations
where using inline slot access is not possible.</P><P>Normal slot access will be used if PCL finds, at method compilation
time, that</P><UL CLASS="itemize"><LI CLASS="li-itemize">
class <TT class=code>foo</TT> has a subclass in which slot <TT class=code>a</TT> is at a
different location, or</LI><LI CLASS="li-itemize">there exists a <TT class=code>slot-value-using-class</TT> method for
<TT class=code>foo</TT> or a subclass of <TT class=code>foo</TT>.
</LI></UL><P>When the declaration is used to optimize calls to slot accessor
generic functions in methods, as opposed to </P><TT class=code>slot-value</TT><P> or
</P><TT class=code>(setf slot-value)</TT><P>, the optimization is additionally not used if</P><UL CLASS="itemize"><LI CLASS="li-itemize">
there exist, at compile time, applicable methods on the
reader/writer generic function that are not standard accessor
methods (for instance, there exist around-methods), or</LI><LI CLASS="li-itemize">applicable reader/writer methods access different slots in a
class accessed inline, and one of its subclasses.
</LI></UL><P>The consequences are undefined if the compile-time environment is not
the same as the run-time environment in these respects, or if the
definition of class </P><TT class=code>foo</TT><P> or any subclass of </P><TT class=code>foo</TT><P> is
changed in an incompatible way, that is, if slot locations change.</P><P>The effect of the </P><TT class=code>inline</TT><P> optimization combined with the
</P><TT class=code>slot-boundp</TT><P> optimization is that CLOS slot access becomes as
fast as structure slot access, which is an order of magnitude faster
than normal CLOS slot access.</P><P><BR>
<A NAME="@vars19"></A><A NAME="VR:optimize-inline-slot-access-p"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>pcl::</TT><TT class=function-name>*optimize-inline-slot-access-p*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
This variable controls if inline slot access optimizations are
performed. It is true by default.
</BLOCKQUOTE><!--TOC subsubsection Automatic Method Recompilation-->
<H4 CLASS="subsubsection"><!--SEC ANCHOR -->2.23.3.3&#XA0;&#XA0;Automatic Method Recompilation</H4><!--SEC END --><P>
<A NAME="@concept18"></A>
<A NAME="@concept19"></A>
<A NAME="@concept20"></A></P><P>Methods using inline slot access can be automatically recompiled after
class changes. Two declarations control which methods are
automatically recompiled.</P><BLOCKQUOTE class=example><PRE>
declaim (ext:auto-compile specifier*)
declaim (ext:not-auto-compile specifier*)

specifier   ::= gf-name | (gf-name qualifier* (specializer*))
gf-name     ::= the name of a generic function
qualifier   ::= a method qualifier
specializer ::= a method specializer
</PRE></BLOCKQUOTE><P>If no specifier is given, auto-compilation is by default done/not done
for all methods of all generic functions using inline slot access;
current default is that it is not done. This global policy can be
overridden on a generic function and method basis. If
</P><TT class=code>specifier</TT><P> is a generic function name, it applies to all methods
of that generic function.</P><P>Examples:</P><BLOCKQUOTE class=example><PRE>
(declaim (ext:auto-compile foo))
(defmethod foo :around ((x bar)) ...)
</PRE></BLOCKQUOTE><P>The around-method </P><TT class=code>foo</TT><P> will be automatically recompiled because
the declamation applies to all methods with name </P><TT class=code>foo</TT><P>.</P><BLOCKQUOTE class=example><PRE>
(declaim (ext:auto-compile (foo (bar))))
(defmethod foo :around ((x bar)) ...)
(defmethod foo ((x bar)) ...)
</PRE></BLOCKQUOTE><P>The around-method will not be automatically recompiled, but the
primary method will.</P><BLOCKQUOTE class=example><PRE>
(declaim (ext:auto-compile foo))
(declaim (ext:not-auto-compile (foo :around (bar)))  
(defmethod foo :around ((x bar)) ...)
(defmethod foo ((x bar)) ...)
</PRE></BLOCKQUOTE><P>The around-method will not be automatically recompiled, because it
is explicitly declaimed not to be. The primary method will be
automatically recompiled because the first declamation applies to
it.</P><P>Auto-recompilation works by recording method bodies using inline slot
access. When PCL determines that a recompilation is necessary, a
</P><TT class=code>defmethod</TT><P> form is constructed and evaluated.</P><P>Auto-compilation can only be done for methods defined in a null
lexical environment. PCL prints a warning and doesn&#X2019;t record the
method body if a method using inline slot access is defined in a
non-null lexical environment. Instead of doing a recompilation on
itself, PCL will then print a warning that the method must be
recompiled manually when classes are changed.</P><!--TOC subsection Inlining Methods in Effective Methods-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc63">2.23.4</A>&#XA0;&#XA0;Inlining Methods in Effective Methods</H3><!--SEC END --><P>
<A NAME="@concept21"></A>
<A NAME="@concept22"></A>
<A NAME="@concept23"></A>
<A NAME="@concept24"></A></P><P>When a generic function is called, an effective method is constructed
from applicable methods. The effective method is called with the
original arguments, and itself calls applicable methods according to
the generic function&#X2019;s method combination. Some of the function call
overhead in effective methods can be removed by inlining methods in
effective methods, at the expense of increased code size.</P><P>Inlining of methods is controlled by the usual </P><TT class=code>inline</TT><P>
declaration. In the following example, both </P><TT class=code>foo</TT><P> methods shown
will be inlined in effective methods:</P><BLOCKQUOTE class=example><PRE>
(declaim (inline (method foo (foo))
                 (method foo :before (foo))))
(defmethod foo ((x foo)) ...)
(defmethod foo :before ((x foo)) ...)
</PRE></BLOCKQUOTE><P>Please note that this form of inlining has no noticeable effect for
effective methods that consist of a primary method only, which doesn&#X2019;t
have keyword arguments. In such cases, PCL uses the primary method
directly for the effective method.</P><P>When the definition of an inlined method is changed, effective methods
are <B>not</B> automatically updated to reflect the change. This is
just as it is when inlining normal functions. Different from the
normal case is that users do not have direct access to effective
methods, as it would be the case when a function is inlined somewhere
else. Because of this, the function </P><TT class=code>pcl:flush-emf-cache</TT><P> is
provided for forcing such an update of effective methods.</P><P><BR>
<A NAME="@funs81"></A><A NAME="FN:flush-emf-cache"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>pcl:</TT><TT class=function-name>flush-emf-cache</TT> &amp;optional gf &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Flush cached effective method functions. If <TT class=code>gf</TT> is supplied,
it should be a generic function metaobject or the name of a generic
function, and this function flushes all cached effective methods for
the given generic function. If <TT class=code>gf</TT> is not supplied, all
cached effective methods are flushed.
</BLOCKQUOTE><P><BR>
<A NAME="@vars20"></A><A NAME="VR:inline-methods-in-emfs"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>pcl::</TT><TT class=function-name>*inline-methods-in-emfs*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
If true, the default, perform method inlining as described above.
If false, don&#X2019;t.
</BLOCKQUOTE><!--TOC subsection Effective Method Precomputation-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc64">2.23.5</A>&#XA0;&#XA0;Effective Method Precomputation</H3><!--SEC END --><P>
<A NAME="@concept25"></A>
<A NAME="@concept26"></A>
<A NAME="@concept27"></A></P><P>When a generic function is called, the generic function&#X2019;s
discriminating function computes the set of methods applicable to
actual arguments and constructs an effective method function from
applicable methods, using the generic function&#X2019;s method combination.</P><P>Effective methods can be precomputed at method load time instead of
when the generic function is called depending on the value of
</P><TT class=code>pcl:*max-emf-precomputation-methods*</TT><P>.</P><P><BR>
<A NAME="@vars21"></A><A NAME="VR:*max-emf-precomputation-methods*"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>pcl:</TT><TT class=function-name>**max-emf-precomputation-methods**</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
If nonzero, the default value is 100, precompute effective methods
when methods are loaded, and the method&#X2019;s generic function has less
than the specified number of methods.<P>If zero, compute effective methods only when the generic function is
called.
</P></BLOCKQUOTE><!--TOC subsection Sealing-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc65">2.23.6</A>&#XA0;&#XA0;Sealing</H3><!--SEC END --><P>
<A NAME="@concept28"></A>
<A NAME="@concept29"></A>
<A NAME="@concept30"></A>
<A NAME="@concept31"></A></P><P>Support for sealing classes and generic functions have been
implemented. Please note that this interface is subject to change.</P><P><BR>
<A NAME="@funs82"></A><A NAME="FN:seal"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>pcl:</TT><TT class=function-name>seal</TT> name (var) <TT class=code>&amp;rest</TT> specifiers &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Seal <TT class=code>name</TT> with respect to the given specifiers; <TT class=code>name</TT>
can be the name of a class or generic-function.<P>Supported specifiers are </P><TT class=code>:subclasses</TT><P> for classes,
which prevents changing subclasses of a class, and </P><TT class=code>:methods</TT><P>
which prevents changing the methods of a generic function.</P><P>Sealing violations signal an error of type </P><TT class=code>pcl:sealed-error</TT><P>.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs83"></A><A NAME="FN:unseal"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>pcl:</TT><TT class=function-name>unseal</TT> name-or-object &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Remove seals from <TT class=code>name-or-object</TT>.
</BLOCKQUOTE><!--TOC subsection Method Tracing and Profiling-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc66">2.23.7</A>&#XA0;&#XA0;Method Tracing and Profiling</H3><!--SEC END --><P>
<A NAME="sec:method-tracing"></A>
<A NAME="@concept32"></A>
<A NAME="@concept33"></A>
<A NAME="@concept34"></A>
<A NAME="@concept35"></A>
<A NAME="@concept36"></A>
<A NAME="@concept37"></A></P><P>Methods can be traced with </P><TT class=code>trace</TT><P>, using function names of the
form </P><TT class=code>(method &lt;name&gt; &lt;qualifiers&gt; &lt;specializers&gt;)</TT><P>. Example:</P><BLOCKQUOTE class=example><PRE>
(defmethod foo ((x integer)) x)
(defmethod foo :before ((x integer)) x)

(trace (method foo (integer)))
(trace (method foo :before (integer)))
(untrace (method foo :before (integer)))
</PRE></BLOCKQUOTE><TT class=code>trace</TT><P> and </P><TT class=code>untrace</TT><P> also allow a name specifier
</P><TT class=code>:methods gf-form</TT><P> for tracing all methods of a generic function:</P><BLOCKQUOTE class=example><PRE>
(trace :methods &#X2019;foo)
(untrace :methods &#X2019;foo)
</PRE></BLOCKQUOTE><P>Methods can also be specified for the </P><TT class=code>:wherein</TT><P> option to
</P><TT class=code>trace</TT><P>. Because this option is a name or a list of names,
methods must be specified as a list. Thus, to trace all calls of
</P><TT class=code>foo</TT><P> from the method </P><TT class=code>bar</TT><P> specialized on integer argument,
use
</P><BLOCKQUOTE class=example><PRE>
  (trace foo :wherein ((method bar (integer))))
</PRE></BLOCKQUOTE><P>
Before and after methods are supported as well:
</P><BLOCKQUOTE class=example><PRE>
  (trace foo :wherein ((method bar :before (integer))))
</PRE></BLOCKQUOTE><P>Method profiling is done analogously to </P><TT class=code>trace</TT><P>:</P><BLOCKQUOTE class=example><PRE>
(defmethod foo ((x integer)) x)
(defmethod foo :before ((x integer)) x)

(profile:profile (method foo (integer)))
(profile:profile (method foo :before (integer)))
(profile:unprofile (method foo :before (integer)))

(profile:profile :methods &#X2019;foo)
(profile:unprofile :methods &#X2019;foo)

(profile:profile-all :methods t)
</PRE></BLOCKQUOTE><!--TOC subsection Misc-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc67">2.23.8</A>&#XA0;&#XA0;Misc</H3><!--SEC END --><P>
<A NAME="@concept38"></A></P><P><BR>
<A NAME="@vars22"></A><A NAME="VR:compile-interpreted-methods-p"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>pcl::</TT><TT class=function-name>*compile-interpreted-methods-p*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
This variable controls compilation of interpreted method functions,
e.g. for methods defined interactively at the REPL. Default is
true, that is, method functions are compiled.
</BLOCKQUOTE><!--TOC section Differences from ANSI Common Lisp-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc68">2.24</A>&#XA0;&#XA0;Differences from ANSI Common Lisp</H2><!--SEC END --><P>
This section describes some of the known differences between CMUCL
and ANSI Common Lisp. Some may be non-compliance issues; same may be
extensions.</P><!--TOC subsection Extensions-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc69">2.24.1</A>&#XA0;&#XA0;Extensions</H3><!--SEC END --><P><BR>
<A NAME="@funs84"></A><A NAME="FN:constantly"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>constantly</TT> value &amp;optional val1 val2 &amp;rest
more-values &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
As an extension, CMUCL allows <TT class=code>constantly</TT> to accept more
than one value which are returned as multiple values.
</BLOCKQUOTE><!--TOC section Function Wrappers-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc70">2.25</A>&#XA0;&#XA0;Function Wrappers</H2><!--SEC END --><P>
<A NAME="@concept39"></A>
<A NAME="@concept40"></A></P><P>Function wrappers, fwrappers for short, are a facility for efficiently
encapsulating functions<SUP><A NAME="text3" HREF="#note3">3</A></SUP>.</P><P>Functions in CMUCL are represented by </P><TT class=code>kernel:fdefn</TT><P>
objects. Each </P><TT class=code>fdefn</TT><P> object contains a reference to its
function&#X2019;s actual code, which we call the function&#X2019;s primary function.</P><P>A function wrapper replaces the primary function in the </P><TT class=code>fdefn</TT><P>
object with a function of its own, and records the original function
in an fwrapper object, a funcallable instance. Thus, when the
function is called, the fwrapper gets called, which in turn might call
the primary function, or a previously installed fwrapper that was
found in the </P><TT class=code>fdefn</TT><P> object when the second fwrapper was
installed.</P><P>Example:</P><BLOCKQUOTE CLASS=lisp> <PRE>
(use-package :fwrappers)

(define-fwrapper foo (x y)
  (format t "x = ~s, y = ~s, user-data = ~s~%"
          x y (fwrapper-user-data fwrapper))
  (let ((value (call-next-function)))
    (format t "value = ~s~%" value)
    value))

(defun bar (x y)
  (+ x y))

(fwrap &#X2019;bar #&#X2019;foo :type &#X2019;foo :user-data 42)

(bar 1 2)
 =&gt;
 x = 1, y = 2, user-data = 42
 value = 3
 3   
</PRE></BLOCKQUOTE><P>Fwrappers are used in the implementation of </P><TT class=code>trace</TT><P> and
</P><TT class=code>profile</TT><P>.</P><P>Please note that </P><TT class=code>fdefinition</TT><P> always returns the primary
definition of a function; if a function is fwrapped,
</P><TT class=code>fdefinition</TT><P> returns the primary function stored in the
innermost fwrapper object. Likewise, if a function is fwrapped,
</P><TT class=code>(setf fdefinition)</TT><P> will set the primary function in the
innermost fwrapper.</P><P><BR>
<A NAME="@funs85"></A><A NAME="FN:define-fwrapper"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>fwrappers:</TT><TT class=function-name>define-fwrapper</TT> name lambda-list <TT class=code>&amp;body</TT> body &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
This macro is like <TT class=code>defun</TT>, but defines a function named
<TT class=variable>name</TT> that can be used as an fwrapper definition.<P>In </P><TT class=variable>body</TT><P>, the symbol </P><TT class=code>fwrapper</TT><P> is bound to the current
fwrapper object.</P><P>The macro </P><TT class=code>call-next-function</TT><P> can be used to invoke the next
fwrapper, or the primary function that is being fwrapped. When
called with no arguments, </P><TT class=code>call-next-function</TT><P> invokes the next
function with the original arguments passed to the fwrapper, unless
you modify one of the parameters. When called with arguments,
</P><TT class=code>call-next-function</TT><P> invokes the next function with the given
arguments.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs86"></A><A NAME="FN:fwrap"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>fwrappers:</TT><TT class=function-name>fwrap</TT> function-name fwrapper &amp;key type
user-data &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
This function wraps function <TT class=code>function-name</TT> in an fwrapper
<TT class=variable>fwrapper</TT> which was defined with <TT class=code>define-fwrapper</TT>.<P>The value of </P><TT class=variable>type</TT><P>, if supplied, is used as an identifying
tag that can be used in various other operations.</P><P>The value of </P><TT class=variable>user-data</TT><P> is stored as user-supplied data in the
fwrapper object that is created for the function encapsulation.
User-data is accessible in the body of fwrappers defined with
</P><TT class=code>define-fwrapper</TT><P> as </P><TT class=code>(fwrapper-user-data fwrapper)</TT><P>.</P><P>Value is the fwrapper object created.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs87"></A><A NAME="FN:funwrap"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>fwrappers:</TT><TT class=function-name>funwrap</TT> function-name &amp;key type test &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Remove fwrappers from the function named <TT class=variable>function-name</TT>. If
<TT class=variable>type</TT> is supplied, remove fwrappers whose type is <TT class=code>equal</TT>
to <TT class=variable>type</TT>. If <TT class=variable>test</TT> is supplied, remove fwrappers
satisfying <TT class=variable>test</TT>.
</BLOCKQUOTE><P><BR>
<A NAME="@funs88"></A><A NAME="FN:find-fwrapper"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>fwrappers:</TT><TT class=function-name>find-fwrapper</TT> function-name &amp;key type test &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Find an fwrapper of <TT class=variable>function-name</TT>. If <TT class=variable>type</TT> is supplied,
find an fwrapper whose type is <TT class=code>equal</TT> to <TT class=variable>type</TT>. If
<TT class=variable>test</TT> is supplied, find an fwrapper satisfying <TT class=variable>test</TT>.
</BLOCKQUOTE><P><BR>
<A NAME="@funs89"></A><A NAME="FN:update-fwrapper"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>fwrappers:</TT><TT class=function-name>update-fwrapper</TT> fwrapper &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Update the funcallable instance function of the fwrapper object
<TT class=variable>fwrapper</TT> from the definition of its function that was 
defined with <TT class=code>define-fwrapper</TT>. This can be used to update
fwrappers after changing a <TT class=code>define-fwrapper</TT>.
</BLOCKQUOTE><P><BR>
<A NAME="@funs90"></A><A NAME="FN:update-fwrappers"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>fwrappers:</TT><TT class=function-name>update-fwrappers</TT> function-name &amp;key type test &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Update fwrappers of <TT class=variable>function-name</TT>; see <TT class=code>update-fwrapper</TT>.
If <TT class=variable>type</TT> is supplied, update fwrappers whose type is
<TT class=code>equal</TT> to <TT class=variable>type</TT>. If <TT class=variable>test</TT> is supplied, update fwrappers
satisfying <TT class=variable>test</TT>.
</BLOCKQUOTE><P><BR>
<A NAME="@funs91"></A><A NAME="FN:set-fwrappers"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>fwrappers:</TT><TT class=function-name>set-fwrappers</TT> function-name fwrappers &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Set <TT class=variable>function-names</TT>&#X2019;s fwrappers to elements of the list
<TT class=variable>fwrappers</TT>, which is assumed to be ordered from outermost to
innermost. <TT class=variable>fwrappers</TT> null means remove all fwrappers.
</BLOCKQUOTE><P><BR>
<A NAME="@funs92"></A><A NAME="FN:list-fwrappers"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>fwrappers:</TT><TT class=function-name>list-fwrappers</TT> function-name &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Return a list of all fwrappers of <TT class=variable>function-name</TT>, ordered
from outermost to innermost.
</BLOCKQUOTE><P><BR>
<A NAME="@funs93"></A><A NAME="FN:push-fwrapper"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>fwrappers:</TT><TT class=function-name>push-fwrapper</TT> fwrapper function-name &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Prepend fwrapper <TT class=variable>fwrapper</TT> to the definition of
<TT class=variable>function-name</TT>. Signal an error if <TT class=variable>function-name</TT> is an
undefined function.
</BLOCKQUOTE><P><BR>
<A NAME="@funs94"></A><A NAME="FN:delete-fwrapper"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>fwrappers:</TT><TT class=function-name>delete-fwrapper</TT> fwrapper function-name &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Remove fwrapper <TT class=variable>fwrapper</TT> from the definition of
<TT class=variable>function-name</TT>. Signal an error if <TT class=variable>function-name</TT> is an
undefined function.
</BLOCKQUOTE><P><BR>
<A NAME="@funs95"></A><A NAME="FN:do-fwrappers"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>fwrappers:</TT><TT class=function-name>do-fwrappers</TT> (var fdefn <TT class=code>&amp;optional</TT>
result) <TT class=code>&amp;body</TT> body &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Evaluate <TT class=variable>body</TT> with <TT class=variable>var</TT> bound to consecutive fwrappers of
<TT class=variable>fdefn</TT>. Return <TT class=variable>result</TT> at the end. Note that <TT class=variable>fdefn</TT>
must be an <TT class=code>fdefn</TT> object. You can use
<TT class=code>kernel:fdefn-or-lose</TT>, for instance, to get the <TT class=code>fdefn</TT>
object from a function name.
</BLOCKQUOTE><!--TOC section Dynamic-Extent Declarations-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc71">2.26</A>&#XA0;&#XA0;Dynamic-Extent Declarations</H2><!--SEC END --><P>
<A NAME="@concept41"></A></P><P><EM>Note: As of the 19a release, </EM></P><TT class=code><EM>dynamic-extent</EM></TT><P><EM> is
unfortunately disabled by default. It is known to cause some issues
with CLX and Hemlock. The cause is not known, but causes random
errors and brokeness. Enable at your own risk. However, it is safe
enough to build all of CMUCL without problems.</EM></P><P>On x86 and sparc, CMUCL can exploit </P><TT class=code>dynamic-extent</TT><P>
declarations by allocating objects on the stack instead of the heap.</P><P>You can tell CMUCL to trust or not trust </P><TT class=code>dynamic-extent</TT><P>
declarations by setting the variable
</P><TT class=variable>*trust-dynamic-extent-declarations*</TT><P>.</P><P><BR>
<A NAME="@vars23"></A><A NAME="VR:trust-dynamic-extent-declarations"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>ext:</TT><TT class=function-name>*trust-dynamic-extent-declarations*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
If the value of <TT class=variable>*trust-dynamic-extent-declarations*</TT> is 
<TT class=code>NIL</TT>, <TT class=code>dynamic-extent</TT> declarations are effectively
ignored.<P>If the value of this variable is a function, the function is called
with four arguments to determine if a </P><TT class=code>dynamic-extent</TT><P> 
declaration should be trusted. The arguments are the safety,
space, speed, and debug settings at the point where the 
</P><TT class=code>dynamic-extent</TT><P> declaration is used. If the function
returns true, the declaration is trusted, otherwise it is not
trusted.</P><P>In all other cases, </P><TT class=code>dynamic-extent</TT><P> declarations are
trusted.
</P></BLOCKQUOTE><P>Please note that stack-allocation is inherently unsafe. If you make a
mistake, and a stack-allocated object or part of it escapes, CMUCL
is likely to crash, or format your hard disk.</P><!--TOC subsection <TT class=code>&amp;rest</TT> argument lists-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc72">2.26.1</A>&#XA0;&#XA0;<TT class=code>&amp;rest</TT> argument lists</H3><!--SEC END --><P>
<A NAME="@concept42"></A></P><P>Rest argument lists can be allocated on the stack by declaring the
rest argument variable </P><TT class=code>dynamic-extent</TT><P>. Examples:</P><BLOCKQUOTE CLASS=lisp> <PRE>
(defun foo (x &amp;rest rest)
  (declare (dynamic-extent rest))
  ...)

(defun bar ()
  (lambda (&amp;rest rest)
    (declare (dynamic-extent rest))
    ...))
</PRE></BLOCKQUOTE><!--TOC subsection Closures-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc73">2.26.2</A>&#XA0;&#XA0;Closures</H3><!--SEC END --><P>
<A NAME="@concept43"></A></P><P>Closures for local functions can be allocated on the stack if the
local function is declared </P><TT class=code>dynamic-extent</TT><P>, and the closure
appears as an argument in the call of a named function. In the
example:</P><BLOCKQUOTE CLASS=lisp> <PRE>
(defun foo (x)
  (flet ((bar () x))
    (declare (dynamic-extent #&#X2019;bar))
    (baz #&#X2019;bar)))
</PRE></BLOCKQUOTE><P>the closure passed to function </P><TT class=code>baz</TT><P> is allocated on the stack.
Likewise in the example:</P><BLOCKQUOTE CLASS=lisp> <PRE>
(defun foo (x)
  (flet ((bar () x))
    (baz #&#X2019;bar)
    (locally (declare (dynamic-extent #&#X2019;bar))
      (baz #&#X2019;bar))))
</PRE></BLOCKQUOTE><P><A NAME="@concept44"></A></P><P>Stack-allocation of closures can also automatically take place when
calling certain known CL functions taking function arguments, for
example </P><TT class=code>some</TT><P> or </P><TT class=code>find-if</TT><P>.</P><!--TOC subsection <TT class=code>list</TT>, <TT class=code>list*</TT>, and <TT class=code>cons</TT>-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc74">2.26.3</A>&#XA0;&#XA0;<TT class=code>list</TT>, <TT class=code>list*</TT>, and <TT class=code>cons</TT></H3><!--SEC END --><P>
<A NAME="@concept45"></A></P><P>New conses allocated by </P><TT class=code>list</TT><P>, </P><TT class=code>list*</TT><P>, or </P><TT class=code>cons</TT><P>
which are used to initialize variables can be allocated from the stack
if the variables are declared </P><TT class=code>dynamic-extent</TT><P>. In the case of
</P><TT class=code>cons</TT><P>, only the outermost cons cell is allocated from the stack;
this is an arbitrary restriction.</P><BLOCKQUOTE CLASS=lisp> <PRE>
(let ((x (list 1 2))
      (y (list* 1 2 x))
      (z (cons 1 (cons 2 nil))))
  (declare (dynamic-extent x y z))
  ...
  (setq x (list 2 3))
  ...)
</PRE></BLOCKQUOTE><P>Please note that the </P><TT class=code>setq</TT><P> of </P><TT class=code>x</TT><P> in the example program
assigns to </P><TT class=code>x</TT><P> a list that is allocated from the heap. This is
another arbitrary restriction that exists because other Lisps behave
that way.</P><!--TOC section Modular Arithmetic-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc75">2.27</A>&#XA0;&#XA0;Modular Arithmetic</H2><!--SEC END --><P>
<A NAME="@concept46"></A></P><P>This section is mostly taken, with permission, from the documentation
for SBCL.</P><P>Some numeric functions have a property: </P><TT class=code>N</TT><P> lower bits of
the result depend only on </P><TT class=code>N</TT><P> lower bits of (all or some)
arguments. If the compiler sees an expression of form </P><TT class=code>(logand
exp mask)</TT><P>, where </P><TT class=code>exp</TT><P> is a tree of such &#X201C;good&#X201D; functions
and </P><TT class=code>mask</TT><P> is known to be of type </P><TT class=code>(unsigned-byte
w)</TT><P>, where </P><TT class=code>w</TT><P> is a "good" width, all intermediate results
will be cut to </P><TT class=code>w</TT><P> bits (but it is not done for variables
and constants!). This often results in an ability to use simple
machine instructions for the functions.</P><P>Consider an example.
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(defun i (x y)
  (declare (type (unsigned-byte 32) x y))
  (ldb (byte 32 0) (logxor x (lognot y))))
</PRE></BLOCKQUOTE><P>
The result of </P><TT class=code>(lognot y)</TT><P> will be negative and of
type </P><TT class=code>(signed-byte 33)</TT><P>, so a naive implementation on a 32-bit
platform is unable to use 32-bit arithmetic here. But modular
arithmetic optimizer is able to do it: because the result is cut down
to 32 bits, the compiler will replace </P><TT class=code>logxor</TT><P>
and </P><TT class=code>lognot</TT><P> with versions cutting results to 32 bits, and
because terminals (here&#X2014;expressions </P><TT class=code>x</TT><P> and </P><TT class=code>y</TT><P>)
are also of type </P><TT class=code>(unsigned-byte 32)</TT><P>, 32-bit machine
arithmetic can be used.</P><P>Currently &#X201C;good&#X201D; functions
are </P><TT class=code>+</TT><P>, </P><TT class=code>-</TT><P>, </P><TT class=code>*</TT><P>; </P><TT class=code>logand</TT><P>, </P><TT class=code>logior</TT><P>,
</P><TT class=code>logxor</TT><P>, </P><TT class=code>lognot</TT><P> and their combinations;
and </P><TT class=code>ash</TT><P> with the positive second argument. &#X201C;Good&#X201D; widths
are 32 on HPPA, MIPS, PPC, Sparc and X86 and 64 on Alpha. While it is
possible to support smaller widths as well, currently it is not
implemented.</P><P>A more extensive description of modular arithmetic can be found in the
paper &#X201C;Efficient Hardware Arithmetic in Common Lisp&#X201D; by Alexey
Dejneka, and Christophe Rhodes, to be published.</P><!--TOC section Extension to REQUIRE-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc76">2.28</A>&#XA0;&#XA0;Extension to REQUIRE</H2><!--SEC END --><P>
<A NAME="@concept47"></A></P><P>The behavior of </P><TT class=code>require</TT><P> when called with only one argument is
implementation-defined. In CMUCL, functions from the list
</P><TT class=variable>*module-provider-functions*</TT><P> are called in order with the
stringified module name as the argument. The first function to return
non-</P><TT class=variable>NIL</TT><P> is assumed to have loaded the module.</P><P>By default the functions </P><TT class=code>module-provide-cmucl-defmodule</TT><P> and
</P><TT class=code>module-provide- cmucl-library</TT><P> are on this list of functions, in
that order.</P><P><BR>
<A NAME="@vars24"></A><A NAME="VR:module-provider-functions"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>ext:</TT><TT class=function-name>*module-provider-functions*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
This is a list of functions taking a single argument.
<TT class=code>require</TT> calls each function in turn with the stringified
module name. The first function to return non-<TT class=variable>NIL</TT> indicates
that the module has been loaded. The remaining functions, if any,
are not called.<P>To add new providers, push the new provider function onto the
beginning of this list.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs96"></A><A NAME="FN:defmodule"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>ext:</TT><TT class=function-name>defmodule</TT> name <TT class=code>&amp;rest</TT> files &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Defines a module by registering the files that need to be loaded
when the module is required. If <TT class=variable>name</TT> is a symbol, its print
name is used after downcasing it.
</BLOCKQUOTE><P><BR>
<A NAME="@funs97"></A><A NAME="FN:module-provide-cmucl-defmodule"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>ext:</TT><TT class=function-name>module-provide-cmucl-defmodule</TT> module-name &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
This function is the module-provider for modules registered by a
<TT class=code>ext:defmodule</TT> form. 
</BLOCKQUOTE><P><BR>
<A NAME="@funs98"></A><A NAME="FN:module-provide-cmucl-library"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>ext:</TT><TT class=function-name>module-provide-cmucl-library</TT> module-name &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
This function is the module-provider for CMUCL&#X2019;s libraries,
including Gray streams, simple streams, CLX, CLM, Hemlock,
<EM>etc</EM>.<P>This function causes a file to be loaded whose name is formed by
merging the search-list &#X201C;modules:&#X201D; and the concatenation of
module-name with the suffix &#X201C;-LIBRARY&#X201D;. Note that both the
module-name and the suffix are each, separately, converted from
:case :common to :case :local. This merged name will be probed with
both a .lisp and .fasl extensions, calling </P><TT class=code>LOAD</TT><P> if it exists.
</P></BLOCKQUOTE><!--TOC section Localization-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc77">2.29</A>&#XA0;&#XA0;Localization</H2><!--SEC END --><P>
<A NAME="sec:localization"></A></P><P>CMUCL support localization where messages can be presented in the
native language. This is done in the style of </P><TT class=code>gettext</TT><P> which
marks strings that are to be translated and provides the lookup to
convert the string to the specified language.</P><P>All messages from CMUCL can be translated but as of this writing,
the only complete translation is a Pig Latin translation done by
machine. There are a few messages translated to Korean.</P><P>In general, translatable strings are marked as such by using the
functions </P><TT class=code>intl:gettext</TT><P> and </P><TT class=code>intl:ngettext</TT><P> or by using the
reader macros <CODE>_</CODE> or <CODE>_N</CODE>. When loading or compiling, such
strings are recorded for translation. At runtime, such strings are
looked in and the translation is returned. Doc strings do not need to
be noted in any way; the are automatically noted for translation.</P><P>By default, recording of translatable strings is disabled. To enable
recording of strings, call </P><TT class=code>intl:translation-enable</TT><P>.</P><!--TOC subsection Dictionary-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc78">2.29.1</A>&#XA0;&#XA0;Dictionary</H3><!--SEC END --><P>
<A NAME="sec:localization-dictionary"></A></P><P><BR>
<A NAME="@funs99"></A><A NAME="FN:translation-enable"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>intl:</TT><TT class=function-name>translation-enable</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Enable recording of translatable strings.
</BLOCKQUOTE><P><BR>
<A NAME="@funs100"></A><A NAME="FN:translation-disable"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>intl:</TT><TT class=function-name>translation-disable</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Disablle recording of translatable strings.
</BLOCKQUOTE><P><BR>
<A NAME="@funs101"></A><A NAME="FN:setlocale"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>intl:</TT><TT class=function-name>setlocale</TT> <TT class=code>&amp;optional</TT> locale &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Sets the locale to the locale specified by <TT class=variable>locale</TT>. If
<TT class=variable>locale</TT> is not give or is <TT class=code>nil</TT>, the locale is determined by
look at the environment variables <TT class=code>LANGUAGE</TT>, <TT class=code>LC_ALL</TT>,
<TT class=code>LC_MESSAGES</TT>, or <TT class=code>LANG</TT>. If none of these are set, the
locale is unchanged.<P>The default locale is &#X201C;C&#X201D;.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs102"></A><A NAME="FN:textdomain"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>intl:</TT><TT class=function-name>textdomain</TT> domain &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Set the default domain to the domain specified by <TT class=variable>domain</TT>.
Typically, this only needs to be done at the top of each source
file. This is used to <TT class=code>gettext</TT> and <TT class=code>ngettext</TT> to set the
domain for the message string.
</BLOCKQUOTE><P><BR>
<A NAME="@funs103"></A><A NAME="FN:gettext"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>intl:</TT><TT class=function-name>gettext</TT> string &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Look up the specified string, <TT class=variable>string</TT>, in the current message
domain and return its translation.
</BLOCKQUOTE><P><BR>
<A NAME="@funs104"></A><A NAME="FN:dgettext"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>intl:</TT><TT class=function-name>dgettext</TT> domain string &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Look up the specified string, <TT class=variable>string</TT>, in the message domain,
<TT class=variable>domain</TT>. The translation is returned.<P>When compiled, this also function also records the string so that an
appropriate message template file can be created. (See
</P><TT class=code>intl::dump-pot-files</TT><P>.) 
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs105"></A><A NAME="FN:ngettext"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>intl:</TT><TT class=function-name>ngettext</TT> singular plural n &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Look up the singular or plural form of a message in the default
domain. The singular form is <TT class=variable>singular</TT>; the plural is
<TT class=variable>plural</TT>. The number of items is specified by <TT class=variable>n</TT> in case
the correct translation depends on the actual number of items.
</BLOCKQUOTE><P><BR>
<A NAME="@funs106"></A><A NAME="FN:dngettext"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>intl:</TT><TT class=function-name>dngettext</TT> domain singular plural n &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Look up the singular or plural form of a message in the specified
domain, <TT class=variable>domain</TT>. The singular form is <TT class=variable>singular</TT>; the
plural is <TT class=variable>plural</TT>. The number of items is specified by <TT class=variable>n</TT>
in case the correct translation depends on the actual number of
items.<P>When compiled, this also function also records the singular and
plural forms so that an appropriate message template file can be
created. (See </P><TT class=code>intl::dump-pot-files</TT><P>.)
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs107"></A><A NAME="FN:dump-pot-files"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>intl::</TT><TT class=function-name>dump-pot-files</TT> <TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline">c</SPAN>opyright
output-directory &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Dumps the translatable strings recorded by <TT class=code>dgettext</TT> and
<TT class=code>dngettext</TT>. The message template file (pot file) is written
to a file in the directory specified by <TT class=variable>output-directory</TT>, and
the name of the file is the domain of the string.<P>If </P><TT class=variable>copyright</TT><P> is specified, this is placed in the output file
as the copyright message.
</P></BLOCKQUOTE><P><BR>
<A NAME="@vars25"></A><A NAME="VR:locale-directories"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>intl:</TT><TT class=function-name>*locale-directories*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
This is a list of directory pathnames where the translations can be found.
</BLOCKQUOTE><P><BR>
<A NAME="@funs108"></A><A NAME="FN:install"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>intl:</TT><TT class=function-name>install</TT> <TT class=code>&amp;optional</TT> (rt *readtable*) &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Installs reader macros and comment reader into the specified
readtable as explained below. The readtable defaults to
<TT class=variable>*readtable*</TT>.
</BLOCKQUOTE><P>Two reader macros are also provided: </P><TT class=code>_&#X201D;</TT><P> and </P><TT class=code>_N&#X201D;</TT><P>. The
first is equivalent to wrapping </P><TT class=code>dgettext</TT><P> around the string.
The second returns the string, but also records the string. This is
needed when we want to record a docstring for translation or any other
string in a place where a macro or function call would be incorrect.</P><P>Also, the standard comment reader is extended to allow translator
comments to be saved and written to the messages template file so that
the translator may not need to look at the original source to
understand the string. Any comment line that begins with exactly
<CODE>"TRANSLATORS: "</CODE> is saved. This means each translator comment
must be preceded by this string to be saved; the translator comment
ends at the end of each line.</P><!--TOC subsection Example Usage-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc79">2.29.2</A>&#XA0;&#XA0;Example Usage</H3><!--SEC END --><P>
<A NAME="sec:localization-usage"></A></P><P>Here is a simple example of how to localize your code. Let the file
</P><TT class=code>intl-ex.lisp</TT><P> contain:</P><BLOCKQUOTE class=example><PRE>

(intl:textdomain "example")  

(defun foo (x y)
  "Cool function foo of x and y"
  (let ((result (bar x y)))
    ;; TRANSLATORS:  One line comment about bar.
    (format t _"bar of ~A and ~A = ~A~%" x y result)
    #| TRANSLATORS:  Multiline comment about
    how many Xs there are
    |#
    (format t (intl:ngettext "There is one X"
                             "There are many Xs"
                             x))
    result))
</PRE></BLOCKQUOTE><P>The call to </P><TT class=code>textdomain</TT><P> sets the default domain for all
translatable strings following the call.</P><P>Here is a sample session for creating a template file:</P><BLOCKQUOTE class=example><PRE>
* (intl:install)

T
* (intl:translation-enable)

T
* (compile-file "intl-ex")

#P"/Volumes/share/cmucl/cvs/intl-ex.sse2f"
NIL
NIL
* (intl::dump-pot-files :output-directory "./")

Dumping 3 messages for domain "example"
NIL
*
</PRE></BLOCKQUOTE><P>When this file is compiled, all of the translatable strings are
recorded. This includes the docstring for </P><TT class=code>foo</TT><P>, the string for
the first </P><TT class=code>format</TT><P>, and the string marked by the call to
</P><TT class=code>intl:ngettext</TT><P>.</P><P>A file named &#X201C;example.pot&#X201D; in the directory &#X201C;./&#X201D; is created.
The contents of this file are:
</P><BLOCKQUOTE class=example><PRE>
#@ example

# SOME DESCRIPTIVE TITLE
# FIRST AUTHOR &lt;EMAIL@ADDRESS&gt;, YEAR
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: PACKAGE VERSION"
"Report-Msgid-Bugs-To: "
"PO-Revision-Date: YEAR-MO-DA HO:MI +ZONE"
"Last-Translator: FULL NAME &lt;EMAIL@ADDRESS&gt;"
"Language-Team: LANGUAGE &lt;LL@li.org&gt;"
"MIME-Version: 1.0"
"Content-Type: text/plain; charset=UTF-8"
"Content-Transfer-Encoding: 8bit"

#.  One line comment about bar.
#: intl-ex.lisp
msgid "bar of ~A and ~A = ~A~%"
msgstr ""

#.  Multiline comment about
    how many Xs there are
#: intl-ex.lisp
msgid "Cool function foo of x and y"
msgstr ""

#: intl-ex.lisp
msgid "There is one X"
msgid_plural "There are many Xs"
msgstr[0] ""

</PRE></BLOCKQUOTE><P>To finish the translation, a corresponding &#X201C;example.po&#X201D; file needs
to be created with the appropriate translations for the given
strings. This file must be placed in some directory that is included
in </P><TT class=code>intl:*locale-directories*</TT><P>.</P><P>Suppose the translation is done for Korean. Then the user can set the
environment variables appropriately or call </P><TT class=code>(intl:setlocale
"ko")</TT><P>. Note that the external format for the standard streams
needs to be set up appropriately too. It is up to the user to set
this correctly. Once this is all done, the output from the function
</P><TT class=code>foo</TT><P> will now be in Korean instead of English as in the original
source file.</P><P>For further information, we refer the reader to documentation on
<A HREF="http://www.gnu.org/software/gettext/manual/gettext.html">gettext</A>.
</P><!--TOC section Static Arrays-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc80">2.30</A>&#XA0;&#XA0;Static Arrays</H2><!--SEC END --><P>
<A NAME="sec:static-arrays"></A></P><P>CMUCL supports static arrays which are arrays that are not moved by
the garbage collector. To create such an array, use the
</P><TT class=code>:allocation</TT><P> option to </P><TT class=code>make-array</TT><P> with a value of
</P><TT class=code>:malloc</TT><P>. These arrays appear as normal Lisp arrays, but are
actually allocated from the </P><TT class=code>C</TT><P> heap (hence the </P><TT class=code>:malloc</TT><P>).
Thus, the number and size of such arrays are limited by the available
</P><TT class=code>C</TT><P> heap.</P><P>Also, only certain types of arrays can be allocated. The static array
cannot be adjustable and cannot be displaced to. The array must also
be a </P><TT class=code>simple-array</TT><P> of one dimension. The element type is also
constrained to be one of the types in
Table&#XA0;<A HREF="#tbl:static-array-types">2.3</A>.</P><BLOCKQUOTE CLASS="table"><DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV>
<DIV CLASS="center">
<TABLE BORDER=1 CELLSPACING=0 CELLPADDING=1><TR><TD ALIGN=center NOWRAP> <TT class=code>(unsigned-byte 8)</TT></TD></TR>
<TR><TD ALIGN=center NOWRAP> <TT class=code>(unsigned-byte 16)</TT></TD></TR>
<TR><TD ALIGN=center NOWRAP> <TT class=code>(unsigned-byte 32)</TT></TD></TR>
<TR><TD ALIGN=center NOWRAP> <TT class=code>(signed-byte 8)</TT></TD></TR>
<TR><TD ALIGN=center NOWRAP> <TT class=code>(signed-byte 16)</TT></TD></TR>
<TR><TD ALIGN=center NOWRAP> <TT class=code>(signed-byte 32)</TT></TD></TR>
<TR><TD ALIGN=center NOWRAP> <TT class=code>single-float</TT></TD></TR>
<TR><TD ALIGN=center NOWRAP> <TT class=code>double-float</TT></TD></TR>
<TR><TD ALIGN=center NOWRAP> <TT class=code>(complex single-float)</TT></TD></TR>
<TR><TD ALIGN=center NOWRAP> <TT class=code>(complex double-float)</TT></TD></TR>
</TABLE>
<DIV CLASS="caption"><TABLE CELLSPACING=6 CELLPADDING=0><TR><TD VALIGN=top ALIGN=left>Table 2.3: Allowed element types for static arrays</TD></TR>
</TABLE></DIV>
<A NAME="tbl:static-array-types"></A>
</DIV>
<DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV></BLOCKQUOTE><P>The arrays are properly handled by GC. GC will not move the arrays,
but they will be properly removed up if they become garbage.
</P><!--NAME extensions.html-->
<!--BEGIN NOTES chapter-->
<HR CLASS="ffootnoterule"><DL CLASS="thefootnotes"><DT CLASS="dt-thefootnotes">
<A NAME="note1" HREF="#text1">1</A></DT><DD CLASS="dd-thefootnotes">This
implementation was donated by Paul Foley
</DD><DT CLASS="dt-thefootnotes"><A NAME="note2" HREF="#text2">2</A></DT><DD CLASS="dd-thefootnotes">&#X201C;Mersenne
Twister: A 623-Dimensionally Equidistributed Uniform Pseudorandom
Number Generator,&#X201D; ACM Trans. on Modeling and Computer Simulation,
Vol. 8, No. 1, January 1998, pp.3&#X2013;30
</DD><DT CLASS="dt-thefootnotes"><A NAME="note3" HREF="#text3">3</A></DT><DD CLASS="dd-thefootnotes">This feature was independently
developed, but the interface is modelled after a similar feature in
Allegro. Some names, however, have been changed.
</DD></DL>
<!--END NOTES-->
<!--TOC chapter The Debugger-->
<H1 CLASS="chapter"><!--SEC ANCHOR --><A NAME="htoc81">Chapter&#XA0;3</A>&#XA0;&#XA0;The Debugger</H1><!--SEC END --><P>
<A NAME="@concept48"></A>
<A NAME="debugger"></A></P><DIV CLASS="center">
<B>by Robert MacLachlan</B>
</DIV><!--TOC section Debugger Introduction-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc82">3.1</A>&#XA0;&#XA0;Debugger Introduction</H2><!--SEC END --><P>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 Common Lisp debugger that:
</P><UL CLASS="itemize"><LI CLASS="li-itemize">Tells you when a variable doesn&#X2019;t have a value because it hasn&#X2019;t been
initialized yet or has already been deallocated, or</LI><LI CLASS="li-itemize">Can display the precise source location corresponding to a code
location in the debugged program.
</LI></UL><P>
These features allow the debugging of compiled code to be made almost
indistinguishable from interpreted code debugging.</P><P>The debugger is an interactive command loop that allows a user to examine
the function call stack. The debugger is invoked when:
</P><UL CLASS="itemize"><LI CLASS="li-itemize">A <A NAME="@types18"></A><TT class=code>serious-condition</TT> is signaled, and it is not handled, or</LI><LI CLASS="li-itemize"><A NAME="@funs109"></A><TT class=code>error</TT> is called, and the condition it signals is not handled, or</LI><LI CLASS="li-itemize">The debugger is explicitly invoked with the Common Lisp <A NAME="@funs110"></A><TT class=code>break</TT>
or <A NAME="@funs111"></A><TT class=code>debug</TT> functions.
</LI></UL><P><I>Note: there are two debugger interfaces in CMUCL: 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. See section&#XA0;</I><A HREF="#motif-interface"><I>2.9.1</I></A><I> for a very brief
discussion of the graphical interface.</I></P><P>When you enter the TTY debugger, it looks something like this:</P><BLOCKQUOTE class=example><PRE>
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]
</PRE></BLOCKQUOTE><P>The first group of lines describe what the error was that put us in the
debugger. In this case </P><TT class=code>car</TT><P> was called on </P><TT class=code>3</TT><P>. After </P><TT class=code>Restarts:</TT><P>
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.</P><!--TOC section The Command Loop-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc83">3.2</A>&#XA0;&#XA0;The Command Loop</H2><!--SEC END --><P>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: </P><TT class=code>help</TT><P> can be typed as
</P><TT class=code>h</TT><P>, </P><TT class=code>he</TT><P>, etc. For convenience, some commands have
ambiguous one-letter abbreviations: </P><TT class=code>f</TT><P> for </P><TT class=code>frame</TT><P>.</P><P>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 </P><TT class=code>list-locals</TT><P> command or the </P><TT class=code>debug:var</TT><P>
function, or you can wrap the variable in a </P><TT class=code>progn</TT><P> to hide it from
the command loop.</P><P>The debugger prompt is &#X201C;</P><TT class=variable>frame</TT><TT class=code>]</TT><P>&#X201D;, where </P><TT class=variable>frame</TT><P> 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.</P><P><A NAME="@concept49"></A> The debugger evaluates forms in the lexical
environment of the functions being debugged. The debugger can only
access variables. You can&#X2019;t </P><TT class=code>go</TT><P> or </P><TT class=code>return-from</TT><P> into a
function, and you can&#X2019;t call local functions. Special variable
references are evaluated with their current value (the innermost binding
around the debugger invocation)&#X2014;you don&#X2019;t get the value that the
special had in the current frame. See section&#XA0;<A HREF="#debug-vars">3.4</A> for more
information on debugger variable access.</P><!--TOC section Stack Frames-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc84">3.3</A>&#XA0;&#XA0;Stack Frames</H2><!--SEC END --><P>
<A NAME="@concept50"></A> <A NAME="@concept51"></A></P><P>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:
</P><UL CLASS="itemize"><LI CLASS="li-itemize">Variables (see section&#XA0;<A HREF="#debug-vars">3.4</A>), which are the values being operated
on, and</LI><LI CLASS="li-itemize">Arguments to the call (which are really just particularly interesting
variables), and</LI><LI CLASS="li-itemize">A current location (see section&#XA0;<A HREF="#source-locations">3.5</A>), 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.
</LI></UL><!--TOC subsection Stack Motion-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc85">3.3.1</A>&#XA0;&#XA0;Stack Motion</H3><!--SEC END --><P>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:

</P><DL CLASS="list"><DT CLASS="dt-list">
<TT class=code>up</TT><BR>
</DT><DD CLASS="dd-list">
Move up to the next higher frame. More recent function calls are considered
to be higher on the stack.</DD><DT CLASS="dt-list"><TT class=code>down</TT><BR>
</DT><DD CLASS="dd-list">
Move down to the next lower frame.</DD><DT CLASS="dt-list"><TT class=code>top</TT><BR>
</DT><DD CLASS="dd-list">
Move to the highest frame.</DD><DT CLASS="dt-list"><TT class=code>bottom</TT><BR>
</DT><DD CLASS="dd-list">
Move to the lowest frame.</DD><DT CLASS="dt-list"><TT class=code>frame</TT> [<I>n</I><BR>
</DT><DD CLASS="dd-list">]
Move to the frame with the specified number. Prompts for the number if not
supplied.</DD></DL><!--TOC subsection How Arguments are Printed-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc86">3.3.2</A>&#XA0;&#XA0;How Arguments are Printed</H3><!--SEC END --><P>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:</P><BLOCKQUOTE CLASS=lisp> <PRE>
(myfun (+ 3 4) &#X2019;a)
</PRE></BLOCKQUOTE><P>would look like this:</P><BLOCKQUOTE class=example><PRE>
(MYFUN 7 A)
</PRE></BLOCKQUOTE><P>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:</P><BLOCKQUOTE CLASS=lisp> <PRE>
(subseq "foo" 1)
</PRE></BLOCKQUOTE><P>would look like this:</P><BLOCKQUOTE class=example><PRE>
(SUBSEQ "foo" 1 3)
</PRE></BLOCKQUOTE><P>And this call:</P><BLOCKQUOTE CLASS=lisp> <PRE>
(string-upcase "test case")
</PRE></BLOCKQUOTE><P>would look like this:</P><BLOCKQUOTE class=example><PRE>
(STRING-UPCASE "test case" :START 0 :END NIL)
</PRE></BLOCKQUOTE><P>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.</P><TT class=code><TT class=code>&amp;rest</TT></TT><P> arguments are handled somewhat differently. The value of
the rest argument variable is displayed as the spread-out arguments to
the call, so:</P><BLOCKQUOTE CLASS=lisp> <PRE>
(format t "~A is a ~A." "This" &#X2019;test)
</PRE></BLOCKQUOTE><P>would look like this:</P><BLOCKQUOTE class=example><PRE>
(FORMAT T "~A is a ~A." "This" &#X2019;TEST)
</PRE></BLOCKQUOTE><P>Rest arguments cause an exception to the normal display of keyword
arguments in functions that have both </P><TT class=code><TT class=code>&amp;rest</TT></TT><P> and </P><TT class=code>&amp;key</TT><P>
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.</P><P>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
</P><TT class=code>#&lt;unused-arg&gt;</TT><P> instead of the value. Similarly, if for any of a number of
reasons (described in more detail in section <A HREF="#debug-vars">3.4</A>) the value of the
variable is unavailable or not known to be available, then
</P><TT class=code>#&lt;unavailable-arg&gt;</TT><P> will be printed instead of the argument value.</P><P>Printing of argument values is controlled by </P><TT class=code>*debug-print-level*</TT><P> and
<A NAME="@vars26"></A></P><TT class=code>*debug-print-length*</TT><P>.</P><!--TOC subsection Function Names-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc87">3.3.3</A>&#XA0;&#XA0;Function Names</H3><!--SEC END --><P>
<A NAME="@concept52"></A>
<A NAME="@concept53"></A></P><P>If a function is defined by </P><TT class=code>defun</TT><P>, </P><TT class=code>labels</TT><P>, or </P><TT class=code>flet</TT><P>, then the
debugger will print the actual function name after the open parenthesis, like:</P><BLOCKQUOTE class=example><PRE>
(STRING-UPCASE "test case" :START 0 :END NIL)
((SETF AREF) #\a "for" 1)
</PRE></BLOCKQUOTE><P>Otherwise, the function name is a string, and will be printed in quotes:</P><BLOCKQUOTE class=example><PRE>
("DEFUN MYFUN" BAR)
("DEFMACRO DO" (DO ((I 0 (1+ I))) ((= I 13))) NIL)
("SETQ *GC-NOTIFY-BEFORE*")
</PRE></BLOCKQUOTE><P>This string name is derived from the </P><TT class=code>def</TT><TT class=variable>mumble</TT><P> form
that encloses or expanded into the lambda, or the outermost enclosing
form if there is no </P><TT class=code>def</TT><TT class=variable>mumble</TT><P>.</P><!--TOC subsection Funny Frames-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc88">3.3.4</A>&#XA0;&#XA0;Funny Frames</H3><!--SEC END --><P>
<A NAME="@concept54"></A>
<A NAME="@concept55"></A>
<A NAME="@concept56"></A>
<A NAME="@concept57"></A>
<A NAME="@concept58"></A>
<A NAME="@concept59"></A></P><P>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.</P><P>These funny frames are flagged by printing &#X201C;</P><TT class=code>[</TT><TT class=variable>keyword</TT><TT class=code>]</TT><P>&#X201D; after the
parentheses. For example, this call:</P><BLOCKQUOTE CLASS=lisp> <PRE>
(car &#X2019;a &#X2019;b)
</PRE></BLOCKQUOTE><P>will look like this:</P><BLOCKQUOTE class=example><PRE>
(CAR 2 A) [:EXTERNAL]
</PRE></BLOCKQUOTE><P>And this call:</P><BLOCKQUOTE CLASS=lisp> <PRE>
(string-upcase "test case" :end)
</PRE></BLOCKQUOTE><P>would look like this:</P><BLOCKQUOTE class=example><PRE>
("DEFUN STRING-UPCASE" "test case" 335544424 1) [:OPTIONAL]
</PRE></BLOCKQUOTE><P>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 (see section&#XA0;<A HREF="#source-locations">3.5</A>.)</P><P>With recursive or block compiled functions
(see section&#XA0;<A HREF="#block-compilation">5.7</A>), an </P><TT class=code>:EXTERNAL</TT><P> 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 </P><TT class=code>:CLEANUP</TT><P> frames during the execution
of </P><TT class=code>unwind-protect</TT><P> cleanup code. Note that inline expansion and
open-coding affect what frames are present in the debugger, see
sections <A HREF="#debugger-policy">3.6</A> and <A HREF="#open-coding">4.8</A>.</P><!--TOC subsection Debug Tail Recursion-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc89">3.3.5</A>&#XA0;&#XA0;Debug Tail Recursion</H3><!--SEC END --><P>
<A NAME="debug-tail-recursion"></A>
<A NAME="@concept60"></A>
<A NAME="@concept61"></A></P><P>Both the compiler and the interpreter are &#X201C;properly tail recursive.&#X201D; If a
function call is in a tail-recursive position, the stack frame will be
deallocated <EM>at the time of the call</EM>, rather than after the call returns.
Consider this backtrace:
</P><BLOCKQUOTE class=example><PRE>
(BAR ...) 
(FOO ...)
</PRE></BLOCKQUOTE><P>
Because of tail recursion, it is not necessarily the case that
</P><TT class=code>FOO</TT><P> directly called </P><TT class=code>BAR</TT><P>. It may be that </P><TT class=code>FOO</TT><P> called
some other function </P><TT class=code>FOO2</TT><P> which then called </P><TT class=code>BAR</TT><P>
tail-recursively, as in this example:
</P><BLOCKQUOTE class=example><PRE>
(defun foo ()
  ...
  (foo2 ...)
  ...)

(defun foo2 (...)
  ...
  (bar ...))

(defun bar (...)
  ...)
</PRE></BLOCKQUOTE><P>Usually the elimination of tail-recursive frames makes debugging more
pleasant, since theses 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
<A HREF="#source-locations">3.5</A>.)</P><P>The elimination of tail-recursive frames can be prevented by disabling
tail-recursion optimization, which happens when the </P><TT class=code>debug</TT><P>
optimization quality is greater than </P><TT class=code>2</TT><P>
(see section&#XA0;<A HREF="#debugger-policy">3.6</A>.)</P><P>For a more thorough discussion of tail recursion, see section&#XA0;<A HREF="#tail-recursion">5.5</A>.</P><!--TOC subsection Unknown Locations and Interrupts-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc90">3.3.6</A>&#XA0;&#XA0;Unknown Locations and Interrupts</H3><!--SEC END --><P>
<A NAME="unknown-locations"></A>
<A NAME="@concept62"></A>
<A NAME="@concept63"></A>
<A NAME="@concept64"></A>
<A NAME="@concept65"></A></P><P>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 </P><TT class=variable>unknown</TT><P>. If the code
location for a frame is unknown, then some variables may be
inaccessible, and the source location cannot be precisely displayed.</P><P>There are three reasons why a code location could be unknown:
</P><UL CLASS="itemize"><LI CLASS="li-itemize">There is inadequate debug information due to the value of the <TT class=code>debug</TT>
optimization quality. See section&#XA0;<A HREF="#debugger-policy">3.6</A>.</LI><LI CLASS="li-itemize">The debugger was entered because of an interrupt such as <TT class=code>^<I>C</I></TT>.</LI><LI CLASS="li-itemize">A hardware error such as &#X201C;<TT class=code>bus error</TT>&#X201D; occurred in code that was
compiled unsafely due to the value of the <TT class=code>safety</TT> optimization
quality. See section&#XA0;<A HREF="#optimize-declaration">4.7.1</A>.
</LI></UL><P>In the last two cases, the values of argument variables are accessible,
but may be incorrect. See section&#XA0;<A HREF="#debug-var-validity">3.4.1</A> for more details on
when variable values are accessible.</P><P>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&#X2019;t be located. If this happens, return from the
interrupt and try again.</P><P>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.</P><!--TOC section Variable Access-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc91">3.4</A>&#XA0;&#XA0;Variable Access</H2><!--SEC END --><P>
<A NAME="debug-vars"></A>
<A NAME="@concept66"></A>
<A NAME="@concept67"></A></P><P>There are three ways to access the current frame&#X2019;s local variables in the
debugger. The simplest is to type the variable&#X2019;s name into the debugger&#X2019;s
read-eval-print loop. The debugger will evaluate the variable reference as
though it had appeared inside that frame.</P><P>The debugger doesn&#X2019;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.</P><P>When there are ambiguous variables, the evaluator assigns each one a
small integer identifier. The </P><TT class=code>debug:var</TT><P> function and the
</P><TT class=code>list-locals</TT><P> command use this identifier to distinguish between
ambiguous variables:

</P><DL CLASS="list"><DT CLASS="dt-list">
<TT class=code>list-locals</TT> <TT class=code>{<TT class=variable>prefix</TT>}</TT><BR>
</DT><DD CLASS="dd-list">This command prints the name and value of all variables in the current
frame whose name has the specified <TT class=variable>prefix</TT>. <TT class=variable>prefix</TT> may be a
string or a symbol. If no <TT class=variable>prefix</TT> is given, then all available
variables are printed. If a variable has a potentially ambiguous name,
then the name is printed with a &#X201C;<TT class=code>#</TT><TT class=variable>identifier</TT>&#X201D; suffix, where
<TT class=variable>identifier</TT> is the small integer used to make the name unique.
</DD></DL><P><BR>
<A NAME="@funs112"></A><A NAME="FN:var"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>debug:</TT><TT class=function-name>var</TT> <TT class=variable>name</TT> <TT class=code>&amp;optional</TT> <TT class=variable>identifier</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns the value of the variable in the current frame
with the specified </P><TT class=variable>name</TT><P>. If supplied, </P><TT class=variable>identifier</TT><P>
determines which value to return when there are ambiguous variables.</P><P>When </P><TT class=variable>name</TT><P> is a symbol, it is interpreted as the symbol name of
the variable, i.e. the package is significant. If </P><TT class=variable>name</TT><P> is an
uninterned symbol (gensym), then return the value of the uninterned
variable with the same name. If </P><TT class=variable>name</TT><P> is a string,
</P><TT class=code>debug:var</TT><P> interprets it as the prefix of a variable name, and
must unambiguously complete to the name of a valid variable.</P><P>This function is useful mainly for accessing the value of uninterned
or ambiguous variables, since most variables can be evaluated
directly.
</P></BLOCKQUOTE><!--TOC subsection Variable Value Availability-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc92">3.4.1</A>&#XA0;&#XA0;Variable Value Availability</H3><!--SEC END --><P>
<A NAME="debug-var-validity"></A>
<A NAME="@concept68"></A>
<A NAME="@concept69"></A>
<A NAME="@concept70"></A></P><P>The value of a variable may be unavailable to the debugger in portions of the
program where Common Lisp 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.</P><P>The one exception is this: if you interrupt (e.g., with </P><TT class=code>^<I>C</I></TT><P>) or if there is
an unexpected hardware error such as &#X201C;</P><TT class=code>bus error</TT><P>&#X201D; (which should only happen
in unsafe code), then the values displayed for arguments to the interrupted
frame might be incorrect.<SUP><A NAME="text4" HREF="#note4">1</A></SUP>
This exception applies only to the interrupted frame: any frame farther down
the stack will be fine.</P><P>The value of a variable may be unavailable for these reasons:
</P><UL CLASS="itemize"><LI CLASS="li-itemize">The value of the <TT class=code>debug</TT> 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
<TT class=code>debug</TT> is at least <TT class=code>2</TT>.</LI><LI CLASS="li-itemize">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 <TT class=code>debug</TT> optimization quality is <TT class=code>3</TT>.</LI><LI CLASS="li-itemize">The variable&#X2019;s name is an uninterned symbol (gensym). To save space, the
compiler only dumps debug information about uninterned variables when the
<TT class=code>debug</TT> optimization quality is <TT class=code>3</TT>.</LI><LI CLASS="li-itemize">The frame&#X2019;s location is unknown (see section&#XA0;<A HREF="#unknown-locations">3.3.6</A>) 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.</LI><LI CLASS="li-itemize">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 <TT class=code>compile-speed</TT>
optimization quality, but most source-level optimizations are done under all
compilation policies.
</LI></UL><P>Since it is especially useful to be able to get the arguments to a function,
argument variables are treated specially when the </P><TT class=code>speed</TT><P> optimization
quality is less than </P><TT class=code>3</TT><P> and the </P><TT class=code>debug</TT><P> quality is at least </P><TT class=code>1</TT><P>.
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, </P><TT class=code>debug</TT><P> must be at least </P><TT class=code>2</TT><P> for values to be
available, and even then, values are only available at known locations.</P><!--TOC subsection Note On Lexical Variable Access-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc93">3.4.2</A>&#XA0;&#XA0;Note On Lexical Variable Access</H3><!--SEC END --><P>
<A NAME="@concept71"></A></P><P>When the debugger command loop establishes variable bindings for available
variables, these variable bindings have lexical scope and dynamic
extent.<SUP><A NAME="text5" HREF="#note5">2</A></SUP> You can close over them, but such closures
can&#X2019;t be used as upward funargs.</P><P>You can also set local variables using </P><TT class=code>setq</TT><P>, 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.</P><!--TOC section Source Location Printing-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc94">3.5</A>&#XA0;&#XA0;Source Location Printing</H2><!--SEC END --><P>
<A NAME="source-locations"></A>
<A NAME="@concept72"></A></P><P>One of CMUCL&#X2019;s unique capabilities is source level debugging of compiled
code. These commands display the source location for the current frame:

</P><DL CLASS="list"><DT CLASS="dt-list">
<TT class=code>source</TT> <TT class=code>{<TT class=variable>context</TT>}</TT><BR>
</DT><DD CLASS="dd-list">This command displays the file that the current frame&#X2019;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 <TT class=variable>context</TT> is
specified, then it is an integer specifying the number of enclosing levels of
list structure to print.</DD><DT CLASS="dt-list"><TT class=code>vsource</TT> <TT class=code>{<TT class=variable>context</TT>}</TT><BR>
</DT><DD CLASS="dd-list">This command is identical to <TT class=code>source</TT>, except that it uses the
global values of <TT class=code>*print-level*</TT> and <TT class=code>*print-length*</TT> instead
of the debugger printing control variables <TT class=code>*debug-print-level*</TT>
and <TT class=code>*debug-print-length*</TT>.
</DD></DL><P>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 </P><TT class=code>*some-random-special*</TT><P>, then the innermost
enclosing evaluated form will be printed. Here are some possible
enclosing forms:
</P><BLOCKQUOTE class=example><PRE>
(let ((a *some-random-special*))
  ...)

(+ *some-random-special* ...)
</PRE></BLOCKQUOTE><P>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
</P><TT class=filename>/usr/me/mystuff.lisp</TT><P> looked like this:
</P><BLOCKQUOTE class=example><PRE>
(defmacro mymac ()
  &#X2019;(myfun))

(defun foo ()
  (mymac)
  ...)
</PRE></BLOCKQUOTE><P>
If </P><TT class=code>foo</TT><P> has called </P><TT class=code>myfun</TT><P>, and is waiting for it to return, then the
</P><TT class=code>source</TT><P> command would print:
</P><BLOCKQUOTE class=example><PRE>
; File: /usr/me/mystuff.lisp

(MYMAC)
</PRE></BLOCKQUOTE><P>
Note that the macro use was printed, not the actual function call form,
</P><TT class=code>(myfun)</TT><P>.</P><P>If enclosing source is printed by giving an argument to </P><TT class=code>source</TT><P> or
</P><TT class=code>vsource</TT><P>, then the actual source form is marked by wrapping it in a list
whose first element is </P><TT class=code>#:***HERE***</TT><P>. In the previous example, 
</P><TT class=code>source 1</TT><P> would print:
</P><BLOCKQUOTE class=example><PRE>
; File: /usr/me/mystuff.lisp

(DEFUN FOO ()
  (#:***HERE***
   (MYMAC))
  ...)
</PRE></BLOCKQUOTE><!--TOC subsection How the Source is Found-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc95">3.5.1</A>&#XA0;&#XA0;How the Source is Found</H3><!--SEC END --><P>If the code was defined from Common Lisp by </P><TT class=code>compile</TT><P> or
</P><TT class=code>eval</TT><P>, then the source can always be reliably located. If the
code was defined from a </P><TT class=code>fasl</TT><P> file created by
<A NAME="@funs113"></A></P><TT class=code>compile-file</TT><P>, 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.</P><P>The source file is opened using the </P><TT class=code>truename</TT><P> 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&#X2019;t
be located using this name, then the debugger gives up and signals an
error.</P><P>If the source file can be found, but has been modified since the time it was
compiled, the debugger prints this warning:
</P><BLOCKQUOTE class=example><PRE>
; File has been modified since compilation:
;   <TT class=variable>filename</TT>
; Using form offset instead of character position.
</PRE></BLOCKQUOTE><P>
where </P><TT class=variable>filename</TT><P> 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:
</P><UL CLASS="itemize"><LI CLASS="li-itemize">No top-level forms before the top-level form containing the source have been
added or deleted, and</LI><LI CLASS="li-itemize">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.)
</LI></UL><P>If the heuristic doesn&#X2019;t work, the displayed source will be wrong, but will
probably be near the actual source. If the &#X201C;shape&#X201D; 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.</P><P>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 </P><TT class=code>eq</TT><P>
list twice. If you don&#X2019;t define read macros and don&#X2019;t use </P><TT class=code>##</TT><P> in
perverted ways, you don&#X2019;t need to worry about this.</P><!--TOC subsection Source Location Availability-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc96">3.5.2</A>&#XA0;&#XA0;Source Location Availability</H3><!--SEC END --><P><A NAME="@concept73"></A>
Source location information is only available when the </P><TT class=code>debug</TT><P>
optimization quality is at least </P><TT class=code>2</TT><P>. If source location information is
unavailable, the source commands will give an error message.</P><P>If source location information is available, but the source location is
unknown because of an interrupt or unexpected hardware error
(see section&#XA0;<A HREF="#unknown-locations">3.3.6</A>), then the command will print:</P><BLOCKQUOTE class=example><PRE>
Unknown location: using block start.
</PRE></BLOCKQUOTE><P>and then proceed to print the source location for the start of the
<EM>basic block</EM> enclosing the code location.
<A NAME="@concept74"></A> <A NAME="@concept75"></A> 
It&#X2019;s a bit complicated to explain exactly what a basic block is, but
here are some properties of the block start location:</P><UL CLASS="itemize"><LI CLASS="li-itemize">The block start location may be the same as the true location.</LI><LI CLASS="li-itemize">The block start location will never be later in the the
program&#X2019;s flow of control than the true location.</LI><LI CLASS="li-itemize">No conditional control structures (such as <TT class=code>if</TT>,
<TT class=code>cond</TT>, <TT class=code>or</TT>) 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 <EM>do not</EM>
end basic blocks.</LI><LI CLASS="li-itemize">The head of a loop will be the start of a block.</LI><LI CLASS="li-itemize">The programming language concept of &#X201C;block structure&#X201D; and the
Common Lisp <TT class=code>block</TT> special form are totally unrelated to the
compiler&#X2019;s basic block.
</LI></UL><P>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.)</P><!--TOC section Compiler Policy Control-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc97">3.6</A>&#XA0;&#XA0;Compiler Policy Control</H2><!--SEC END --><P>
<A NAME="debugger-policy"></A>
<A NAME="@concept76"></A>
<A NAME="@concept77"></A>
<A NAME="@concept78"></A></P><P>The compilation policy specified by </P><TT class=code>optimize</TT><P> declarations affects the
behavior seen in the debugger. The </P><TT class=code>debug</TT><P> 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.</P><P>Unlike the other optimization qualities (which are compared in relative value
to evaluate tradeoffs), the </P><TT class=code>debug</TT><P> 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 </P><TT class=code>debug</TT><P> quality:

</P><DL CLASS="list"><DT CLASS="dt-list">
<TT class=code>0</TT><BR>
</DT><DD CLASS="dd-list">
Only the function name and enough information to allow the stack to
be parsed.</DD><DT CLASS="dt-list"><TT class=code>&gt; 0</TT><BR>
</DT><DD CLASS="dd-list">
Any level greater than <TT class=code>0</TT> gives level <TT class=code>0</TT> plus all
argument variables. Values will only be accessible if the argument
variable is never set and
<TT class=code>speed</TT> is not <TT class=code>3</TT>. CMUCL allows any real value for optimization
qualities. It may be useful to specify <TT class=code>0.5</TT> to get backtrace argument
display without argument documentation.</DD><DT CLASS="dt-list"><TT class=code>1</TT><BR>
</DT><DD CLASS="dd-list"> Level <TT class=code>1</TT> provides argument documentation
(printed arglists) and derived argument/result type information.
This makes <A NAME="@funs114"></A><TT class=code>describe</TT> more informative, and allows the
compiler to do compile-time argument count and type checking for any
calls compiled at run-time.</DD><DT CLASS="dt-list"><TT class=code>2</TT><BR>
</DT><DD CLASS="dd-list">
Level <TT class=code>1</TT> plus all interned local variables, source location
information, and lifetime information that tells the debugger when arguments
are available (even when <TT class=code>speed</TT> is <TT class=code>3</TT> or the argument is set.) This is
the default.</DD><DT CLASS="dt-list"><TT class=code>&gt; 2</TT><BR>
</DT><DD CLASS="dd-list">
Any level greater than <TT class=code>2</TT> gives level <TT class=code>2</TT> and in addition
disables tail-call optimization, so that the backtrace will contain
frames for all invoked functions, even those in tail positions.</DD><DT CLASS="dt-list"><TT class=code>3</TT><BR>
</DT><DD CLASS="dd-list">
Level <TT class=code>2</TT> plus all uninterned variables. In addition, lifetime
analysis is disabled (even when <TT class=code>speed</TT> is <TT class=code>3</TT>), 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. 
</DD></DL><P>As you can see, if the </P><TT class=code>speed</TT><P> quality is </P><TT class=code>3</TT><P>, debugger performance is
degraded. This effect comes from the elimination of argument variable
special-casing (see section&#XA0;<A HREF="#debug-var-validity">3.4.1</A>.) Some degree of
speed/debuggability tradeoff is unavoidable, but the effect is not too drastic
when </P><TT class=code>debug</TT><P> is at least </P><TT class=code>2</TT><P>.</P><P><A NAME="@concept79"></A>
<A NAME="@concept80"></A>
In addition to </P><TT class=code>inline</TT><P> and </P><TT class=code>notinline</TT><P> declarations, the relative values
of the </P><TT class=code>speed</TT><P> and </P><TT class=code>space</TT><P> qualities also change whether functions are
inline expanded (see section&#XA0;<A HREF="#inline-expansion">5.8</A>.) 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
&#X201C;semi-inline&#X201D;, 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.</P><!--TOC section Exiting Commands-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc98">3.7</A>&#XA0;&#XA0;Exiting Commands</H2><!--SEC END --><P>These commands get you out of the debugger.</P><DL CLASS="list"><DT CLASS="dt-list">
<TT class=code>quit</TT><BR>
</DT><DD CLASS="dd-list">
Throw to top level.</DD><DT CLASS="dt-list"><TT class=code>restart</TT> <TT class=code>{<TT class=variable>n</TT>}</TT><BR>
</DT><DD CLASS="dd-list">Invokes the <TT class=variable>n</TT>th restart case as displayed by the <TT class=code>error</TT>
command. If <TT class=variable>n</TT> is not specified, the available restart cases are
reported.</DD><DT CLASS="dt-list"><TT class=code>go</TT><BR>
</DT><DD CLASS="dd-list">
Calls <TT class=code>continue</TT> on the condition given to <TT class=code>debug</TT>. If there is no
restart case named <TT class=variable>continue</TT>, then an error is signaled.</DD><DT CLASS="dt-list"><TT class=code>abort</TT><BR>
</DT><DD CLASS="dd-list">
Calls <TT class=code>abort</TT> on the condition given to <TT class=code>debug</TT>. This is
useful for popping debug command loop levels or aborting to top level,
as the case may be.</DD></DL><!--TOC section Information Commands-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc99">3.8</A>&#XA0;&#XA0;Information Commands</H2><!--SEC END --><P>Most of these commands print information about the current frame or
function, but a few show general information.</P><DL CLASS="list"><DT CLASS="dt-list">
<TT class=code>help</TT>, <TT class=code>?</TT><BR>
</DT><DD CLASS="dd-list">
Displays a synopsis of debugger commands.</DD><DT CLASS="dt-list"><TT class=code>describe</TT><BR>
</DT><DD CLASS="dd-list">
Calls <TT class=code>describe</TT> on the current function, displays number of local
variables, and indicates whether the function is compiled or interpreted.</DD><DT CLASS="dt-list"><TT class=code>print</TT><BR>
</DT><DD CLASS="dd-list">
Displays the current function call as it would be displayed by moving to
this frame.</DD><DT CLASS="dt-list"><TT class=code>vprint</TT> (or <TT class=code>pp</TT>) <TT class=code>{<TT class=variable>verbosity</TT>}</TT><BR>
</DT><DD CLASS="dd-list">Displays the current function call using <TT class=code>*print-level*</TT> and
<TT class=code>*print-length*</TT> instead of <TT class=code>*debug-print-level*</TT> and
<TT class=code>*debug-print-length*</TT>. <TT class=variable>verbosity</TT> is a small integer
(default 2) that controls other dimensions of verbosity.</DD><DT CLASS="dt-list"><TT class=code>error</TT><BR>
</DT><DD CLASS="dd-list">
Prints the condition given to <TT class=code>invoke-debugger</TT> and the active
proceed cases.</DD><DT CLASS="dt-list"><TT class=code>backtrace</TT> <TT class=code>{<TT class=variable>n</TT>}</TT><BR>
</DT><DD CLASS="dd-list"><BR>
Displays all the frames from the current to the bottom. Only shows
<TT class=variable>n</TT> frames if specified. The printing is controlled by
<TT class=code>*debug-print-level*</TT> and <TT class=code>*debug-print-length*</TT>.</DD></DL><!--TOC section Breakpoint Commands-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc100">3.9</A>&#XA0;&#XA0;Breakpoint Commands</H2><!--SEC END --><P><A NAME="@concept81"></A></P><P>CMUCL supports setting of breakpoints inside compiled functions and
stepping of compiled code. Breakpoints can only be set at at known
locations (see section&#XA0;<A HREF="#unknown-locations">3.3.6</A>), so these commands are largely
useless unless the </P><TT class=code>debug</TT><P> optimize quality is at least </P><TT class=code>2</TT><P>
(see section&#XA0;<A HREF="#debugger-policy">3.6</A>). These commands manipulate breakpoints:

</P><DL CLASS="list"><DT CLASS="dt-list">

<TT class=code>breakpoint</TT> <TT class=variable>location</TT> <TT class=code>{<TT class=variable>option</TT> <TT class=variable>value</TT>}</TT><SUP>*</SUP><BR>
</DT><DD CLASS="dd-list">
Set a breakpoint in some function. <TT class=variable>location</TT> may be an integer
code location number (as displayed by <TT class=code>list-locations</TT>) or a
keyword. The keyword can be used to indicate setting a breakpoint at
the function start (<TT class=code>:start</TT>, <TT class=code>:s</TT>) or function end
(<TT class=code>:end</TT>, <TT class=code>:e</TT>). The <TT class=code>breakpoint</TT> command has
<TT class=code>:condition</TT>, <TT class=code>:break</TT>, <TT class=code>:print</TT> and <TT class=code>:function</TT>
options which work similarly to the <TT class=code>trace</TT> options.</DD><DT CLASS="dt-list"><TT class=code>list-locations</TT> (or <TT class=code>ll</TT>) <TT class=code>{<TT class=variable>function</TT>}</TT><BR>
</DT><DD CLASS="dd-list">List all the code locations in the current frame&#X2019;s function, or in
<TT class=variable>function</TT> if it is supplied. The display format is the code
location number, a colon and then the source form for that location:
<BLOCKQUOTE class=example><PRE>
3: (1- N)
</PRE></BLOCKQUOTE>
If consecutive locations have the same source, then a numeric range like
<TT class=code>3-5:</TT> 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
<TT class=code>breakpoint</TT>) command.</DD><DT CLASS="dt-list"><TT class=code>list-breakpoints</TT> (or <TT class=code>lb</TT>)<BR>
</DT><DD CLASS="dd-list">List all currently active breakpoints with their breakpoint number.</DD><DT CLASS="dt-list"><TT class=code>delete-breakpoint</TT> (or <TT class=code>db</TT>) <TT class=code>{<TT class=variable>number</TT>}</TT><BR>
</DT><DD CLASS="dd-list">Delete a breakpoint specified by its breakpoint number. If no number is
specified, delete all breakpoints.</DD><DT CLASS="dt-list"><TT class=code>step</TT><BR>
</DT><DD CLASS="dd-list">Step to the next possible breakpoint location in the current function.
This always steps over function calls, instead of stepping into them
</DD></DL><!--TOC subsection Breakpoint Example-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc101">3.9.1</A>&#XA0;&#XA0;Breakpoint Example</H3><!--SEC END --><P>Consider this definition of the factorial function:</P><BLOCKQUOTE CLASS=lisp> <PRE>
(defun ! (n)
  (if (zerop n)
      1
      (* n (! (1- n)))))
</PRE></BLOCKQUOTE><P>This debugger session demonstrates the use of breakpoints:</P><BLOCKQUOTE class=example><PRE>
common-lisp-user&gt; (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 #&#X2019;!
0: #&#X2019;(LAMBDA (N) (BLOCK ! (IF # 1 #)))
1: (ZEROP N)
2: (* N (! (1- N)))
3: (1- N)
4: (! (1- N))
5: (* N (! (1- N)))
6: #&#X2019;(LAMBDA (N) (BLOCK ! (IF # 1 #)))
0] br 2
(* N (! (1- N)))
1: 2 in !
Added.
0] q

common-lisp-user&gt; (! 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] 
</PRE></BLOCKQUOTE><!--TOC section Function Tracing-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc102">3.10</A>&#XA0;&#XA0;Function Tracing</H2><!--SEC END --><P>
<A NAME="@concept82"></A>
<A NAME="@concept83"></A></P><P>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.</P><P><BR>
<A NAME="@funs115"></A><A NAME="FN:trace"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>trace</TT> <TT class=code>{option global-value}</TT><SUP>*</SUP> <TT class=code>{name <TT class=code>{option
value}</TT><SUP>*</SUP>}</TT><SUP>*</SUP> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><TT class=code>trace</TT><P> is a debugging tool that prints information when
specified functions are called. In its simplest form:
</P><BLOCKQUOTE class=example><PRE>
    (trace <TT class=variable>name-1</TT> <TT class=variable>name-2</TT> ...)
  </PRE></BLOCKQUOTE><TT class=code>trace</TT><P> causes a printout on <A NAME="@vars27"></A></P><TT class=code>*trace-output*</TT><P> each time
that one of the named functions is entered or returns (the
</P><TT class=variable>names</TT><P> 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
<A NAME="@vars28"></A></P><TT class=code>*debug-print-level*</TT><P> and <A NAME="@vars29"></A></P><TT class=code>*debug-print-length*</TT><P>.</P><P>Local functions defined by </P><TT class=code>flet</TT><P> and </P><TT class=code>labels</TT><P> can be
traced using the syntax </P><TT class=code>(flet f f1 f2 ...)</TT><P> or </P><TT class=code>(labels f
f1 f2 ...)</TT><P> where </P><TT class=code>f</TT><P> is the </P><TT class=code>flet</TT><P> or </P><TT class=code>labels</TT><P>
function we want to trace and </P><TT class=code>f1</TT><P>, </P><TT class=code>f2</TT><P>, are the
functions containing the local function </P><TT class=code>f</TT><P>.
Invidiual methods can also be traced using the syntax </P><TT class=code>(method
<TT class=variable>name</TT> <TT class=variable>qualifiers</TT> <TT class=variable>specializers</TT>)</TT><P>.
See&#XA0;<A HREF="#sec:method-tracing">2.23.7</A> for more information.</P><P>If no </P><TT class=variable>names</TT><P> or </P><TT class=variable>options</TT><P> are are given, </P><TT class=code>trace</TT><P>
returns the list of all currently traced functions,
</P><TT class=code>*traced-function-list*</TT><P>.</P><P>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 </P><TT class=code>trace</TT><P>. If an already traced function is traced again,
any new options replace the old options. The following options are
defined:

</P><DL CLASS="list"><DT CLASS="dt-list">

<TT class=code>:condition</TT> <TT class=variable>form</TT>, <TT class=code>:condition-after</TT> <TT class=variable>form</TT>,
<TT class=code>:condition-all</TT> <TT class=variable>form</TT><BR>
</DT><DD CLASS="dd-list"> If <TT class=code>:condition</TT> is specified,
then <TT class=code>trace</TT> does nothing unless <TT class=variable>form</TT> evaluates to true
at the time of the call. <TT class=code>:condition-after</TT> is similar, but
suppresses the initial printout, and is tested when the function
returns. <TT class=code>:condition-all</TT> tries both before and after.</DD><DT CLASS="dt-list"><TT class=code>:wherein</TT> <TT class=variable>names</TT><BR>
</DT><DD CLASS="dd-list"> If specified, <TT class=variable>names</TT> is a
function name or list of names. <TT class=code>trace</TT> 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 <TT class=code>"DEFUN FOO"</TT>. Individual
methods can also be traced. See section&#XA0;<A HREF="#sec:method-tracing">2.23.7</A>.</DD><DT CLASS="dt-list"><TT class=code>:wherein-only</TT> <TT class=variable>names</TT><BR>
</DT><DD CLASS="dd-list"> If specified, this is just
like <TT class=code>:wherein</TT>, but trace produces output only if the
immediate caller of the traced function is one of the functions
listed in <TT class=variable>names</TT>.</DD><DT CLASS="dt-list"><TT class=code>:break</TT> <TT class=variable>form</TT>, <TT class=code>:break-after</TT> <TT class=variable>form</TT>,
<TT class=code>:break-all</TT> <TT class=variable>form</TT><BR>
</DT><DD CLASS="dd-list"> If specified, and <TT class=variable>form</TT> 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.</DD><DT CLASS="dt-list"><TT class=code>:print</TT> <TT class=variable>form</TT>, <TT class=code>:print-after</TT> <TT class=variable>form</TT>,
<TT class=code>:print-all</TT> <TT class=variable>form</TT><BR>
</DT><DD CLASS="dd-list"> In addition to the usual printout, the
result of evaluating <TT class=variable>form</TT> 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.</DD><DT CLASS="dt-list"><TT class=code>:function</TT> <TT class=variable>function-form</TT><BR>
</DT><DD CLASS="dd-list"> This is a not really an
option, but rather another way of specifying what function to
trace. The <TT class=variable>function-form</TT> is evaluated immediately, and the
resulting function is traced.</DD><DT CLASS="dt-list"><TT class=code>:encapsulate <TT class=code>{:default | t | nil}</TT></TT><BR>
</DT><DD CLASS="dd-list"> 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 <TT class=code>funcall</TT>.<P>When </P><TT class=code>:encapsulate</TT><P> is true, tracing is done via encapsulation.
</P><TT class=code>:default</TT><P> is the default, and means to use encapsulation for
interpreted functions and funcallable instances, breakpoints
otherwise. When encapsulation is used, forms are <I>not</I>
evaluated in the function&#X2019;s lexical environment, but
</P><TT class=code>debug:arg</TT><P> can still be used.</P><P>Note that if you trace using </P><TT class=code>:encapsulate</TT><P>, you will
only get a trace or breakpoint at the outermost call to the traced
function, not on recursive calls.</P></DD></DL><P>In the case of functions where the known return convention is used
to optimize, encapsulation may be necessary in order to make
tracing work at all. The symptom of this occurring is an error
stating
</P><BLOCKQUOTE class=example><PRE>
    Error in function <TT class=variable>foo</TT>: :FUNCTION-END breakpoints are
    currently unsupported for the known return convention.
  </PRE></BLOCKQUOTE><P>
in such cases we recommend using </P><TT class=code>(trace <TT class=variable>foo</TT> :encapsulate
t)</TT><P><A NAME="@concept84"></A>
<A NAME="@concept85"></A>
<A NAME="@concept86"></A>
<A NAME="@concept87"></A>
<A NAME="@concept88"></A></P><TT class=code>:condition</TT><P>, </P><TT class=code>:break</TT><P> and </P><TT class=code>:print</TT><P> forms are evaluated in
the lexical environment of the called function; </P><TT class=code>debug:var</TT><P> and
</P><TT class=code>debug:arg</TT><P> can be used. The </P><TT class=code>-after</TT><P> and </P><TT class=code>-all</TT><P>
forms are evaluated in the null environment.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs116"></A><A NAME="FN:untrace"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>untrace</TT>  <TT class=code>&amp;rest</TT> <TT class=variable>function-names</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This macro turns off tracing for the specified functions, and
removes their names from </P><TT class=code>*traced-function-list*</TT><P>. If no
</P><TT class=variable>function-names</TT><P> are given, then all currently traced functions
are untraced.
</P></BLOCKQUOTE><P><BR>
<A NAME="@vars30"></A><A NAME="VR:traced-function-list"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>*traced-function-list*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>A list of function names maintained and used by </P><TT class=code>trace</TT><P>,
</P><TT class=code>untrace</TT><P>, and </P><TT class=code>untrace-all</TT><P>. This list should contain
the names of all functions currently being traced.
</P></BLOCKQUOTE><P><BR>
<A NAME="@vars31"></A><A NAME="VR:max-trace-indentation"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>*max-trace-indentation*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>The maximum number of spaces which should be used to indent trace
printout. This variable is initially set to 40.
</P></BLOCKQUOTE><P><BR>
<A NAME="@vars32"></A><A NAME="VR:trace-encapsulate-package-names"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>debug:</TT><TT class=function-name>*trace-encapsulate-package-names*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>A list of package names. Functions from these packages are traced
using encapsulation instead of function-end breakpoints. This list
should at least include those packages containing functions used
directly or indirectly in the implementation of </P><TT class=code>trace</TT><P>.
</P></BLOCKQUOTE><!--TOC subsection Encapsulation Functions-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc103">3.10.1</A>&#XA0;&#XA0;Encapsulation Functions</H3><!--SEC END --><P>
<A NAME="@concept89"></A>
<A NAME="@concept90"></A></P><P>The encapsulation functions provide a mechanism for intercepting the
arguments and results of a function. </P><TT class=code>encapsulate</TT><P> 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 Common Lisp <A NAME="@funs117"></A></P><TT class=code>fdefinition</TT><P> function always returns
the original definition, stripping off any encapsulation.</P><P>The original definition of the symbol can be restored at any time by
the </P><TT class=code>unencapsulate</TT><P> function. </P><TT class=code>encapsulate</TT><P> and </P><TT class=code>unencapsulate</TT><P>
allow a symbol to be multiply encapsulated in such a way that different
encapsulations can be completely transparent to each other.</P><P>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.</P><P><BR>
<A NAME="@funs118"></A><A NAME="FN:encapsulate"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>encapsulate</TT> <TT class=variable>symbol</TT> <TT class=variable>type</TT> <TT class=variable>body</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>Saves the current definition of </P><TT class=variable>symbol</TT><P>, and replaces it with a
function which returns the result of evaluating the form,
</P><TT class=variable>body</TT><P>. </P><TT class=variable>Type</TT><P> is an arbitrary lisp object which is the
type of encapsulation.</P><P>When the new function is called, the following variables are bound
for the evaluation of </P><TT class=variable>body</TT><P>:

</P><DL CLASS="list"><DT CLASS="dt-list">
<TT class=code>extensions:argument-list</TT><BR>
</DT><DD CLASS="dd-list"> A list of the arguments to
the function.</DD><DT CLASS="dt-list"><TT class=code>extensions:basic-definition</TT><BR>
</DT><DD CLASS="dd-list"> The unencapsulated
definition of the function.
</DD></DL><P>
The unencapsulated definition may be called with the original
arguments by including the form
</P><BLOCKQUOTE CLASS=lisp> <PRE>
    (apply extensions:basic-definition extensions:argument-list)
  </PRE></BLOCKQUOTE><TT class=code>encapsulate</TT><P> always returns </P><TT class=variable>symbol</TT><P>.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs119"></A><A NAME="FN:unencapsulate"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>unencapsulate</TT> <TT class=variable>symbol</TT> <TT class=variable>type</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>Undoes </P><TT class=variable>symbol</TT><P>&#X2019;s most recent encapsulation of type </P><TT class=variable>type</TT><P>.
</P><TT class=variable>Type</TT><P> is compared with </P><TT class=code>eq</TT><P>. Encapsulations of other
types are left in place.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs120"></A><A NAME="FN:encapsulated-p"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>encapsulated-p</TT> <TT class=variable>symbol</TT> <TT class=variable>type</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>Returns </P><TT class=code>t</TT><P> if </P><TT class=variable>symbol</TT><P> has an encapsulation of type
</P><TT class=variable>type</TT><P>. Returns </P><TT class=code>nil</TT><P> otherwise. </P><TT class=variable>type</TT><P> is compared with
</P><TT class=code>eq</TT><P>.
</P></BLOCKQUOTE><!--TOC subsection Tracing Examples-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc104">3.10.2</A>&#XA0;&#XA0;Tracing Examples</H3><!--SEC END --><P>
Here is an example of tracing with some of the possible options.
For simplicity, this is the function:
</P><BLOCKQUOTE class=example><PRE>
    (defun fact (n)
      (declare (double-float n) (optimize speed))
      (if (zerop n)
          1d0
          (* n (fact (1- n)))))
    (compile &#X2019;fact)
  </PRE></BLOCKQUOTE><P>This example shows how to use the :condition option:
</P><BLOCKQUOTE class=example><PRE>
    (trace fact :condition (= 4d0 (debug:arg 0)))
    (fact 10d0) -&gt;
      0: (FACT 4.0d0)
      0: FACT returned 24.0d0
    3628800.0d0
  </PRE></BLOCKQUOTE><P>
As we can see, we produced output when the condition was satisfied.</P><P>Here&#X2019;s another example:
</P><BLOCKQUOTE class=example><PRE>
    (untrace)
    (trace fact :break (= 4d0 (debug:arg 0)))
    (fact 10d0) -&gt;
      0: (FACT 5.0d0)
        1: (FACT 4.0d0)


    Breaking before traced call to FACT:
       [Condition of type SIMPLE-CONDITION]

    Restarts:
      0: [CONTINUE] Return from BREAK.
      1: [ABORT   ] Return to Top-Level.

    Debug  (type H for help)
  </PRE></BLOCKQUOTE><P>
In this example, we see that normal tracing occurs until we the
argument reaches 4d0, at which point, we break into the debugger.</P><!--TOC section Specials-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc105">3.11</A>&#XA0;&#XA0;Specials</H2><!--SEC END --><P>
These are the special variables that control the debugger action.</P><P><BR>
<A NAME="@vars33"></A><A NAME="VR:debug-print-level"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>debug:</TT><TT class=function-name>*debug-print-level*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
<P><A NAME="@vars34"></A><A NAME="VR:debug-print-length"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>debug:</TT><TT class=function-name>*debug-print-length*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><TT class=code>*print-level*</TT><P> and </P><TT class=code>*print-length*</TT><P> are bound to these
values during the execution of some debug commands. When evaluating
arbitrary expressions in the debugger, the normal values of
</P><TT class=code>*print-level*</TT><P> and </P><TT class=code>*print-length*</TT><P> are in effect. These
variables are initially set to 3 and 5, respectively.
</P></BLOCKQUOTE><!--NAME debugger.html-->
<!--BEGIN NOTES chapter-->
<HR CLASS="ffootnoterule"><DL CLASS="thefootnotes"><DT CLASS="dt-thefootnotes">
<A NAME="note4" HREF="#text4">1</A></DT><DD CLASS="dd-thefootnotes">Since the location of an interrupt or hardware
error will always be an unknown location (see section&#XA0;<A HREF="#unknown-locations">3.3.6</A>),
non-argument variable values will never be available in the interrupted frame.
</DD><DT CLASS="dt-thefootnotes"><A NAME="note5" HREF="#text5">2</A></DT><DD CLASS="dd-thefootnotes">The variable bindings are actually created using the Common Lisp
<TT class=code>symbol-macrolet</TT> special form.
</DD></DL>
<!--END NOTES-->
<!--TOC chapter The Compiler-->
<H1 CLASS="chapter"><!--SEC ANCHOR --><A NAME="htoc106">Chapter&#XA0;4</A>&#XA0;&#XA0;The Compiler</H1><!--SEC END --><!--TOC section Compiler Introduction-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc107">4.1</A>&#XA0;&#XA0;Compiler Introduction</H2><!--SEC END --><P>This chapter contains information about the compiler that every CMUCL user
should be familiar with. Chapter <A HREF="#advanced-compiler">5</A> goes into greater
depth, describing ways to use more advanced features.</P><P>The CMUCL compiler (also known as Python, not to be confused
with the programming language of the same name) has many features
that are seldom or never supported by conventional Common Lisp
compilers:</P><UL CLASS="itemize"><LI CLASS="li-itemize"> 
Source level debugging of compiled code (see chapter
<A HREF="#debugger">3</A>.)</LI><LI CLASS="li-itemize">Type error compiler warnings for type errors detectable at
compile time.</LI><LI CLASS="li-itemize">Compiler error messages that provide a good indication of where
the error appeared in the source.</LI><LI CLASS="li-itemize">Full run-time checking of all potential type errors, with
optimization of type checks to minimize the cost.</LI><LI CLASS="li-itemize">Scheme-like features such as proper tail recursion and extensive
source-level optimization.</LI><LI CLASS="li-itemize">Advanced tuning and optimization features such as comprehensive
efficiency notes, flow analysis, and untagged number representations
(see chapter <A HREF="#advanced-compiler">5</A>.)
</LI></UL><!--TOC section Calling the Compiler-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc108">4.2</A>&#XA0;&#XA0;Calling the Compiler</H2><!--SEC END --><P>
<A NAME="@concept91"></A></P><P>Functions may be compiled using </P><TT class=code>compile</TT><P>, </P><TT class=code>compile-file</TT><P>, or 
</P><TT class=code>compile-from-stream</TT><P>. </P><P><BR>
<A NAME="@funs121"></A><A NAME="FN:compile"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>compile</TT>  <TT class=variable>name</TT> <TT class=code>&amp;optional</TT> <TT class=variable>definition</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function compiles the function whose name is </P><TT class=variable>name</TT><P>. If
</P><TT class=variable>name</TT><P> is </P><TT class=code>nil</TT><P>, the compiled function object is returned. If
</P><TT class=variable>definition</TT><P> is supplied, it should be a lambda expression that
is to be compiled and then placed in the function cell of
</P><TT class=variable>name</TT><P>. As per the proposed X3J13 cleanup
&#X201C;compile-argument-problems&#X201D;, </P><TT class=variable>definition</TT><P> may also be an
interpreted function.</P><P>The return values are as per the proposed X3J13 cleanup
&#X201C;compiler-diagnostics&#X201D;. The first value is the function name or
function object. The second value is </P><TT class=code>nil</TT><P> if no compiler
diagnostics were issued, and </P><TT class=code>t</TT><P> otherwise. The third value is
</P><TT class=code>nil</TT><P> if no compiler diagnostics other than style warnings were
issued. A non-</P><TT class=code>nil</TT><P> value indicates that there were &#X201C;serious&#X201D;
compiler diagnostics issued, or that other conditions of type
<A NAME="@types19"></A></P><TT class=code>error</TT><P> or <A NAME="@types20"></A></P><TT class=code>warning</TT><P> (but not
<A NAME="@types21"></A></P><TT class=code>style-warning</TT><P>) were signaled during compilation.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs122"></A><A NAME="FN:compile-file"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>compile-file</TT> 
<TT class=variable>input-pathname</TT>
<TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=code>:output-file</TT> <TT class=code>:error-file</TT> <TT class=code>:trace-file</TT></SPAN><BR>
 <TT class=code>:error-output</TT> <TT class=code>:verbose</TT> <TT class=code>:print</TT> <TT class=code>:progress</TT><BR>
 <TT class=code>:load</TT> <TT class=code>:block-compile</TT> <TT class=code>:entry-points</TT><BR>
 <TT class=code>:byte-compile</TT> <TT class=code>:xref</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>The CMUCL </P><TT class=code>compile-file</TT><P> is extended through the addition of
several new keywords and an additional interpretation of
</P><TT class=variable>input-pathname</TT><P>:

</P><DL CLASS="list"><DT CLASS="dt-list">
<TT class=variable>input-pathname</TT><BR>
</DT><DD CLASS="dd-list"> 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
<TT class=variable>block-compile</TT>.</DD><DT CLASS="dt-list"><TT class=code>:output-file</TT><BR>
</DT><DD CLASS="dd-list"> This argument specifies the name of the
output file. <TT class=code>t</TT> gives the default name, <TT class=code>nil</TT> suppresses
the output file.</DD><DT CLASS="dt-list"><TT class=code>:error-file</TT><BR>
</DT><DD CLASS="dd-list"> 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.) <TT class=code>t</TT>
gives "<TT class=variable>name</TT><TT class=code>.err</TT>" (the default), and <TT class=code>nil</TT>
suppresses the output file.</DD><DT CLASS="dt-list"><TT class=code>:error-output</TT><BR>
</DT><DD CLASS="dd-list"> If <TT class=code>t</TT> (the default), then error
output is sent to <TT class=code>*error-output*</TT>. If a stream, then output
is sent to that stream instead. If <TT class=code>nil</TT>, then error output is
suppressed. Note that this error output is in addition to (but
the same as) the output placed in the <TT class=variable>error-file</TT>.</DD><DT CLASS="dt-list"><TT class=code>:verbose</TT><BR>
</DT><DD CLASS="dd-list"> If <TT class=code>t</TT> (the default), then the compiler
prints to error output at the start and end of compilation of each
file. See <A NAME="@vars35"></A><TT class=code>*compile-verbose*</TT>.</DD><DT CLASS="dt-list"><TT class=code>:print</TT><BR>
</DT><DD CLASS="dd-list"> If <TT class=code>t</TT> (the default), then the compiler
prints to error output when each function is compiled. See
<A NAME="@vars36"></A><TT class=code>*compile-print*</TT>.</DD><DT CLASS="dt-list"><TT class=code>:progress</TT><BR>
</DT><DD CLASS="dd-list"> If <TT class=code>t</TT> (default <TT class=code>nil</TT>), then the
compiler prints to error output progress information about the
phases of compilation of each function. This is a CMUCL extension
that is useful mainly in large block compilations. See
<A NAME="@vars37"></A><TT class=code>*compile-progress*</TT>.</DD><DT CLASS="dt-list"><TT class=code>:trace-file</TT><BR>
</DT><DD CLASS="dd-list"> If <TT class=code>t</TT>, several of the intermediate
representations (including annotated assembly code) are dumped out
to this file. <TT class=code>t</TT> gives "<TT class=variable>name</TT><TT class=code>.trace</TT>". Trace
output is off by default. See section&#XA0;<A HREF="#trace-files">5.12.5</A>.</DD><DT CLASS="dt-list"><TT class=code>:load</TT><BR>
</DT><DD CLASS="dd-list"> If <TT class=code>t</TT>, load the resulting output file.</DD><DT CLASS="dt-list"><TT class=code>:block-compile</TT><BR>
</DT><DD CLASS="dd-list"> Controls the compile-time resolution of
function calls. By default, only self-recursive calls are
resolved, unless an <TT class=code>ext:block-start</TT> declaration appears in
the source file. See section&#XA0;<A HREF="#compile-file-block">5.7.3</A>.</DD><DT CLASS="dt-list"><TT class=code>:entry-points</TT><BR>
</DT><DD CLASS="dd-list"> If non-<TT class=code>nil</TT>, 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.) See section&#XA0;<A HREF="#compile-file-block">5.7.3</A>.</DD><DT CLASS="dt-list"><TT class=code>:byte-compile</TT><BR>
</DT><DD CLASS="dd-list"> If <TT class=code>t</TT>, compiling to a compact
interpreted byte code is enabled. Possible values are <TT class=code>t</TT>,
<TT class=code>nil</TT>, and <TT class=code>:maybe</TT> (the default.) See
<A NAME="@vars38"></A><TT class=code>*byte-compile-default*</TT> and see section&#XA0;<A HREF="#byte-compile">5.9</A>.</DD><DT CLASS="dt-list"><TT class=code>:xref</TT><BR>
</DT><DD CLASS="dd-list"> If non-<TT class=code>nil</TT>, enable recording of cross-reference
information. The default is the value of
<TT class=code>c:*record-xref-info*</TT>. See section&#XA0;<A HREF="#xref">12</A>. Note that the
compiled fasl file will also contain cross-reference information
and loading the fasl later will populate the cross-reference database.
</DD></DL><P>The return values are as per the proposed X3J13 cleanup
&#X201C;compiler-diagnostics&#X201D;. The first value from </P><TT class=code>compile-file</TT><P>
is the truename of the output file, or </P><TT class=code>nil</TT><P> if the file could
not be created. The interpretation of the second and third values
is described above for </P><TT class=code>compile</TT><P>.
</P></BLOCKQUOTE><P><BR>
<A NAME="@vars39"></A><A NAME="VR:compile-verbose"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>*compile-verbose*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
<P><A NAME="@vars40"></A><A NAME="VR:compile-print"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>*compile-print*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><P><A NAME="@vars41"></A><A NAME="VR:compile-progress"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>*compile-progress*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><P>These variables determine the default values for the </P><TT class=code>:verbose</TT><P>,
</P><TT class=code>:print</TT><P> and </P><TT class=code>:progress</TT><P> arguments to </P><TT class=code>compile-file</TT><P>.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs123"></A><A NAME="FN:compile-from-stream"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>compile-from-stream</TT> <TT class=variable>input-stream</TT>
<TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=code>:error-stream</TT></SPAN><BR>
 <TT class=code>:trace-stream</TT><BR>
 <TT class=code>:block-compile</TT> <TT class=code>:entry-points</TT><BR>
 <TT class=code>:byte-compile</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function is similar to </P><TT class=code>compile-file</TT><P>, but it takes all
its arguments as streams. It reads Common Lisp code from
</P><TT class=variable>input-stream</TT><P> until end of file is reached, compiling into the
current environment. This function returns the same two values as
the last two values of </P><TT class=code>compile</TT><P>. No output files are
produced.
</P></BLOCKQUOTE><!--TOC section Compilation Units-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc109">4.3</A>&#XA0;&#XA0;Compilation Units</H2><!--SEC END --><P>
<A NAME="@concept92"></A></P><P>CMUCL supports the </P><TT class=code>with-compilation-unit</TT><P> macro added to the
language by the X3J13 &#X201C;with-compilation-unit&#X201D; compiler cleanup
issue. 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.</P><P><BR>
<A NAME="@funs124"></A><A NAME="FN:with-compilation-unit"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>with-compilation-unit</TT> (<TT class=code>{<TT class=variable>key</TT> <TT class=variable>value</TT>}</TT><SUP>*</SUP>) <TT class=code>{<TT class=variable>form</TT>}</TT><SUP>*</SUP> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This macro evaluates the </P><TT class=variable>forms</TT><P> in an environment that causes
warnings for undefined variables, functions and types to be delayed
until all the forms have been evaluated. Each keyword </P><TT class=variable>value</TT><P>
is an evaluated form. These keyword options are recognized:

</P><DL CLASS="list"><DT CLASS="dt-list">
<TT class=code>:override</TT><BR>
</DT><DD CLASS="dd-list"> If uses of <TT class=code>with-compilation-unit</TT> are
dynamically nested, the outermost use will take precedence,
suppressing printing of undefined warnings by inner uses.
However, when the <TT class=code>override</TT> option is true this shadowing is
inhibited; an inner use will print summary warnings for the
compilations within the inner scope.</DD><DT CLASS="dt-list"><TT class=code>:optimize</TT><BR>
</DT><DD CLASS="dd-list"> This is a CMUCL extension that specifies of the
&#X201C;global&#X201D; compilation policy for the dynamic extent of the body.
The argument should evaluate to an <TT class=code>optimize</TT> declare form,
like:
<BLOCKQUOTE CLASS=lisp> <PRE>
      (optimize (speed 3) (safety 0))
    </PRE></BLOCKQUOTE>
See section&#XA0;<A HREF="#optimize-declaration">4.7.1</A></DD><DT CLASS="dt-list"><TT class=code>:optimize-interface</TT><BR>
</DT><DD CLASS="dd-list"> Similar to <TT class=code>:optimize</TT>, but
specifies the compilation policy for function interfaces (argument
count and type checking) for the dynamic extent of the body.
See section&#XA0;<A HREF="#optimize-interface-declaration">4.7.2</A>.</DD><DT CLASS="dt-list"><TT class=code>:context-declarations</TT><BR>
</DT><DD CLASS="dd-list"> This is a CMUCL extension that
pattern-matches on function names, automatically splicing in any
appropriate declarations at the head of the function definition.
See section&#XA0;<A HREF="#context-declarations">5.7.5</A>.
</DD></DL></BLOCKQUOTE><!--TOC subsection Undefined Warnings-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc110">4.3.1</A>&#XA0;&#XA0;Undefined Warnings</H3><!--SEC END --><P><A NAME="@concept93"></A>
Warnings about undefined variables, functions and types are delayed until the
end of the current compilation unit. The compiler entry functions
(</P><TT class=code>compile</TT><P>, etc.) implicitly use </P><TT class=code>with-compilation-unit</TT><P>, so undefined
warnings will be printed at the end of the compilation unless there is an
enclosing </P><TT class=code>with-compilation-unit</TT><P>. In order the gain the benefit of this
mechanism, you should wrap a single </P><TT class=code>with-compilation-unit</TT><P> around the calls
to </P><TT class=code>compile-file</TT><P>, i.e.:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(with-compilation-unit ()
  (compile-file "file1")
  (compile-file "file2")
  ...)
</PRE></BLOCKQUOTE><P>Unlike for functions and types, undefined warnings for variables are
not suppressed when a definition (e.g. </P><TT class=code>defvar</TT><P>) appears after
the reference (but in the same compilation unit.) This is because
doing special declarations out of order just doesn&#X2019;t
work&#X2014;although early references will be compiled as special,
bindings will be done lexically.</P><P>Undefined warnings are printed with full source context
(see section&#XA0;<A HREF="#error-messages">4.4</A>), which tremendously simplifies the problem
of finding undefined references that resulted from macroexpansion.
After printing detailed information about the undefined uses of each
name, </P><TT class=code>with-compilation-unit</TT><P> also prints summary listings of the
names of all the undefined functions, types and variables.</P><P><BR>
<A NAME="@vars42"></A><A NAME="VR:undefined-warning-limit"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>*undefined-warning-limit*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>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:
</P><BLOCKQUOTE class=example><PRE>
    Warning: <TT class=variable>count</TT> more uses of undefined function <TT class=variable>name</TT>.
  </PRE></BLOCKQUOTE><P>
When the value is </P><TT class=code>0</TT><P>, then the undefined warnings are not
broken down by name at all: only the summary listing of undefined
names is printed.
</P></BLOCKQUOTE><!--TOC section Interpreting Error Messages-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc111">4.4</A>&#XA0;&#XA0;Interpreting Error Messages</H2><!--SEC END --><P>
<A NAME="error-messages"></A>
<A NAME="@concept94"></A>
<A NAME="@concept95"></A></P><P>One of Python&#X2019;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:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(defmacro zoq (x)
  &#X2018;(roq (ploq (+ ,x 3))))

(defun foo (y)
  (declare (symbol y))
  (zoq y))
</PRE></BLOCKQUOTE><P>
The main problem with this program is that it is trying to add </P><TT class=code>3</TT><P> to a
symbol. Note also that the functions </P><TT class=code>roq</TT><P> and </P><TT class=code>ploq</TT><P> aren&#X2019;t defined
anywhere.</P><!--TOC subsection The Parts of the Error Message-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc112">4.4.1</A>&#XA0;&#XA0;The Parts of the Error Message</H3><!--SEC END --><P>The compiler will produce this warning:</P><BLOCKQUOTE class=example><PRE>
File: /usr/me/stuff.lisp
In: DEFUN FOO
  (ZOQ Y)
&#X2013;&gt; ROQ PLOQ + 
==&gt;
  Y
Warning: Result is a SYMBOL, not a NUMBER.
</PRE></BLOCKQUOTE><P>In this example we see each of the six possible parts of a compiler error
message:</P><DL CLASS="list"><DT CLASS="dt-list">
 
<TT class=code>File: /usr/me/stuff.lisp</TT><BR>
</DT><DD CLASS="dd-list"> This is the <TT class=variable>file</TT> 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
<TT class=code>with-compilation-unit</TT> is used to delay undefined warnings.</DD><DT CLASS="dt-list"><TT class=code>In: DEFUN FOO</TT><BR>
</DT><DD CLASS="dd-list"> This is the <TT class=variable>definition</TT> 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 &#X201C;<TT class=code>DEF</TT>&#X201D;. If there is no enclosing
<TT class=variable>def</TT>mumble, then the outermost form is used. If there are
multiple <TT class=variable>def</TT>mumbles, then they are all printed from the
out in, separated by <TT class=code>=&gt;</TT>&#X2019;s. In this example, the problem
was in the <TT class=code>defun</TT> for <TT class=code>foo</TT>.</DD><DT CLASS="dt-list"><TT class=code>(ZOQ Y)</TT><BR>
</DT><DD CLASS="dd-list"> This is the <EM>original source</EM> 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 <TT class=code>compile</TT> or the top-level form read from the
source file. In this example, the expansion of the <TT class=code>zoq</TT> macro
was responsible for the error.</DD><DT CLASS="dt-list"><TT class=code>&#X2013;&gt; ROQ PLOQ +</TT><BR>
</DT><DD CLASS="dd-list"> This is the <EM>processing path</EM>
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 <TT class=code>roq</TT>, <TT class=code>ploq</TT> and <TT class=code>+</TT>. These calls resulted
from the expansion of the <TT class=code>zoq</TT> macro.</DD><DT CLASS="dt-list"><TT class=code>==&gt; Y</TT><BR>
</DT><DD CLASS="dd-list"> This is the <EM>actual source</EM> 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
<TT class=code>y</TT>.</DD><DT CLASS="dt-list"><TT class=code>Warning: Result is a SYMBOL, not a NUMBER.</TT><BR>
</DT><DD CLASS="dd-list"> This is
the <TT class=variable>explanation</TT> the problem. In this example, the problem is
that <TT class=code>y</TT> evaluates to a <TT class=code>symbol</TT>, but is in a context
where a number is required (the argument to <TT class=code>+</TT>).
</DD></DL><P>Note that each part of the error message is distinctively marked:</P><UL CLASS="itemize"><LI CLASS="li-itemize"> 
<TT class=code>File:</TT> and <TT class=code>In:</TT> mark the file and definition,
respectively.</LI><LI CLASS="li-itemize">The original source is an indented form with no prefix.</LI><LI CLASS="li-itemize">Each line of the processing path is prefixed with <TT class=code>&#X2013;&gt;</TT>.</LI><LI CLASS="li-itemize">The actual source form is indented like the original source, but
is marked by a preceding <TT class=code>==&gt;</TT> line. This is like the
&#X201C;macroexpands to&#X201D; notation used in <I>Common Lisp: The Language</I>.</LI><LI CLASS="li-itemize">The explanation is prefixed with the error severity
(see section&#XA0;<A HREF="#error-severity">4.4.4</A>), either <TT class=code>Error:</TT>, <TT class=code>Warning:</TT>, or
<TT class=code>Note:</TT>.
</LI></UL><P>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:</P><BLOCKQUOTE class=example><PRE>
File: /usr/me/stuff.lisp
In: DEFUN FOO
  (ZOQ Y)
&#X2013;&gt; ROQ 
==&gt;
  (PLOQ (+ Y 3))
Warning: Undefined function: PLOQ

==&gt;
  (ROQ (PLOQ (+ Y 3)))
Warning: Undefined function: ROQ
</PRE></BLOCKQUOTE><P>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:</P><BLOCKQUOTE class=example><PRE>
[Last message occurs <TT class=variable>repeats</TT> times]
</PRE></BLOCKQUOTE><P>where </P><TT class=variable>repeats</TT><P> is the number of times the message was given.</P><P>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.</P><!--TOC subsection The Original and Actual Source-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc113">4.4.2</A>&#XA0;&#XA0;The Original and Actual Source</H3><!--SEC END --><P>
<A NAME="@concept96"></A>
<A NAME="@concept97"></A></P><P>The <EM>original source</EM> 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.)</P><P>When the <EM>actual source</EM> 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.</P><P>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:</P><BLOCKQUOTE CLASS=lisp> <PRE>
(defun bar (x)
  (let (a)
    (declare (fixnum a))
    (setq a (foo x))
    a))
</PRE></BLOCKQUOTE><P>gives this error message:</P><BLOCKQUOTE class=example><PRE>
In: DEFUN BAR
  (LET (A) (DECLARE (FIXNUM A)) (SETQ A (FOO X)) A)
Warning: The binding of A is not a FIXNUM:
  NIL
</PRE></BLOCKQUOTE><P>This error message is not saying &#X201C;there&#X2019;s a problem somewhere in this
</P><TT class=code>let</TT><P>&#X201D;&#X2014;it is saying that there is a problem with the
</P><TT class=code>let</TT><P> itself. In this example, the problem is that </P><TT class=code>a</TT><P>&#X2019;s
</P><TT class=code>nil</TT><P> initial value is not a </P><TT class=code>fixnum</TT><P>.</P><!--TOC subsection The Processing Path-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc114">4.4.3</A>&#XA0;&#XA0;The Processing Path</H3><!--SEC END --><P>
<A NAME="@concept98"></A>
<A NAME="@concept99"></A>
<A NAME="@concept100"></A></P><P>The processing path is mainly useful for debugging macros, so if you don&#X2019;t
write macros, you can ignore the processing path. Consider this example:</P><BLOCKQUOTE CLASS=lisp> <PRE>
(defun foo (n)
  (dotimes (i n *undefined*)))
</PRE></BLOCKQUOTE><P>Compiling results in this error message:</P><BLOCKQUOTE class=example><PRE>
In: DEFUN FOO
  (DOTIMES (I N *UNDEFINED*))
&#X2013;&gt; DO BLOCK LET TAGBODY RETURN-FROM 
==&gt;
  (PROGN *UNDEFINED*)
Warning: Undefined variable: *UNDEFINED*
</PRE></BLOCKQUOTE><P>Note that </P><TT class=code>do</TT><P> appears in the processing path. This is because </P><TT class=code>dotimes</TT><P>
expands into:</P><BLOCKQUOTE CLASS=lisp> <PRE>
(do ((i 0 (1+ i)) (#:g1 n))
    ((&gt;= i #:g1) *undefined*)
  (declare (type unsigned-byte i)))
</PRE></BLOCKQUOTE><P>The rest of the processing path results from the expansion of </P><TT class=code>do</TT><P>:</P><BLOCKQUOTE CLASS=lisp> <PRE>
(block nil
  (let ((i 0) (#:g1 n))
    (declare (type unsigned-byte i))
    (tagbody (go #:g3)
     #:g2    (psetq i (1+ i))
     #:g3    (unless (&gt;= i #:g1) (go #:g2))
             (return-from nil (progn *undefined*)))))
</PRE></BLOCKQUOTE><P>In this example, the compiler descended into the </P><TT class=code>block</TT><P>,
</P><TT class=code>let</TT><P>, </P><TT class=code>tagbody</TT><P> and </P><TT class=code>return-from</TT><P> to reach the
</P><TT class=code>progn</TT><P> printed as the actual source. This is a place where the
&#X201C;actual source appears in explanation&#X201D; rule was applied. The
innermost actual source form was the symbol </P><TT class=code>*undefined*</TT><P> itself,
but that also appeared in the explanation, so the compiler backed out
one level.</P><!--TOC subsection Error Severity-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc115">4.4.4</A>&#XA0;&#XA0;Error Severity</H3><!--SEC END --><P>
<A NAME="error-severity"></A>
<A NAME="@concept101"></A>
<A NAME="@concept102"></A></P><P>There are three levels of compiler error severity:</P><DL CLASS="list"><DT CLASS="dt-list">
 
Error<BR>
</DT><DD CLASS="dd-list"> 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
<TT class=code>error</TT>. 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.</DD><DT CLASS="dt-list">Warning<BR>
</DT><DD CLASS="dd-list"> 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:
<UL CLASS="itemize"><LI CLASS="li-itemize">Violation of type declarations, or</LI><LI CLASS="li-itemize">Function calls that have the wrong number of arguments or
malformed keyword argument lists, or</LI><LI CLASS="li-itemize">Referencing a variable declared <TT class=code>ignore</TT>, or unrecognized
declaration specifiers.
</LI></UL><P>In the language of the Common Lisp 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.</P></DD><DT CLASS="dt-list">Note<BR>
</DT><DD CLASS="dd-list"> Notes are used when there is something that seems a bit
odd, but that might reasonably appear in correct programs.
</DD></DL><P>Note that the compiler does not fully conform to the proposed X3J13
&#X201C;compiler-diagnostics&#X201D; 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&#X2019;t really signaled using the condition system.</P><!--TOC subsection Errors During Macroexpansion-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc116">4.4.5</A>&#XA0;&#XA0;Errors During Macroexpansion</H3><!--SEC END --><P>
<A NAME="@concept103"></A></P><P>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 </P><TT class=code>*break-on-signals*</TT><P> to </P><TT class=code>error</TT><P>. For
example, this definition:</P><BLOCKQUOTE CLASS=lisp> <PRE>
(defun foo (e l)
  (do ((current l (cdr current))
       ((atom current) nil))
      (when (eq (car current) e) (return current))))
</PRE></BLOCKQUOTE><P>gives this error:</P><BLOCKQUOTE class=example><PRE>
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)
</PRE></BLOCKQUOTE><!--TOC subsection Read Errors-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc117">4.4.6</A>&#XA0;&#XA0;Read Errors</H3><!--SEC END --><P>
<A NAME="@concept104"></A></P><P>The compiler also handles errors while reading the source. For example:</P><BLOCKQUOTE class=example><PRE>
Error: Read error at 2:
 "(,/\foo)"
Error in function LISP::COMMA-MACRO.
Comma not inside a backquote.
</PRE></BLOCKQUOTE><P>The &#X201C;</P><TT class=code>at 2</TT><P>&#X201D; 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, &#X201C;</P><TT class=code>(,/\foo)</TT><P>&#X201D;, is the line in
the source that contains the error file position. The &#X201C;</P><TT class=code>/\ </TT><P>&#X201D;
indicates the error position within that line (in this example,
immediately after the offending comma.)</P><P>When in Hemlock (or any other EMACS-like editor), you can go to a
character position with:</P><BLOCKQUOTE class=example><PRE>
M-&lt; C-u <TT class=variable>position</TT> C-f
</PRE></BLOCKQUOTE><P>Note that if the source is from a Hemlock buffer, then the position
is relative to the start of the compiled region or </P><TT class=code>defun</TT><P>, not the
file or buffer start.</P><P>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 </P><TT class=code>*read-suppress*</TT><P> true. If the compiler can recover from the
error, then it substitutes a call to </P><TT class=code>cerror</TT><P> for the unreadable form and
proceeds to compile the rest of the file normally.</P><P>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:</P><BLOCKQUOTE class=example><PRE>
Error: Read error in form starting at 14:
 "(defun test ()"
Error in function LISP::FLUSH-WHITESPACE.
EOF while reading #&lt;Stream for file "/usr/me/test.lisp"&gt;
</PRE></BLOCKQUOTE><P>In this case, &#X201C;</P><TT class=code>starting at 14</TT><P>&#X201D; 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 "</P><TT class=code>(defun test ()</TT><P>" is first line after the starting
position that the compiler thinks might contain the unmatched open
delimiter.</P><!--TOC subsection Error Message Parameterization-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc118">4.4.7</A>&#XA0;&#XA0;Error Message Parameterization</H3><!--SEC END --><P>
<A NAME="@concept105"></A>
<A NAME="@concept106"></A></P><P>There is some control over the verbosity of error messages. See also
<A NAME="@vars43"></A></P><TT class=code>*undefined-warning-limit*</TT><P>, </P><TT class=code>*efficiency-note-limit*</TT><P> and
<A NAME="@vars44"></A></P><TT class=code>*efficiency-note-cost-threshold*</TT><P>.</P><P><BR>
<A NAME="@vars45"></A><A NAME="VR:enclosing-source-cutoff"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>*enclosing-source-cutoff*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"> <P>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 </P><TT class=code>1</TT><P>
allows you to see more of the guts of the macroexpanded source,
which is useful when debugging macros.
</P></BLOCKQUOTE><P><BR>
<A NAME="@vars46"></A><A NAME="VR:error-print-length"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>*error-print-length*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
<P><A NAME="@vars47"></A><A NAME="VR:error-print-level"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>*error-print-level*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><P>These variables are the print level and print length used in
printing error messages. The default values are </P><TT class=code>5</TT><P> and
</P><TT class=code>3</TT><P>. If null, the global values of </P><TT class=code>*print-level*</TT><P> and
</P><TT class=code>*print-length*</TT><P> are used.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs125"></A><A NAME="FN:def-source-context"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>def-source-context</TT> <TT class=variable>name</TT> <TT class=variable>lambda-list</TT> <TT class=code>{form}</TT><SUP>*</SUP> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This macro defines how to extract an abbreviated source context from
the </P><TT class=variable>name</TT><P>d form when it appears in the compiler input.
</P><TT class=variable>lambda-list</TT><P> is a </P><TT class=code>defmacro</TT><P> style lambda-list used to
parse the arguments. The </P><TT class=variable>body</TT><P> should return a list of
subforms that can be printed on about one line. There are
predefined methods for </P><TT class=code>defstruct</TT><P>, </P><TT class=code>defmethod</TT><P>, 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.
</P></BLOCKQUOTE><!--TOC section Types in Python-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc119">4.5</A>&#XA0;&#XA0;Types in Python</H2><!--SEC END --><P>
<A NAME="@concept107"></A></P><P>A big difference between Python and all other Common Lisp compilers
is the approach to type checking and amount of knowledge about types:
</P><UL CLASS="itemize"><LI CLASS="li-itemize">Python treats type declarations much differently that other
Lisp compilers do. Python doesn&#X2019;t blindly believe type
declarations; it considers them assertions about the program that
should be checked.</LI><LI CLASS="li-itemize">Python also has a tremendously greater knowledge of the
Common Lisp type system than other compilers. Support is incomplete
only for the <TT class=code>not</TT>, <TT class=code>and</TT> and <TT class=code>satisfies</TT> types.
</LI></UL><P>
See also sections <A HREF="#advanced-type-stuff">5.2</A> and <A HREF="#type-inference">5.3</A>.</P><!--TOC subsection Compile Time Type Errors-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc120">4.5.1</A>&#XA0;&#XA0;Compile Time Type Errors</H3><!--SEC END --><P>
<A NAME="@concept108"></A>
<A NAME="@concept109"></A></P><P>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&#X2019;t always indicate an incorrect program. For example, consider
this code fragment:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(defun raz (foo)
  (let ((x (case foo
             (:this 13)
             (:that 9)
             (:the-other 42))))
    (declare (fixnum x))
    (foo x)))
</PRE></BLOCKQUOTE><P>Compilation produces this warning:</P><BLOCKQUOTE class=example><PRE>
In: DEFUN RAZ
  (CASE FOO (:THIS 13) (:THAT 9) (:THE-OTHER 42))
&#X2013;&gt; LET COND IF COND IF COND IF 
==&gt;
  (COND)
Warning: This is not a FIXNUM:
  NIL
</PRE></BLOCKQUOTE><P>In this case, the warning is telling you that if </P><TT class=code>foo</TT><P> isn&#X2019;t any
of </P><TT class=code>:this</TT><P>, </P><TT class=code>:that</TT><P> or </P><TT class=code>:the-other</TT><P>, then </P><TT class=code>x</TT><P> will be
initialized to </P><TT class=code>nil</TT><P>, which the </P><TT class=code>fixnum</TT><P> declaration makes
illegal. The warning will go away if </P><TT class=code>ecase</TT><P> is used instead of
</P><TT class=code>case</TT><P>, or if </P><TT class=code>:the-other</TT><P> is changed to </P><TT class=code>t</TT><P>.</P><P>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&#X2019;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.</P><P><BR>
<A NAME="@funs126"></A><A NAME="FN:required-argument"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>required-argument</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>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 </P><TT class=code>defstruct</TT><P> slot defaults corresponding to
required arguments. See section&#XA0;<A HREF="#empty-type">5.2.5</A>.</P><P>Although this function is a CMUCL extension, it is relatively harmless
to use it in otherwise portable code, since you can easily define it
yourself:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
    (defun required-argument ()
      (error "A required keyword argument was not supplied."))
    </PRE></BLOCKQUOTE></BLOCKQUOTE><P>Type warnings are inhibited when the
</P><TT class=code>extensions:inhibit-warnings</TT><P> optimization quality is </P><TT class=code>3</TT><P>
(see section&#XA0;<A HREF="#compiler-policy">4.7</A>.) This can be used in a local declaration
to inhibit type warnings in a code fragment that has spurious
warnings.</P><!--TOC subsection Precise Type Checking-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc121">4.5.2</A>&#XA0;&#XA0;Precise Type Checking</H3><!--SEC END --><P>
<A NAME="precise-type-checks"></A>
<A NAME="@concept110"></A>
<A NAME="@concept111"></A></P><P>With the default compilation policy, all type
assertions<SUP><A NAME="text6" HREF="#note6">1</A></SUP> are precisely
checked. Precise checking means that the check is done as though
</P><TT class=code>typep</TT><P> had been called with the exact type specifier that
appeared in the declaration. Python uses </P><TT class=variable>policy</TT><P> to determine
whether to trust type assertions (see section&#XA0;<A HREF="#compiler-policy">4.7</A>). Type
assertions from declarations are indistinguishable from the type
assertions on arguments to built-in functions. In Python, adding
type declarations makes code safer.</P><P>If a variable is declared to be </P><TT class=code>(integer 3 17)</TT><P>, then its
value must always always be an integer between </P><TT class=code>3</TT><P> and </P><TT class=code>17</TT><P>.
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 </P><TT class=code>and</TT><P> type specifier.</P><P>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 </P><TT class=code>the</TT><P>) may be lost.</P><P>The types of structure slots are also checked. The value of a
structure slot must always be of the type indicated in any </P><TT class=code>:type</TT><P>
slot option.<SUP><A NAME="text7" HREF="#note7">2</A></SUP> Because of precise type checking,
the arguments to slot accessors are checked to be the correct type of
structure.</P><P>In traditional Common Lisp 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.</P><P>To gain maximum benefit from Python&#X2019;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 </P><TT class=code>or</TT><P>,
</P><TT class=code>member</TT><P> 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.</P><P>Python uses the </P><TT class=code>safety</TT><P> optimization quality (rather than
presence or absence of declarations) to choose one of three levels of
run-time type error checking: see section&#XA0;<A HREF="#optimize-declaration">4.7.1</A>.
See section&#XA0;<A HREF="#advanced-type-stuff">5.2</A> for more information about types in
Python.</P><!--TOC subsection Weakened Type Checking-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc122">4.5.3</A>&#XA0;&#XA0;Weakened Type Checking</H3><!--SEC END --><P>
<A NAME="weakened-type-checks"></A>
<A NAME="@concept112"></A>
<A NAME="@concept113"></A></P><P>When the value for the </P><TT class=code>speed</TT><P> optimization quality is greater
than </P><TT class=code>safety</TT><P>, and </P><TT class=code>safety</TT><P> is not </P><TT class=code>0</TT><P>, 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 &#X201C;safe&#X201D; code in other Common Lisp compilers.</P><P>A type check is weakened by changing the check to be for some
convenient supertype of the asserted type. For example,
</P><TT class=code>(integer 3 17)</TT><P> is changed to </P><TT class=code>fixnum</TT><P>,
</P><TT class=code>(simple-vector 17)</TT><P> to </P><TT class=code>simple-vector</TT><P>, and structure
types are changed to </P><TT class=code>structure</TT><P>. A complex check like:
</P><BLOCKQUOTE class=example><PRE>
(or node hunk (member :foo :bar :baz))
</PRE></BLOCKQUOTE><P>
will be omitted entirely (i.e., the check is weakened to </P><TT class=code>*</TT><P>.) If
a precise check can be done for no extra cost, then no weakening is
done.</P><P>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.</P><P>For example, if this code was compiled with weakened checks:</P><BLOCKQUOTE CLASS=lisp> <PRE>
(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))
</PRE></BLOCKQUOTE><P>and </P><TT class=code>myfun</TT><P> was passed a </P><TT class=code>foo</TT><P>, then no type error would be
signaled, and we would try to multiply a </P><TT class=code>simple-vector</TT><P> as
though it were a float (with unpredictable results.) This is because
the check for </P><TT class=code>bar</TT><P> was weakened to </P><TT class=code>structure</TT><P>, yet when
compiling the call to </P><TT class=code>bar-a</TT><P>, the compiler thinks it knows it
has a </P><TT class=code>bar</TT><P>.</P><P>Note that normally even weakened type checks report the precise type
in error messages. For example, if </P><TT class=code>myfun</TT><P>&#X2019;s </P><TT class=code>bar</TT><P> check is
weakened to </P><TT class=code>structure</TT><P>, and the argument is </P><TT class=code>nil</TT><P>, then the
error will be:</P><BLOCKQUOTE class=example><PRE>
Type-error in MYFUN:
  NIL is not of type BAR
</PRE></BLOCKQUOTE><P>However, there is some speed and space cost for signaling a precise
error, so the weakened type is reported if the </P><TT class=code>speed</TT><P>
optimization quality is </P><TT class=code>3</TT><P> or </P><TT class=code>debug</TT><P> quality is less than
</P><TT class=code>1</TT><P>:</P><BLOCKQUOTE class=example><PRE>
Type-error in MYFUN:
  NIL is not of type STRUCTURE
</PRE></BLOCKQUOTE><P>See section&#XA0;<A HREF="#optimize-declaration">4.7.1</A> for further discussion of the
</P><TT class=code>optimize</TT><P> declaration.</P><!--TOC section Getting Existing Programs to Run-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc123">4.6</A>&#XA0;&#XA0;Getting Existing Programs to Run</H2><!--SEC END --><P>
<A NAME="@concept114"></A>
<A NAME="@concept115"></A>
<A NAME="@concept116"></A></P><P>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.</P><P>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.</B> Python does much more type inference than other
Common Lisp compilers, so believing an incorrect declaration does much
more damage.</P><P>The most common problem is with variables whose initial value doesn&#X2019;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:</P><BLOCKQUOTE class=example><PRE>
(prog (foo)
  (declare (fixnum foo))
  (setq foo ...)
  ...)
</PRE></BLOCKQUOTE><P>Here the variable </P><TT class=code>foo</TT><P> is given an initial value of </P><TT class=code>nil</TT><P>, but
is declared to be a </P><TT class=code>fixnum</TT><P>. 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:</P><BLOCKQUOTE class=example><PRE>
(prog (foo)
  (declare (type (or fixnum null) foo))
  (setq foo ...)
  ...)
</PRE></BLOCKQUOTE><P>or change the initial value:</P><BLOCKQUOTE class=example><PRE>
(prog ((foo 0))
  (declare (fixnum foo))
  (setq foo ...)
  ...)
</PRE></BLOCKQUOTE><P>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.</P><P>Another declaration problem occasionally encountered is incorrect
declarations on </P><TT class=code>defmacro</TT><P> arguments. This probably usually
happens when a function is converted into a macro. Consider this
macro:</P><BLOCKQUOTE CLASS=lisp> <PRE>
(defmacro my-1+ (x)
  (declare (fixnum x))
  &#X2018;(the fixnum (1+ ,x)))
</PRE></BLOCKQUOTE><P>Although legal and well-defined Common Lisp, this meaning of this
definition is almost certainly not what the writer intended. For
example, this call is illegal:</P><BLOCKQUOTE CLASS=lisp> <PRE>
(my-1+ (+ 4 5))
</PRE></BLOCKQUOTE><P>The call is illegal because the argument to the macro is </P><TT class=code>(+ 4
5)</TT><P>, which is a </P><TT class=code>list</TT><P>, not a </P><TT class=code>fixnum</TT><P>. 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
</P><TT class=code>the</TT><P> in the expansion:</P><BLOCKQUOTE CLASS=lisp> <PRE>
(defmacro my-1+ (x)
  &#X2018;(the fixnum (1+ (the fixnum ,x))))
</PRE></BLOCKQUOTE><P>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.
See section&#XA0;<A HREF="#inline-expansion">5.8</A>.</P><P>Some more subtle problems are caused by incorrect declarations that
can&#X2019;t be detected at compile time. Consider this code:</P><BLOCKQUOTE class=example><PRE>
(do ((pos 0 (position #\a string :start (1+ pos))))
    ((null pos))
  (declare (fixnum pos))
  ...)
</PRE></BLOCKQUOTE><P>Although </P><TT class=code>pos</TT><P> is almost always a </P><TT class=code>fixnum</TT><P>, it is </P><TT class=code>nil</TT><P>
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 </P><TT class=code>position</TT><P> will complain
because </P><TT class=code>(1+ nil)</TT><P> isn&#X2019;t a sensible start.) Why? Because if
you compile without type checks, the compiler just quietly believes
the type declaration. Since </P><TT class=code>pos</TT><P> is always a </P><TT class=code>fixnum</TT><P>, it
is never </P><TT class=code>nil</TT><P>, so </P><TT class=code>(null pos)</TT><P> is never true, and the loop
exit test is optimized away. Such errors are sometimes flagged by
unreachable code notes (see section&#XA0;<A HREF="#dead-code-notes">5.4.5</A>), 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.</P><P>In this case, the fix is to weaken the type declaration to
</P><TT class=code>(or fixnum null)</TT><P>.<SUP><A NAME="text8" HREF="#note8">3</A></SUP>
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 </P><TT class=code>fixnum</TT><P>, since </P><TT class=code>nil</TT><P> is not a legal
numeric argument. Another possible fix would be to say:</P><BLOCKQUOTE class=example><PRE>
(do ((pos 0 (position #\a string :start (1+ pos))))
    ((null pos))
  (let ((pos pos))
    (declare (fixnum pos))
    ...))
</PRE></BLOCKQUOTE><P>This would be preferable in some circumstances, since it would allow a
non-standard representation to be used for the local </P><TT class=code>pos</TT><P>
variable in the loop body (see section <A HREF="#ND-variables">5.11.3</A>.)</P><P>In summary, remember that <EM>all</EM> values that a variable <EM>ever</EM>
has must be of the declared type, and that you should test using safe
code initially.</P><!--TOC section Compiler Policy-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc124">4.7</A>&#XA0;&#XA0;Compiler Policy</H2><!--SEC END --><P>
<A NAME="compiler-policy"></A>
<A NAME="@concept117"></A>
<A NAME="@concept118"></A></P><P>The policy is what tells the compiler </P><TT class=variable>how</TT><P> to compile a program.
This is logically (and often textually) distinct from the program
itself. Broad control of policy is provided by the </P><TT class=code>optimize</TT><P>
declaration; other declarations and variables control more specific
aspects of compilation.</P><!--TOC subsection The Optimize Declaration-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc125">4.7.1</A>&#XA0;&#XA0;The Optimize Declaration</H3><!--SEC END --><P>
<A NAME="optimize-declaration"></A>
<A NAME="@concept119"></A>
<A NAME="@concept120"></A></P><P>The </P><TT class=code>optimize</TT><P> declaration recognizes six different
</P><TT class=variable>qualities</TT><P>. 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 </P><TT class=code>speed</TT><P> is greater than </P><TT class=code>safety</TT><P>, then improve speed at
the cost of safety.</P><P>The default for all qualities (except </P><TT class=code>debug</TT><P>) is </P><TT class=code>1</TT><P>.
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 </P><TT class=code>speed</TT><P>, </P><TT class=code>compile-speed</TT><P> and </P><TT class=code>space</TT><P> in
favor of </P><TT class=code>safety</TT><P> and </P><TT class=code>debug</TT><P>. 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.</P><P>If the value for a quality is </P><TT class=code>0</TT><P> or </P><TT class=code>3</TT><P>, then it may have a
special interpretation. A value of </P><TT class=code>0</TT><P> means &#X201C;totally
unimportant&#X201D;, and a </P><TT class=code>3</TT><P> means &#X201C;ultimately important.&#X201D; These
extreme optimization values enable &#X201C;heroic&#X201D; compilation strategies
that are not always desirable and sometimes self-defeating.
Specifying more than one quality as </P><TT class=code>3</TT><P> is not desirable, since
it doesn&#X2019;t tell the compiler which quality is most important.</P><P>These are the optimization qualities:

</P><DL CLASS="list"><DT CLASS="dt-list">
<TT class=code>speed</TT><BR>
</DT><DD CLASS="dd-list"> <A NAME="@concept121"></A>How fast the
program should is run. <TT class=code>speed 3</TT> enables some optimizations
that hurt debuggability.</DD><DT CLASS="dt-list"><TT class=code>compilation-speed</TT><BR>
</DT><DD CLASS="dd-list"> <A NAME="@concept122"></A>How fast the compiler should run. Note that increasing
this above <TT class=code>safety</TT> weakens type checking.</DD><DT CLASS="dt-list"><TT class=code>space</TT><BR>
</DT><DD CLASS="dd-list"> <A NAME="@concept123"></A>How much space
the compiled code should take up. Inline expansion is mostly
inhibited when <TT class=code>space</TT> is greater than <TT class=code>speed</TT>. A value
of <TT class=code>0</TT> enables promiscuous inline expansion. Wide use of a
<TT class=code>0</TT> value is not recommended, as it may waste so much space
that run time is slowed. See section&#XA0;<A HREF="#inline-expansion">5.8</A> for a discussion
of inline expansion.</DD><DT CLASS="dt-list"><TT class=code>debug</TT><BR>
</DT><DD CLASS="dd-list"> <A NAME="@concept124"></A>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.
See section&#XA0;<A HREF="#debugger-policy">3.6</A> for more details.</DD><DT CLASS="dt-list"><TT class=code>safety</TT><BR>
</DT><DD CLASS="dd-list"> <A NAME="@concept125"></A>How much
error checking should be done. If <TT class=code>speed</TT>, <TT class=code>space</TT> or
<TT class=code>compilation-speed</TT> is more important than <TT class=code>safety</TT>, then
type checking is weakened (see section&#XA0;<A HREF="#weakened-type-checks">4.5.3</A>). If
<TT class=code>safety</TT> if <TT class=code>0</TT>, then no run time error checking is done.
In addition to suppressing type checks, <TT class=code>0</TT> also suppresses
argument count checking, unbound-symbol checking and array bounds
checks.</DD><DT CLASS="dt-list"><TT class=code>extensions:inhibit-warnings</TT><BR>
</DT><DD CLASS="dd-list"> <A NAME="@concept126"></A>This is a CMUCL 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 <TT class=code>speed</TT> is greater than <TT class=code>inhibit-warnings</TT>,
then notes about how to improve speed will be printed, etc. The
default value is <TT class=code>1</TT>, so raising the value for any standard
quality above its default enables notes for that quality. If
<TT class=code>inhibit-warnings</TT> is <TT class=code>3</TT>, then all notes and most
non-serious warnings are inhibited. This is useful with
<TT class=code>declare</TT> to suppress warnings about unavoidable problems.
</DD></DL><!--TOC subsection The Optimize-Interface Declaration-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc126">4.7.2</A>&#XA0;&#XA0;The Optimize-Interface Declaration</H3><!--SEC END --><P>
<A NAME="optimize-interface-declaration"></A>
<A NAME="@concept127"></A>
<A NAME="@concept128"></A></P><P>The </P><TT class=code>extensions:optimize-interface</TT><P> declaration is identical in
syntax to the </P><TT class=code>optimize</TT><P> 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 </P><TT class=code>optimize-interface</TT><P> declaration can specify that arguments
should be checked even when the general </P><TT class=code>optimize</TT><P> policy is
unsafe.</P><P>Note that this argument checking is the checking of user-supplied
arguments to any functions defined within the scope of the
declaration, </P><TT class=code>not</TT><P> the checking of arguments to Common Lisp
primitives that appear in those definitions.</P><P>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 </P><TT class=code>:context-declarations</TT><P> option to
<A NAME="@funs127"></A></P><TT class=code>with-compilation-unit</TT><P>.</P><!--TOC section Open Coding and Inline Expansion-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc127">4.8</A>&#XA0;&#XA0;Open Coding and Inline Expansion</H2><!--SEC END --><P>
<A NAME="open-coding"></A>
<A NAME="@concept129"></A>
<A NAME="@concept130"></A>
<A NAME="@concept131"></A></P><P>Since Common Lisp forbids the redefinition of standard functions<SUP><A NAME="text9" HREF="#note9">4</A></SUP>, 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:
</P><UL CLASS="itemize"><LI CLASS="li-itemize">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 <TT class=code>trace</TT> macro. Special-casing of standard functions can be
inhibited using the <TT class=code>notinline</TT> declaration.</LI><LI CLASS="li-itemize">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,
see section&#XA0;<A HREF="#compiler-policy">4.7</A>.
</LI></UL><P>When a function call is <EM>open coded</EM>, inline code whose effect is
equivalent to the function call is substituted for that function call.
When a function call is <EM>closed coded</EM>, 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 </P><TT class=code>nthcdr</TT><P> were to be open
coded, then</P><BLOCKQUOTE CLASS=lisp> <PRE>
(nthcdr 4 foobar)
</PRE></BLOCKQUOTE><P>might turn into</P><BLOCKQUOTE CLASS=lisp> <PRE>
(cdr (cdr (cdr (cdr foobar))))
</PRE></BLOCKQUOTE><P>or even </P><BLOCKQUOTE CLASS=lisp> <PRE>
(do ((i 0 (1+ i))
     (list foobar (cdr foobar)))
    ((= i 4) list))
</PRE></BLOCKQUOTE><P>If </P><TT class=code>nth</TT><P> is closed coded, then</P><BLOCKQUOTE CLASS=lisp> <PRE>
(nth x l)
</PRE></BLOCKQUOTE><P>might stay the same, or turn into something like:</P><BLOCKQUOTE CLASS=lisp> <PRE>
(car (nthcdr x l))
</PRE></BLOCKQUOTE><P>In general, open coding sacrifices space for speed, but some functions (such as
</P><TT class=code>car</TT><P>) 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 <EM>static call</EM>. Static function call uses a more efficient calling
convention that forbids redefinition.
</P><!--NAME compiler.html-->
<!--BEGIN NOTES chapter-->
<HR CLASS="ffootnoterule"><DL CLASS="thefootnotes"><DT CLASS="dt-thefootnotes">
<A NAME="note6" HREF="#text6">1</A></DT><DD CLASS="dd-thefootnotes">There are a few circumstances where a type
declaration is discarded rather than being used as type assertion.
This doesn&#X2019;t affect safety much, since such discarded declarations
are also not believed to be true by the compiler.
</DD><DT CLASS="dt-thefootnotes"><A NAME="note7" HREF="#text7">2</A></DT><DD CLASS="dd-thefootnotes">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
<TT class=code>required-argument</TT> is used.
</DD><DT CLASS="dt-thefootnotes"><A NAME="note8" HREF="#text8">3</A></DT><DD CLASS="dd-thefootnotes">Actually, this declaration is
totally unnecessary in Python, since it already knows
<TT class=code>position</TT> returns a non-negative <TT class=code>fixnum</TT> or <TT class=code>nil</TT>.
</DD><DT CLASS="dt-thefootnotes"><A NAME="note9" HREF="#text9">4</A></DT><DD CLASS="dd-thefootnotes">See the
proposed X3J13 &#X201C;lisp-symbol-redefinition&#X201D; cleanup.
</DD></DL>
<!--END NOTES-->
<!--TOC chapter Advanced Compiler Use and Efficiency Hints-->
<H1 CLASS="chapter"><!--SEC ANCHOR --><A NAME="htoc128">Chapter&#XA0;5</A>&#XA0;&#XA0;Advanced Compiler Use and Efficiency Hints</H1><!--SEC END --><P>
<A NAME="advanced-compiler"></A></P><DIV CLASS="center">
<B>by Robert MacLachlan</B>
</DIV><!--TOC section Advanced Compiler Introduction-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc129">5.1</A>&#XA0;&#XA0;Advanced Compiler Introduction</H2><!--SEC END --><P>In CMUCL, as with 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&#X2019;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.</P><P>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.</P><!--TOC subsection Types-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc130">5.1.1</A>&#XA0;&#XA0;Types</H3><!--SEC END --><P>Python&#X2019;s support for types is unusual in three major ways:
</P><UL CLASS="itemize"><LI CLASS="li-itemize">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. See section&#XA0;<A HREF="#precise-type-checks">4.5.2</A>. Python
produces completely safe code; optimized type checking maintains
reasonable efficiency on conventional hardware
(see section&#XA0;<A HREF="#type-check-optimization">5.3.6</A>.)</LI><LI CLASS="li-itemize">Comprehensive support for the Common Lisp type system makes complex
type specifiers useful. Using type specifiers such as <TT class=code>or</TT> and
<TT class=code>member</TT> has both efficiency and robustness advantages.
See section&#XA0;<A HREF="#advanced-type-stuff">5.2</A>.</LI><LI CLASS="li-itemize">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
<A HREF="#type-inference">5.3</A> and <A HREF="#non-descriptor">5.11.2</A>.
</LI></UL><!--TOC subsection Optimization-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc131">5.1.2</A>&#XA0;&#XA0;Optimization</H3><!--SEC END --><P>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 &#X201C;reasonable&#X201D;
ways to code a given problem. It is desirable to make all of these
equivalent solutions have comparable efficiency so that programmers
don&#X2019;t have to waste time discovering the most efficient solution.</P><P>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 &#X201C;best&#X201D; solution. Source level optimization
transforms the original program into a more efficient (but equivalent)
program. Although the optimizer isn&#X2019;t doing anything the programmer
couldn&#X2019;t have done, this high-level optimization is important because:</P><UL CLASS="itemize"><LI CLASS="li-itemize"> 
The programmer can code simply and directly, rather than
obfuscating code to please the compiler.</LI><LI CLASS="li-itemize">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.
</LI></UL><P>Source level optimization eliminates the need for macros to optimize
their expansion, and also increases the effectiveness of inline
expansion. See sections <A HREF="#source-optimization">5.4</A> and
<A HREF="#inline-expansion">5.8</A>.</P><P>Efficient support for a safer programming style is the biggest
advantage of source level optimization. Existing tuned programs
typically won&#X2019;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:</P><UL CLASS="itemize"><LI CLASS="li-itemize"> 
Low level optimization and register allocation provides modest
speedups in any program.</LI><LI CLASS="li-itemize">Block compilation and inline expansion can reduce function call
overhead, but may require some program restructuring. See sections
<A HREF="#inline-expansion">5.8</A>, <A HREF="#local-call">5.6</A> and
<A HREF="#block-compilation">5.7</A>.</LI><LI CLASS="li-itemize">Efficiency notes will point out important type declarations that
are often missed even in highly tuned programs.
See section&#XA0;<A HREF="#efficiency-notes">5.13</A>.</LI><LI CLASS="li-itemize">Existing programs can be compiled safely without prohibitive
speed penalty, although they would be faster and safer with added
declarations. See section&#XA0;<A HREF="#type-check-optimization">5.3.6</A>.</LI><LI CLASS="li-itemize">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
<TT class=code>optimize</TT> declarations to the source.
See section&#XA0;<A HREF="#context-declarations">5.7.5</A>.</LI><LI CLASS="li-itemize">Byte compilation can be used to dramatically reduce the size of
code that is not speed-critical. See section&#XA0;<A HREF="#byte-compile">5.9</A>
</LI></UL><!--TOC subsection Function Call-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc132">5.1.3</A>&#XA0;&#XA0;Function Call</H3><!--SEC END --><P>The sort of symbolic programs generally written in Common Lisp 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 Common Lisp 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:</P><UL CLASS="itemize"><LI CLASS="li-itemize"> 
Local call resolves function references at compile time,
allowing better calling sequences and optimization across function
calls. See section&#XA0;<A HREF="#local-call">5.6</A>.</LI><LI CLASS="li-itemize">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 Common Lisp implementations support
inline expansion, it becomes a more powerful tool with Python&#X2019;s
source level optimization. See sections <A HREF="#source-optimization">5.4</A>
and <A HREF="#inline-expansion">5.8</A>.
</LI></UL><P>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:</P><UL CLASS="itemize"><LI CLASS="li-itemize"> 
Proper tail recursion. See section&#XA0;<A HREF="#tail-recursion">5.5</A></LI><LI CLASS="li-itemize">Relatively efficient closures.</LI><LI CLASS="li-itemize">A <TT class=code>funcall</TT> that is as efficient as normal named call.</LI><LI CLASS="li-itemize">Calls to local functions such as from <TT class=code>labels</TT> are
optimized:
<UL CLASS="itemize"><LI CLASS="li-itemize">Control transfer is a direct jump.</LI><LI CLASS="li-itemize">The closure environment is passed in registers rather than heap
allocated.</LI><LI CLASS="li-itemize">Keyword arguments and multiple values are implemented more
efficiently.
</LI></UL><P>See section&#XA0;<A HREF="#local-call">5.6</A>.
</P></LI></UL><!--TOC subsection Representation of Objects-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc133">5.1.4</A>&#XA0;&#XA0;Representation of Objects</H3><!--SEC END --><P>Sometimes traditional Common Lisp implementation techniques compare so
poorly to the techniques used in other languages that Common Lisp can
become an impractical language choice. Terrible inefficiencies appear
in number-crunching programs, since Common Lisp 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.</P><P>See section <A HREF="#non-descriptor">5.11.2</A> for more about object representations and
numeric types. Also see section&#XA0;<A HREF="#efficiency-notes">5.13</A> about efficiency notes.</P><!--TOC subsection Writing Efficient Code-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc134">5.1.5</A>&#XA0;&#XA0;Writing Efficient Code</H3><!--SEC END --><P>
<A NAME="efficiency-overview"></A></P><P>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:
</P><UL CLASS="itemize"><LI CLASS="li-itemize">The program should be correct&#X2014;it doesn&#X2019;t matter how
quickly you get the wrong answer.</LI><LI CLASS="li-itemize">Both the programmer and the user will make errors, so the
program must be robust&#X2014;it must detect errors in a way that
allows easy correction.</LI><LI CLASS="li-itemize">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 &#X201C;hot
spots&#X201D; will be.
</LI></UL><P>The best way to get efficient code that is still worth using, is to separate
coding from tuning. During coding, you should:
</P><UL CLASS="itemize"><LI CLASS="li-itemize">Use a coding style that aids correctness and robustness without
being incompatible with efficiency.</LI><LI CLASS="li-itemize">Choose appropriate data structures that allow efficient
algorithms and object representations
(see section&#XA0;<A HREF="#object-representation">5.10</A>). Try to make interfaces abstract
enough so that you can change to a different representation if
profiling reveals a need.</LI><LI CLASS="li-itemize">Whenever you make an assumption about a function argument or
global data structure, add consistency assertions, either with type
declarations or explicit uses of <TT class=code>assert</TT>, <TT class=code>ecase</TT>, etc.
</LI></UL><P>During tuning, you should:
</P><UL CLASS="itemize"><LI CLASS="li-itemize">Identify the hot spots in the program through profiling (section
<A HREF="#profiling">5.14</A>.)</LI><LI CLASS="li-itemize">Identify inefficient constructs in the hot spot with efficiency
notes, more profiling, or manual inspection of the source. See
sections <A HREF="#general-efficiency">5.12</A> and <A HREF="#efficiency-notes">5.13</A>.</LI><LI CLASS="li-itemize">Add declarations and consider the application of optimizations.
See sections <A HREF="#local-call">5.6</A>, <A HREF="#inline-expansion">5.8</A> and
<A HREF="#non-descriptor">5.11.2</A>.</LI><LI CLASS="li-itemize">If all else fails, consider algorithm or data structure changes.
If you did a good job coding, changes will be easy to introduce.
</LI></UL><!--TOC section More About Types in Python-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc135">5.2</A>&#XA0;&#XA0;More About Types in Python</H2><!--SEC END --><P>
<A NAME="advanced-type-stuff"></A>
<A NAME="@concept132"></A></P><P>This section goes into more detail describing what types and declarations are
recognized by Python. The area where Python differs most radically from
previous Common Lisp compilers is in its support for types:
</P><UL CLASS="itemize"><LI CLASS="li-itemize">Precise type checking helps to find bugs at run time.</LI><LI CLASS="li-itemize">Compile-time type checking helps to find bugs at compile time.</LI><LI CLASS="li-itemize">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.</LI><LI CLASS="li-itemize">Support for detailed types provides a wealth of opportunity for
operation-specific type inference and optimization.
</LI></UL><!--TOC subsection More Types Meaningful-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc136">5.2.1</A>&#XA0;&#XA0;More Types Meaningful</H3><!--SEC END --><P>Common Lisp has a very powerful type system, but conventional Common Lisp
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
</P><TT class=code>fixnum</TT><P> will be recognized by the compiler, but a highly
specific declaration such as </P><TT class=code>(integer 3 17)</TT><P> is totally
ignored.</P><P>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.</P><P>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.</P><P>Python &#X201C;understands&#X201D; the list-style </P><TT class=code>or</TT><P>, </P><TT class=code>member</TT><P>,
</P><TT class=code>function</TT><P>, array and number type specifiers. Understanding
means that:
</P><UL CLASS="itemize"><LI CLASS="li-itemize">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.</LI><LI CLASS="li-itemize">In many contexts, the extra information from these type
specifier is used to good effect. In particular, type checking in
Python is <TT class=variable>precise</TT>, so these complex types can be used
in declarations to make interesting assertions about functions and
data structures (see section&#XA0;<A HREF="#precise-type-checks">4.5.2</A>.) More specific
declarations also aid type inference and reduce the cost for type
checking.
</LI></UL><P>For related information, see section&#XA0;<A HREF="#numeric-types">5.11</A> for numeric types, and
section <A HREF="#array-types">5.10.3</A> for array types.</P><!--TOC subsection Canonicalization-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc137">5.2.2</A>&#XA0;&#XA0;Canonicalization</H3><!--SEC END --><P>
<A NAME="@concept133"></A>
<A NAME="@concept134"></A>
<A NAME="@concept135"></A></P><P>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&#X2019;s
canonical representation, these types are equivalent:
</P><BLOCKQUOTE class=example><PRE>
(or list (member :end)) &lt;==&gt; (or cons (member nil :end))
</PRE></BLOCKQUOTE><P>
This has two implications for the user:
</P><UL CLASS="itemize"><LI CLASS="li-itemize">The standard symbol type specifiers for <TT class=code>atom</TT>,
<TT class=code>null</TT>, <TT class=code>fixnum</TT>, etc., are in no way magical. The
<A NAME="@types22"></A><TT class=code>null</TT> type is actually defined to be <TT class=code>(member
nil)</TT>, <A NAME="@types23"></A><TT class=code>list</TT> is <TT class=code>(or cons null)</TT>, and
<A NAME="@types24"></A><TT class=code>fixnum</TT> is <TT class=code>(signed-byte 30)</TT>.</LI><LI CLASS="li-itemize">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.
</LI></UL><!--TOC subsection Member Types-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc138">5.2.3</A>&#XA0;&#XA0;Member Types</H3><!--SEC END --><P>
<A NAME="@concept136"></A></P><P>The <A NAME="@types25"></A></P><TT class=code>member</TT><P> type specifier can be used to represent
&#X201C;symbolic&#X201D; values, analogous to the enumerated types of Pascal. For
example, the second value of </P><TT class=code>find-symbol</TT><P> has this type:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(member :internal :external :inherited nil)
</PRE></BLOCKQUOTE><P>
Member types are very useful for expressing consistency constraints on data
structures, for example:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(defstruct ice-cream
  (flavor :vanilla :type (member :vanilla :chocolate :strawberry)))
</PRE></BLOCKQUOTE><P>
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.</P><!--TOC subsection Union Types-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc139">5.2.4</A>&#XA0;&#XA0;Union Types</H3><!--SEC END --><P>
<A NAME="@concept137"></A>
<A NAME="@concept138"></A></P><P>The <A NAME="@types26"></A></P><TT class=code>or</TT><P> (union) type specifier is understood, and is
meaningfully applied in many contexts. The use of </P><TT class=code>or</TT><P> allows
assertions to be made about types in dynamically typed programs. For
example:</P><BLOCKQUOTE CLASS=lisp> <PRE>
(defstruct box
  (next nil :type (or box null))
  (top :removed :type (or box-top (member :removed))))
</PRE></BLOCKQUOTE><P>The type assertion on the </P><TT class=code>top</TT><P> slot ensures that an error will be signaled
when there is an attempt to store an illegal value (such as </P><TT class=code>:rmoved</TT><P>.)
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:</P><BLOCKQUOTE CLASS=lisp> <PRE>
(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))))
</PRE></BLOCKQUOTE><P>Union types are also useful in type inference for representing types that are
partially constrained. For example, the result of this expression:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(if foo
    (logior x y)
    (list x y))
</PRE></BLOCKQUOTE><P>
can be expressed as </P><TT class=code>(or integer cons)</TT><P>.</P><!--TOC subsection The Empty Type-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc140">5.2.5</A>&#XA0;&#XA0;The Empty Type</H3><!--SEC END --><P>
<A NAME="empty-type"></A>
<A NAME="@concept139"></A>
<A NAME="@concept140"></A>
<A NAME="@concept141"></A></P><P>The type </P><TT class=code>nil</TT><P> is also called the empty type, since no object is of
type </P><TT class=code>nil</TT><P>. The union of no types, </P><TT class=code>(or)</TT><P>, is also empty.
Python&#X2019;s interpretation of an expression whose type is </P><TT class=code>nil</TT><P> 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
</P><TT class=code>error</TT><P> or a use of </P><TT class=code>return</TT><P> is </P><TT class=code>nil</TT><P>. 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 </P><TT class=code>nil</TT><P>, but does in fact
return, then (in safe compilation policies) a &#X201C;</P><TT class=code>NIL Function
returned</TT><P>&#X201D; error will be signaled. See also the function
<A NAME="@funs128"></A></P><TT class=code>required-argument</TT><P>.</P><!--TOC subsection Function Types-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc141">5.2.6</A>&#XA0;&#XA0;Function Types</H3><!--SEC END --><P>
<A NAME="function-types"></A>
<A NAME="@concept142"></A>
<A NAME="@concept143"></A></P><P><A NAME="@funs129"></A></P><TT class=code>function</TT><P> types are understood in the restrictive sense, specifying:
</P><UL CLASS="itemize"><LI CLASS="li-itemize">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.</LI><LI CLASS="li-itemize">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&#X2019;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
<TT class=code>foo</TT> is declared to have a <TT class=code>fixnum</TT> argument, then the
<TT class=code>1+</TT> in <TT class=code>(foo (1+ x))</TT> is compiled with knowledge that
the result must be a fixnum.</LI><LI CLASS="li-itemize">The types the values that will be bound to argument variables in
the function&#X2019;s definition. Declaring a function&#X2019;s type with
<TT class=code>ftype</TT> implicitly declares the types of the arguments in the
definition. Python checks for consistency between the definition
and the <TT class=code>ftype</TT> declaration. Because of precise type checking,
an error will be signaled when a function is called with an
argument of the wrong type.</LI><LI CLASS="li-itemize">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 <TT class=code>fixnum</TT>, then when a call to
that function appears in an expression, the expression will be
compiled with knowledge that the call will return a <TT class=code>fixnum</TT>.</LI><LI CLASS="li-itemize">The type of return value(s) that the definition must return.
The result type in an <TT class=code>ftype</TT> declaration is treated like an
implicit <TT class=code>the</TT> 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.
</LI></UL><P>This is consistent with the new interpretation of function types and
the </P><TT class=code>ftype</TT><P> declaration in the proposed X3J13
&#X201C;function-type-argument-type-semantics&#X201D; cleanup. Note also, that if
you don&#X2019;t explicitly declare the type of a function using a global
</P><TT class=code>ftype</TT><P> declaration, then Python will compute a function type
from the definition, providing a degree of inter-routine type
inference, see section&#XA0;<A HREF="#function-type-inference">5.3.3</A>.</P><!--TOC subsection The Values Declaration-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc142">5.2.7</A>&#XA0;&#XA0;The Values Declaration</H3><!--SEC END --><P>
<A NAME="@concept144"></A></P><P>CMUCL supports the </P><TT class=code>values</TT><P> declaration as an extension to
Common Lisp. The syntax of the declaration is 
</P><TT class=code>(values <TT class=variable>type1</TT> <TT class=variable>type2</TT>&#X2026;<TT class=variable>typen</TT>)</TT><P>. This
declaration is semantically equivalent to a </P><TT class=code>the</TT><P> form wrapped
around the body of the special form in which the </P><TT class=code>values</TT><P>
declaration appears. The advantage of </P><TT class=code>values</TT><P> over
<A NAME="@funs130"></A></P><TT class=code>the</TT><P> is purely syntactic&#X2014;it doesn&#X2019;t introduce more
indentation. For example:</P><BLOCKQUOTE class=example><PRE>
(defun foo (x)
  (declare (values single-float))
  (ecase x
    (:this ...)
    (:that ...)
    (:the-other ...)))
</PRE></BLOCKQUOTE><P>is equivalent to:</P><BLOCKQUOTE class=example><PRE>
(defun foo (x)
  (the single-float
       (ecase x
         (:this ...)
         (:that ...)
         (:the-other ...))))
</PRE></BLOCKQUOTE><P>and</P><BLOCKQUOTE class=example><PRE>
(defun floor (number &amp;optional (divisor 1))
  (declare (values integer real))
  ...)
</PRE></BLOCKQUOTE><P>is equivalent to:</P><BLOCKQUOTE class=example><PRE>
(defun floor (number &amp;optional (divisor 1))
  (the (values integer real)
       ...))
</PRE></BLOCKQUOTE><P>In addition to being recognized by </P><TT class=code>lambda</TT><P> (and hence by
</P><TT class=code>defun</TT><P>), the </P><TT class=code>values</TT><P> declaration is recognized by all the
other special forms with bodies and declarations: </P><TT class=code>let</TT><P>,
</P><TT class=code>let*</TT><P>, </P><TT class=code>labels</TT><P> and </P><TT class=code>flet</TT><P>. 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
</P><TT class=code>values</TT><P> declaration will depend on the macro.</P><P>If you declare the types of all arguments to a function, and also
declare the return value types with </P><TT class=code>values</TT><P>, 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 (see section&#XA0;<A HREF="#function-types">5.2.6</A>.) This provides a
way to declare the types of functions that is much less syntactically
awkward than using the </P><TT class=code>ftype</TT><P> declaration with a </P><TT class=code>function</TT><P>
type specifier.</P><P>Although the </P><TT class=code>values</TT><P> 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
</P><TT class=code>declaration</TT><P> proclamation.</P><!--TOC subsection Structure Types-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc143">5.2.8</A>&#XA0;&#XA0;Structure Types</H3><!--SEC END --><P>
<A NAME="structure-types"></A>
<A NAME="@concept145"></A>
<A NAME="@concept146"></A>
<A NAME="@concept147"></A></P><P>Because of precise type checking, structure types are much better
supported by Python than by conventional compilers:</P><UL CLASS="itemize"><LI CLASS="li-itemize"> 
The structure argument to structure accessors is precisely
checked&#X2014;if you call <TT class=code>foo-a</TT> on a <TT class=code>bar</TT>, an error
will be signaled.</LI><LI CLASS="li-itemize">The types of slot values are precisely checked&#X2014;if you pass
the wrong type argument to a constructor or a slot setter, then an
error will be signaled.
</LI></UL><P>This error checking is tremendously useful for detecting bugs in
programs that manipulate complex data structures.</P><P>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&#X2019;s type. Consider
this example:</P><BLOCKQUOTE CLASS=lisp> <PRE>
(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)))
</PRE></BLOCKQUOTE><TT class=code>make-it</TT><P> and </P><TT class=code>use-it</TT><P> are compiled with no checking on the
types of the float slots, yet </P><TT class=code>use-it</TT><P> can use
</P><TT class=code>single-float</TT><P> arithmetic with perfect safety. Note that
</P><TT class=code>make-coordinate</TT><P> must still check the values of </P><TT class=code>x</TT><P> and
</P><TT class=code>y</TT><P> unless the call is block compiled or inline expanded
(see section&#XA0;<A HREF="#local-call">5.6</A>.) 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.</P><!--TOC subsection The Freeze-Type Declaration-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc144">5.2.9</A>&#XA0;&#XA0;The Freeze-Type Declaration</H3><!--SEC END --><P>
<A NAME="@concept148"></A>
<A NAME="freeze-type"></A></P><P>The </P><TT class=code>extensions:freeze-type</TT><P> declaration is a CMUCL 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 </P><TT class=code>declaim</TT><P> or </P><TT class=code>proclaim</TT><P>). Currently
</P><TT class=code>freeze-type</TT><P> only affects structure type testing done by
</P><TT class=code>typep</TT><P>, </P><TT class=code>typecase</TT><P>, etc. Here is an example:</P><BLOCKQUOTE CLASS=lisp> <PRE>
(declaim (freeze-type foo bar))
</PRE></BLOCKQUOTE><P>This asserts that the types </P><TT class=code>foo</TT><P> and </P><TT class=code>bar</TT><P> 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.</P><!--TOC subsection Type Restrictions-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc145">5.2.10</A>&#XA0;&#XA0;Type Restrictions</H3><!--SEC END --><P>
<A NAME="@concept149"></A></P><P>Avoid use of the </P><TT class=code>and</TT><P>, </P><TT class=code>not</TT><P> and </P><TT class=code>satisfies</TT><P> 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.
</P><TT class=code>and</TT><P> types are effective as long as the intersection can be
canonicalized to a type that doesn&#X2019;t use </P><TT class=code>and</TT><P>. For example:</P><BLOCKQUOTE class=example><PRE>
(and fixnum unsigned-byte)
</PRE></BLOCKQUOTE><P>is fine, since it is the same as:</P><BLOCKQUOTE class=example><PRE>
(integer 0 <TT class=variable>most-positive-fixnum</TT>)
</PRE></BLOCKQUOTE><P>but this type:</P><BLOCKQUOTE class=example><PRE>
(and symbol (not (member :end)))
</PRE></BLOCKQUOTE><P>will not be fully understood by type interference since the </P><TT class=code>and</TT><P>
can&#X2019;t be removed by canonicalization.</P><P>Using any of these type specifiers in a type test with </P><TT class=code>typep</TT><P> or
</P><TT class=code>typecase</TT><P> is fine, since as tests, these types can be translated
into the </P><TT class=code>and</TT><P> macro, the </P><TT class=code>not</TT><P> function or a call to the
satisfies predicate.</P><!--TOC subsection Type Style Recommendations-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc146">5.2.11</A>&#XA0;&#XA0;Type Style Recommendations</H3><!--SEC END --><P>
<A NAME="@concept150"></A></P><P>Python provides good support for some currently unconventional ways of
using the Common Lisp 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:
</P><UL CLASS="itemize"><LI CLASS="li-itemize">Declare the types of all function arguments and structure slots
as precisely as possible (while avoiding <TT class=code>not</TT>, <TT class=code>and</TT> and
<TT class=code>satisfies</TT>). Put these declarations in during initial coding
so that type assertions can find bugs for you during debugging.</LI><LI CLASS="li-itemize">Use the <A NAME="@types27"></A><TT class=code>member</TT> type specifier where there are a small
number of possible symbol values, for example: <TT class=code>(member :red
:blue :green)</TT>.</LI><LI CLASS="li-itemize">Use the <A NAME="@types28"></A><TT class=code>or</TT> type specifier in situations where the
type is not certain, but there are only a few possibilities, for
example: <TT class=code>(or list vector)</TT>.</LI><LI CLASS="li-itemize">Declare integer types with the tightest bounds that you can,
such as <TT class=code>(integer 3 7)</TT>.</LI><LI CLASS="li-itemize">Define <A NAME="@funs131"></A><TT class=code>deftype</TT> or <A NAME="@funs132"></A><TT class=code>defstruct</TT> types before
they are used. Definition after use is legal (producing no
&#X201C;undefined type&#X201D; warnings), but type tests and structure
operations will be compiled much less efficiently.</LI><LI CLASS="li-itemize">Use the <TT class=code>extensions:freeze-type</TT> declaration to speed up
type testing for structure types which won&#X2019;t have new subtypes added
later. See section&#XA0;<A HREF="#freeze-type">5.2.9</A></LI><LI CLASS="li-itemize">In addition to declaring the array element type and simpleness,
also declare the dimensions if they are fixed, for example:
<BLOCKQUOTE class=example><PRE>
    (simple-array single-float (1024 1024))
  </PRE></BLOCKQUOTE>
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.
See section&#XA0;<A HREF="#array-types">5.10.3</A>.</LI><LI CLASS="li-itemize">Avoid use of the <A NAME="@funs133"></A><TT class=code>the</TT> 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
<TT class=code>the</TT>, but it is preferable to constrain the argument types
more, allowing the compiler to prove the desired result type.</LI><LI CLASS="li-itemize">Don&#X2019;t bother declaring the type of <A NAME="@funs134"></A><TT class=code>let</TT> 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&#X2019;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 <TT class=code>car</TT>), or
comes from some weakly typed function, such as <TT class=code>read</TT>.</LI><LI CLASS="li-itemize">Declarations are sometimes necessary for integer loop variables,
since the compiler can&#X2019;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.
</LI></UL><!--TOC section Type Inference-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc147">5.3</A>&#XA0;&#XA0;Type Inference</H2><!--SEC END --><P>
<A NAME="type-inference"></A>
<A NAME="@concept151"></A>
<A NAME="@concept152"></A>
<A NAME="@concept153"></A></P><P>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 Common Lisp compilers, remember that the more precise
and comprehensive type declarations are, the more type inference will
be able to do.</P><!--TOC subsection Variable Type Inference-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc148">5.3.1</A>&#XA0;&#XA0;Variable Type Inference</H3><!--SEC END --><P>
<A NAME="variable-type-inference"></A></P><P>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&#X2019;s references. The types of <A NAME="@funs135"></A></P><TT class=code>multiple-value-bind</TT><P>
variables are similarly inferred from the types of the individual
values of the values form.</P><P>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 <A NAME="@types29"></A></P><TT class=code>and</TT><P> type specifier. In this example:
</P><BLOCKQUOTE class=example><PRE>
(defmacro my-dotimes ((var count) &amp;body body)
  &#X2018;(do ((,var 0 (1+ ,var)))
       ((&gt;= ,var ,count))
     (declare (type (integer 0 *) ,var))
     ,@body))

(my-dotimes (i ...)
  (declare (fixnum i))
  ...)
</PRE></BLOCKQUOTE><P>
the two declarations for </P><TT class=code>i</TT><P> are intersected, so </P><TT class=code>i</TT><P> is
known to be a non-negative fixnum.</P><P>In practice, this type inference is limited to lets and local
functions, since the compiler can&#X2019;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:
</P><UL CLASS="itemize"><LI CLASS="li-itemize">When the initial value of a variable is a untyped expression,
such as <TT class=code>(car x)</TT>, and</LI><LI CLASS="li-itemize">When the type of one of the variable&#X2019;s definitions is a function
of the variable&#X2019;s current value, as in: <TT class=code>(setq x (1+ x))</TT>
</LI></UL><!--TOC subsection Local Function Type Inference-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc149">5.3.2</A>&#XA0;&#XA0;Local Function Type Inference</H3><!--SEC END --><P>
<A NAME="@concept154"></A></P><P>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.</P><P>The result type of a local function is computed in a special way that
takes tail recursion (see section&#XA0;<A HREF="#tail-recursion">5.5</A>) into consideration.
The result type is the union of all possible return values that aren&#X2019;t
tail-recursive calls. For example, Python will infer that the
result type of this function is </P><TT class=code>integer</TT><P>:</P><BLOCKQUOTE CLASS=lisp> <PRE>
(defun ! (n res)
  (declare (integer n res))
  (if (zerop n)
      res
      (! (1- n) (* n res))))
</PRE></BLOCKQUOTE><P>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
<A HREF="#local-call-return">5.6.5</A>.</P><!--TOC subsection Global Function Type Inference-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc150">5.3.3</A>&#XA0;&#XA0;Global Function Type Inference</H3><!--SEC END --><P>
<A NAME="function-type-inference"></A>
<A NAME="@concept155"></A></P><P>As described in section <A HREF="#function-types">5.2.6</A>, a global function type
(<A NAME="@types30"></A></P><TT class=code>ftype</TT><P>) 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&#X2019;s definition if
there is no </P><TT class=code>ftype</TT><P> declaration. Any type declarations on the
argument variables are used as the argument types in the derived
function type, and the compiler&#X2019;s best guess for the result type of
the function is used as the result type in the derived function type.</P><P>This method of deriving function types from the definition implicitly assumes
that functions won&#X2019;t be redefined at run-time. Consider this example:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(defun foo-p (x)
  (let ((res (and (consp x) (eq (car x) &#X2019;foo))))
    (format t "It is ~:[not ~;~]foo." res)))

(defun frob (it)
  (if (foo-p it)
      (setf (cadr it) &#X2019;yow!)
      (1+ it)))
</PRE></BLOCKQUOTE><P>Presumably, the programmer really meant to return </P><TT class=code>res</TT><P> from
</P><TT class=code>foo-p</TT><P>, but he seems to have forgotten. When he tries to call
do </P><TT class=code>(frob (list &#X2019;foo nil))</TT><P>, </P><TT class=code>frob</TT><P> will flame out when
it tries to add to a </P><TT class=code>cons</TT><P>. Realizing his error, he fixes
</P><TT class=code>foo-p</TT><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 </P><TT class=code>foo-p</TT><P> is
</P><TT class=code>null</TT><P>, and then proceeded to optimize away the </P><TT class=code>setf</TT><P> in
</P><TT class=code>frob</TT><P>.</P><P>Fortunately, in this example, the error is detected at compile time
due to notes about unreachable code (see section&#XA0;<A HREF="#dead-code-notes">5.4.5</A>.)
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.</P><P><BR>
<A NAME="@vars48"></A><A NAME="VR:derive-function-types"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>*derive-function-types*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>If true (the default), argument and result type information derived
from compilation of </P><TT class=code>defun</TT><P>s is used when compiling calls to
that function. If false, only information from </P><TT class=code>ftype</TT><P>
proclamations will be used.
</P></BLOCKQUOTE><!--TOC subsection Operation Specific Type Inference-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc151">5.3.4</A>&#XA0;&#XA0;Operation Specific Type Inference</H3><!--SEC END --><P>
<A NAME="operation-type-inference"></A>
<A NAME="@concept156"></A>
<A NAME="@concept157"></A>
<A NAME="@concept158"></A></P><P>Many of the standard Common Lisp functions have special type inference
procedures that determine the result type as a function of the
argument types. For example, the result type of </P><TT class=code>aref</TT><P> is the
array element type. Here are some other examples of type inferences:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(logand x #xFF) ==&gt; (unsigned-byte 8)

(+ (the (integer 0 12) x) (the (integer 0 1) y)) ==&gt; (integer 0 13)

(ash (the (unsigned-byte 16) x) -8) ==&gt; (unsigned-byte 8)
</PRE></BLOCKQUOTE><!--TOC subsection Dynamic Type Inference-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc152">5.3.5</A>&#XA0;&#XA0;Dynamic Type Inference</H3><!--SEC END --><P>
<A NAME="constraint-propagation"></A>
<A NAME="@concept159"></A>
<A NAME="@concept160"></A>
<A NAME="@concept161"></A></P><P>Python uses flow analysis to infer types in dynamically typed
programs. For example:</P><BLOCKQUOTE class=example><PRE>
(ecase x
  (list (length x))
  ...)
</PRE></BLOCKQUOTE><P>Here, the compiler knows the argument to </P><TT class=code>length</TT><P> is a list,
because the call to </P><TT class=code>length</TT><P> is only done when </P><TT class=code>x</TT><P> is a
list. The most significant efficiency effect of inference from
assertions is usually in type check optimization.</P><P>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 <A NAME="@funs136"></A></P><TT class=code>if</TT><P>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 </P><TT class=code>eq</TT><P>.</P><P>If there is an </P><TT class=code>eq</TT><P> (or </P><TT class=code>eql</TT><P>) test, then the compiler will
actually substitute one argument for the other in the true branch.
For example:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(when (eq x :yow!) (return x))
</PRE></BLOCKQUOTE><P>
becomes:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(when (eq x :yow!) (return :yow!))
</PRE></BLOCKQUOTE><P>
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 </P><TT class=code>(not (member :yow!))</TT><P> in the example
above. This can eliminate redundant tests, for example:
</P><BLOCKQUOTE class=example><PRE>
(if (eq x nil)
    ...
    (if x a b))
</PRE></BLOCKQUOTE><P>
is transformed to this:
</P><BLOCKQUOTE class=example><PRE>
(if (eq x nil)
    ...
    a)
</PRE></BLOCKQUOTE><P>
Variables appearing as </P><TT class=code>if</TT><P> tests are interpreted as
</P><TT class=code>(not (eq <TT class=variable>var</TT> nil))</TT><P> tests. The compiler also converts
</P><TT class=code>=</TT><P> into </P><TT class=code>eql</TT><P> where possible. It is difficult to do
inference directly on </P><TT class=code>=</TT><P> since it does implicit coercions.</P><P>When there is an explicit </P><TT class=code>&lt;</TT><P> or </P><TT class=code>&gt;</TT><P> test on numeric
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 </P><TT class=code>dotimes</TT><P> with a </P><TT class=code>fixnum</TT><P> repeat count, the compiler
proves that fixnum arithmetic can be used.</P><P>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:</P><BLOCKQUOTE CLASS=lisp> <PRE>
(defun foo (x)
  (+ (car x) x))
</PRE></BLOCKQUOTE><P>results in this warning:</P><BLOCKQUOTE class=example><PRE>
In: DEFUN FOO
  (+ (CAR X) X)
==&gt;
  X
Warning: Result is a LIST, not a NUMBER.
</PRE></BLOCKQUOTE><P>Note that Common Lisp&#X2019;s dynamic type checking semantics make dynamic type
inference useful even in programs that aren&#X2019;t really dynamically
typed, for example:</P><BLOCKQUOTE CLASS=lisp> <PRE>
(+ (car x) (length x))
</PRE></BLOCKQUOTE><P>Here, </P><TT class=code>x</TT><P> presumably always holds a list, but in the absence of a
declaration the compiler cannot assume </P><TT class=code>x</TT><P> 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
</P><TT class=code>length</TT><P> is always a list because the call to </P><TT class=code>length</TT><P> is
only done after the list-specific </P><TT class=code>car</TT><P> operation.</P><!--TOC subsection Type Check Optimization-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc153">5.3.6</A>&#XA0;&#XA0;Type Check Optimization</H3><!--SEC END --><P>
<A NAME="type-check-optimization"></A>
<A NAME="@concept162"></A>
<A NAME="@concept163"></A></P><P>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.</P><P>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:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(defstruct foo a b c)
(defstruct link
  (foo (required-argument) :type foo)
  (next nil :type (or link null)))

(foo-a (link-foo x))
</PRE></BLOCKQUOTE><P>Here, there is no need to check that the result of </P><TT class=code>link-foo</TT><P> is
a </P><TT class=code>foo</TT><P>, since it always is. Even when some type checks are
necessary, type inference can often reduce the number:
</P><BLOCKQUOTE class=example><PRE>
(defun test (x)
  (let ((a (foo-a x))
        (b (foo-b x))
        (c (foo-c x)))
    ...))
</PRE></BLOCKQUOTE><P>
In this example, only one </P><TT class=code>(foo-p x)</TT><P> check is needed. This
applies to a lesser degree in list operations, such as:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(if (eql (car x) 3) (cdr x) y)
</PRE></BLOCKQUOTE><P>
Here, we only have to check that </P><TT class=code>x</TT><P> is a list once.</P><P>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 </P><TT class=code>car</TT><P> and </P><TT class=code>cdr</TT><P>:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(defun memq (e l)
  (do ((current l (cdr current)))
      ((atom current) nil)
    (when (eq (car current) e) (return current))))
</PRE></BLOCKQUOTE><P><A NAME="@concept164"></A>
Python reduces the cost of checks that must be done through an
optimization called </P><TT class=variable>complementing</TT><P>. A complemented check for
</P><TT class=variable>type</TT><P> is simply a check that the value is not of the type
</P><TT class=code>(not <TT class=variable>type</TT>)</TT><P>. This is only interesting when something
is known about the actual type, in which case we can test for the
complement of </P><TT class=code>(and <TT class=variable>known-type</TT> (not <TT class=variable>type</TT>))</TT><P>, or
the difference between the known type and the assertion. An example:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(link-foo (link-next x))
</PRE></BLOCKQUOTE><P>
Here, we change the type check for </P><TT class=code>link-foo</TT><P> from a test for
</P><TT class=code>foo</TT><P> to a test for:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(not (and (or foo null) (not foo)))
</PRE></BLOCKQUOTE><P>
or more simply </P><TT class=code>(not null)</TT><P>. This is probably the most
important use of complementing, since the situation is fairly common,
and a </P><TT class=code>null</TT><P> test is much cheaper than a structure type test.</P><P>Here is a more complicated example that illustrates the combination of
complementing with dynamic type inference:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(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)))))
</PRE></BLOCKQUOTE><P>
This loop can be compiled with no type checks. The </P><TT class=code>link</TT><P> test
for </P><TT class=code>link-foo</TT><P> and </P><TT class=code>link-next</TT><P> is complemented to
</P><TT class=code>(not null)</TT><P>, and then deleted because of the explicit
</P><TT class=code>null</TT><P> test. As before, no check is necessary for </P><TT class=code>foo-a</TT><P>,
since the </P><TT class=code>link-foo</TT><P> is always a </P><TT class=code>foo</TT><P>. This sort of
situation shows how precise type checking combined with precise
declarations can actually result in reduced type checking.</P><!--TOC section Source Optimization-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc154">5.4</A>&#XA0;&#XA0;Source Optimization</H2><!--SEC END --><P>
<A NAME="source-optimization"></A>
<A NAME="@concept165"></A></P><P>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. </P><!--TOC subsection Let Optimization-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc155">5.4.1</A>&#XA0;&#XA0;Let Optimization</H3><!--SEC END --><P>
<A NAME="let-optimization"></A></P><P><A NAME="@concept166"></A> <A NAME="@concept167"></A></P><P>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.</P><P>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:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(let ((a #&#X2019;(lambda (x) (zow x))))
  (funcall a 3))
</PRE></BLOCKQUOTE><P>
effectively transforms to:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(zow 3)
</PRE></BLOCKQUOTE><P>
This transformation is done even when the function is a closure, as in:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(let ((a (let ((y (zug)))
           #&#X2019;(lambda (x) (zow x y)))))
  (funcall a 3))
</PRE></BLOCKQUOTE><P>
becoming:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(zow 3 (zug))
</PRE></BLOCKQUOTE><P>A constant variable is a lexical variable that is never assigned to,
always keeping its initial value. Whenever possible, avoid setting
lexical variables&#X2014;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:
</P><BLOCKQUOTE class=example><PRE>
(let ((x (f x)))
  ...)
</PRE></BLOCKQUOTE><P>
is </P><TT class=variable>more</TT><P> efficient than this form:
</P><BLOCKQUOTE class=example><PRE>
(setq x (f x))
...
</PRE></BLOCKQUOTE><P>
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 Common Lisp compiler, but most let
optimizations are only done on constant variables.</P><P>Constant variables with only a single use are also optimized away,
even when the initial value is not constant.<SUP><A NAME="text10" HREF="#note10">1</A></SUP> For example, this expansion of
</P><TT class=code>incf</TT><P>:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(let ((#:g3 (+ x 1)))
  (setq x #:G3))
</PRE></BLOCKQUOTE><P>
becomes:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(setq x (+ x 1))
</PRE></BLOCKQUOTE><P>
The type semantics of this transformation are more important than the
elimination of the variable itself. Consider what happens when
</P><TT class=code>x</TT><P> is declared to be a </P><TT class=code>fixnum</TT><P>; after the transformation,
the compiler can compile the addition knowing that the result is a
</P><TT class=code>fixnum</TT><P>, whereas before the transformation the addition would
have to allow for fixnum overflow.</P><P>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.</P><P>Note that a let is actually a degenerate case of local call
(see section&#XA0;<A HREF="#let-calls">5.6.2</A>), and that let optimization can be done on calls
that weren&#X2019;t created by a let. Also, local call allows an applicative
style of iteration that is totally assignment free.</P><!--TOC subsection Constant Folding-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc156">5.4.2</A>&#XA0;&#XA0;Constant Folding</H3><!--SEC END --><P>
<A NAME="@concept168"></A>
<A NAME="@concept169"></A></P><P>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.</P><P>It is convenient to rely on constant folding when programming, as in this
example:
</P><BLOCKQUOTE class=example><PRE>
(defconstant limit 42)

(defun foo ()
  (... (1- limit) ...))
</PRE></BLOCKQUOTE><P>
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.</P><P><A NAME="@concept170"></A> Constant folding of a user
defined function is enabled by the </P><TT class=code>extensions:constant-function</TT><P>
proclamation. In this example:
</P><BLOCKQUOTE class=example><PRE>
(declaim (ext:constant-function myfun))
(defun myexp (x y)
  (declare (single-float x y))
  (exp (* (log x) y)))

 ... (myexp 3.0 1.3) ...
</PRE></BLOCKQUOTE><P>
The call to </P><TT class=code>myexp</TT><P> is constant-folded to </P><TT class=code>4.1711674</TT><P>.</P><!--TOC subsection Unused Expression Elimination-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc157">5.4.3</A>&#XA0;&#XA0;Unused Expression Elimination</H3><!--SEC END --><P>
<A NAME="@concept171"></A>
<A NAME="@concept172"></A></P><P>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
</P><TT class=code>extensions:constant-function</TT><P> is also subject to unused
expression elimination.</P><P>Note that Python will eliminate parts of unused expressions known
to be side-effect free, even if there are other unknown parts. For
example:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(let ((a (list (foo) (bar))))
  (if t
      (zow)
      (raz a)))
</PRE></BLOCKQUOTE><P>
becomes:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(progn (foo) (bar))
(zow)
</PRE></BLOCKQUOTE><!--TOC subsection Control Optimization-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc158">5.4.4</A>&#XA0;&#XA0;Control Optimization</H3><!--SEC END --><P>
<A NAME="@concept173"></A>
<A NAME="@concept174"></A></P><P>The most important optimization of control is recognizing when an
<A NAME="@funs137"></A></P><TT class=code>if</TT><P> test is known at compile time, then deleting the
</P><TT class=code>if</TT><P>, the test expression, and the unreachable branch of the
</P><TT class=code>if</TT><P>. This can be considered a special case of constant folding,
although the test doesn&#X2019;t have to be truly constant as long as it is
definitely not </P><TT class=code>nil</TT><P>. Note also, that type inference propagates the
result of an </P><TT class=code>if</TT><P> test to the true and false branches,
see section&#XA0;<A HREF="#constraint-propagation">5.3.5</A>.</P><P>A related </P><TT class=code>if</TT><P> optimization is this transformation:<SUP><A NAME="text11" HREF="#note11">2</A></SUP>
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(if (if a b c) x y)
</PRE></BLOCKQUOTE><P>
into:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(if a
    (if b x y)
    (if c x y))
</PRE></BLOCKQUOTE><P>
The opportunity for this sort of optimization usually results from a
conditional macro. For example:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(if (not a) x y)
</PRE></BLOCKQUOTE><P>
is actually implemented as this:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(if (if a nil t) x y)
</PRE></BLOCKQUOTE><P>
which is transformed to this:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(if a
    (if nil x y)
    (if t x y))
</PRE></BLOCKQUOTE><P>
which is then optimized to this:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(if a y x)
</PRE></BLOCKQUOTE><P>
Note that due to Python&#X2019;s internal representations, the
</P><TT class=code>if</TT><P>&#X2014;</P><TT class=code>if</TT><P> situation will be recognized even if other
forms are wrapped around the inner </P><TT class=code>if</TT><P>, like:
</P><BLOCKQUOTE class=example><PRE>
(if (let ((g ...))
      (loop
        ...
        (return (not g))
        ...))
    x y)
</PRE></BLOCKQUOTE><P>In Python, all the Common Lisp macros really are macros, written in
terms of </P><TT class=code>if</TT><P>, </P><TT class=code>block</TT><P> and </P><TT class=code>tagbody</TT><P>, 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 </P><TT class=code>tagbody</TT><P> 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.</P><!--TOC subsection Unreachable Code Deletion-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc159">5.4.5</A>&#XA0;&#XA0;Unreachable Code Deletion</H3><!--SEC END --><P>
<A NAME="dead-code-notes"></A>
<A NAME="@concept175"></A>
<A NAME="@concept176"></A></P><P>Python will delete code whenever it can prove that the code can never be
executed. Code becomes unreachable when:</P><UL CLASS="itemize"><LI CLASS="li-itemize">
An <TT class=code>if</TT> is optimized away, or</LI><LI CLASS="li-itemize">There is an explicit unconditional control transfer such as <TT class=code>go</TT> or
<TT class=code>return-from</TT>, or</LI><LI CLASS="li-itemize">The last reference to a local function is deleted (or there never was any
reference.)
</LI></UL><P>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:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(defun foo ()
  (if t
      (write-line "True.")
      (write-line "False.")))
</PRE></BLOCKQUOTE><P>
will result in this note:
</P><BLOCKQUOTE class=example><PRE>
In: DEFUN FOO
  (WRITE-LINE "False.")
Note: Deleting unreachable code.
</PRE></BLOCKQUOTE><P>It is important to pay attention to unreachable code notes, since they often
indicate a subtle type error. For example:
</P><BLOCKQUOTE class=example><PRE>
(defstruct foo a b)

(defun lose (x)
  (let ((a (foo-a x))
        (b (if x (foo-b x) :none)))
    ...))
</PRE></BLOCKQUOTE><P>
results in this note:
</P><BLOCKQUOTE class=example><PRE>
In: DEFUN LOSE
  (IF X (FOO-B X) :NONE)
==&gt;
  :NONE
Note: Deleting unreachable code.
</PRE></BLOCKQUOTE><P>
The </P><TT class=code>:none</TT><P> is unreachable, because type inference knows that the argument
to </P><TT class=code>foo-a</TT><P> must be a </P><TT class=code>foo</TT><P>, and thus can&#X2019;t be </P><TT class=code>nil</TT><P>. Presumably the
programmer forgot that </P><TT class=code>x</TT><P> could be </P><TT class=code>nil</TT><P> when he wrote the binding for
</P><TT class=code>a</TT><P>.</P><P>Here is an example with an incorrect declaration:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(defun count-a (string)
  (do ((pos 0 (position #\a string :start (1+ pos)))
       (count 0 (1+ count)))
      ((null pos) count)
    (declare (fixnum pos))))
</PRE></BLOCKQUOTE><P>
This time our note is:
</P><BLOCKQUOTE class=example><PRE>
In: DEFUN COUNT-A
  (DO ((POS 0 #) (COUNT 0 #))
      ((NULL POS) COUNT)
    (DECLARE (FIXNUM POS)))
&#X2013;&gt; BLOCK LET TAGBODY RETURN-FROM PROGN 
==&gt;
  COUNT
Note: Deleting unreachable code.
</PRE></BLOCKQUOTE><P>The problem here is that </P><TT class=code>pos</TT><P> can never be null since it is declared a
</P><TT class=code>fixnum</TT><P>.</P><P>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.</P><P>Not all unreachable code results in a note:</P><UL CLASS="itemize"><LI CLASS="li-itemize"> 
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.</LI><LI CLASS="li-itemize">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 <TT class=code>nil</TT> and <TT class=code>t</TT> are never
given, since it is too easy to confuse these constants in expanded
code with ones in the original source.</LI><LI CLASS="li-itemize">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.
</LI></UL><P>Somewhat spurious unreachable code notes can also result when a macro
inserts multiple copies of its arguments in different contexts, for
example:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(defmacro t-and-f (var form)
  &#X2018;(if ,var ,form ,form))

(defun foo (x)
  (t-and-f x (if x "True." "False.")))
</PRE></BLOCKQUOTE><P>
results in these notes:
</P><BLOCKQUOTE class=example><PRE>
In: DEFUN FOO
  (IF X "True." "False.")
==&gt;
  "False."
Note: Deleting unreachable code.

==&gt;
  "True."
Note: Deleting unreachable code.
</PRE></BLOCKQUOTE><P>It seems like it has deleted both branches of the </P><TT class=code>if</TT><P>, 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 </P><TT class=variable>some</TT><P> code being deleted when a unreachable code note is
printed.</P><!--TOC subsection Multiple Values Optimization-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc160">5.4.6</A>&#XA0;&#XA0;Multiple Values Optimization</H3><!--SEC END --><P>
<A NAME="@concept177"></A>
<A NAME="@concept178"></A></P><P>Within a function, Python implements uses of multiple values
particularly efficiently. Multiple values can be kept in arbitrary
registers, so using multiple values doesn&#X2019;t imply stack manipulation
and representation conversion. For example, this code:
</P><BLOCKQUOTE class=example><PRE>
(let ((a (if x (foo x) u))
      (b (if x (bar x) v)))
  ...)
</PRE></BLOCKQUOTE><P>
is actually more efficient written this way:
</P><BLOCKQUOTE class=example><PRE>
(multiple-value-bind
    (a b)
    (if x
        (values (foo x) (bar x))
        (values u v))
  ...)
</PRE></BLOCKQUOTE><P>Also, see section&#XA0;<A HREF="#local-call-return">5.6.5</A> for information on how local call
provides efficient support for multiple function return values.</P><!--TOC subsection Source to Source Transformation-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc161">5.4.7</A>&#XA0;&#XA0;Source to Source Transformation</H3><!--SEC END --><P>
<A NAME="@concept179"></A>
<A NAME="@concept180"></A></P><P>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:</P><BLOCKQUOTE CLASS=lisp> <PRE>
(defun my-zerop () (zerop x))
</PRE></BLOCKQUOTE><P>gives this warning:</P><BLOCKQUOTE class=example><PRE>
In: DEFUN MY-ZEROP
  (ZEROP X)
==&gt;
  (= X 0)
Warning: Undefined variable: X
</PRE></BLOCKQUOTE><P>The original </P><TT class=code>zerop</TT><P> has been transformed into a call to
</P><TT class=code>=</TT><P>. This transformation is indicated with the same </P><TT class=code>==&gt;</TT><P>
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:</P><BLOCKQUOTE CLASS=lisp> <PRE>
(defun foo (x) (logand 1 x))
</PRE></BLOCKQUOTE><P>gives this efficiency note:</P><BLOCKQUOTE class=example><PRE>
In: DEFUN FOO
  (LOGAND 1 X)
==&gt;
  (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.
</PRE></BLOCKQUOTE><P>Here, the compiler commuted the call to </P><TT class=code>logand</TT><P>, introducing
temporaries. The note complains that the </P><TT class=variable>first</TT><P> argument is not
a </P><TT class=code>fixnum</TT><P>, when in the original call, it was the second
argument. To make things more confusing, the compiler introduced
temporaries called </P><TT class=code>c::x</TT><P> and </P><TT class=code>c::y</TT><P> that are bound to
</P><TT class=code>y</TT><P> and </P><TT class=code>1</TT><P>, respectively.</P><P>You will also notice source-to-source optimizations when efficiency
notes are enabled (see section&#XA0;<A HREF="#efficiency-notes">5.13</A>.) 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,
</P><TT class=code>my-zerop</TT><P> above will also give this efficiency note:
</P><BLOCKQUOTE class=example><PRE>
In: DEFUN FOO
  (ZEROP X)
==&gt;
  (= X 0)
Note: Unable to optimize because:
      Operands might not be the same type, so can&#X2019;t open code.
</PRE></BLOCKQUOTE><!--TOC subsection Style Recommendations-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc162">5.4.8</A>&#XA0;&#XA0;Style Recommendations</H3><!--SEC END --><P>
<A NAME="@concept181"></A></P><P>Source level optimization makes possible a clearer and more relaxed programming
style:
</P><UL CLASS="itemize"><LI CLASS="li-itemize">Don&#X2019;t use macros purely to avoid function call. If you want an
inline function, write it as a function and declare it inline. It&#X2019;s
clearer, less error-prone, and works just as well.</LI><LI CLASS="li-itemize">Don&#X2019;t write macros that try to &#X201C;optimize&#X201D; 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.</LI><LI CLASS="li-itemize">Make use of local functions (i.e., <TT class=code>labels</TT> or <TT class=code>flet</TT>)
and tail-recursion in places where it is clearer. Local function
call is faster than full call.</LI><LI CLASS="li-itemize">Avoid setting local variables when possible. Binding a new
<TT class=code>let</TT> variable is at least as efficient as setting an existing
variable, and is easier to understand, both for the compiler and the
programmer.</LI><LI CLASS="li-itemize">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.
</LI></UL><!--TOC section Tail Recursion-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc163">5.5</A>&#XA0;&#XA0;Tail Recursion</H2><!--SEC END --><P>
<A NAME="tail-recursion"></A>
<A NAME="@concept182"></A>
<A NAME="@concept183"></A></P><P>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 </P><TT class=code>myfun</TT><P> is tail-recursive:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(defun myfun (x)
  (if (oddp (random x))
      (isqrt x)
      (myfun (1- x))))
</PRE></BLOCKQUOTE><P>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.</P><P>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:</P><BLOCKQUOTE CLASS=lisp> <PRE>
(defun fun1 (x)
  something-that-uses-x)

(defun fun2 (y)
  something-that-uses-y)

(do ((x something (fun2 (fun1 x))))
    (nil))
</PRE></BLOCKQUOTE><P>You can write:</P><BLOCKQUOTE CLASS=lisp> <PRE>
(defun fun1 (x)
  (fun2 something-that-uses-x))

(defun fun2 (y)
  (fun1 something-that-uses-y))

(fun1 something)
</PRE></BLOCKQUOTE><P>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 </P><TT class=code>prog</TT><P>.</P><P>It helps to understand how to use tail recursion if you think of a
tail-recursive call as a </P><TT class=code>psetq</TT><P> that assigns the argument values to the
called function&#X2019;s variables, followed by a </P><TT class=code>go</TT><P> 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.)</P><P>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&#X2014;in fact it isn&#X2019;t really clearly worse, just different.
See section&#XA0;<A HREF="#debug-tail-recursion">3.3.5</A> for information about the debugger
implications of tail recursion, and how to turn it off for the sake of
more conservative backtrace information.</P><P>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 </P><TT class=code>fun2</TT><P> will always be compiled as a
tail-recursive call:</P><BLOCKQUOTE CLASS=lisp> <PRE>
(defun fun1 (x)
  (fun2 x))
</PRE></BLOCKQUOTE><P>So tail recursion doesn&#X2019;t necessarily have anything to do with recursion
as it is normally thought of. See section&#XA0;<A HREF="#local-tail-recursion">5.6.4</A> for more
discussion of using tail recursion to implement loops.</P><!--TOC subsection Tail Recursion Exceptions-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc164">5.5.1</A>&#XA0;&#XA0;Tail Recursion Exceptions</H3><!--SEC END --><P>Although Python is claimed to be &#X201C;properly&#X201D; tail-recursive, some
might dispute this, since there are situations where tail recursion is
inhibited:
</P><UL CLASS="itemize"><LI CLASS="li-itemize">When the call is enclosed by a special binding, or</LI><LI CLASS="li-itemize">When the call is enclosed by a <TT class=code>catch</TT> or
<TT class=code>unwind-protect</TT>, or</LI><LI CLASS="li-itemize">When the call is enclosed by a <TT class=code>block</TT> or <TT class=code>tagbody</TT>
and the block name or <TT class=code>go</TT> tag has been closed over.
</LI></UL><P>
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.</P><P>In addition, optimization of tail-recursive calls is inhibited when
the </P><TT class=code>debug</TT><P> optimization quality is greater than </P><TT class=code>2</TT><P>
(see section&#XA0;<A HREF="#debugger-policy">3.6</A>.)</P><!--TOC section Local Call-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc165">5.6</A>&#XA0;&#XA0;Local Call</H2><!--SEC END --><P>
<A NAME="local-call"></A>
<A NAME="@concept184"></A>
<A NAME="@concept185"></A>
<A NAME="@concept186"></A></P><P>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 Common Lisp 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:
</P><UL CLASS="itemize"><LI CLASS="li-itemize">Local call makes the use of the lexical function binding forms
<A NAME="@funs138"></A><TT class=code>flet</TT> and <A NAME="@funs139"></A><TT class=code>labels</TT> much more efficient. A local
call is always faster than a full call, and in many cases is much
faster.</LI><LI CLASS="li-itemize">Local call is a natural approach to <I>block compilation</I>, a
compilation technique that resolves function references at compile
time. Block compilation speeds function call, but increases
compilation times and prevents function redefinition.
</LI></UL><!--TOC subsection Self-Recursive Calls-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc166">5.6.1</A>&#XA0;&#XA0;Self-Recursive Calls</H3><!--SEC END --><P>
<A NAME="@concept187"></A></P><P>Local call is used when a function defined by </P><TT class=code>defun</TT><P> calls itself. For
example:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(defun fact (n)
  (if (zerop n)
      1
      (* n (fact (1- n)))))
</PRE></BLOCKQUOTE><P>This use of local call speeds recursion, but can also complicate
debugging, since <A NAME="@funs140"></A></P><TT class=code>trace</TT><P> will only show the first call to
</P><TT class=code>fact</TT><P>, and not the recursive calls. This is because the
recursive calls directly jump to the start of the function, and don&#X2019;t
indirect through the </P><TT class=code>symbol-function</TT><P>. Self-recursive local
call is inhibited when the </P><TT class=code>:block-compile</TT><P> argument to
</P><TT class=code>compile-file</TT><P> is </P><TT class=code>nil</TT><P> (see section&#XA0;<A HREF="#compile-file-block">5.7.3</A>.)</P><!--TOC subsection Let Calls-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc167">5.6.2</A>&#XA0;&#XA0;Let Calls</H3><!--SEC END --><P>
<A NAME="let-calls"></A>
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 </P><TT class=code>let</TT><P>:</P><BLOCKQUOTE class=example><PRE>
(let ((a (foo))
      (b (bar)))
  ...)
</PRE></BLOCKQUOTE><P>is internally represented as though it was macroexpanded into:</P><BLOCKQUOTE class=example><PRE>
(funcall #&#X2019;(lambda (a b)
             ...)
         (foo)
         (bar))
</PRE></BLOCKQUOTE><P>This implementation is acceptable because the simple cases of local
call (equivalent to a </P><TT class=code>let</TT><P>) result in good code. This doesn&#X2019;t
make </P><TT class=code>let</TT><P> any more efficient, but does make local calls that are
semantically the same as </P><TT class=code>let</TT><P> much more efficient than full
calls. For example, these definitions are all the same as far as the
compiler is concerned:</P><BLOCKQUOTE class=example><PRE>
(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 #&#X2019;(lambda (a)
                    ...some stuff...)))
    ...some other stuff...
    (funcall funvar something)))
</PRE></BLOCKQUOTE><P>Although local call is most efficient when the function is called only
once, a call doesn&#X2019;t have to be equivalent to a </P><TT class=code>let</TT><P> 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.
See section&#XA0;<A HREF="#let-optimization">5.4.1</A> for a discussion of the optimizations done on
let calls.</P><!--TOC subsection Closures-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc168">5.6.3</A>&#XA0;&#XA0;Closures</H3><!--SEC END --><P>
<A NAME="@concept188"></A></P><P>Local call allows for much more efficient use of closures, since the
closure environment doesn&#X2019;t need to be allocated on the heap, or even
stored in memory at all. In this example, there is no penalty for
</P><TT class=code>localfun</TT><P> referencing </P><TT class=code>a</TT><P> and </P><TT class=code>b</TT><P>:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(defun foo (a b)
  (flet ((localfun (x)
           (1+ (* a b x))))
    (if (= a b)
        (localfun (- x))
        (localfun x))))
</PRE></BLOCKQUOTE><P>
In local call, the compiler effectively passes closed-over values as
extra arguments, so there is no need for you to &#X201C;optimize&#X201D; local
function use by explicitly passing in lexically visible values.
Closures may also be subject to let optimization
(see section&#XA0;<A HREF="#let-optimization">5.4.1</A>.)</P><P>Note: indirect value cells are currently always allocated on the heap
when a variable is both assigned to (with </P><TT class=code>setq</TT><P> or </P><TT class=code>setf</TT><P>)
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&#X2019;t have to.</P><!--TOC subsection Local Tail Recursion-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc169">5.6.4</A>&#XA0;&#XA0;Local Tail Recursion</H3><!--SEC END --><P>
<A NAME="local-tail-recursion"></A>
<A NAME="@concept189"></A>
<A NAME="@concept190"></A></P><P>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 </P><TT class=code>go</TT><P> and </P><TT class=code>setq</TT><P>. This has not caught on in the
Common Lisp community, since conventional Common Lisp compilers don&#X2019;t
implement local call. In Python, users can choose to write loops
such as:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(defun ! (n)
  (labels ((loop (n total)
             (if (zerop n)
                 total
                 (loop (1- n) (* n total)))))
    (loop n 1)))
</PRE></BLOCKQUOTE><P><BR>
<A NAME="@funs141"></A><A NAME="FN:iterate"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>iterate</TT> <TT class=variable>name</TT> (<TT class=code>{(<TT class=variable>var</TT> <TT class=variable>initial-value</TT>)}</TT><SUP>*</SUP>)
<TT class=code>{<TT class=variable>declaration</TT>}</TT><SUP>*</SUP> <TT class=code>{<TT class=variable>form</TT>}</TT><SUP>*</SUP> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This macro provides syntactic sugar for using <A NAME="@funs142"></A></P><TT class=code>labels</TT><P> to
do iteration. It creates a local function </P><TT class=variable>name</TT><P> with the
specified </P><TT class=variable>var</TT><P>s as its arguments and the </P><TT class=variable>declaration</TT><P>s and
</P><TT class=variable>form</TT><P>s as its body. This function is then called with the
</P><TT class=variable>initial-values</TT><P>, and the result of the call is return from the
macro.</P><P>Here is our factorial example rewritten using </P><TT class=code>iterate</TT><P>:</P><BLOCKQUOTE CLASS=lisp> <PRE>
    (defun ! (n)
      (iterate loop
               ((n n)
               (total 1))
        (if (zerop n)
          total
          (loop (1- n) (* n total)))))
  </PRE></BLOCKQUOTE><P>The main advantage of using </P><TT class=code>iterate</TT><P> over </P><TT class=code>do</TT><P> is that
</P><TT class=code>iterate</TT><P> naturally allows stepping to be done differently
depending on conditionals in the body of the loop. </P><TT class=code>iterate</TT><P>
can also be used to implement algorithms that aren&#X2019;t really
iterative by simply doing a non-tail call. For example, the
standard recursive definition of factorial can be written like this:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(iterate fact
         ((n n))
  (if (zerop n)
      1
      (* n (fact (1- n)))))
</PRE></BLOCKQUOTE></BLOCKQUOTE><!--TOC subsection Return Values-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc170">5.6.5</A>&#XA0;&#XA0;Return Values</H3><!--SEC END --><P>
<A NAME="local-call-return"></A>
<A NAME="@concept191"></A>
<A NAME="@concept192"></A></P><P>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 </P><TT class=code>nil</TT><P> arguments to </P><TT class=code>values</TT><P> in some
cases, but the result is more efficient, not less so.</P><P>When efficiency notes are enabled (see section&#XA0;<A HREF="#efficiency-notes">5.13</A>), and the
compiler wants to use known values return, but can&#X2019;t prove that the
function always returns the same number of values, then it will print
a note like this:
</P><BLOCKQUOTE class=example><PRE>
In: DEFUN GRUE
  (DEFUN GRUE (X) (DECLARE (FIXNUM X)) (COND (# #) (# NIL) (T #)))
Note: Return type not fixed values, so can&#X2019;t use known return convention:
  (VALUES (OR (INTEGER -536870912 -1) NULL) &amp;REST T)
</PRE></BLOCKQUOTE><P>In order to implement proper tail recursion in the presence of known
values return (see section&#XA0;<A HREF="#tail-recursion">5.5</A>), the compiler sometimes must
prove that multiple functions all return the same number of values.
When this can&#X2019;t be proven, the compiler will print a note like this:
</P><BLOCKQUOTE class=example><PRE>
In: DEFUN BLUE
  (DEFUN BLUE (X) (DECLARE (FIXNUM X)) (COND (# #) (# #) (# #) (T #)))
Note: Return value count mismatch prevents known return from
      these functions:
  BLUE
  SNOO
</PRE></BLOCKQUOTE><P>
See section&#XA0;<A HREF="#number-local-call">5.11.10</A> for the interaction between local call
and the representation of numeric types.</P><!--TOC section Block Compilation-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc171">5.7</A>&#XA0;&#XA0;Block Compilation</H2><!--SEC END --><P>
<A NAME="block-compilation"></A>
<A NAME="@concept193"></A>
<A NAME="@concept194"></A></P><P>Block compilation allows calls to global functions defined by
<A NAME="@funs143"></A></P><TT class=code>defun</TT><P> to be compiled as local calls. The function call
can be in a different top-level form than the </P><TT class=code>defun</TT><P>, or even in a
different file.</P><P>In addition, block compilation allows the declaration of the <I>entry points</I>
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.</P><P>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.)</P><P>Block compilation also allows the use of non-descriptor arguments and return
values in non-trivial programs (see section&#XA0;<A HREF="#number-local-call">5.11.10</A>).</P><!--TOC subsection Block Compilation Semantics-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc172">5.7.1</A>&#XA0;&#XA0;Block Compilation Semantics</H3><!--SEC END --><P>The effect of block compilation can be envisioned as the compiler turning all
the </P><TT class=code>defun</TT><P>s in the block compilation into a single </P><TT class=code>labels</TT><P> form:
</P><BLOCKQUOTE class=example><PRE>
(declaim (start-block fun1 fun3))

(defun fun1 ()
  ...)

(defun fun2 ()
  ...
  (fun1)
  ...)

(defun fun3 (x)
  (if x
      (fun1)
      (fun2)))

(declaim (end-block))
</PRE></BLOCKQUOTE><P>
becomes:
</P><BLOCKQUOTE class=example><PRE>
(labels ((fun1 ()
           ...)
         (fun2 ()
           ...
           (fun1)
           ...)
         (fun3 (x)
           (if x
               (fun1)
               (fun2))))
  (setf (fdefinition &#X2019;fun1) #&#X2019;fun1)
  (setf (fdefinition &#X2019;fun3) #&#X2019;fun3))
</PRE></BLOCKQUOTE><P>
Calls between the block compiled functions are local calls, so changing the
global definition of </P><TT class=code>fun1</TT><P> will have no effect on what </P><TT class=code>fun2</TT><P> does;
</P><TT class=code>fun2</TT><P> will keep calling the old </P><TT class=code>fun1</TT><P>.</P><P>The entry points </P><TT class=code>fun1</TT><P> and </P><TT class=code>fun3</TT><P> are still installed in
the </P><TT class=code>symbol-function</TT><P> as the global definitions of the functions,
so a full call to an entry point works just as before. However,
</P><TT class=code>fun2</TT><P> is not an entry point, so it is not globally defined. In
addition, </P><TT class=code>fun2</TT><P> is only called in one place, so it will be let
converted.</P><!--TOC subsection Block Compilation Declarations-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc173">5.7.2</A>&#XA0;&#XA0;Block Compilation Declarations</H3><!--SEC END --><P>
<A NAME="@concept195"></A>
<A NAME="@concept196"></A>
<A NAME="@concept197"></A></P><P>The </P><TT class=code>extensions:start-block</TT><P> and </P><TT class=code>extensions:end-block</TT><P>
declarations allow fine-grained control of block compilation. These
declarations are only legal as a global declarations (</P><TT class=code>declaim</TT><P>
or </P><TT class=code>proclaim</TT><P>).</P><P><BR>

The </P><TT class=code>start-block</TT><P> declaration has this syntax:
</P><BLOCKQUOTE class=example><PRE>
(start-block <TT class=code>{<TT class=variable>entry-point-name</TT>}</TT><SUP>*</SUP>)
</PRE></BLOCKQUOTE><P>
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 </P><TT class=variable>all</TT><P> functions are made into
entry points. If already block compiling, then the compiler ends the
current block and starts a new one.</P><P><BR>

The </P><TT class=code>end-block</TT><P> declaration has no arguments:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(end-block)
</PRE></BLOCKQUOTE><P>
The </P><TT class=code>end-block</TT><P> 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.</P><!--TOC subsection Compiler Arguments-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc174">5.7.3</A>&#XA0;&#XA0;Compiler Arguments</H3><!--SEC END --><P>
<A NAME="compile-file-block"></A>
<A NAME="@concept198"></A></P><P>The </P><TT class=code>:block-compile</TT><P> and </P><TT class=code>:entry-points</TT><P> arguments to
</P><TT class=code>extensions:compile-from-stream</TT><P> and <A NAME="@funs144"></A></P><TT class=code>compile-file</TT><P> provide overall
control of block compilation, and allow block compilation without requiring
modification of the program source.</P><P>There are three possible values of the </P><TT class=code>:block-compile</TT><P> argument:

</P><DL CLASS="list"><DT CLASS="dt-list">
<TT class=code>nil</TT><BR>
</DT><DD CLASS="dd-list"> Do no compile-time resolution of global function
names, not even for self-recursive calls. This inhibits any
<TT class=code>start-block</TT> declarations appearing in the file, allowing all
functions to be incrementally redefined.</DD><DT CLASS="dt-list"><TT class=code>t</TT><BR>
</DT><DD CLASS="dd-list"> Start compiling in block compilation mode. This is
mainly useful for block compiling small files that contain no
<TT class=code>start-block</TT> declarations. See also the <TT class=code>:entry-points</TT>
argument.</DD><DT CLASS="dt-list"><TT class=code>:specified</TT><BR>
</DT><DD CLASS="dd-list"> Start compiling in form-at-a-time mode, but
exploit any <TT class=code>start-block</TT> declarations and compile
self-recursive calls as local calls. Normally <TT class=code>:specified</TT> is
the default for this argument (see <A NAME="@vars49"></A><TT class=code>*block-compile-default*</TT>.)
</DD></DL><P>The </P><TT class=code>:entry-points</TT><P> argument can be used in conjunction with
</P><TT class=code>:block-compile</TT><TT class=code>t</TT><P> to specify the entry-points to a
block-compiled file. If not specified or </P><TT class=code>nil</TT><P>, all global functions
will be compiled as entry points. When </P><TT class=code>:block-compile</TT><P> is not
</P><TT class=code>t</TT><P>, this argument is ignored.</P><P><BR>
<A NAME="@vars50"></A><A NAME="VR:block-compile-default"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>*block-compile-default*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This variable determines the default value for the
</P><TT class=code>:block-compile</TT><P> argument to </P><TT class=code>compile-file</TT><P> and
</P><TT class=code>compile-from-stream</TT><P>. The initial value of this variable is
</P><TT class=code>:specified</TT><P>, but </P><TT class=code>nil</TT><P> is sometimes useful for totally
inhibiting block compilation.
</P></BLOCKQUOTE><!--TOC subsection Practical Difficulties-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc175">5.7.4</A>&#XA0;&#XA0;Practical Difficulties</H3><!--SEC END --><P>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 </P><TT class=code>start-block</TT><P> 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&#X2019;s function call structure.
If you want to initially develop code with full incremental
redefinition, you can compile with <A NAME="@vars51"></A></P><TT class=code>*block-compile-default*</TT><P> set to
</P><TT class=code>nil</TT><P>.</P><P>Note if a </P><TT class=code>defun</TT><P> appears in a non-null lexical environment, then
calls to it cannot be block compiled.</P><P>Unless files are very small, it is probably impractical to block compile
multiple files as a unit by specifying a list of files to </P><TT class=code>compile-file</TT><P>.
Semi-inline expansion (see section&#XA0;<A HREF="#semi-inline">5.8.2</A>) provides another way to
extend block compilation across file boundaries.</P><!--TOC subsection Context Declarations-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc176">5.7.5</A>&#XA0;&#XA0;Context Declarations</H3><!--SEC END --><P>
<A NAME="context-declarations"></A>
<A NAME="@concept199"></A>
<A NAME="@concept200"></A></P><P>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.)</P><P>The </P><TT class=code>:context-declarations</TT><P> option to <A NAME="@funs145"></A></P><TT class=code>with-compilation-unit</TT><P> 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:
</P><BLOCKQUOTE class=example><PRE>
(<TT class=variable>context-spec</TT> <TT class=code>{<TT class=variable>declare-form</TT>}</TT><SUP>+</SUP>)
</PRE></BLOCKQUOTE><P>
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:
</P><BLOCKQUOTE class=example><PRE>
    :context-declarations
    &#X2019;((:external (declare (optimize (safety 2)))))
</PRE></BLOCKQUOTE><P>
This will cause all functions that are named by external symbols to be
compiled with </P><TT class=code>safety 2</TT><P>.</P><P>The full syntax of context specs is:

</P><DL CLASS="list"><DT CLASS="dt-list">
<TT class=code>:internal</TT>, <TT class=code>:external</TT><BR>
</DT><DD CLASS="dd-list"> True if the symbol is internal
(external) in its home package.</DD><DT CLASS="dt-list"><TT class=code>:uninterned</TT><BR>
</DT><DD CLASS="dd-list"> True if the symbol has no home package.</DD><DT CLASS="dt-list"><TT class=code>(:package <TT class=code>{<TT class=variable>package-name</TT>}</TT><SUP>*</SUP>)</TT><BR>
</DT><DD CLASS="dd-list"> True if the
symbol&#X2019;s home package is in any of the named packages (false if
uninterned.)</DD><DT CLASS="dt-list"><TT class=code>:anonymous</TT><BR>
</DT><DD CLASS="dd-list"> True if the function doesn&#X2019;t have any
interesting name (not <TT class=code>defmacro</TT>, <TT class=code>defun</TT>, <TT class=code>labels</TT>
or <TT class=code>flet</TT>).</DD><DT CLASS="dt-list"><TT class=code>:macro</TT>, <TT class=code>:function</TT><BR>
</DT><DD CLASS="dd-list"> <TT class=code>:macro</TT> is a global
(<TT class=code>defmacro</TT>) macro. <TT class=code>:function</TT> is anything else.</DD><DT CLASS="dt-list"><TT class=code>:local</TT>, <TT class=code>:global</TT><BR>
</DT><DD CLASS="dd-list"> <TT class=code>:local</TT> is a <TT class=code>labels</TT> or
<TT class=code>flet</TT>. <TT class=code>:global</TT> is anything else.</DD><DT CLASS="dt-list"><TT class=code>(:or <TT class=code>{<TT class=variable>context-spec</TT>}</TT><SUP>*</SUP>)</TT><BR>
</DT><DD CLASS="dd-list"> True when any
supplied <TT class=variable>context-spec</TT> is true.</DD><DT CLASS="dt-list"><TT class=code>(:and <TT class=code>{<TT class=variable>context-spec</TT>}</TT><SUP>*</SUP>)</TT><BR>
</DT><DD CLASS="dd-list"> True only when all
supplied <TT class=variable>context-spec</TT>s are true.</DD><DT CLASS="dt-list"><TT class=code>(:not <TT class=code>{<TT class=variable>context-spec</TT>}</TT><SUP>*</SUP>)</TT><BR>
</DT><DD CLASS="dd-list"> True when
<TT class=variable>context-spec</TT> is false.</DD><DT CLASS="dt-list"><TT class=code>(:member <TT class=code>{<TT class=variable>name</TT>}</TT><SUP>*</SUP>)</TT><BR>
</DT><DD CLASS="dd-list"> True when the defined
name is one of these names (<TT class=code>equal</TT> test.)</DD><DT CLASS="dt-list"><TT class=code>(:match <TT class=code>{<TT class=variable>pattern</TT>}</TT><SUP>*</SUP>)</TT><BR>
</DT><DD CLASS="dd-list"> True when any of the
patterns is a substring of the name. The name is wrapped with
<TT class=code>$</TT>&#X2019;s, so &#X201C;<TT class=code>$FOO</TT>&#X201D; matches names beginning with
&#X201C;<TT class=code>FOO</TT>&#X201D;, etc.
</DD></DL><!--TOC subsection Context Declaration Example-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc177">5.7.6</A>&#XA0;&#XA0;Context Declaration Example</H3><!--SEC END --><P>Here is a more complex example of </P><TT class=code>with-compilation-unit</TT><P> options:
</P><BLOCKQUOTE class=example><PRE>
:optimize &#X2019;(optimize (speed 2) (space 2) (inhibit-warnings 2)
                     (debug 1) (safety 0))
:optimize-interface &#X2019;(optimize-interface (safety 1) (debug 1))
:context-declarations
&#X2019;(((:or :external (:and (:match "%") (:match "SET")))
   (declare (optimize-interface (safety 2))))
  ((:or (:and :external :macro)
        (:match "$PARSE-"))
   (declare (optimize (safety 2)))))
</PRE></BLOCKQUOTE><P>
The </P><TT class=code>optimize</TT><P> and </P><TT class=code>extensions:optimize-interface</TT><P>
declarations (see section&#XA0;<A HREF="#optimize-declaration">4.7.1</A>) set up the global
compilation policy. The bodies of functions are to be compiled
completely unsafe (</P><TT class=code>safety 0</TT><P>), but argument count and weakened
argument type checking is to be done when a function is called
(</P><TT class=code>speed 2 safety 1</TT><P>).</P><P>The first declaration specifies that all functions that are external
or whose names contain both &#X201C;</P><TT class=code>%</TT><P>&#X201D; and &#X201C;</P><TT class=code>SET</TT><P>&#X201D; are to be
compiled compiled with completely safe interfaces (</P><TT class=code>safety 2</TT><P>).
The reason for this particular </P><TT class=code>:match</TT><P> rule is that </P><TT class=code>setf</TT><P>
inverse functions in this system tend to have both strings in their
name somewhere. We want </P><TT class=code>setf</TT><P> inverses to be safe because they
are implicitly called by users even though their name is not exported.</P><P>The second declaration makes external macros or functions whose names
start with &#X201C;</P><TT class=code>PARSE-</TT><P>&#X201D; 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 </P><TT class=code>:match</TT><P> rule is used because macros
often have auxiliary functions whose names begin with this string.</P><P>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 </P><TT class=code>:match</TT><P> option depends on naming
conventions used in coding.</P><!--TOC section Inline Expansion-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc178">5.8</A>&#XA0;&#XA0;Inline Expansion</H2><!--SEC END --><P>
<A NAME="inline-expansion"></A>
<A NAME="@concept201"></A>
<A NAME="@concept202"></A>
<A NAME="@concept203"></A>
<A NAME="@concept204"></A>
<A NAME="@concept205"></A></P><P>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 (</P><TT class=code>defun</TT><P>) must be done in a null lexical
environment (not nested in a </P><TT class=code>let</TT><P> or other binding form.) Local
functions (</P><TT class=code>flet</TT><P>) can be inline expanded in any environment.
Combined with Python&#X2019;s source-level optimization, inline expansion
can be used for things that formerly required macros for efficient
implementation. In Python, macros don&#X2019;t have any efficiency
advantage, so they need only be used where a macro&#X2019;s syntactic
flexibility is required.</P><P>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 Common Lisp, this is straightforwardly expressed by
inserting the </P><TT class=code>lambda</TT><P> corresponding to the original definition:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(proclaim &#X2019;(inline my-1+))
(defun my-1+ (x) (+ x 1))

(my-1+ someval) ==&gt; ((lambda (x) (+ x 1)) someval)
</PRE></BLOCKQUOTE><P>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:
</P><UL CLASS="itemize"><LI CLASS="li-itemize">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.</LI><LI CLASS="li-itemize">With functions so simple that they take less space to inline
expand than would be taken to call the function (such as
<TT class=code>my-1+</TT> 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 Common Lisp functions.
</LI></UL><P>In addition to this speed/space tradeoff from inline expansion&#X2019;s
avoidance of the call, inline expansion can also reveal opportunities
for optimization. Python&#X2019;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.</P><P>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.</P><P>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 </P><TT class=code>member</TT><P> function:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(proclaim &#X2019;(inline member))
(defun member (item list &amp;key
                    (key #&#X2019;identity)
                    (test #&#X2019;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)))))

</PRE></BLOCKQUOTE><P>
After inline expansion, this call is simplified to the obvious code:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(member a l :key #&#X2019;foo-a :test #&#X2019;char=) ==&gt;

(do ((list list (cdr list)))
    ((null list) nil)
  (let ((car (car list)))
    (if (char= item (foo-a car))
        (return list))))
</PRE></BLOCKQUOTE><P>
In this example, there could easily be more than an order of magnitude
improvement in speed. In addition to eliminating the original call to
</P><TT class=code>member</TT><P>, inline expansion also allows the calls to </P><TT class=code>char=</TT><P>
and </P><TT class=code>foo-a</TT><P> to be open-coded. We go from a loop with three tests
and two calls to a loop with one test and no calls.</P><P>See section&#XA0;<A HREF="#source-optimization">5.4</A> for more discussion of source level
optimization.</P><!--TOC subsection Inline Expansion Recording-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc179">5.8.1</A>&#XA0;&#XA0;Inline Expansion Recording</H3><!--SEC END --><P>
<A NAME="@concept206"></A></P><P>Inline expansion requires that the source for the inline expanded function to
be available when calls to the function are compiled. The compiler doesn&#X2019;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 </P><TT class=code>inline</TT><P> and
</P><TT class=code>extensions:maybe-inline</TT><P> (see section&#XA0;<A HREF="#maybe-inline-declaration">5.8.3</A>)
declarations.</P><P>In addition to recording the inline expansion of inline functions at the time
the function is compiled, </P><TT class=code>compile-file</TT><P> 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.</P><P>If a function is declared inline, but no expansion is recorded, then the
compiler will give an efficiency note like:</P><BLOCKQUOTE class=example><PRE>
Note: MYFUN is declared inline, but has no expansion.
</PRE></BLOCKQUOTE><P>When you get this note, check that the </P><TT class=code>inline</TT><P> 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 </P><TT class=code>defun</TT><P> could not be
recorded because the </P><TT class=code>defun</TT><P> was in a non-null lexical environment.</P><!--TOC subsection Semi-Inline Expansion-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc180">5.8.2</A>&#XA0;&#XA0;Semi-Inline Expansion</H3><!--SEC END --><P>
<A NAME="semi-inline"></A></P><P>Python supports </P><TT class=variable>semi-inline</TT><P> 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
(see section&#XA0;<A HREF="#local-call">5.6</A>.) 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 </P><TT class=code>space</TT><P> optimization quality is </P><TT class=code>0</TT><P>, and the
function has been declared </P><TT class=code>extensions:maybe-inline</TT><P>.</P><P>This mechanism of inline expansion combined with local call also
allows recursive functions to be inline expanded. If a recursive
function is declared </P><TT class=code>inline</TT><P>, 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.</P><!--TOC subsection The Maybe-Inline Declaration-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc181">5.8.3</A>&#XA0;&#XA0;The Maybe-Inline Declaration</H3><!--SEC END --><P>
<A NAME="maybe-inline-declaration"></A>
<A NAME="@concept207"></A></P><P>The </P><TT class=code>extensions:maybe-inline</TT><P> declaration is a CMUCL
extension. It is similar to </P><TT class=code>inline</TT><P>, 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, </P><TT class=code>extensions:maybe-inline</TT><P> causes the expansion for
the named functions to be recorded, but the functions aren&#X2019;t actually
inline expanded unless </P><TT class=code>space</TT><P> is </P><TT class=code>0</TT><P> or the function is
eventually (perhaps locally) declared </P><TT class=code>inline</TT><P>.</P><P>Use of the </P><TT class=code>extensions:maybe-inline</TT><P> declaration followed by the
</P><TT class=code>defun</TT><P> is preferable to the standard idiom of:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(proclaim &#X2019;(inline myfun))
(defun myfun () ...)
(proclaim &#X2019;(notinline myfun))

;;; <I>Any calls to </I><TT class=code><I>myfun</I></TT><I> here are not inline expanded.</I>

(defun somefun ()
  (declare (inline myfun))
  ;;
  ;; <I>Calls to </I><TT class=code><I>myfun</I></TT><I> here are inline expanded.</I>
  ...)
</PRE></BLOCKQUOTE><P>
The problem with using </P><TT class=code>notinline</TT><P> in this way is that in
Common Lisp it does more than just suppress inline expansion, it also
forbids the compiler to use any knowledge of </P><TT class=code>myfun</TT><P> until a
later </P><TT class=code>inline</TT><P> declaration overrides the </P><TT class=code>notinline</TT><P>. This
prevents compiler warnings about incorrect calls to the function, and
also prevents block compilation.</P><P>The </P><TT class=code>extensions:maybe-inline</TT><P> declaration is used like this:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(proclaim &#X2019;(extensions:maybe-inline myfun))
(defun myfun () ...)

;;; <I>Any calls to </I><TT class=code><I>myfun</I></TT><I> here are not inline expanded.</I>

(defun somefun ()
  (declare (inline myfun))
  ;;
  ;; <I>Calls to </I><TT class=code><I>myfun</I></TT><I> here are inline expanded.</I>
  ...)

(defun someotherfun ()
  (declare (optimize (space 0)))
  ;;
  ;; <I>Calls to </I><TT class=code><I>myfun</I></TT><I> here are expanded semi-inline.</I>
  ...)
</PRE></BLOCKQUOTE><P>
In this example, the use of </P><TT class=code>extensions:maybe-inline</TT><P> causes the
expansion to be recorded when the </P><TT class=code>defun</TT><P> for </P><TT class=code>somefun</TT><P> is
compiled, and doesn&#X2019;t waste space through doing inline expansion by
default. Unlike </P><TT class=code>notinline</TT><P>, 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.</P><P>When the goal is merely to control whether inline expansion is done by
default, it is preferable to use </P><TT class=code>extensions:maybe-inline</TT><P> rather
than </P><TT class=code>notinline</TT><P>. The </P><TT class=code>notinline</TT><P> 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.</P><!--TOC section Byte Coded Compilation-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc182">5.9</A>&#XA0;&#XA0;Byte Coded Compilation</H2><!--SEC END --><P>
<A NAME="byte-compile"></A>
<A NAME="@concept208"></A>
<A NAME="@concept209"></A></P><P>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 Common Lisp interpreters.</P><P>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.</P><P>When byte-compiling, the compiler compiles about twice as fast, and
can produce a hardware independent object file (</P><TT class=filename>.bytef</TT><P> type.)
This file can be loaded like a normal fasl file on any implementation
of CMUCL with the same byte-ordering.</P><P>The decision to byte compile or native compile can be done on a
per-file or per-code-object basis. The </P><TT class=code>:byte-compile</TT><P> argument to
<A NAME="@funs146"></A></P><TT class=code>compile-file</TT><P> has these possible values:</P><DL CLASS="list"><DT CLASS="dt-list">

<TT class=code>nil</TT><BR>
</DT><DD CLASS="dd-list"> Don&#X2019;t byte compile anything in this file.</DD><DT CLASS="dt-list"><TT class=code>t</TT><BR>
</DT><DD CLASS="dd-list"> Byte compile everything in this file and produce a
processor-independent <TT class=filename>.bytef</TT> file.</DD><DT CLASS="dt-list"><TT class=code>:maybe</TT><BR>
</DT><DD CLASS="dd-list"> Produce a normal fasl file, but byte compile any
functions for which the <TT class=code>speed</TT> optimization quality is
<TT class=code>0</TT> and the <TT class=code>debug</TT> quality is not greater than <TT class=code>1</TT>.
</DD></DL><P><BR>
<A NAME="@vars52"></A><A NAME="VR:byte-compile-top-level"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>*byte-compile-top-level*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>If this variable is true (the default) and the </P><TT class=code>:byte-compile</TT><P>
argument to </P><TT class=code>compile-file</TT><P> is </P><TT class=code>:maybe</TT><P>, then byte compile
top-level code (code outside of any </P><TT class=code>defun</TT><P>, </P><TT class=code>defmethod</TT><P>,
etc.)
</P></BLOCKQUOTE><P><BR>
<A NAME="@vars53"></A><A NAME="VR:byte-compile-default"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>*byte-compile-default*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This variable determines the default value for the
</P><TT class=code>:byte-compile</TT><P> argument to </P><TT class=code>compile-file</TT><P>, initially
</P><TT class=code>:maybe</TT><P>.
</P></BLOCKQUOTE><!--TOC section Object Representation-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc183">5.10</A>&#XA0;&#XA0;Object Representation</H2><!--SEC END --><P>
<A NAME="object-representation"></A>
<A NAME="@concept210"></A>
<A NAME="@concept211"></A>
<A NAME="@concept212"></A></P><P>A somewhat subtle aspect of writing efficient Common Lisp 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
(see section&#XA0;<A HREF="#non-descriptor">5.11.2</A>), but is also due to the sheer number of
object types that Common Lisp 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.</P><!--TOC subsection Think Before You Use a List-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc184">5.10.1</A>&#XA0;&#XA0;Think Before You Use a List</H3><!--SEC END --><P>
<A NAME="@concept213"></A></P><P>Although Lisp&#X2019;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</I>. The
language has grown since Lisp 1.5&#X2014;new data types supersede lists
for many purposes.</P><!--TOC subsection Structure Representation-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc185">5.10.2</A>&#XA0;&#XA0;Structure Representation</H3><!--SEC END --><P>
<A NAME="@concept214"></A> One of the best ways of
building complex data structures is to define appropriate structure
types using <A NAME="@funs147"></A></P><TT class=code>defstruct</TT><P>. 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.</P><P>Even if structures weren&#X2019;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:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(rplaca (caddr (cadddr x)) (caddr y))
</PRE></BLOCKQUOTE><P>
could have been written using structures in this way:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(setf (beverage-flavor (astronaut-beverage x)) (beverage-flavor y))
</PRE></BLOCKQUOTE><P>
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 </P><TT class=code>astronaut</TT><P> will never be confused
with a </P><TT class=code>beverage</TT><P>, and the result of </P><TT class=code>beverage-flavor</TT><P> is
always a flavor. See sections <A HREF="#structure-types">5.2.8</A> and
<A HREF="#freeze-type">5.2.9</A> for more information about structure types.
See section&#XA0;<A HREF="#type-inference">5.3</A> for a number of examples that make clear the
advantages of structure typing.</P><P>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.</P><!--TOC subsection Arrays-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc186">5.10.3</A>&#XA0;&#XA0;Arrays</H3><!--SEC END --><P>
<A NAME="array-types"></A>
<A NAME="@concept215"></A></P><P>Arrays are often the most efficient representation for collections of objects
because:
</P><UL CLASS="itemize"><LI CLASS="li-itemize">Array representations are often the most compact. An array is
always more compact than a list containing the same number of
elements.</LI><LI CLASS="li-itemize">Arrays allow fast constant-time access.</LI><LI CLASS="li-itemize">Arrays are easily destructively modified, which can reduce
consing.</LI><LI CLASS="li-itemize">Array element types can be specialized, which reduces both
overall size and consing (see section&#XA0;<A HREF="#specialized-array-types">5.11.8</A>.)
</LI></UL><P>Access of arrays that are not of type </P><TT class=code>simple-array</TT><P> is less
efficient, so declarations are appropriate when an array is of a
simple type like </P><TT class=code>simple-string</TT><P> or </P><TT class=code>simple-bit-vector</TT><P>.
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 </P><TT class=code>:displaced-to</TT><P>, </P><TT class=code>:fill-pointer</TT><P> or
</P><TT class=code>adjustable</TT><P> arguments to </P><TT class=code>make-array</TT><P>. If you don&#X2019;t use
these hairy options, then arrays can always be declared to be simple.</P><P>Because of the many specialized array types and the possibility of
non-simple arrays, array access is much like generic arithmetic
(see section&#XA0;<A HREF="#generic-arithmetic">5.11.4</A>). 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,
see section&#XA0;<A HREF="#efficiency-notes">5.13</A>.</P><!--TOC subsection Vectors-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc187">5.10.4</A>&#XA0;&#XA0;Vectors</H3><!--SEC END --><P>
<A NAME="@concept216"></A></P><P>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 </P><TT class=code>simple-string</TT><P> in preference to
</P><TT class=code>string</TT><P>, etc.</P><P>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
</P><TT class=code>nth</TT><P> and </P><TT class=code>nthcdr</TT><P>. If you are using these functions you
should probably be using a vector.</P><!--TOC subsection Bit-Vectors-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc188">5.10.5</A>&#XA0;&#XA0;Bit-Vectors</H3><!--SEC END --><P>
<A NAME="@concept217"></A></P><P>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 </P><TT class=code>simple-bit-vector</TT><P>s are efficient,
since they operate on a word at a time.</P><!--TOC subsection Hashtables-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc189">5.10.6</A>&#XA0;&#XA0;Hashtables</H3><!--SEC END --><P>
<A NAME="@concept218"></A></P><P>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).</P><TT class=code>assoc</TT><P> is fairly fast when the </P><TT class=variable>test</TT><P> argument is </P><TT class=code>eq</TT><P>
or </P><TT class=code>eql</TT><P> 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
</P><TT class=code>equal</TT><P> 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.</P><P>The style argument observes that although hash-tables and alists
overlap in function, they do not do all things equally well.
</P><UL CLASS="itemize"><LI CLASS="li-itemize">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.</LI><LI CLASS="li-itemize">Hashtables are good for maintaining a global association. The
value associated with an entry can easily be changed with
<TT class=code>setf</TT>. With an alist, one has to go through contortions,
either <TT class=code>rplacd</TT>&#X2019;ing the cons if the entry exists, or pushing a
new one if it doesn&#X2019;t. The side-effecting nature of hash-table
operations is an advantage here.
</LI></UL><P>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. See section&#XA0;<A HREF="#advanced-type-stuff">5.2</A> for information on types
in CMUCL.</P><!--TOC section Numbers-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc190">5.11</A>&#XA0;&#XA0;Numbers</H2><!--SEC END --><P>
<A NAME="numeric-types"></A>
<A NAME="@concept219"></A>
<A NAME="@concept220"></A></P><P>Numbers are interesting because numbers are one of the few Common Lisp 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
efficiency advantage.</P><P>Using hardware representations is problematical in Common Lisp 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 Common Lisp program with efficiency comparable to that obtained in
statically typed languages such as C, but not all Common Lisp
implementations succeed. There are two main barriers to efficient
numerical code in Common Lisp:
</P><UL CLASS="itemize"><LI CLASS="li-itemize">The compiler must prove that the numerical expression is in fact
statically typed, and</LI><LI CLASS="li-itemize">The compiler must be able to somehow reconcile the conflicting
demands of the hardware mandated number representation with the
Common Lisp requirements of dynamic typing and garbage-collecting
dynamic storage allocation.
</LI></UL><P>Because of its type inference (see section&#XA0;<A HREF="#type-inference">5.3</A>) and efficiency
notes (see section&#XA0;<A HREF="#efficiency-notes">5.13</A>), Python is better than
conventional Common Lisp 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.</P><!--TOC subsection Descriptors-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc191">5.11.1</A>&#XA0;&#XA0;Descriptors</H3><!--SEC END --><P>
<A NAME="@concept221"></A>
<A NAME="@concept222"></A>
<A NAME="@concept223"></A>
<A NAME="@concept224"></A></P><P>Common Lisp&#X2019;s dynamic typing requires that it be possible to represent
any value with a fixed length object, known as a </P><TT class=variable>descriptor</TT><P>.
This fixed-length requirement is implicit in features such as:
</P><UL CLASS="itemize"><LI CLASS="li-itemize">Data types (like <TT class=code>simple-vector</TT>) that can contain any type
of object, and that can be destructively modified to contain
different objects (of possibly different types.)</LI><LI CLASS="li-itemize">Functions that can be called with any type of argument, and that
can be redefined at run time.
</LI></UL><P>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 </P><TT class=variable>immediate</TT><P>. Descriptors for
objects larger than one word are in reality pointers to the memory
actually containing the object.</P><P>Representing objects using pointers has two major disadvantages:
</P><UL CLASS="itemize"><LI CLASS="li-itemize">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 &#X201C;consing&#X201D;) is inefficient in several
ways. See section&#XA0;<A HREF="#consing">5.12.2</A>.</LI><LI CLASS="li-itemize">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.
</LI></UL><P>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&#X2019;t seem like much, but it has a major efficiency
implication&#X2014;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 </P><TT class=code>fixnum</TT><P>) or a natural pointer
representation (with the attendant consing overhead.)</P><!--TOC subsection Non-Descriptor Representations-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc192">5.11.2</A>&#XA0;&#XA0;Non-Descriptor Representations</H3><!--SEC END --><P>
<A NAME="non-descriptor"></A>
<A NAME="@concept225"></A>
<A NAME="@concept226"></A></P><P>From the discussion above, we can see that the standard descriptor
representation has many problems, the worst being number consing.
Common Lisp compilers try to avoid these descriptor efficiency problems by using
</P><TT class=variable>non-descriptor</TT><P> representations. A compiler that uses non-descriptor
representations can compile this function so that it does no number consing:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(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)))))
</PRE></BLOCKQUOTE><P>
If a descriptor representation were used, each iteration of the loop might
cons two floats and do three times as many memory references.</P><P>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.</P><P>Many Common Lisp compilers support non-descriptor representations for
float types such as </P><TT class=code>single-float</TT><P> and </P><TT class=code>double-float</TT><P>
(section <A HREF="#float-efficiency">5.11.7</A>.) Python adds support for full
word integers (see section&#XA0;<A HREF="#word-integers">5.11.6</A>), characters
(see section&#XA0;<A HREF="#characters">5.11.11</A>) and system-area pointers (unconstrained
pointers, see section&#XA0;<A HREF="#system-area-pointers">6.5</A>.) Many Common Lisp compilers
support non-descriptor representations for variables (section
<A HREF="#ND-variables">5.11.3</A>) and array elements (section
<A HREF="#specialized-array-types">5.11.8</A>.) Python adds support for
non-descriptor arguments and return values in local call
(see section&#XA0;<A HREF="#number-local-call">5.11.10</A>) and structure slots (see section&#XA0;<A HREF="#raw-slots">5.11.9</A>).</P><!--TOC subsection Variables-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc193">5.11.3</A>&#XA0;&#XA0;Variables</H3><!--SEC END --><P>
<A NAME="ND-variables"></A>
<A NAME="@concept227"></A>
<A NAME="@concept228"></A>
<A NAME="@concept229"></A></P><P>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 (see section&#XA0;<A HREF="#type-inference">5.3</A>) often needs
some help from user-supplied declarations. The best kind of type
declaration is a variable type declaration placed at the binding
point:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(let ((x (car l)))
  (declare (single-float x))
  ...)
</PRE></BLOCKQUOTE><P>
Use of </P><TT class=code>the</TT><P>, or of variable declarations not at the binding form
is insufficient to allow non-descriptor representation of the
variable&#X2014;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:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(etypecase x
  ((signed-byte 32)
   (let ((x x))
     (declare (type (signed-byte 32) x)) 
     ...))
  ...)
</PRE></BLOCKQUOTE><P>
The declaration on the inner </P><TT class=code>x</TT><P> is necessary here due to a phase
ordering problem. Although the compiler will eventually prove that
the outer </P><TT class=code>x</TT><P> is a </P><TT class=code>(signed-byte 32)</TT><P> within that
</P><TT class=code>etypecase</TT><P> branch, the inner </P><TT class=code>x</TT><P> would have been optimized
away by that time. Declaring the type makes let optimization more
cautious.</P><P>Note that storing a value into a global (or </P><TT class=code>special</TT><P>) 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.</P><P>Efficiency notes signal use of inefficient representations, so
programmer&#X2019;s needn&#X2019;t continuously worry about the details of
representation selection (see section&#XA0;<A HREF="#representation-eff-note">5.13.3</A>.)</P><!--TOC subsection Generic Arithmetic-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc194">5.11.4</A>&#XA0;&#XA0;Generic Arithmetic</H3><!--SEC END --><P>
<A NAME="generic-arithmetic"></A>
<A NAME="@concept230"></A>
<A NAME="@concept231"></A>
<A NAME="@concept232"></A></P><P>In Common Lisp, arithmetic operations are </P><TT class=variable>generic</TT><P>.<SUP><A NAME="text12" HREF="#note12">3</A></SUP>
The </P><TT class=code>+</TT><P> function can be passed </P><TT class=code>fixnum</TT><P>s, </P><TT class=code>bignum</TT><P>s,
</P><TT class=code>ratio</TT><P>s, and various kinds of </P><TT class=code>float</TT><P>s and
</P><TT class=code>complex</TT><P>es, in any combination. In addition to the inherent
complexity of </P><TT class=code>bignum</TT><P> and </P><TT class=code>ratio</TT><P> 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.</P><P>This is ridiculous, since even Common Lisp 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:
</P><UL CLASS="itemize"><LI CLASS="li-itemize">All the arguments must be known to be a good type of number.</LI><LI CLASS="li-itemize">The result must be known to be a good type of number.</LI><LI CLASS="li-itemize">Any intermediate values such as the result of <TT class=code>(+ a b)</TT>
in the call <TT class=code>(+ a b c)</TT> must be known to be a good type of
number.</LI><LI CLASS="li-itemize">All the above numbers with good types must be of the <TT class=variable>same</TT>
good type. Don&#X2019;t try to mix integers and floats or different float
formats.
</LI></UL><P>The &#X201C;good types&#X201D; are </P><TT class=code>(signed-byte 32)</TT><P>,
</P><TT class=code>(unsigned-byte 32)</TT><P>, </P><TT class=code>single-float</TT><P>,
</P><TT class=code>double-float</TT><P>, </P><TT class=code>(complex single-float)</TT><P>, and </P><TT class=code>(complex
double-float)</TT><P>. See sections <A HREF="#fixnums">5.11.5</A>, <A HREF="#word-integers">5.11.6</A>
and <A HREF="#float-efficiency">5.11.7</A> for more discussion of good numeric types.</P><TT class=code>float</TT><P> is not a good type, since it might mean either
</P><TT class=code>single-float</TT><P> or </P><TT class=code>double-float</TT><P>. </P><TT class=code>integer</TT><P> is not a
good type, since it might mean </P><TT class=code>bignum</TT><P>. </P><TT class=code>rational</TT><P> is not
a good type, since it might mean </P><TT class=code>ratio</TT><P>. 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
(see section&#XA0;<A HREF="#type-inference">5.3</A>). The </P><TT class=code>integer</TT><P> and
</P><TT class=code>unsigned-byte</TT><P> (or non-negative integer) types are especially
useful in this regard, since they can often be strengthened to a good
integer type.</P><P>As noted above, CMUCL has support for </P><TT class=code>(complex single-float)</TT><P>
and </P><TT class=code>(complex double-float)</TT><P>. These can be unboxed and, thus,
are quite efficient. However, arithmetic with complex types such as:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(complex float)
(complex fixnum)
</PRE></BLOCKQUOTE><P>
will be significantly slower than the good complex types but is still
faster than </P><TT class=code>bignum</TT><P> or </P><TT class=code>ratio</TT><P> arithmetic, since the
implementation is much simpler.</P><P>Note: don&#X2019;t use </P><TT class=code>/</TT><P> to divide integers unless you want the
overhead of rational arithmetic. Use </P><TT class=code>truncate</TT><P> even when you
know that the arguments divide evenly.</P><P>You don&#X2019;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&#X2014;see section&#XA0;<A HREF="#efficiency-notes">5.13</A>.</P><!--TOC subsection Fixnums-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc195">5.11.5</A>&#XA0;&#XA0;Fixnums</H3><!--SEC END --><P>
<A NAME="fixnums"></A>
<A NAME="@concept233"></A>
<A NAME="@concept234"></A></P><P>A fixnum is a &#X201C;FIXed precision NUMber&#X201D;. In modern Common Lisp
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.</P><P>It is useful to distinguish the </P><TT class=code>fixnum</TT><P> type from the fixnum
representation of integers. In Python, there is absolutely nothing
magical about the </P><TT class=code>fixnum</TT><P> type in comparison to other finite
integer types. </P><TT class=code>fixnum</TT><P> is equivalent to (is defined with
</P><TT class=code>deftype</TT><P> to be) </P><TT class=code>(signed-byte 30)</TT><P>. </P><TT class=code>fixnum</TT><P> is
simply the largest subset of integers that <EM>can be represented</EM>
using an immediate fixnum descriptor.</P><P>Unlike in other Common Lisp compilers, it is in no way desirable to use
the </P><TT class=code>fixnum</TT><P> type in declarations in preference to more
restrictive integer types such as </P><TT class=code>bit</TT><P>, </P><TT class=code>(integer -43
7)</TT><P> and </P><TT class=code>(unsigned-byte 8)</TT><P>. Since Python does
understand these integer types, it is preferable to use the more
restrictive type, as it allows better type inference
(see section&#XA0;<A HREF="#operation-type-inference">5.3.4</A>.)</P><P>The small, efficient fixnum is contrasted with bignum, or &#X201C;BIG
NUMber&#X201D;. 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.</P><P>A crucial point is that the compiler will use generic arithmetic if it
can&#X2019;t </P><TT class=variable>prove</TT><P> that all the arguments, intermediate values, and
results are fixnums. With bounded integer types such as
</P><TT class=code>fixnum</TT><P>, the result type proves to be especially problematical,
since these types are not closed under common arithmetic operations
such as </P><TT class=code>+</TT><P>, </P><TT class=code>-</TT><P>, </P><TT class=code>*</TT><P> and </P><TT class=code>/</TT><P>. For example,
</P><TT class=code>(1+ (the fixnum x))</TT><P> does not necessarily evaluate to a
</P><TT class=code>fixnum</TT><P>. Bignums were added to Common Lisp to get around this
problem, but they really just transform the correctness problem &#X201C;if
this add overflows, you will get the wrong answer&#X201D; to the efficiency
problem &#X201C;if this add </P><TT class=variable>might</TT><P> overflow then your program will run
slowly (because of generic arithmetic.)&#X201D;</P><P>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: </P><TT class=code>(1+ (the fixnum x))</TT><P> may not always be a
</P><TT class=code>fixnum</TT><P>, but </P><TT class=code>(1+ (the (unsigned-byte 8) x))</TT><P> always
is. Of course, you can also assert the result type by putting in lots
of </P><TT class=code>the</TT><P> declarations and then compiling with </P><TT class=code>safety</TT><TT class=code>0</TT><P>.</P><!--TOC subsection Word Integers-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc196">5.11.6</A>&#XA0;&#XA0;Word Integers</H3><!--SEC END --><P>
<A NAME="word-integers"></A>
<A NAME="@concept235"></A></P><P>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:</P><BLOCKQUOTE CLASS=lisp> <PRE>
(signed-byte 32)
(unsigned-byte 32)
</PRE></BLOCKQUOTE><P>is reasonably efficient, although subtypes of </P><TT class=code>fixnum</TT><P> remain
somewhat more efficient.</P><P>If a word integer must be represented as a descriptor, then the
</P><TT class=code>bignum</TT><P> 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
</P><TT class=code>fixnum</TT><P> and word integer operands; just declare the most
specific integer type you can, and let the compiler decide what
representation to use.</P><P>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.</P><P>The remarks in section <A HREF="#fixnums">5.11.5</A> 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
</P><TT class=code>fixnum</TT><P>s to word integers. Note that mixing
</P><TT class=code>(unsigned-byte 32)</TT><P> arguments with arguments of any signed
type (such as </P><TT class=code>fixnum</TT><P>) is a no-no, since the result might not be
unsigned.</P><!--TOC subsection Floating Point Efficiency-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc197">5.11.7</A>&#XA0;&#XA0;Floating Point Efficiency</H3><!--SEC END --><P>
<A NAME="float-efficiency"></A>
<A NAME="@concept236"></A></P><P>Arithmetic on objects of type </P><TT class=code>single-float</TT><P> and </P><TT class=code>double-float</TT><P> 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.
</P><TT class=code>(1+ (the single-float x))</TT><P> is always a </P><TT class=code>single-float</TT><P>.</P><P>Although they are not specially implemented, </P><TT class=code>short-float</TT><P> and
</P><TT class=code>long-float</TT><P> are also acceptable in declarations, since they are
synonyms for the </P><TT class=code>single-float</TT><P> and </P><TT class=code>double-float</TT><P> types,
respectively.</P><P>In CMUCL, list-style float type specifiers such as
</P><TT class=code>(single-float 0.0 1.0)</TT><P> will be used to good effect.</P><P>For example, in this function,</P><BLOCKQUOTE class=example><PRE>
  (defun square (x)
    (declare (type (single-float 0f0 10f0)))
    (* x x))
</PRE></BLOCKQUOTE><P>Python can deduce that the
return type of the function </P><TT class=code>square</TT><P> is </P><TT class=code>(single-float
0f0 100f0)</TT><P>.</P><P>Many union types are also supported so that</P><BLOCKQUOTE class=example><PRE>
  (+ (the (or (integer 1 1) (integer 5 5)) x)
     (the (or (integer 10 10) (integer 20 20)) y))
</PRE></BLOCKQUOTE><P>has the inferred type </P><TT class=code>(or (integer 11 11) (integer 15 15)
(integer 21 21) (integer 25 25))</TT><P>. This also works for
floating-point numbers. Member types are also supported.</P><P>CMUCL can also 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.</P><P>For example, consider the function
</P><BLOCKQUOTE class=example><PRE>
  (defun fun (x)
    (declare (type (single-float (0f0) 100f0) x))
    (values (sqrt x) (log x)))
</PRE></BLOCKQUOTE><P>
With this declaration, the compiler can determine that the argument
to </P><TT class=code>sqrt</TT><P> and </P><TT class=code>log</TT><P> are always non-negative so that the result 
is always a </P><TT class=code>single-float</TT><P>. In fact, the return type for this
function is derived to be </P><TT class=code>(values (single-float 0f0 10f0)
(single-float * 2f0))</TT><P>.</P><P>If the declaration were reduced to just </P><TT class=code>(declare
(single-float x))</TT><P>, the argument to </P><TT class=code>sqrt</TT><P> and </P><TT class=code>log</TT><P>
could be negative. This forces the use of the generic versions of
these functions because the result could be a complex number.</P><P>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.<SUP><A NAME="text13" HREF="#note13">4</A></SUP>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
(see section&#XA0;<A HREF="#representation-eff-note">5.13.3</A>) from the compiler will guide you
on what declarations might be useful.</P><P>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 <A HREF="#specialized-array-types">5.11.8</A>,
<A HREF="#raw-slots">5.11.9</A> and <A HREF="#number-local-call">5.11.10</A>.</P><P>See section&#XA0;<A HREF="#ieee-float">2.1.2</A> for information on the extensions to support IEEE
floating point.</P><!--TOC subsubsection Signed Zeroes and Special Functions-->
<H4 CLASS="subsubsection"><!--SEC ANCHOR -->5.11.7.1&#XA0;&#XA0;Signed Zeroes and Special Functions</H4><!--SEC END --><P>CMUCL supports IEEE signed zeroes. In typical usage, the signed
zeroes are not a problem and can be treated as an unsigned zero.
However, some of the special functions have branch points at zero, so
care must be taken.</P><P>For example, suppose we have the function
</P><BLOCKQUOTE class=example><PRE>
  (defun fun (x)
    (declare (type (single-float 0f0) x))
    (log x))
</PRE></BLOCKQUOTE><P>
The derived result of the function is </P><TT class=code>(OR SINGLE-FLOAT
(COMPLEX SINGLE-FLOAT))</TT><P> because the declared values for
</P><TT class=code>x</TT><P> includes both &#X2212;0.0 and 0.0 and </P><TT class=code>(log -0.0)</TT><P> is
actually a complex number. Because of this, the generic complex log
routine is used.</P><P>If the declaration for </P><TT class=code>x</TT><P> were </P><TT class=code>(single-float (0f0))</TT><P> so +0.0
is not included or </P><TT class=code>(or (single-float (0f0)) (member 0f0))</TT><P> so
+0.0 is include but not &#X2212;0.0, the derived type would be
</P><TT class=code>single-float</TT><P> for both cases. By declaring </P><TT class=code>x</TT><P> this way,
the log can be implemented using a fast real-valued log routine
instead of the generic log routine.</P><P>CMUCL implements the branch cuts and values given by
Kahan<SUP><A NAME="text14" HREF="#note14">5</A></SUP>.</P><!--TOC subsection Specialized Arrays-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc198">5.11.8</A>&#XA0;&#XA0;Specialized Arrays</H3><!--SEC END --><P>
<A NAME="specialized-array-types"></A>
<A NAME="@concept237"></A>
<A NAME="@concept238"></A>
<A NAME="@concept239"></A></P><P>Common Lisp supports specialized array element types through the
</P><TT class=code>:element-type</TT><P> argument to </P><TT class=code>make-array</TT><P>. 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
advantages:
</P><UL CLASS="itemize"><LI CLASS="li-itemize">A specialized array can save space by packing multiple elements
into a single word. For example, a <TT class=code>base-char</TT> array can have
4 elements per word, and a <TT class=code>bit</TT> array can have 32. This
space-efficient representation is possible because it is not
necessary to separately indicate the type of each element.</LI><LI CLASS="li-itemize">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.
</LI></UL><P>These are the specialized element types currently supported:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
bit
(unsigned-byte 2)
(unsigned-byte 4)
(unsigned-byte 8)
(unsigned-byte 16)
(unsigned-byte 32)
(signed-byte 8)
(signed-byte 16)
(signed-byte 30)
(signed-byte 32)
base-character
single-float
double-float
ext:double-double-float
(complex single-float)
(complex double-float)
(complex ext:double-double-float)
</PRE></BLOCKQUOTE><P>Although a </P><TT class=code>simple-vector</TT><P> can hold any type of object, </P><TT class=code>t</TT><P>
should still be considered a specialized array type, since arrays with
element type </P><TT class=code>t</TT><P> are specialized to hold descriptors.</P><P>When using non-descriptor representations, it is particularly
important to make sure that array accesses are open-coded, since in
addition to the generic operation overhead, efficiency is lost when
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,
see section&#XA0;<A HREF="#efficiency-notes">5.13</A>. See section&#XA0;<A HREF="#array-types">5.10.3</A>.</P><!--TOC subsection Specialized Structure Slots-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc199">5.11.9</A>&#XA0;&#XA0;Specialized Structure Slots</H3><!--SEC END --><P>
<A NAME="raw-slots"></A>
<A NAME="@concept240"></A>
<A NAME="@concept241"></A></P><P>Structure slots declared by the </P><TT class=code>:type</TT><TT class=code>defstruct</TT><P> slot option
to have certain known numeric types are also given non-descriptor
representations. These types (and subtypes of these types) are supported:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(unsigned-byte 32)
single-float
double-float
(complex single-float)
(complex double-float)
</PRE></BLOCKQUOTE><P>The primary advantage of specialized slot representations is a large
reduction spurious memory allocation and access overhead of programs
that intensively use these types.</P><!--TOC subsection Interactions With Local Call-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc200">5.11.10</A>&#XA0;&#XA0;Interactions With Local Call</H3><!--SEC END --><P>
<A NAME="number-local-call"></A>
<A NAME="@concept242"></A>
<A NAME="@concept243"></A>
<A NAME="@concept244"></A></P><P>Local call has many advantages (see section&#XA0;<A HREF="#local-call">5.6</A>); 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:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(defun 2+f (x)
  (declare (single-float x))
  (+ x 2.0))
</PRE></BLOCKQUOTE><P>
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 (see section&#XA0;<A HREF="#non-descriptor">5.11.2</A>.) This
extends the applicative programming styles discussed in section
<A HREF="#local-call">5.6</A> to numeric code. Also, if source files are kept reasonably
small, block compilation can be used to reduce number consing to a minimum.</P><P>Note that non-descriptor return values can only be used with the known return
convention (section <A HREF="#local-call-return">5.6.5</A>.) If the compiler can&#X2019;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.</P><!--TOC subsection Representation of Characters-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc201">5.11.11</A>&#XA0;&#XA0;Representation of Characters</H3><!--SEC END --><P>
<A NAME="characters"></A>
<A NAME="@concept245"></A>
<A NAME="@concept246"></A></P><P>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 </P><TT class=code>base-character</TT><P>.</P><!--TOC section General Efficiency Hints-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc202">5.12</A>&#XA0;&#XA0;General Efficiency Hints</H2><!--SEC END --><P>
<A NAME="general-efficiency"></A>
<A NAME="@concept247"></A></P><P>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 Common Lisp implementations. In
each section, there are references to related in-depth discussion.</P><!--TOC subsection Compile Your Code-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc203">5.12.1</A>&#XA0;&#XA0;Compile Your Code</H3><!--SEC END --><P>
<A NAME="@concept248"></A></P><P>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 (</P><TT class=code>fasl</TT><P>) 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.</P><P>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 <A HREF="#debugger">3</A>), 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.</P><P><U>Do not</U> 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.</P><!--TOC subsection Avoid Unnecessary Consing-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc204">5.12.2</A>&#XA0;&#XA0;Avoid Unnecessary Consing</H3><!--SEC END --><P>
<A NAME="consing"></A>
<A NAME="@concept249"></A>
<A NAME="@concept250"></A>
<A NAME="@concept251"></A>
<A NAME="@concept252"></A></P><P>Consing is another name for allocation of storage, as done by the
</P><TT class=code>cons</TT><P> function (hence its name.) </P><TT class=code>cons</TT><P> is by no means the
only function which conses&#X2014;so does </P><TT class=code>make-array</TT><P> and many
other functions. Arithmetic and function call can also have hidden
consing overheads. Consing hurts performance in the following ways:
</P><UL CLASS="itemize"><LI CLASS="li-itemize">Consing reduces memory access locality, increasing paging
activity.</LI><LI CLASS="li-itemize">Consing takes time just like anything else.</LI><LI CLASS="li-itemize">Any space allocated eventually needs to be reclaimed, either by
garbage collection or by starting a new <TT class=code>lisp</TT> process.
</LI></UL><P>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
overhead, but makes copying trivial.</P><P>Note that the remarks in section <A HREF="#efficiency-overview">5.1.5</A> 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&#X2019;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, </P><TT class=variable>then</TT><P> go back and fix the
hot spots.</P><P>See section&#XA0;<A HREF="#non-descriptor">5.11.2</A> for a discussion of how to avoid number consing
in Python.</P><!--TOC subsection Complex Argument Syntax-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc205">5.12.3</A>&#XA0;&#XA0;Complex Argument Syntax</H3><!--SEC END --><P>
<A NAME="@concept253"></A>
<A NAME="@concept254"></A>
<A NAME="@concept255"></A>
<A NAME="@concept256"></A></P><P>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:</P><UL CLASS="itemize"><LI CLASS="li-itemize">
With keyword arguments, the called function has to parse the supplied keywords
by iterating over them and checking them against the desired keywords.</LI><LI CLASS="li-itemize">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.
</LI></UL><P>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.</P><P>Optional arguments have some efficiency advantage over keyword
arguments, but their syntactic clumsiness and lack of extensibility
has caused many Common Lisp programmers to abandon use of optionals
except in functions that have obviously simple and immutable
interfaces (such as </P><TT class=code>subseq</TT><P>), 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.</P><P>Parsing of </P><TT class=code>defmacro</TT><P> 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.</P><P>Keyword argument parsing overhead can also be avoided by use of inline
expansion (see section&#XA0;<A HREF="#inline-expansion">5.8</A>) and block compilation (section
<A HREF="#block-compilation">5.7</A>.)</P><P>Note: the compiler open-codes most heavily used system functions which have
keyword or rest arguments, so that no run-time overhead is involved.</P><!--TOC subsection Mapping and Iteration-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc206">5.12.4</A>&#XA0;&#XA0;Mapping and Iteration</H3><!--SEC END --><P>
<A NAME="@concept257"></A></P><P>One of the traditional Common Lisp 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:</P><BLOCKQUOTE CLASS=lisp> <PRE>
(apply #&#X2019;+ (mapcar #&#X2019;sqrt list-of-numbers))
</PRE></BLOCKQUOTE><P>This programming style is clear and elegant, but unfortunately results
in slow code. There are two reasons why:</P><UL CLASS="itemize"><LI CLASS="li-itemize"> 
The creation of lists of intermediate results causes much
consing (see <A HREF="#consing">5.12.2</A>).</LI><LI CLASS="li-itemize">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.
</LI></UL><P>An example of an iterative version of the same code:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(do ((num list-of-numbers (cdr num))
     (sum 0 (+ (sqrt (car num)) sum)))
    ((null num) sum))
</PRE></BLOCKQUOTE><P>See sections <A HREF="#variable-type-inference">5.3.1</A> and <A HREF="#let-optimization">5.4.1</A>
for a discussion of the interactions of iteration constructs with type
inference and variable optimization. Also, section
<A HREF="#local-tail-recursion">5.6.4</A> discusses an applicative style of
iteration.</P><!--TOC subsection Trace Files and Disassembly-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc207">5.12.5</A>&#XA0;&#XA0;Trace Files and Disassembly</H3><!--SEC END --><P>
<A NAME="trace-files"></A>
<A NAME="@concept258"></A>
<A NAME="@concept259"></A>
<A NAME="@concept260"></A>
<A NAME="@concept261"></A>
<A NAME="@concept262"></A>
<A NAME="@concept263"></A></P><P>In order to write efficient code, you need to know the relative costs
of different operations. The main reason why writing efficient
Common Lisp 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.</P><P>The </P><TT class=code>disassemble</TT><P> 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 </P><TT class=code>:trace-file</TT><P> argument to </P><TT class=code>compile-file</TT><P> to generate a trace
file.</P><P>A trace file is a dump of the compiler&#X2019;s internal representations,
including annotated assembly code. Each component in the program gets
four pages in the trace file (separated by &#X201C;</P><TT class=code>^<I>L</I></TT><P>&#X201D;):
</P><UL CLASS="itemize"><LI CLASS="li-itemize">The implicit-continuation (or IR1) representation of the
optimized source. This is a dump of the flow graph representation
used for &#X201C;source level&#X201D; 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.</LI><LI CLASS="li-itemize">The Virtual Machine (VM, or IR2) representation of the program.
This dump represents the generated code as sequences of &#X201C;Virtual
OPerations&#X201D; (VOPs.) This representation is intermediate between
the source and the assembly code&#X2014;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 <TT class=code>+</TT>) may have multiple implementations with different
cost and applicability. The choice of a particular VOP such as
<TT class=code>+/fixnum</TT> or <TT class=code>+/single-float</TT> 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.</LI><LI CLASS="li-itemize">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.</LI><LI CLASS="li-itemize">A disassembly of the generated code, which has all
pseudo-operations expanded out, but is not annotated with VOPs.
</LI></UL><P>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.</P><!--TOC section Efficiency Notes-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc208">5.13</A>&#XA0;&#XA0;Efficiency Notes</H2><!--SEC END --><P>
<A NAME="efficiency-notes"></A>
<A NAME="@concept264"></A>
<A NAME="@concept265"></A>
<A NAME="@concept266"></A></P><P>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&#X2019;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.</P><P>Efficiency notes are controlled by the
</P><TT class=code>extensions:inhibit-warnings</TT><P> (see section&#XA0;<A HREF="#optimize-declaration">4.7.1</A>)
optimization quality. When </P><TT class=code>speed</TT><P> is greater than
</P><TT class=code>extensions:inhibit-warnings</TT><P>, efficiency notes are enabled.
Note that this implicitly enables efficiency notes whenever
</P><TT class=code>speed</TT><P> is increased from its default of </P><TT class=code>1</TT><P>.</P><P>Consider this program with an obscure missing declaration:</P><BLOCKQUOTE CLASS=lisp> <PRE>
(defun eff-note (x y z)
  (declare (fixnum x y z))
  (the fixnum (+ x y z)))
</PRE></BLOCKQUOTE><P>If compiled with </P><TT class=code>(speed 3) (safety 0)</TT><P>, this note is given:</P><BLOCKQUOTE class=example><PRE>
In: DEFUN EFF-NOTE
  (+ X Y Z)
==&gt;
  (+ (+ 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.
</PRE></BLOCKQUOTE><P>This efficiency note tells us that the result of the intermediate
computation </P><TT class=code>(+ x y)</TT><P> is not known to be a </P><TT class=code>fixnum</TT><P>, so
the addition of the intermediate sum to </P><TT class=code>z</TT><P> must be done less
efficiently. This can be fixed by changing the definition of
</P><TT class=code>eff-note</TT><P>:</P><BLOCKQUOTE CLASS=lisp> <PRE>
(defun eff-note (x y z)
  (declare (fixnum x y z))
  (the fixnum (+ (the fixnum (+ x y)) z)))
</PRE></BLOCKQUOTE><!--TOC subsection Type Uncertainty-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc209">5.13.1</A>&#XA0;&#XA0;Type Uncertainty</H3><!--SEC END --><P>
<A NAME="@concept267"></A>
<A NAME="@concept268"></A></P><P>The main cause of inefficiency is the compiler&#X2019;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.</P><P>Type efficiency notes are given when a value&#X2019;s type is uncertain.
There is an important distinction between values that are <EM>not
known</EM> to be of a good type (uncertain) and values that are <EM>known
not</EM> 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
</P><TT class=code>extensions:inhibit-warnings</TT><P> optimization quality is </P><TT class=code>0</TT><P>
(see section&#XA0;<A HREF="#optimize-declaration">4.7.1</A>.)</P><P>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:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(elt (the list l) i)
</PRE></BLOCKQUOTE><P>
even though a vector access is more efficient than indexing a list.</P><!--TOC subsection Efficiency Notes and Type Checking-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc210">5.13.2</A>&#XA0;&#XA0;Efficiency Notes and Type Checking</H3><!--SEC END --><P>
<A NAME="@concept269"></A>
<A NAME="@concept270"></A>
<A NAME="@concept271"></A></P><P>It is important that the </P><TT class=code>eff-note</TT><P> example above used
</P><TT class=code>(safety 0)</TT><P>. When type checking is enabled, you may get apparently
spurious efficiency notes. With </P><TT class=code>(safety 1)</TT><P>, the note has this extra
line on the end:</P><BLOCKQUOTE class=example><PRE>
The result is a (INTEGER -1610612736 1610612733), not a FIXNUM.
</PRE></BLOCKQUOTE><P>This seems strange, since there is a </P><TT class=code>the</TT><P> declaration on the result of that
second addition.</P><P>In fact, the inefficiency is real, and is a consequence of Python&#X2019;s
treating declarations as assertions to be verified. The compiler
can&#X2019;t assume that the result type declaration is true&#X2014;it must
generate the result and then test whether it is of the appropriate
type.</P><P>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 </P><TT class=code>the</TT><P>) 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:</P><BLOCKQUOTE CLASS=lisp> <PRE>
(defun eff-note (x y z)
  (declare (type (unsigned-byte 18) x y z))
  (+ x y z))
</PRE></BLOCKQUOTE><P>Of course, this declaration is acceptable only if the arguments to </P><TT class=code>eff-note</TT><P>
always </P><TT class=variable>are</TT><TT class=code>(unsigned-byte 18)</TT><P> integers.</P><!--TOC subsection Representation Efficiency Notes-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc211">5.13.3</A>&#XA0;&#XA0;Representation Efficiency Notes</H3><!--SEC END --><P>
<A NAME="representation-eff-note"></A>
<A NAME="@concept272"></A>
<A NAME="@concept273"></A>
<A NAME="@concept274"></A>
<A NAME="@concept275"></A>
<A NAME="@concept276"></A>
<A NAME="@concept277"></A></P><P>When operating on values that have non-descriptor representations
(see section&#XA0;<A HREF="#non-descriptor">5.11.2</A>), 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
<A NAME="@vars54"></A></P><TT class=code>*efficiency-note-cost-threshold*</TT><P>.</P><P>Inefficient representation coercions may be due to type uncertainty,
as in this example:</P><BLOCKQUOTE CLASS=lisp> <PRE>
(defun set-flo (x)
  (declare (single-float x))
  (prog ((var 0.0))
    (setq var (gorp))
    (setq var x)
    (return var)))
</PRE></BLOCKQUOTE><P>which produces this efficiency note:</P><BLOCKQUOTE class=example><PRE>
In: DEFUN SET-FLO
  (SETQ VAR X)
Note: Doing float to pointer coercion (cost 13) from X to VAR.
</PRE></BLOCKQUOTE><P>The variable </P><TT class=code>var</TT><P> is not known to always hold values of type
</P><TT class=code>single-float</TT><P>, so a descriptor representation must be used for its value.
In this sort of situation, adding a declaration will eliminate the inefficiency.</P><P>Often inefficient representation conversions are not due to type
uncertainty&#X2014;instead, they result from evaluating a
non-descriptor expression in a context that requires a descriptor
result:</P><UL CLASS="itemize"><LI CLASS="li-itemize"> 
Assignment to or initialization of any data structure other than
a specialized array (see section&#XA0;<A HREF="#specialized-array-types">5.11.8</A>), or</LI><LI CLASS="li-itemize">Assignment to a <TT class=code>special</TT> variable, or</LI><LI CLASS="li-itemize">Passing as an argument or returning as a value in any function
call that is not a local call (see section&#XA0;<A HREF="#number-local-call">5.11.10</A>.)
</LI></UL><P>If such inefficient coercions appear in a &#X201C;hot spot&#X201D; in the program, data
structures redesign or program reorganization may be necessary to improve
efficiency. See sections <A HREF="#block-compilation">5.7</A>, <A HREF="#numeric-types">5.11</A> and
<A HREF="#profiling">5.14</A>.</P><P>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:</P><BLOCKQUOTE CLASS=lisp> <PRE>
(defun cf+ (x y)
  (declare (single-float x y))
  (cons (+ x y) t))
</PRE></BLOCKQUOTE><P>which gives this efficiency note:</P><BLOCKQUOTE class=example><PRE>
In: DEFUN CF+
  (CONS (+ X Y) T)
Note: Doing float to pointer coercion (cost 13), for:
      The first argument of CONS.
</PRE></BLOCKQUOTE><P>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:</P><BLOCKQUOTE CLASS=lisp> <PRE>
(defun if-cf+ (x y)
  (declare (single-float x y))
  (cons (if (grue) (+ x y) (snoc)) t))
</PRE></BLOCKQUOTE><P>produces this note:</P><BLOCKQUOTE class=example><PRE>
In: DEFUN IF-CF+
  (+ X Y)
Note: Doing float to pointer coercion (cost 13).
</PRE></BLOCKQUOTE><P>In either case, the note&#X2019;s text explanation attempts to include
additional information about what locations are the source and
destination of the coercion. Here are some example notes:
</P><BLOCKQUOTE class=example><PRE>
  (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.
</PRE></BLOCKQUOTE><P>
Note that the return value of a function is also a place to which coercions may
have to be done:
</P><BLOCKQUOTE class=example><PRE>
  (DEFUN F+ (X Y) (DECLARE (SINGLE-FLOAT X Y)) (+ X Y))
Note: Doing float to pointer coercion (cost 13) to "&lt;return value&gt;".
</PRE></BLOCKQUOTE><P>
Sometimes the compiler is unable to determine a name for the source or
destination, in which case the source context is the only clue.</P><!--TOC subsection Verbosity Control-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc212">5.13.4</A>&#XA0;&#XA0;Verbosity Control</H3><!--SEC END --><P>
<A NAME="@concept278"></A>
<A NAME="@concept279"></A></P><P>These variables control the verbosity of efficiency notes:</P><P><BR>
<A NAME="@vars55"></A><A NAME="VR:efficiency-note-cost-threshold"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>*efficiency-note-cost-threshold*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>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 &#X201C;trivial&#X201D; inefficiencies. A value of </P><TT class=code>1</TT><P> will
note any inefficiency.
</P></BLOCKQUOTE><P><BR>
<A NAME="@vars56"></A><A NAME="VR:efficiency-note-limit"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>*efficiency-note-limit*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>When printing some efficiency notes, the compiler reports possible
efficient implementations. The initial value of </P><TT class=code>2</TT><P> prevents
excessively long efficiency notes in the common case where there is
no type information, so all implementations are possible.
</P></BLOCKQUOTE><!--TOC section Profiling-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc213">5.14</A>&#XA0;&#XA0;Profiling</H2><!--SEC END --><P>
<A NAME="@concept280"></A>
<A NAME="@concept281"></A>
<A NAME="@concept282"></A>
<A NAME="@concept283"></A>
<A NAME="profiling"></A></P><P>The first step in improving a program&#X2019;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
</P><TT class=code>profile</TT><P> package. This package provides a macro </P><TT class=code>profile</TT><P>
that encapsulates functions with statistics gathering code.</P><!--TOC subsection Profile Interface-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc214">5.14.1</A>&#XA0;&#XA0;Profile Interface</H3><!--SEC END --><P><BR>
<A NAME="@vars57"></A><A NAME="VR:timed-functions"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>profile:</TT><TT class=function-name>*timed-functions*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This variable holds a list of all functions that are currently being
profiled.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs148"></A><A NAME="FN:profile"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>profile:</TT><TT class=function-name>profile</TT> <TT class=code>{<TT class=variable>name</TT> |<TT class=code>:callers</TT> <TT class=code>t</TT>}</TT><SUP>*</SUP> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This macro wraps profiling code around the named functions. As in
</P><TT class=code>trace</TT><P>, the </P><TT class=variable>name</TT><P>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.</P><P>If </P><TT class=code>:callers <TT class=variable>t</TT></TT><P> is specified, then each function that calls
this function is recorded along with the number of calls made.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs149"></A><A NAME="FN:unprofile"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>profile:</TT><TT class=function-name>unprofile</TT> <TT class=code>{<TT class=variable>name</TT>}</TT><SUP>*</SUP> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This macro removes profiling code from the named functions. If no
</P><TT class=variable>name</TT><P>s are supplied, all currently profiled functions are
unprofiled.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs150"></A><A NAME="FN:profile-all"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>profile:</TT><TT class=function-name>profile-all</TT> <TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=code>:package</TT> <TT class=code>:callers-p</TT></SPAN> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This macro in effect calls </P><TT class=code>profile:profile</TT><P> for each
function in the specified package which defaults to
</P><TT class=code>*package*</TT><P>. </P><TT class=code>:callers-p</TT><P> has the same meaning as in
</P><TT class=code>profile:profile</TT><P>.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs151"></A><A NAME="FN:report-time"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>profile:</TT><TT class=function-name>report-time</TT> <TT class=code>{<TT class=variable>name</TT>}</TT><SUP>*</SUP> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This macro prints a report for each </P><TT class=variable>name</TT><P>d function of the
following information:
</P><UL CLASS="itemize"><LI CLASS="li-itemize">
The total CPU time used in that function for all calls,</LI><LI CLASS="li-itemize">the total number of bytes consed in that function for all
calls,</LI><LI CLASS="li-itemize">the total number of calls,</LI><LI CLASS="li-itemize">the average amount of CPU time per call.
</LI></UL><P>
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 </P><TT class=variable>name</TT><P>s are supplied, then the times for all
currently profiled functions are printed.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs152"></A><A NAME="FN:reset-time"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>reset-time</TT> <TT class=code>{<TT class=variable>name</TT>}</TT><SUP>*</SUP> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This macro resets the profiling counters associated with the
</P><TT class=variable>name</TT><P>d functions. If no </P><TT class=variable>name</TT><P>s are supplied, then all
currently profiled functions are reset.
</P></BLOCKQUOTE><!--TOC subsection Profiling Techniques-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc215">5.14.2</A>&#XA0;&#XA0;Profiling Techniques</H3><!--SEC END --><P>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.</P><P>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.</P><!--TOC subsection Nested or Recursive Calls-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc216">5.14.3</A>&#XA0;&#XA0;Nested or Recursive Calls</H3><!--SEC END --><P>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
&#X201C;leak&#X201D; into the reported time for the outer function. In general, be wary of
profiling short functions that are called many times.</P><!--TOC subsection Clock resolution-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc217">5.14.4</A>&#XA0;&#XA0;Clock resolution</H3><!--SEC END --><P>Unless you are very lucky, the length of your machine&#X2019;s clock &#X201C;tick&#X201D; 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. </P><P>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.</P><!--TOC subsection Profiling overhead-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc218">5.14.5</A>&#XA0;&#XA0;Profiling overhead</H3><!--SEC END --><P>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.</P><P>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.</P><P>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
</P><TT class=code>time</TT><P> macro.) Time unaccounted for is probably being used by functions that
you forgot to profile.</P><!--TOC subsection Additional Timing Utilities-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc219">5.14.6</A>&#XA0;&#XA0;Additional Timing Utilities</H3><!--SEC END --><P><BR>
<A NAME="@funs153"></A><A NAME="FN:time"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>time</TT>  <TT class=variable>form</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This macro evaluates </P><TT class=variable>form</TT><P>, prints some timing and memory
allocation information to </P><TT class=code>*trace-output*</TT><P>, and returns any
values that </P><TT class=variable>form</TT><P> 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
</P><TT class=code>time</TT><P> form is not compiled (e.g. it was typed at top-level),
then </P><TT class=code>compile</TT><P> will be called on the form to give more accurate
timing information. If you really want to time interpreted speed,
you can say:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(time (eval &#X2019;<TT class=variable>form</TT>))
</PRE></BLOCKQUOTE><P>
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:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(time (dotimes (i 100) <TT class=variable>form</TT>))
</PRE></BLOCKQUOTE></BLOCKQUOTE><P><BR>
<A NAME="@funs154"></A><A NAME="FN:get-bytes-consed"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>get-bytes-consed</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>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.
</P></BLOCKQUOTE><P><BR>
<A NAME="@vars58"></A><A NAME="VR:gc-run-time"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>*gc-run-time*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This variable accumulates the run-time consumed by garbage
collection, in the units returned by
<A NAME="@funs155"></A></P><TT class=code>get-internal-run-time</TT><P>.
</P></BLOCKQUOTE><P><BR>
</P><DIV align=left>
[Constant]<BR>
 <TT class=function-name>internal-time-units-per-second</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
The value of internal-time-units-per-second is 100.
</BLOCKQUOTE><!--TOC subsection A Note on Timing-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc220">5.14.7</A>&#XA0;&#XA0;A Note on Timing</H3><!--SEC END --><P>
<A NAME="@concept284"></A>
<A NAME="@concept285"></A>
<A NAME="@concept286"></A></P><P>There are two general kinds of timing information provided by the
</P><TT class=code>time</TT><P> 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&#X2019;t know exactly what those conditions were.</P><P>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. &#X201C;User run time&#X201D; and &#X201C;system run time&#X201D; are numbers
reported by the Unix kernel. They are supposed to be a measure of how
much time the processor spent running your &#X201C;user&#X201D; program (which
will include GC overhead, etc.), and the amount of time that the
kernel spent running &#X201C;on your behalf.&#X201D;</P><P>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.</P><P>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.)</P><P>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 </P><TT class=variable>sum</TT><P> of kernel
and user time is more reproducible. The problem is that as system activity
increases, there is a spurious </P><TT class=variable>decrease</TT><P> in user run time. In effect, as
paging, etc., increases, user time leaks into system time.</P><P>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 &#X201C;ps aux&#X201D; 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.</P><!--TOC subsection Benchmarking Techniques-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc221">5.14.8</A>&#XA0;&#XA0;Benchmarking Techniques</H3><!--SEC END --><P>
<A NAME="@concept287"></A></P><P>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.</P><P>For the first use (measuring the effect of program modifications with
constant hardware), you should look at </P><TT class=variable>both</TT><P> 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 &#X201C;how long it would have
taken to run if I had my own machine.&#X201D; So in the case of comparing CPU
intensive programs, system+user time is relatively real, and reasonable to
use.</P><P>For programs that spend a substantial amount of their time paging, you
really can&#X2019;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.</P><P>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 </P><TT class=variable>exactly</TT><P> the way that they will
</P><TT class=variable>normally</TT><P> be run, and then measure </P><TT class=variable>real</TT><P> 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 64MB of
memory, then run with 64MB. Here, &#X201C;normal&#X201D; means &#X201C;normal for that
machine&#X201D;. </P><P>If you have a program you believe to be CPU intensive, then you might be
tempted to compare &#X201C;run&#X201D; times across systems, hoping to get a meaningful
result even if the benchmarking isn&#X2019;t done under the expected running
condition. Don&#X2019;t to this, for two reasons:</P><UL CLASS="itemize"><LI CLASS="li-itemize"> 
The operating systems might not compute run time in the same
way.</LI><LI CLASS="li-itemize">Under the real running condition, the program might not be CPU
intensive after all.
</LI></UL><P>In the end, only real time means anything&#X2014;it is the amount of time you
have to wait for the result. The only valid uses for run time are:</P><UL CLASS="itemize"><LI CLASS="li-itemize">
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.</LI><LI CLASS="li-itemize">To evaluate the relative performance of CPU intensive programs
in the same environment.
</LI></UL><!--NAME compiler-hint.html-->
<!--BEGIN NOTES chapter-->
<HR CLASS="ffootnoterule"><DL CLASS="thefootnotes"><DT CLASS="dt-thefootnotes">
<A NAME="note10" HREF="#text10">1</A></DT><DD CLASS="dd-thefootnotes">The source
transformation in this example doesn&#X2019;t represent the preservation of
evaluation order implicit in the compiler&#X2019;s internal representation.
Where necessary, the back end will reintroduce temporaries to
preserve the semantics.
</DD><DT CLASS="dt-thefootnotes"><A NAME="note11" HREF="#text11">2</A></DT><DD CLASS="dd-thefootnotes">Note
that the code for <TT class=code>x</TT> and <TT class=code>y</TT> isn&#X2019;t actually replicated.
</DD><DT CLASS="dt-thefootnotes"><A NAME="note12" HREF="#text12">3</A></DT><DD CLASS="dd-thefootnotes">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.
</DD><DT CLASS="dt-thefootnotes"><A NAME="note13" HREF="#text13">4</A></DT><DD CLASS="dd-thefootnotes">This, however, has not actually happened, but
it is a possibility.
</DD><DT CLASS="dt-thefootnotes"><A NAME="note14" HREF="#text14">5</A></DT><DD CLASS="dd-thefootnotes">Kahan, W., &#X201C;Branch Cuts for Complex Elementary
Functions, or Much Ado About Nothing&#X2019;s Sign Bit&#X201D;
in Iserles and Powell (eds.) <I>The State of the Art
in Numerical Analysis</I>, pp. 165-211, Clarendon
Press, 1987
</DD></DL>
<!--END NOTES-->
<!--TOC chapter UNIX Interface-->
<H1 CLASS="chapter"><!--SEC ANCHOR --><A NAME="htoc222">Chapter&#XA0;6</A>&#XA0;&#XA0;UNIX Interface</H1><!--SEC END --><P>
<A NAME="unix-interface"></A></P><DIV CLASS="center">
<B>by Robert MacLachlan, Skef Wholey, Bill Chiles and William Lott</B>
</DIV><P>CMUCL 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 Unix and X11, as well as access to the standard
system documentation.</P><!--TOC section Reading the Command Line-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc223">6.1</A>&#XA0;&#XA0;Reading the Command Line</H2><!--SEC END --><P>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.</P><P><BR>
<A NAME="@vars59"></A><A NAME="VR:command-line-strings"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>*command-line-strings*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
<P><A NAME="@vars60"></A><A NAME="VR:command-line-utility-name"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>*command-line-utility-name*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><P><A NAME="@vars61"></A><A NAME="VR:command-line-words"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>*command-line-words*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><P><A NAME="@vars62"></A><A NAME="VR:command-line-switches"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>*command-line-switches*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><P>The value of </P><TT class=code>*command-line-words*</TT><P> 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
</P><TT class=code>lisp</TT><P>) is stored in </P><TT class=code>*command-line-utility-name*</TT><P>. The
value of </P><TT class=code>*command-line-switches*</TT><P> is a list of
</P><TT class=code>command-line-switch</TT><P> 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 </P><TT class=code>*command-line-words*</TT><P>.
</P></BLOCKQUOTE><P>The following functions may be used to examine </P><TT class=code>command-line-switch</TT><P>
structures.
</P><P><BR>
<A NAME="@funs156"></A><A NAME="FN:cmd-switch-name"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>cmd-switch-name</TT> <TT class=variable>switch</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>Returns the name of the switch, less the preceding hyphen and
trailing equal sign (if any).
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs157"></A><A NAME="FN:cmd-switch-value"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>cmd-switch-value</TT> <TT class=variable>switch</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>Returns the value designated using an embedded equal sign, if any.
If the switch has no equal sign, then this is null.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs158"></A><A NAME="FN:cmd-switch-words"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>cmd-switch-words</TT> <TT class=variable>switch</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>Returns a list of the words between this switch and the next switch
or the end of the command line.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs159"></A><A NAME="FN:cmd-switch-arg"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>cmd-switch-arg</TT> <TT class=variable>switch</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>Returns the first non-null value from </P><TT class=code>cmd-switch-value</TT><P>, the
first element in </P><TT class=code>cmd-switch-words</TT><P>, or the first word in
</P><TT class=variable>command-line-words</TT><P>.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs160"></A><A NAME="FN:get-command-line-switch"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>get-command-line-switch</TT> <TT class=variable>sname</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>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 </P><TT class=code>t</TT><P> is returned. If the switch was not
specified, then </P><TT class=code>nil</TT><P> is returned.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs161"></A><A NAME="FN:defswitch"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>defswitch</TT> <TT class=variable>name</TT> <TT class=code>&amp;optional</TT> <TT class=variable>function</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This macro causes </P><TT class=variable>function</TT><P> to be called when the switch
</P><TT class=variable>name</TT><P> 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.)</P><P>If </P><TT class=variable>function</TT><P> is not supplied, then the switch is parsed into
</P><TT class=variable>command-line-switches</TT><P>, but otherwise ignored. This suppresses
the undefined switch warning which would otherwise take place. The
warning can also be globally suppressed by
</P><TT class=variable>complain-about-illegal-switches</TT><P>.
</P></BLOCKQUOTE><!--TOC section Useful Variables-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc224">6.2</A>&#XA0;&#XA0;Useful Variables</H2><!--SEC END --><P><BR>
<A NAME="@vars63"></A><A NAME="VR:stdin"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>system:</TT><TT class=function-name>*stdin*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
<P><A NAME="@vars64"></A><A NAME="VR:stdout"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>system:</TT><TT class=function-name>*stdout*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><P><A NAME="@vars65"></A><A NAME="VR:stderr"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>system:</TT><TT class=function-name>*stderr*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><P>Streams connected to the standard input, output and error file
descriptors.
</P></BLOCKQUOTE><P><BR>
<A NAME="@vars66"></A><A NAME="VR:tty"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>system:</TT><TT class=function-name>*tty*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>A stream connected to </P><TT class=filename>/dev/tty</TT><P>.
</P></BLOCKQUOTE><P><BR>
<A NAME="@vars67"></A><A NAME="VR:environment-list"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>*environment-list*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
The environment variables inherited by the current process, as a
keyword-indexed alist. For example, to access the DISPLAY
environment variable, you could use<BLOCKQUOTE CLASS=lisp> <PRE>
   (cdr (assoc :display ext:*environment-list*))
</PRE></BLOCKQUOTE><P>Note that the case of the variable name is preserved when converting
to a keyword. Therefore, you need to specify the keyword properly for
variable names containing lower-case letters,
</P></BLOCKQUOTE><!--TOC section Lisp Equivalents for C Routines-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc225">6.3</A>&#XA0;&#XA0;Lisp Equivalents for C Routines</H2><!--SEC END --><P>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.</P><P>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 &#X201C;parameter&#X201D; 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.</P><P>Thus, the C routine declared as</P><BLOCKQUOTE class=example><PRE>
kern_return_t lookup(servport, portsname, portsid)
        port        servport;
        char        *portsname;
        int        *portsid;        /* out */
 
  ...
  *portsid = &lt;expression to compute portsid field&gt;
  return(KERN_SUCCESS);
 
</PRE></BLOCKQUOTE><P>has as its Lisp equivalent something like</P><BLOCKQUOTE CLASS=lisp> <PRE>
(defun lookup (ServPort PortsName)
  ...
  (values
   success
   &lt;expression to compute portsid field&gt;))
</PRE></BLOCKQUOTE><P>If there are multiple out or in-out arguments, then there are multiple
additional returns values.</P><P>Fortunately, CMUCL 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 </P><TT class=code>describe</TT><P> function
(and the Hemlock </P><TT class=code>Describe Function Call</TT><P> command, invoked with
<U>C-M-Shift-A</U>) will list this information. Since the names of arguments
and return values are usually descriptive, the information that
</P><TT class=code>describe</TT><P> 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.</P><!--TOC section Type Translations-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc226">6.4</A>&#XA0;&#XA0;Type Translations</H2><!--SEC END --><P>
<A NAME="@concept288"></A>
<A NAME="@concept289"></A>
<A NAME="@concept290"></A></P><P>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.</P><P>Instances of enumerated types are expressed as keywords in Lisp.
Records, arrays, and pointer types are implemented with the Alien
facility (see section&#XA0;<A HREF="#aliens">8</A>). 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).</P><P>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 Aliens contain pointers to non-Lisp data, the
garbage collector cannot do this itself. If the memory
was obtained from <A NAME="@funs162"></A></P><TT class=code>make-alien</TT><P> or from a foreign function call
to a routine that used </P><TT class=code>malloc</TT><P>, then <A NAME="@funs163"></A></P><TT class=code>free-alien</TT><P> should
be used.</P><!--TOC section System Area Pointers-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc227">6.5</A>&#XA0;&#XA0;System Area Pointers</H2><!--SEC END --><P>
<A NAME="system-area-pointers"></A></P><P><A NAME="@concept291"></A><A NAME="@concept292"></A><A NAME="@concept293"></A>
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.</P><P>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 </P><TT class=code>lisp</TT><P> 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.
See section&#XA0;<A HREF="#non-descriptor">5.11.2</A>.</P><P><BR>
<A NAME="@funs164"></A><A NAME="FN:sap-int"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>system:</TT><TT class=function-name>sap-int</TT> <TT class=variable>sap</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
<P><A NAME="@funs165"></A><A NAME="FN:int-sap"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>system:</TT><TT class=function-name>int-sap</TT> <TT class=variable>int</TT> &nbsp;&nbsp;&nbsp;
</DIV><P>The function </P><TT class=code>sap-int</TT><P> 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 </P><TT class=code>int-sap</TT><P> 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.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs166"></A><A NAME="FN:sap+"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>system:</TT><TT class=function-name>sap+</TT> <TT class=variable>sap</TT> <TT class=variable>offset</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function adds a byte </P><TT class=variable>offset</TT><P> to </P><TT class=variable>sap</TT><P>, returning a new
SAP.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs167"></A><A NAME="FN:sap-ref-8"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>system:</TT><TT class=function-name>sap-ref-8</TT> <TT class=variable>sap</TT> <TT class=variable>offset</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
<P><A NAME="@funs168"></A><A NAME="FN:sap-ref-16"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>system:</TT><TT class=function-name>sap-ref-16</TT> <TT class=variable>sap</TT> <TT class=variable>offset</TT> &nbsp;&nbsp;&nbsp;
</DIV><P><A NAME="@funs169"></A><A NAME="FN:sap-ref-32"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>system:</TT><TT class=function-name>sap-ref-32</TT> <TT class=variable>sap</TT> <TT class=variable>offset</TT> &nbsp;&nbsp;&nbsp;
</DIV><P>These functions return the 8, 16 or 32 bit unsigned integer at
</P><TT class=variable>offset</TT><P> from </P><TT class=variable>sap</TT><P>. The </P><TT class=variable>offset</TT><P> is always a byte
offset, regardless of the number of bits accessed. </P><TT class=code>setf</TT><P> may
be used with the these functions to deposit values into virtual
memory.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs170"></A><A NAME="FN:signed-sap-ref-8"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>system:</TT><TT class=function-name>signed-sap-ref-8</TT> <TT class=variable>sap</TT> <TT class=variable>offset</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
<P><A NAME="@funs171"></A><A NAME="FN:signed-sap-ref-16"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>system:</TT><TT class=function-name>signed-sap-ref-16</TT> <TT class=variable>sap</TT> <TT class=variable>offset</TT> &nbsp;&nbsp;&nbsp;
</DIV><P><A NAME="@funs172"></A><A NAME="FN:signed-sap-ref-32"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>system:</TT><TT class=function-name>signed-sap-ref-32</TT> <TT class=variable>sap</TT> <TT class=variable>offset</TT> &nbsp;&nbsp;&nbsp;
</DIV><P>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.
</P></BLOCKQUOTE><!--TOC section Unix System Calls-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc228">6.6</A>&#XA0;&#XA0;Unix System Calls</H2><!--SEC END --><P>You probably won&#X2019;t have much cause to use them, but all the Unix system
calls are available. The Unix system call functions are in the
</P><TT class=code>Unix</TT><P> package. The name of the interface for a particular system
call is the name of the system call prepended with </P><TT class=code>unix-</TT><P>. The
system usually defines the associated constants without any prefix name.
To find out how to use a particular system call, try using
</P><TT class=code>describe</TT><P> on it. If that is unhelpful, look at the source in
</P><TT class=filename>unix.lisp</TT><P> or consult your system maintainer.</P><P>The Unix system calls indicate an error by returning </P><TT class=code>nil</TT><P> 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-</P><TT class=code>nil</TT><P>, often </P><TT class=code>t</TT><P>.</P><P>For example, to use the </P><TT class=code>chdir</TT><P> syscall: </P><BLOCKQUOTE CLASS=lisp> <PRE>
(multiple-value-bind (success errno)
    (unix:unix-chdir "/tmp")
  (unless success
     (error "Can&#X2019;t change working directory: ~a"
            (unix:get-unix-error-msg errno))))
</PRE></BLOCKQUOTE><P><BR>
<A NAME="@funs173"></A><A NAME="FN:get-unix-error-msg"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>Unix:</TT><TT class=function-name>get-unix-error-msg</TT> <TT class=variable>error</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns a string describing the Unix error number
</P><TT class=variable>error</TT><P> (this is similar to the Unix function </P><TT class=code>perror</TT><P>). 
</P></BLOCKQUOTE><!--TOC section File Descriptor Streams-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc229">6.7</A>&#XA0;&#XA0;File Descriptor Streams</H2><!--SEC END --><P>
<A NAME="sec:fds"></A></P><P>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.
For this purpose, fd-streams exist. See also <A NAME="@funs174"></A></P><TT class=code>read-n-bytes</TT><P>.</P><P><BR>
<A NAME="@funs175"></A><A NAME="FN:make-fd-stream"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>system:</TT><TT class=function-name>make-fd-stream</TT> <TT class=variable>descriptor</TT> <TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=code>:input</TT> <TT class=code>:output</TT>
<TT class=code>:element-type</TT></SPAN><BR>
 <TT class=code>:buffering</TT> <TT class=code>:name</TT>
<TT class=code>:file</TT> <TT class=code>:original</TT><BR>
 <TT class=code>:delete-original</TT>
<TT class=code>:auto-close</TT><BR>
 <TT class=code>:timeout</TT> <TT class=code>:pathname</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function creates a file descriptor stream using
</P><TT class=variable>descriptor</TT><P>. If </P><TT class=code>:input</TT><P> is non-</P><TT class=code>nil</TT><P>, input operations are
allowed. If </P><TT class=code>:output</TT><P> is non-</P><TT class=code>nil</TT><P>, output operations are
allowed. The default is input only. These keywords are defined:

</P><DL CLASS="list"><DT CLASS="dt-list">

<TT class=code>:element-type</TT><BR>
</DT><DD CLASS="dd-list"> is the type of the unit of transaction for
the stream, which defaults to <TT class=code>string-char</TT>. See the Common Lisp
description of <TT class=code>open</TT> for valid values.</DD><DT CLASS="dt-list"><TT class=code>:buffering</TT><BR>
</DT><DD CLASS="dd-list"> is the kind of output buffering desired for
the stream. Legal values are <TT class=code>:none</TT> for no buffering,
<TT class=code>:line</TT> for buffering up to each newline, and <TT class=code>:full</TT> for
full buffering.</DD><DT CLASS="dt-list"><TT class=code>:name</TT><BR>
</DT><DD CLASS="dd-list"> 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 <TT class=code>Stream
for </TT>. If <TT class=variable>name</TT> is unspecified, it defaults to a string
containing <TT class=variable>file</TT> or <TT class=variable>descriptor</TT>, in order of preference.</DD><DT CLASS="dt-list"><TT class=code>:file</TT>, <TT class=code>:original</TT><BR>
</DT><DD CLASS="dd-list"> <TT class=variable>file</TT> specifies the defaulted
namestring of the associated file when creating a file stream
(must be a <TT class=code>simple-string</TT>). <TT class=variable>original</TT> is the
<TT class=code>simple-string</TT> name of a backup file containing the original
contents of <TT class=variable>file</TT> while writing <TT class=variable>file</TT>.<P>When you abort the stream by passing </P><TT class=code>t</TT><P> to </P><TT class=code>close</TT><P> as
the second argument, if you supplied both </P><TT class=variable>file</TT><P> and
</P><TT class=variable>original</TT><P>, </P><TT class=code>close</TT><P> will rename the </P><TT class=variable>original</TT><P> name
to the </P><TT class=variable>file</TT><P> name. When you </P><TT class=code>close</TT><P> the stream
normally, if you supplied </P><TT class=variable>original</TT><P>, and
</P><TT class=variable>delete-original</TT><P> is non-</P><TT class=code>nil</TT><P>, </P><TT class=code>close</TT><P> deletes
</P><TT class=variable>original</TT><P>. If </P><TT class=variable>auto-close</TT><P> is true (the default), then
</P><TT class=variable>descriptor</TT><P> will be closed when the stream is garbage
collected.</P></DD><DT CLASS="dt-list"><TT class=code>:pathname</TT><BR>
</DT><DD CLASS="dd-list">: The original pathname passed to open and
returned by <TT class=code>pathname</TT>; not defaulted or translated.</DD><DT CLASS="dt-list"><TT class=code>:timeout</TT><BR>
</DT><DD CLASS="dd-list"> if non-null, then <TT class=variable>timeout</TT> is an integer
number of seconds after which an input wait should time out. If a
read does time out, then the <TT class=code>system:io-timeout</TT> condition is
signalled.
</DD></DL></BLOCKQUOTE><P><BR>
<A NAME="@funs176"></A><A NAME="FN:fd-stream-p"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>system:</TT><TT class=function-name>fd-stream-p</TT> <TT class=variable>object</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns </P><TT class=code>t</TT><P> if </P><TT class=variable>object</TT><P> is an fd-stream, and
</P><TT class=code>nil</TT><P> if not. Obsolete: use the portable </P><TT class=code>(typep x
&#X2019;file-stream)</TT><P>.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs177"></A><A NAME="FN:fd-stream-fd"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>system:</TT><TT class=function-name>fd-stream-fd</TT> <TT class=variable>stream</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This returns the file descriptor associated with </P><TT class=variable>stream</TT><P>.
</P></BLOCKQUOTE><!--TOC section Unix Signals-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc230">6.8</A>&#XA0;&#XA0;Unix Signals</H2><!--SEC END --><P>
<A NAME="@concept294"></A> <A NAME="@concept295"></A></P><P>CMUCL 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 <EM>Unix Programmer&#X2019;s Manual</EM> are exported
from the Unix package.</P><!--TOC subsection Changing Signal Handlers-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc231">6.8.1</A>&#XA0;&#XA0;Changing Signal Handlers</H3><!--SEC END --><P>
<A NAME="signal-handlers"></A></P><P><BR>
<A NAME="@funs178"></A><A NAME="FN:with-enabled-interrupts"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>system:</TT><TT class=function-name>with-enabled-interrupts</TT> 
<TT class=variable>specs</TT> <TT class=code>&amp;rest</TT> <TT class=variable>body</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This macro should be called with a list of signal specifications,
</P><TT class=variable>specs</TT><P>. Each element of </P><TT class=variable>specs</TT><P> should be a list of
two 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 One or more signal handlers can be
established in this way. </P><TT class=code>with-enabled-interrupts</TT><P> establishes
the correct signal handlers and then executes the forms in
</P><TT class=variable>body</TT><P>. 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 </P><TT class=code>with-enabled-interrupts</TT><P> 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.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs179"></A><A NAME="FN:without-interrupts"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>system:</TT><TT class=function-name>without-interrupts</TT> <TT class=code>&amp;rest</TT> <TT class=variable>body</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>It is sometimes necessary to execute a piece a code that can not be
interrupted. This macro the forms in </P><TT class=variable>body</TT><P> with interrupts
disabled. Note that the Unix interrupts are not actually disabled,
rather they are queued until after </P><TT class=variable>body</TT><P> has finished
executing.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs180"></A><A NAME="FN:with-interrupts"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>system:</TT><TT class=function-name>with-interrupts</TT> <TT class=code>&amp;rest</TT> <TT class=variable>body</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>When executing an interrupt handler, the system disables interrupts,
as if the handler was wrapped in in a </P><TT class=code>without-interrupts</TT><P>.
The macro </P><TT class=code>with-interrupts</TT><P> can be used to enable interrupts
while the forms in </P><TT class=variable>body</TT><P> are evaluated. This is useful if
</P><TT class=variable>body</TT><P> is going to enter a break loop or do some long
computation that might need to be interrupted.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs181"></A><A NAME="FN:without-hemlock"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>system:</TT><TT class=function-name>without-hemlock</TT> <TT class=code>&amp;rest</TT> <TT class=variable>body</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>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 </P><TT class=variable>body</TT><P> after
exiting Hemlock. When </P><TT class=variable>body</TT><P> has been executed, control is
returned to Hemlock.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs182"></A><A NAME="FN:enable-interrupt"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>system:</TT><TT class=function-name>enable-interrupt</TT> <TT class=variable>signal</TT> <TT class=variable>function</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function establishes </P><TT class=variable>function</TT><P> as the handler for
</P><TT class=variable>signal</TT><P>.

Unless you want to establish a global signal handler, you should use
the macro </P><TT class=code>with-enabled-interrupts</TT><P> to temporarily establish a
signal handler. 
</P><TT class=code>enable-interrupt</TT><P> returns the old function associated with the
signal. 
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs183"></A><A NAME="FN:ignore-interrupt"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>system:</TT><TT class=function-name>ignore-interrupt</TT> <TT class=variable>signal</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>Ignore-interrupt sets the Unix signal mechanism to ignore
</P><TT class=variable>signal</TT><P> which means that the Lisp process will never see the
signal. Ignore-interrupt returns the old function associated with
the signal or </P><TT class=code>nil</TT><P> if none is currently defined.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs184"></A><A NAME="FN:default-interrupt"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>system:</TT><TT class=function-name>default-interrupt</TT> <TT class=variable>signal</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>Default-interrupt can be used to tell the Unix signal mechanism to
perform the default action for </P><TT class=variable>signal</TT><P>. For details on what
the default action for a signal is, see section 2 of the <EM>Unix
Programmer&#X2019;s Manual</EM>. In general, it is likely to ignore the
signal or to cause a core dump.
</P></BLOCKQUOTE><!--TOC subsection Examples of Signal Handlers-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc232">6.8.2</A>&#XA0;&#XA0;Examples of Signal Handlers</H3><!--SEC END --><P>The following code is the signal handler used by the Lisp system for the
SIGINT signal.</P><BLOCKQUOTE CLASS=lisp> <PRE>
(defun ih-sigint (signal code scp)
  (declare (ignore signal code scp))
  (without-hemlock
   (with-interrupts
    (break "Software Interrupt" t))))
</PRE></BLOCKQUOTE><P>The </P><TT class=code>without-hemlock</TT><P> form is used to make sure that Hemlock is exited before
a break loop is entered. The </P><TT class=code>with-interrupts</TT><P> 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.</P><P>The following function is the Lisp signal handler for the SIGTSTP signal
which suspends a process and returns to the Unix shell.</P><BLOCKQUOTE CLASS=lisp> <PRE>
(defun ih-sigtstp (signal code scp)
  (declare (ignore signal code scp))
  (without-hemlock
   (Unix:unix-kill (Unix:unix-getpid) Unix:sigstop)))
</PRE></BLOCKQUOTE><P>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.</P><P>To set up these interrupt handlers, the following is recommended:</P><BLOCKQUOTE CLASS=lisp> <PRE>
(with-enabled-interrupts ((Unix:SIGINT #&#X2019;ih-sigint)
                          (Unix:SIGTSTP #&#X2019;ih-sigtstp))
  &lt;user code to execute with the above signal handlers enabled.&gt;
)
</PRE></BLOCKQUOTE><!--NAME unix.html-->
<!--TOC chapter Event Dispatching with SERVE-EVENT-->
<H1 CLASS="chapter"><!--SEC ANCHOR --><A NAME="htoc233">Chapter&#XA0;7</A>&#XA0;&#XA0;Event Dispatching with SERVE-EVENT</H1><!--SEC END --><P>
<A NAME="serve-event"></A></P><DIV CLASS="center">
<B>by Bill Chiles and Robert MacLachlan</B>
</DIV><P>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. CMUCL
achieves this by having a central scheduling mechanism based on an
event-driven, object-oriented paradigm.</P><P>An </P><TT class=variable>event</TT><P> 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.</P><!--TOC section Object Sets-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc234">7.1</A>&#XA0;&#XA0;Object Sets</H2><!--SEC END --><P>
<A NAME="object-sets"></A>
<A NAME="@concept296"></A></P><P>An <EM>object set</EM> 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.</P><P><BR>
<A NAME="@funs185"></A><A NAME="FN:make-object-set"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>system:</TT><TT class=function-name>make-object-set</TT> <TT class=variable>name</TT> <TT class=code>&amp;optional</TT> <TT class=variable>default-handler</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function makes a new object set. </P><TT class=variable>Name</TT><P> is a string used
only for purposes of identifying the object set when it is printed.
</P><TT class=variable>Default-handler</TT><P> is the function used as a handler when an
undefined operation occurs on an object in the set. You can define
operations with the </P><TT class=code>serve-</TT><TT class=variable>operation</TT><P> functions exported
the </P><TT class=code>extensions</TT><P> package for X events
(see section&#XA0;<A HREF="#x-serve-mumbles">7.4</A>). Objects are added with
</P><TT class=code>system:add-xwindow-object</TT><P>. Initially the object set has no
objects and no defined operations.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs186"></A><A NAME="FN:object-set-operation"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>system:</TT><TT class=function-name>object-set-operation</TT> <TT class=variable>object-set</TT> <TT class=variable>operation-code</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns the handler function that is the
implementation of the operation corresponding to
</P><TT class=variable>operation-code</TT><P> in </P><TT class=variable>object-set</TT><P>. When set with
</P><TT class=code>setf</TT><P>, the setter function establishes the new handler. The
</P><TT class=code>serve-</TT><TT class=variable>operation</TT><P> functions exported from the
</P><TT class=code>extensions</TT><P> package for X events (see section&#XA0;<A HREF="#x-serve-mumbles">7.4</A>)
call this on behalf of the user when announcing a new operation for
an object set.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs187"></A><A NAME="FN:add-xwindow-object"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>system:</TT><TT class=function-name>add-xwindow-object</TT> <TT class=variable>window</TT> <TT class=variable>object</TT> <TT class=variable>object-set</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>These functions add </P><TT class=variable>port</TT><P> or </P><TT class=variable>window</TT><P> to </P><TT class=variable>object-set</TT><P>.
</P><TT class=variable>Object</TT><P> is an arbitrary Lisp object that is associated with the
</P><TT class=variable>port</TT><P> or </P><TT class=variable>window</TT><P> capability. </P><TT class=variable>Window</TT><P> is a CLX
window. When an event occurs, </P><TT class=code>system:serve-event</TT><P> passes
</P><TT class=variable>object</TT><P> as an argument to the handler function.
</P></BLOCKQUOTE><!--TOC section The SERVE-EVENT Function-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc235">7.2</A>&#XA0;&#XA0;The SERVE-EVENT Function</H2><!--SEC END --><P>The </P><TT class=code>system:serve-event</TT><P> function is the standard way for an application
to wait for something to happen. For example, the Lisp system calls
</P><TT class=code>system:serve-event</TT><P> when it wants input from X or a terminal stream.
The idea behind </P><TT class=code>system:serve-event</TT><P> is that it knows the appropriate
action to take when any interesting event happens. If an application calls
</P><TT class=code>system:serve-event</TT><P> when it is idle, then any other applications with
pending events can run. This allows several applications to run &#X201C;at the
same time&#X201D; 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.</P><P><BR>
<A NAME="@funs188"></A><A NAME="FN:serve-event"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>system:</TT><TT class=function-name>serve-event</TT> <TT class=code>&amp;optional</TT> <TT class=variable>timeout</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function waits for an event to happen and then dispatches to
the correct handler function. If specified, </P><TT class=variable>timeout</TT><P> is the
number of seconds to wait before timing out. A time out of zero
seconds is legal and causes </P><TT class=code>system:serve-event</TT><P> to poll for
any events immediately available for processing.
</P><TT class=code>system:serve-event</TT><P> returns </P><TT class=code>t</TT><P> if it serviced at least
one event, and </P><TT class=code>nil</TT><P> otherwise. Depending on the application, when
</P><TT class=code>system:serve-event</TT><P> returns </P><TT class=code>t</TT><P>, you might want to call it
repeatedly with a timeout of zero until it returns </P><TT class=code>nil</TT><P>.</P><P>If input is available on any designated file descriptor, then this
calls the appropriate handler function supplied by
</P><TT class=code>system:add-fd-handler</TT><P>.</P><P>Since events for many different applications may arrive
simultaneously, an application waiting for a specific event must
loop on </P><TT class=code>system:serve-event</TT><P> until the desired event happens.
Since programs such as Hemlock call </P><TT class=code>system:serve-event</TT><P> for
input, applications usually do not need to call
</P><TT class=code>system:serve-event</TT><P> at all; Hemlock allows other
application&#X2019;s handlers to run when it goes into an input wait.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs189"></A><A NAME="FN:serve-all-events"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>system:</TT><TT class=function-name>serve-all-events</TT> <TT class=code>&amp;optional</TT> <TT class=variable>timeout</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function is similar to </P><TT class=code>system:serve-event</TT><P>, except it
serves all the pending events rather than just one. It returns
</P><TT class=code>t</TT><P> if it serviced at least one event, and </P><TT class=code>nil</TT><P> otherwise.
</P></BLOCKQUOTE><!--TOC section Using SERVE-EVENT with Unix File Descriptors-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc236">7.3</A>&#XA0;&#XA0;Using SERVE-EVENT with Unix File Descriptors</H2><!--SEC END --><P>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
</P><TT class=code>system:serve-event</TT><P> 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&#X2019;s single argument.</P><P><BR>
<A NAME="@funs190"></A><A NAME="FN:add-fd-handler"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>system:</TT><TT class=function-name>add-fd-handler</TT> <TT class=variable>fd</TT> <TT class=variable>direction</TT> <TT class=variable>function</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function installs and returns a new handler for the file
descriptor </P><TT class=variable>fd</TT><P>. </P><TT class=variable>direction</TT><P> can be either </P><TT class=code>:input</TT><P> if
the system should invoke the handler when input is available or
</P><TT class=code>:output</TT><P> 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 </P><TT class=code>system:remove-fd-handler</TT><TT class=variable>function</TT><P> must take one argument, the file descriptor.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs191"></A><A NAME="FN:remove-fd-handler"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>system:</TT><TT class=function-name>remove-fd-handler</TT> <TT class=variable>handler</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function removes </P><TT class=variable>handler</TT><P>, that </P><TT class=code>add-fd-handler</TT><P> must
have previously returned.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs192"></A><A NAME="FN:with-fd-handler"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>system:</TT><TT class=function-name>with-fd-handler</TT> (<TT class=variable>fd</TT> <TT class=variable>direction</TT> <TT class=variable>function</TT>)
<TT class=code>{<TT class=variable>form</TT>}</TT><SUP>*</SUP> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This macro executes the supplied forms with a handler installed
using </P><TT class=variable>fd</TT><P>, </P><TT class=variable>direction</TT><P>, and </P><TT class=variable>function</TT><P>. See
</P><TT class=code>system:add-fd-handler</TT><P>. The given forms are wrapped in an
</P><TT class=code>unwind-protect</TT><P>; the handler is removed (see
</P><TT class=code>system:remove-fd-handler</TT><P>) when done.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs193"></A><A NAME="FN:wait-until-fd-usable"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>system:</TT><TT class=function-name>wait-until-fd-usable</TT> <TT class=variable>fd</TT> <TT class=variable>direction</TT> <TT class=code>&amp;optional</TT> <TT class=variable>timeout</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function waits for up to </P><TT class=variable>timeout</TT><P> seconds for </P><TT class=variable>fd</TT><P> to
become usable for </P><TT class=variable>direction</TT><P> (either </P><TT class=code>:input</TT><P> or
</P><TT class=code>:output</TT><P>). If </P><TT class=variable>timeout</TT><P> is </P><TT class=code>nil</TT><P> or unspecified, this
waits forever.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs194"></A><A NAME="FN:invalidate-descriptor"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>system:</TT><TT class=function-name>invalidate-descriptor</TT> <TT class=variable>fd</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function removes all handlers associated with </P><TT class=variable>fd</TT><P>. This
should only be used in drastic cases (such as I/O errors, but not
necessarily EOF). Normally, you should use </P><TT class=code>remove-fd-handler</TT><P>
to remove the specific handler.
</P></BLOCKQUOTE><!--TOC section Using SERVE-EVENT with the CLX Interface to X-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc237">7.4</A>&#XA0;&#XA0;Using SERVE-EVENT with the CLX Interface to X</H2><!--SEC END --><P>
<A NAME="x-serve-mumbles"></A></P><P>Remember from section <A HREF="#object-sets">7.1</A>, 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.</P><P>The following is a discussion of functions exported from the </P><TT class=code>extensions</TT><P>
package that facilitate handling CLX events through </P><TT class=code>system:serve-event</TT><P>.
The first two routines are useful regardless of whether you use
</P><TT class=code>system:serve-event</TT><P>:
</P><P><BR>
<A NAME="@funs195"></A><A NAME="FN:open-clx-display"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>ext:</TT><TT class=function-name>open-clx-display</TT> <TT class=code>&amp;optional</TT> <TT class=variable>string</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function parses </P><TT class=variable>string</TT><P> for an X display specification
including display and screen numbers. </P><TT class=variable>String</TT><P> defaults to the
following:
</P><BLOCKQUOTE class=example><PRE>
    (cdr (assoc :display ext:*environment-list* :test #&#X2019;eq))
  </PRE></BLOCKQUOTE><P>
If any field in the display specification is missing, this signals
an error. </P><TT class=code>ext:open-clx-display</TT><P> returns the CLX display and
screen.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs196"></A><A NAME="FN:flush-display-events"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>ext:</TT><TT class=function-name>flush-display-events</TT> <TT class=variable>display</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function flushes all the events in </P><TT class=variable>display</TT><P>&#X2019;s event queue
including the current event, in case the user calls this from within
an event handler.
</P></BLOCKQUOTE><!--TOC subsection Without Object Sets-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc238">7.4.1</A>&#XA0;&#XA0;Without Object Sets</H3><!--SEC END --><P>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.</P><P><BR>
<A NAME="@funs197"></A><A NAME="FN:enable-clx-event-handling"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>ext:</TT><TT class=function-name>enable-clx-event-handling</TT> <TT class=variable>display</TT> <TT class=variable>handler</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"> <P>This function causes </P><TT class=code>system:serve-event</TT><P> to notice when there
is input on </P><TT class=variable>display</TT><P>&#X2019;s connection to the X11 server. When this
happens, </P><TT class=code>system:serve-event</TT><P> invokes </P><TT class=variable>handler</TT><P> on
</P><TT class=variable>display</TT><P> in a dynamic context with an error handler bound that
flushes all events from </P><TT class=variable>display</TT><P> 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
</P><TT class=code>system:serve-event</TT><P> for input. Calling this repeatedly on the
same </P><TT class=variable>display</TT><P> establishes </P><TT class=variable>handler</TT><P> as a new handler,
replacing any previous one for </P><TT class=variable>display</TT><P>.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs198"></A><A NAME="FN:disable-clx-event-handling"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>ext:</TT><TT class=function-name>disable-clx-event-handling</TT> <TT class=variable>display</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function undoes the effect of
</P><TT class=code>ext:enable-clx-event-handling</TT><P>.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs199"></A><A NAME="FN:with-clx-event-handling"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>ext:</TT><TT class=function-name>with-clx-event-handling</TT> (<TT class=variable>display</TT> <TT class=variable>handler</TT>) <TT class=code>{form}</TT><SUP>*</SUP> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This macro evaluates each </P><TT class=variable>form</TT><P> in a context where
</P><TT class=code>system:serve-event</TT><P> invokes </P><TT class=variable>handler</TT><P> on </P><TT class=variable>display</TT><P>
whenever there is input on </P><TT class=variable>display</TT><P>&#X2019;s connection to the X
server. This destroys any previously established handler for
</P><TT class=variable>display</TT><P>.
</P></BLOCKQUOTE><!--TOC subsection With Object Sets-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc239">7.4.2</A>&#XA0;&#XA0;With Object Sets</H3><!--SEC END --><P>This section discusses the use of object sets and
</P><TT class=code>system:serve-event</TT><P> 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.</P><P>For each CLX event-key symbol-name iXXX (for example,
</P><TT class=variable>key-press</TT><P>), there is a function </P><TT class=code>serve-</TT><P>iXXX of two
arguments, an object set and a function. The </P><TT class=code>serve-</TT><P>iXXX
function establishes the function as the handler for the </P><TT class=code>:XXX</TT><P>
event in the object set. Recall from section <A HREF="#object-sets">7.1</A>,
</P><TT class=code>system:add-xwindow-object</TT><P> associates some Lisp object with a
CLX window in an object set. When </P><TT class=code>system:serve-event</TT><P> notices
activity on a window, it calls the function given to
</P><TT class=code>ext:enable-clx-event-handling</TT><P>. If this function is
</P><TT class=code>ext:object-set-event-handler</TT><P>, it calls the function given to
</P><TT class=code>serve-</TT><P>iXXX, passing the object given to
</P><TT class=code>system:add-xwindow-object</TT><P> and the event&#X2019;s slots as well as a
couple other arguments described below.</P><P>To use object sets in this way:</P><UL CLASS="itemize"><LI CLASS="li-itemize"> 
Create an object set.</LI><LI CLASS="li-itemize">Define some operations on it using the <TT class=code>serve-</TT>iXXX
functions.</LI><LI CLASS="li-itemize">Add an object for every window on which you receive requests.
This can be the CLX window itself or some structure more meaningful
to your application.</LI><LI CLASS="li-itemize">Call <TT class=code>system:serve-event</TT> to service an X event.
</LI></UL><P><BR>
<A NAME="@funs200"></A><A NAME="FN:object-set-event-handler"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>ext:</TT><TT class=function-name>object-set-event-handler</TT> <TT class=variable>display</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function is a suitable argument to
</P><TT class=code>ext:enable-clx-event-handling</TT><P>. 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, </P><TT class=code>ext:object-set-event-handler</TT><P> passes the
following arguments:
</P><UL CLASS="itemize"><LI CLASS="li-itemize">
The object, as established by
<TT class=code>system:add-xwindow-object</TT>, on which the event occurred.
</LI><LI CLASS="li-itemize">event-key, see <TT class=code>xlib:event-case</TT>.
</LI><LI CLASS="li-itemize">send-event-p, see <TT class=code>xlib:event-case</TT>.
</LI></UL><P>Describing any </P><TT class=code>ext:serve-</TT><TT class=variable>event-key-name</TT><P> function, where
</P><TT class=variable>event-key-name</TT><P> is an event-key symbol-name (for example,
</P><TT class=code>ext:serve-key-press</TT><P>), indicates exactly what all the
arguments are in their correct order.</P><P>When creating an object set for use with
</P><TT class=code>ext:object-set-event-handler</TT><P>, specify
</P><TT class=code>ext:default-clx-event-handler</TT><P> 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.
</P></BLOCKQUOTE><!--TOC section A SERVE-EVENT Example-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc240">7.5</A>&#XA0;&#XA0;A SERVE-EVENT Example</H2><!--SEC END --><P>This section contains two examples using </P><TT class=code>system:serve-event</TT><P>. The first
one does not use object sets, and the second, slightly more complicated one
does.</P><!--TOC subsection Without Object Sets Example-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc241">7.5.1</A>&#XA0;&#XA0;Without Object Sets Example</H3><!--SEC END --><P>This example defines an input handler for a CLX display connection. It only
recognizes </P><TT class=code>:key-press</TT><P> events. The body of the example loops over
</P><TT class=code>system:serve-event</TT><P> to get input.</P><BLOCKQUOTE CLASS=lisp> <PRE>
(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&#X2019;s Manual for convenient
             ;; input mapping function.
             (ext:translate-character display code state))
      ;; Make XLIB:EVENT-CASE discard the event.
      t)))
</PRE></BLOCKQUOTE><BLOCKQUOTE CLASS=lisp> <PRE>
(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
                                :event-mask
                                (xlib:make-event-mask :key-press))))
    ;; 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 #&#X2019;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&#X2019;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 #&#X2019;(lambda (&amp;key event-window &amp;allow-other-keys)
                  (if (eq event-window win)
                      (setf result t)
                      nil)))
    result))
</PRE></BLOCKQUOTE><!--TOC subsection With Object Sets Example-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc242">7.5.2</A>&#XA0;&#XA0;With Object Sets Example</H3><!--SEC END --><P>This example involves more work, but you get a little more for your effort. It
defines two objects, </P><TT class=code>input-box</TT><P> and </P><TT class=code>slider</TT><P>, and establishes a
</P><TT class=code>:key-press</TT><P> handler for each object, </P><TT class=code>key-pressed</TT><P> and
</P><TT class=code>slider-pressed</TT><P>. 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.</P><BLOCKQUOTE CLASS=lisp> <PRE>
(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&#X2019;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 "#&lt;Input-Box ~S&gt;" (input-box-display object)))

(defvar *input-box-windows*
        (system:make-object-set "Input Box Windows"
                                #&#X2019;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&#X2019;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* #&#X2019;key-pressed)
</PRE></BLOCKQUOTE><BLOCKQUOTE CLASS=lisp> <PRE>
(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 "#&lt;Slider ~S  0..~D&gt;"
          (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"
                                #&#X2019;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  &#X2013;&gt;  ~D.~%"
          (xlib:window-id event-window)
          ;; See Hemlock Command Implementor&#X2019;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* #&#X2019;slider-pressed)
</PRE></BLOCKQUOTE><BLOCKQUOTE CLASS=lisp> <PRE>
(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
                                 :event-mask
                                 (xlib:make-event-mask :key-press)))
         (swindow (create-window :parent (screen-root screen)
                                 :x 0 :y 300 :width 200 :height 50
                                 :background white :border black
                                 :border-width 2
                                 :event-mask
                                 (xlib:make-event-mask :key-press)))
         (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
                                         #&#X2019;ext:object-set-event-handler)
          ;; Add the windows to the appropriate object sets.
          (system:add-xwindow-object iwindow input-box
                                       *input-box-windows*)
          (system:add-xwindow-object swindow slider
                                       *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))))
</PRE></BLOCKQUOTE><BLOCKQUOTE CLASS=lisp> <PRE>
(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&#X2019;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 #&#X2019;(lambda (&amp;key event-window &amp;allow-other-keys)
                  (if (eq event-window win)
                      (setf result t)
                      nil)))
    result))
</PRE></BLOCKQUOTE><!--NAME serve-event.html-->
<!--TOC chapter Alien Objects-->
<H1 CLASS="chapter"><!--SEC ANCHOR --><A NAME="htoc243">Chapter&#XA0;8</A>&#XA0;&#XA0;Alien Objects</H1><!--SEC END --><P>
<A NAME="aliens"></A></P><DIV CLASS="center">
<B>by Robert MacLachlan and William Lott</B>
</DIV><!--TOC section Introduction to Aliens-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc244">8.1</A>&#XA0;&#XA0;Introduction to Aliens</H2><!--SEC END --><P>Because of Lisp&#X2019;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:</P><UL CLASS="itemize"><LI CLASS="li-itemize">
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 &#X201C;glue&#X201D; code must be
written to perform the translation.</LI><LI CLASS="li-itemize">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.</LI><LI CLASS="li-itemize">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.
</LI></UL><P>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&#X2019;t automatically be
converted into Lisp values are represented by objects of type
</P><TT class=code>alien-value</TT><P>. 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
</P><TT class=code>alien-value</TT><P> object.</P><P>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.</P><!--TOC section Alien Types-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc245">8.2</A>&#XA0;&#XA0;Alien Types</H2><!--SEC END --><P>Alien types have a description language based on nested list structure. For
example:</P><BLOCKQUOTE class=example><PRE>
struct foo {
    int a;
    struct foo *b[100];
};
</PRE></BLOCKQUOTE><P>has the corresponding Alien type:</P><BLOCKQUOTE CLASS=lisp> <PRE>
(struct foo
  (a int)
  (b (array (* (struct foo)) 100)))
</PRE></BLOCKQUOTE><!--TOC subsection Defining Alien Types-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc246">8.2.1</A>&#XA0;&#XA0;Defining Alien Types</H3><!--SEC END --><P>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:</P><BLOCKQUOTE CLASS=lisp> <PRE>
(struct foo (a (* (struct foo))))
</PRE></BLOCKQUOTE><P>An anonymous structure or union type is specified by using the name
</P><TT class=code>nil</TT><P>. The <A NAME="@funs201"></A></P><TT class=code>with-alien</TT><P> macro defines a local scope which
&#X201C;captures&#X201D; any named type definitions. Other types are not
inherently named, but can be given named abbreviations using
</P><TT class=code>def-alien-type</TT><P>.</P><P><BR>
<A NAME="@funs202"></A><A NAME="FN:def-alien-type"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>alien:</TT><TT class=function-name>def-alien-type</TT> name type &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"> 
This macro globally defines <TT class=variable>name</TT> as a shorthand for the Alien
type <TT class=variable>type</TT>. When introducing global structure and union type
definitions, <TT class=variable>name</TT> may be <TT class=code>nil</TT>, in which case the name to
define is taken from the type&#X2019;s name.
</BLOCKQUOTE><!--TOC subsection Alien Types and Lisp Types-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc247">8.2.2</A>&#XA0;&#XA0;Alien Types and Lisp Types</H3><!--SEC END --><P>The Alien types form a subsystem of the CMUCL type system. An
</P><TT class=code>alien</TT><P> type specifier provides a way to use any Alien type as a
Lisp type specifier. For example</P><BLOCKQUOTE CLASS=lisp> <PRE>
(typep foo &#X2019;(alien (* int)))
</PRE></BLOCKQUOTE><P>can be used to determine whether </P><TT class=code>foo</TT><P> is a pointer to an
</P><TT class=code>int</TT><P>. </P><TT class=code>alien</TT><P> type specifiers can be used in the same ways
as ordinary type specifiers (like </P><TT class=code>string</TT><P>.) Alien type
declarations are subject to the same precise type checking as any
other declaration (see section&#XA0;<A HREF="#precise-type-checks">4.5.2</A>.)</P><P>Note that the Alien type system overlaps with normal Lisp type
specifiers in some cases. For example, the type specifier
</P><TT class=code>(alien single-float)</TT><P> is identical to </P><TT class=code>single-float</TT><P>, since
Alien floats are automatically converted to Lisp floats. When
</P><TT class=code>type-of</TT><P> is called on an Alien value that is not automatically
converted to a Lisp value, then it will return an </P><TT class=code>alien</TT><P> type
specifier.</P><!--TOC subsection Alien Type Specifiers-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc248">8.2.3</A>&#XA0;&#XA0;Alien Type Specifiers</H3><!--SEC END --><P>Some Alien type names are Common Lisp symbols, but the names are
still exported from the </P><TT class=code>alien</TT><P> package, so it is legal to say
</P><TT class=code>alien:single-float</TT><P>. These are the basic Alien type specifiers: </P><P><BR>
<BR>
<A NAME="@types31"></A></P><DIV align=left>
[Alien type]<BR>
 <TT class=function-name>*</TT> <TT class=variable><TT class=variable>type</TT></TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>A pointer to an object of the specified </P><TT class=variable>type</TT><P>. If </P><TT class=variable>type</TT><P>
is </P><TT class=code>t</TT><P>, then it means a pointer to anything, similar to
&#X201C;</P><TT class=code>void *</TT><P>&#X201D; in ANSI C. Currently, the only way to detect a
null pointer is:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
  (zerop (sap-int (alien-sap <TT class=variable>ptr</TT>)))
</PRE></BLOCKQUOTE><P>
See section&#XA0;<A HREF="#system-area-pointers">6.5</A>
</P></BLOCKQUOTE><P><BR>
<BR>
<A NAME="@types32"></A></P><DIV align=left>
[Alien type]<BR>
 <TT class=function-name>array</TT> <TT class=variable><TT class=variable>type</TT> <TT class=code>{<TT class=variable>dimension</TT>}</TT><SUP>*</SUP></TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"> <P>An array of the specified </P><TT class=variable>dimensions</TT><P>, holding elements of type
</P><TT class=variable>type</TT><P>. Note that </P><TT class=code>(* int)</TT><P> and </P><TT class=code>(array int)</TT><P> are
considered to be different types when type checking is done; pointer
and array types must be explicitly coerced using </P><TT class=code>cast</TT><P>.</P><P>Arrays are accessed using </P><TT class=code>deref</TT><P>, 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 </P><TT class=code>nil</TT><P> as the
first dimension. Fixed-size arrays can be allocated as array
elements, structure slots or </P><TT class=code>with-alien</TT><P> variables. Dynamic
arrays can only be allocated using <A NAME="@funs203"></A></P><TT class=code>make-alien</TT><P>.
</P></BLOCKQUOTE><P><BR>
<BR>
<A NAME="@types33"></A></P><DIV align=left>
[Alien type]<BR>
 <TT class=function-name>struct</TT> <TT class=variable><TT class=variable>name</TT> 
<TT class=code>{(<TT class=variable>field</TT> <TT class=variable>type</TT> <TT class=code>{<TT class=variable>bits</TT>}</TT>)}</TT><SUP>*</SUP></TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>A structure type with the specified </P><TT class=variable>name</TT><P> and </P><TT class=variable>fields</TT><P>.
Fields are allocated at the same positions used by the
implementation&#X2019;s C compiler. </P><TT class=variable>bits</TT><P> is intended for C-like bit
field support, but is currently unused. If </P><TT class=variable>name</TT><P> is </P><TT class=code>nil</TT><P>,
then the type is anonymous.</P><P>If a named Alien </P><TT class=code>struct</TT><P> specifier is passed to
<A NAME="@funs204"></A></P><TT class=code>def-alien-type</TT><P> or <A NAME="@funs205"></A></P><TT class=code>with-alien</TT><P>, then this defines,
respectively, a new global or local Alien structure type. If no
</P><TT class=variable>fields</TT><P> are specified, then the fields are taken from the
current (local or global) Alien structure type definition of
</P><TT class=variable>name</TT><P>.
</P></BLOCKQUOTE><P><BR>
<BR>
<A NAME="@types34"></A></P><DIV align=left>
[Alien type]<BR>
 <TT class=function-name>union</TT> <TT class=variable><TT class=variable>name</TT> 
<TT class=code>{(<TT class=variable>field</TT> <TT class=variable>type</TT> <TT class=code>{<TT class=variable>bits</TT>}</TT>)}</TT><SUP>*</SUP></TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>Similar to </P><TT class=code>struct</TT><P>, 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.
</P></BLOCKQUOTE><P><BR>
<BR>
<A NAME="@types35"></A></P><DIV align=left>
[Alien type]<BR>
 <TT class=function-name>enum</TT> <TT class=variable><TT class=variable>name</TT> <TT class=code>{<TT class=variable>spec</TT>}</TT><SUP>*</SUP></TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>An enumeration type that maps between integer values and keywords.
If </P><TT class=variable>name</TT><P> is </P><TT class=code>nil</TT><P>, then the type is anonymous. Each
</P><TT class=variable>spec</TT><P> is either a keyword, or a list </P><TT class=code>(<TT class=variable>keyword</TT>
<TT class=variable>value</TT>)</TT><P>. If </P><TT class=variable>integer</TT><P> 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.)
</P></BLOCKQUOTE><P><BR>
<BR>
<A NAME="@types36"></A></P><DIV align=left>
[Alien type]<BR>
 <TT class=function-name>signed</TT> <TT class=variable><TT class=code>{<TT class=variable>bits</TT>}</TT></TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"> 
A signed integer with the specified number of bits precision. The
upper limit on integer precision is determined by the machine&#X2019;s word
size. If no size is specified, the maximum size will be used.
</BLOCKQUOTE><P><BR>
<BR>
<A NAME="@types37"></A></P><DIV align=left>
[Alien type]<BR>
 <TT class=function-name>integer</TT> <TT class=variable><TT class=code>{<TT class=variable>bits</TT>}</TT></TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"> 
Identical to <TT class=code>signed</TT>&#X2014;the distinction between <TT class=code>signed</TT>
and <TT class=code>integer</TT> is purely stylistic.
</BLOCKQUOTE><P><BR>
<BR>
<A NAME="@types38"></A></P><DIV align=left>
[Alien type]<BR>
 <TT class=function-name>unsigned</TT> <TT class=variable><TT class=code>{<TT class=variable>bits</TT>}</TT></TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Like <TT class=code>signed</TT>, but specifies an unsigned integer.
</BLOCKQUOTE><P><BR>
<BR>
<A NAME="@types39"></A></P><DIV align=left>
[Alien type]<BR>
 <TT class=function-name>boolean</TT> <TT class=variable><TT class=code>{<TT class=variable>bits</TT>}</TT></TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Similar to an enumeration type that maps <TT class=code>0</TT> to <TT class=code>nil</TT> and
all other values to <TT class=code>t</TT>. <TT class=variable>bits</TT> determines the amount of
storage allocated to hold the truth value.
</BLOCKQUOTE><P><BR>
<BR>
<A NAME="@types40"></A></P><DIV align=left>
[Alien type]<BR>
 <TT class=function-name>single-float</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
A floating-point number in IEEE single format.
</BLOCKQUOTE><P><BR>
<BR>
<A NAME="@types41"></A></P><DIV align=left>
[Alien type]<BR>
 <TT class=function-name>double-float</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
A floating-point number in IEEE double format.
</BLOCKQUOTE><P><BR>
<BR>
<A NAME="@types42"></A></P><DIV align=left>
[Alien type]<BR>
 <TT class=function-name>function</TT> <TT class=variable><TT class=variable>result-type</TT> <TT class=code>{<TT class=variable>arg-type</TT>}</TT><SUP>*</SUP></TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
<A NAME="alien-function-types"></A>
A Alien function that takes arguments of the specified
<TT class=variable>arg-types</TT> and returns a result of type <TT class=variable>result-type</TT>.
Note that the only context where a <TT class=code>function</TT> type is directly
specified is in the argument to <TT class=code>alien-funcall</TT> (see section
<A NAME="@funs206"></A><TT class=code>alien-funcall</TT>.) In all other contexts, functions are
represented by function pointer types: <TT class=code>(* (function ...))</TT>.
</BLOCKQUOTE><P><BR>
<BR>
<A NAME="@types43"></A></P><DIV align=left>
[Alien type]<BR>
 <TT class=function-name>system-area-pointer</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
A pointer which is represented in Lisp as a
<TT class=code>system-area-pointer</TT> object (see section&#XA0;<A HREF="#system-area-pointers">6.5</A>.)
</BLOCKQUOTE><!--TOC subsection The C-Call Package-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc249">8.2.4</A>&#XA0;&#XA0;The C-Call Package</H3><!--SEC END --><P>The </P><TT class=code>c-call</TT><P> package exports these type-equivalents to the C type
of the same name: </P><TT class=code>char</TT><P>, </P><TT class=code>short</TT><P>, </P><TT class=code>int</TT><P>, </P><TT class=code>long</TT><P>,
</P><TT class=code>unsigned-char</TT><P>, </P><TT class=code>unsigned-short</TT><P>, </P><TT class=code>unsigned-int</TT><P>,
</P><TT class=code>unsigned-long</TT><P>, </P><TT class=code>float</TT><P>, </P><TT class=code>double</TT><P>. </P><TT class=code>c-call</TT><P> also
exports these types:</P><P><BR>
<BR>
<A NAME="@types44"></A></P><DIV align=left>
[Alien type]<BR>
 <TT class=function-name>void</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
This type is used in function types to declare that no useful value
is returned. Evaluation of an <TT class=code>alien-funcall</TT> form will return
zero values.
</BLOCKQUOTE><P><BR>
<BR>
<A NAME="@types45"></A></P><DIV align=left>
[Alien type]<BR>
 <TT class=function-name>c-string</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
This type is similar to <TT class=code>(* char)</TT>, but is interpreted as a
null-terminated string, and is automatically converted into a Lisp
string when accessed. If the pointer is C <TT class=code>NULL</TT> (or 0), then
accessing gives Lisp <TT class=code>nil</TT>.<P>With Unicode, a Lisp string is not the same as a C string since a
Lisp string uses two bytes for each character. In this case, a
C string is converted to a Lisp string by taking each byte of the
C-string and applying </P><TT class=code>code-char</TT><P> to create each character of
the Lisp string.</P><P>Similarly, a Lisp string is converted to a C string by taking the
low 8 bits of the </P><TT class=code>char-code</TT><P> of each character and assigning
that to each byte of the C string.</P><P>In either case, </P><TT class=code>string-encode</TT><P> and </P><TT class=code>string-decode</TT><P> may be
useful to convert Unicode Lisp strings to or from C strings.</P><P>Assigning a Lisp string to a </P><TT class=code>c-string</TT><P> structure field or
variable stores the contents of the string to the memory already
pointed to by that variable. When an Alien of type </P><TT class=code>(* char)</TT><P>
is assigned to a </P><TT class=code>c-string</TT><P>, then the </P><TT class=code>c-string</TT><P> pointer
is assigned to. This allows </P><TT class=code>c-string</TT><P> pointers to be
initialized. For example:</P><BLOCKQUOTE CLASS=lisp> <PRE>
  (def-alien-type nil (struct foo (str c-string)))
  
  (defun make-foo (str)
    (let ((my-foo (make-alien (struct foo))))
      (setf (slot my-foo &#X2019;str) (make-alien char (length str)))
      (setf (slot my-foo &#X2019;str) str)
      my-foo))
</PRE></BLOCKQUOTE><P>Storing Lisp </P><TT class=code>nil</TT><P> writes C </P><TT class=code>NULL</TT><P> to the </P><TT class=code>c-string</TT><P>
pointer.
</P></BLOCKQUOTE><!--TOC section Alien Operations-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc250">8.3</A>&#XA0;&#XA0;Alien Operations</H2><!--SEC END --><P>This section describes the basic operations on Alien values.</P><!--TOC subsection Alien Access Operations-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc251">8.3.1</A>&#XA0;&#XA0;Alien Access Operations</H3><!--SEC END --><P><BR>
<A NAME="@funs207"></A><A NAME="FN:deref"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>alien:</TT><TT class=function-name>deref</TT> <TT class=variable>pointer-or-array</TT> <TT class=code>&amp;rest</TT><TT class=variable>indices</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>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. </P><TT class=code>deref</TT><P> can be set with
</P><TT class=code>setf</TT><P> to assign a new value.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs208"></A><A NAME="FN:slot"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>alien:</TT><TT class=function-name>slot</TT> <TT class=variable>struct-or-union</TT> <TT class=variable>slot-name</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function extracts the value of slot </P><TT class=variable>slot-name</TT><P> from the an
Alien </P><TT class=code>struct</TT><P> or </P><TT class=code>union</TT><P>. If </P><TT class=variable>struct-or-union</TT><P> is a
pointer to a structure or union, then it is automatically
dereferenced. This can be set with </P><TT class=code>setf</TT><P> to assign a new
value. Note that </P><TT class=variable>slot-name</TT><P> is evaluated, and need not be a
compile-time constant (but only constant slot accesses are
efficiently compiled.)
</P></BLOCKQUOTE><!--TOC subsection Alien Coercion Operations-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc252">8.3.2</A>&#XA0;&#XA0;Alien Coercion Operations</H3><!--SEC END --><P><BR>
<A NAME="@funs209"></A><A NAME="FN:addr"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>alien:</TT><TT class=function-name>addr</TT> <TT class=variable>alien-expr</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This macro returns a pointer to the location specified by
</P><TT class=variable>alien-expr</TT><P>, which must be either an Alien variable, a use of
</P><TT class=code>deref</TT><P>, a use of </P><TT class=code>slot</TT><P>, or a use of
<A NAME="@funs210"></A></P><TT class=code>extern-alien</TT><P>.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs211"></A><A NAME="FN:cast"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>alien:</TT><TT class=function-name>cast</TT> <TT class=variable>alien</TT> <TT class=variable>new-type</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This macro converts </P><TT class=variable>alien</TT><P> to a new Alien with the specified
</P><TT class=variable>new-type</TT><P>. Both types must be an Alien pointer, array or
function type. Note that the result is not </P><TT class=code>eq</TT><P> to the
argument, but does refer to the same data bits.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs212"></A><A NAME="FN:sap-alien"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>alien:</TT><TT class=function-name>sap-alien</TT> <TT class=variable>sap</TT> <TT class=variable>type</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
<P><A NAME="@funs213"></A><A NAME="FN:alien-sap"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>alien:</TT><TT class=function-name>alien-sap</TT> <TT class=variable>alien-value</TT> &nbsp;&nbsp;&nbsp;
</DIV><TT class=code>sap-alien</TT><P> converts </P><TT class=variable>sap</TT><P> (a system area pointer
see section&#XA0;<A HREF="#system-area-pointers">6.5</A>) to an Alien value with the specified
</P><TT class=variable>type</TT><P>. </P><TT class=variable>type</TT><P> is not evaluated.</P><TT class=code>alien-sap</TT><P> returns the SAP which points to </P><TT class=variable>alien-value</TT><P>&#X2019;s
data.</P><P>The </P><TT class=variable>type</TT><P> to </P><TT class=code>sap-alien</TT><P> and the type of the </P><TT class=variable>alien-value</TT><P> to
</P><TT class=code>alien-sap</TT><P> must some Alien pointer, array or record type.
</P></BLOCKQUOTE><!--TOC subsection Alien Dynamic Allocation-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc253">8.3.3</A>&#XA0;&#XA0;Alien Dynamic Allocation</H3><!--SEC END --><P>Dynamic Aliens are allocated using the </P><TT class=code>malloc</TT><P> library, so foreign code
can call </P><TT class=code>free</TT><P> on the result of </P><TT class=code>make-alien</TT><P>, and Lisp code can
call </P><TT class=code>free-alien</TT><P> on objects allocated by foreign code.</P><P><BR>
<A NAME="@funs214"></A><A NAME="FN:make-alien"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>alien:</TT><TT class=function-name>make-alien</TT> <TT class=variable>type</TT> <TT class=code>{<TT class=variable>size</TT>}</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This macro returns a dynamically allocated Alien of the specified
</P><TT class=variable>type</TT><P> (which is not evaluated.) The allocated memory is not
initialized, and may contain arbitrary junk. If supplied,
</P><TT class=variable>size</TT><P> is an expression to evaluate to compute the size of the
allocated object. There are two major cases:
</P><UL CLASS="itemize"><LI CLASS="li-itemize">
When <TT class=variable>type</TT> is an array type, an array of that type is
allocated and a <TT class=variable>pointer</TT> to it is returned. Note that you
must use <TT class=code>deref</TT> to change the result to an array before you
can use <TT class=code>deref</TT> to read or write elements:<BLOCKQUOTE CLASS=lisp> <PRE>
(defvar *foo* (make-alien (array char 10)))

(type-of *foo*) ==&gt; (alien (* (array (signed 8) 10)))

(setf (deref (deref foo) 0) 10) ==&gt; 10
</PRE></BLOCKQUOTE><P>If supplied, </P><TT class=variable>size</TT><P> is used as the first dimension for the
array.</P></LI><LI CLASS="li-itemize">When <TT class=variable>type</TT> is any other type, then then an object for
that type is allocated, and a <TT class=variable>pointer</TT> to it is returned. So
<TT class=code>(make-alien int)</TT> returns a <TT class=code>(* int)</TT>. If <TT class=variable>size</TT>
is specified, then a block of that many objects is allocated, with
the result pointing to the first one.
</LI></UL></BLOCKQUOTE><P><BR>
<A NAME="@funs215"></A><A NAME="FN:free-alien"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>alien:</TT><TT class=function-name>free-alien</TT> <TT class=variable>alien</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function frees the storage for </P><TT class=variable>alien</TT><P> (which must have
been allocated with </P><TT class=code>make-alien</TT><P> or </P><TT class=code>malloc</TT><P>.)
</P></BLOCKQUOTE><P>See also <A NAME="@funs216"></A></P><TT class=code>with-alien</TT><P>, which stack-allocates Aliens.</P><!--TOC section Alien Variables-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc254">8.4</A>&#XA0;&#XA0;Alien Variables</H2><!--SEC END --><P>Both local (stack allocated) and external (C global) Alien variables are
supported.</P><!--TOC subsection Local Alien Variables-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc255">8.4.1</A>&#XA0;&#XA0;Local Alien Variables</H3><!--SEC END --><P><BR>
<A NAME="@funs217"></A><A NAME="FN:with-alien"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>alien:</TT><TT class=function-name>with-alien</TT> <TT class=code>{(<TT class=variable>name</TT> <TT class=variable>type</TT> 
<TT class=code>{<TT class=variable>initial-value</TT>}</TT>)}</TT><SUP>*</SUP> <TT class=code>{form}</TT><SUP>*</SUP> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This macro establishes local alien variables with the specified
Alien types and names for dynamic extent of the body. The variable
</P><TT class=variable>names</TT><P> are established as symbol-macros; the bindings have
lexical scope, and may be assigned with </P><TT class=code>setq</TT><P> or </P><TT class=code>setf</TT><P>.
This form is analogous to defining a local variable in C: additional
storage is allocated, and the initial value is copied.</P><TT class=code>with-alien</TT><P> also establishes a new scope for named structures
and unions. Any </P><TT class=variable>type</TT><P> 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 </P><TT class=variable>foo</TT><P> can be referenced by its name using:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
  (struct foo)
</PRE></BLOCKQUOTE></BLOCKQUOTE><!--TOC subsection External Alien Variables-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc256">8.4.2</A>&#XA0;&#XA0;External Alien Variables</H3><!--SEC END --><P> 
<A NAME="external-aliens"></A></P><P>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
</P><TT class=code>extern-alien</TT><P>, </P><TT class=code>def-alien-variable</TT><P> and
<A NAME="@funs218"></A></P><TT class=code>def-alien-routine</TT><P> use this conversion heuristic:
</P><UL CLASS="itemize"><LI CLASS="li-itemize">
Alien names are converted to Lisp names by uppercasing and
replacing underscores with hyphens.</LI><LI CLASS="li-itemize">Conversely, Lisp names are converted to Alien names by
lowercasing and replacing hyphens with underscores.</LI><LI CLASS="li-itemize">Both the Lisp symbol and Alien string names may be separately
specified by using a list of the form:
<BLOCKQUOTE CLASS=lisp> <PRE>
  (<TT class=variable>alien-string</TT> <TT class=variable>lisp-symbol</TT>)
</PRE></BLOCKQUOTE>
</LI></UL><P><BR>
<A NAME="@funs219"></A><A NAME="FN:def-alien-variable"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>alien:</TT><TT class=function-name>def-alien-variable</TT> <TT class=variable>name</TT> <TT class=variable>type</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This macro defines </P><TT class=variable>name</TT><P> as an external Alien variable of the
specified Alien </P><TT class=variable>type</TT><P>. </P><TT class=variable>name</TT><P> and </P><TT class=variable>type</TT><P> 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 &#X201C;global symbol macros&#X201D;; a reference to the
variable fetches the contents of the external variable. Similarly,
setting the variable stores new contents&#X2014;the new contents must be
of the declared </P><TT class=variable>type</TT><P>.</P><P>For example, it is often necessary to read the global C variable
</P><TT class=code>errno</TT><P> to determine why a particular function call failed. It
is possible to define errno and make it accessible from Lisp by the
following:
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(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)
</PRE></BLOCKQUOTE></BLOCKQUOTE><P><BR>
<A NAME="@funs220"></A><A NAME="FN:extern-alien"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>alien:</TT><TT class=function-name>extern-alien</TT> <TT class=variable>name</TT> <TT class=variable>type</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This macro returns an Alien with the specified </P><TT class=variable>type</TT><P> which
points to an externally defined value. </P><TT class=variable>name</TT><P> is not evaluated,
and may be specified either as a string or a symbol. </P><TT class=variable>type</TT><P> is
an unevaluated Alien type specifier.
</P></BLOCKQUOTE><!--TOC section Alien Data Structure Example-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc257">8.5</A>&#XA0;&#XA0;Alien Data Structure Example</H2><!--SEC END --><P>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:</P><BLOCKQUOTE CLASS=lisp> <PRE>
struct foo {
    int a;
    struct foo *b[100];
};

 &lt;==&gt;

(def-alien-type nil
  (struct foo
    (a int)
    (b (array (* (struct foo)) 100))))
</PRE></BLOCKQUOTE><P>With this definition, the following C expression can be translated in this way:</P><BLOCKQUOTE class=example><PRE>
struct foo f;
f.b[7].a

 &lt;==&gt;

(with-alien ((f (struct foo)))
  (slot (deref (slot f &#X2019;b) 7) &#X2019;a)
  ;;
  ;; Do something with f...
  )
</PRE></BLOCKQUOTE><P>Or consider this example of an external C variable and some accesses:</P><BLOCKQUOTE class=example><PRE>
struct c_struct {
        short x, y;
        char a, b;
        int z;
        c_struct *n;
};

extern struct c_struct *my_struct;

my_struct-&gt;x++;
my_struct-&gt;a = 5;
my_struct = my_struct-&gt;n;
</PRE></BLOCKQUOTE><P>which can be made be manipulated in Lisp like this:</P><BLOCKQUOTE CLASS=lisp> <PRE>
(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 &#X2019;x))
(setf (slot my-struct &#X2019;a) 5)
(setq my-struct (slot my-struct &#X2019;n))
</PRE></BLOCKQUOTE><!--TOC section Loading Unix Object Files-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc258">8.6</A>&#XA0;&#XA0;Loading Unix Object Files</H2><!--SEC END --><P>CMUCL is able to load foreign object files at runtime, using the
function </P><TT class=code>load-foreign</TT><P>. This function is able to load shared
libraries (that are typically named <CODE>.so</CODE>) via the dlopen
mechanism. It can also load <CODE>.a</CODE> or <CODE>.o</CODE> object files by
calling the linker on the files and libraries to create a loadable
object file. Once loaded, the external symbols that define routines
and variables are made available for future external references (e.g.
by </P><TT class=code>extern-alien</TT><P>.) </P><TT class=code>load-foreign</TT><P> must be run before any of
the defined symbols are referenced.</P><P>Note that if a Lisp core image is saved (using <A NAME="@funs221"></A></P><TT class=code>save-lisp</TT><P>), all
loaded foreign code is lost when the image is restarted. </P><P><BR>
<A NAME="@funs222"></A><A NAME="FN:load-foreign"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>ext:</TT><TT class=function-name>load-foreign</TT> <TT class=variable>files</TT> <TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=code>:libraries</TT> <TT class=code>:base-file</TT> <TT class=code>:env</TT></SPAN> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><TT class=variable>files</TT><P> is a </P><TT class=code>simple-string</TT><P> or list of
</P><TT class=code>simple-string</TT><P>s specifying the names of the object files. If
</P><TT class=variable>files</TT><P> is a simple-string, the file that it designates is
loaded using the platform&#X2019;s dlopen mechanism. If it is a list of
strings, the platform linker </P><TT class=code>ld</TT><P> is invoked to transform the
object files into a loadable object file. </P><TT class=variable>libraries</TT><P> is a list
of </P><TT class=code>simple-string</TT><P>s specifying libraries in a format that the
platform linker expects. The default value for </P><TT class=variable>libraries</TT><P> is
</P><TT class=code>("-lc")</TT><P> (i.e., the standard C library). </P><TT class=variable>base-file</TT><P> is
the file to use for the initial symbol table information. The
default is the Lisp start up code: </P><TT class=filename>path:lisp</TT><P>. </P><TT class=variable>env</TT><P>
should be a list of simple strings in the format of Unix environment
variables (i.e., </P><TT class=code><TT class=variable>A</TT>=<TT class=variable>B</TT></TT><P>, where </P><TT class=variable>A</TT><P> is an
environment variable and </P><TT class=variable>B</TT><P> is its value). The default value
for </P><TT class=variable>env</TT><P> 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.
</P></BLOCKQUOTE><!--TOC section Alien Function Calls-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc259">8.7</A>&#XA0;&#XA0;Alien Function Calls</H2><!--SEC END --><P>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.</P><P>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.</P><!--TOC subsection The alien-funcall Primitive-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc260">8.7.1</A>&#XA0;&#XA0;The alien-funcall Primitive</H3><!--SEC END --><P><BR>
<A NAME="@funs223"></A><A NAME="FN:alien-funcall"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>alien:</TT><TT class=function-name>alien-funcall</TT> <TT class=variable>alien-function</TT> <TT class=code>&amp;rest</TT> <TT class=variable>arguments</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function is the foreign function call primitive:
</P><TT class=variable>alien-function</TT><P> is called with the supplied </P><TT class=variable>arguments</TT><P> and
its value is returned. The </P><TT class=variable>alien-function</TT><P> is an arbitrary
run-time expression; to call a constant function, use
<A NAME="@funs224"></A></P><TT class=code>extern-alien</TT><P> or </P><TT class=code>def-alien-routine</TT><P>.</P><P>The type of </P><TT class=variable>alien-function</TT><P> must be </P><TT class=code>(alien (function
...))</TT><P> or </P><TT class=code>(alien (* (function ...)))</TT><P>,
See section&#XA0;<A HREF="#alien-function-types">8.2.3</A>. 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:
</P><UL CLASS="itemize"><LI CLASS="li-itemize">
Structure type return values are not implemented.
</LI><LI CLASS="li-itemize">Passing of structures by value is not implemented.
</LI></UL></BLOCKQUOTE><P>Here is an example which allocates a </P><TT class=code>(struct foo)</TT><P>, calls a foreign
function to initialize it, then returns a Lisp vector of all the
</P><TT class=code>(* (struct foo))</TT><P> objects filled in by the foreign call:</P><BLOCKQUOTE CLASS=lisp> <PRE>
;; 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)))
                 (addr f))
  ;;
  ;; Find how many foos to use by getting the A field.
  (let* ((num (slot f &#X2019;a))
         (result (make-array num)))
    ;;
    ;; Get a pointer to the array so that we don&#X2019;t have to keep
    ;; extracting it:
    (with-alien ((a (* (array (* (struct foo)) 100)) (addr (slot f &#X2019;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)))
</PRE></BLOCKQUOTE><!--TOC subsection The def-alien-routine Macro-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc261">8.7.2</A>&#XA0;&#XA0;The def-alien-routine Macro</H3><!--SEC END --><P><BR>
<A NAME="@funs225"></A><A NAME="FN:def-alien-routine"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>alien:</TT><TT class=function-name>def-alien-routine</TT> <TT class=variable>name</TT> <TT class=variable>result-type</TT>
<TT class=code>{(<TT class=variable>aname</TT> <TT class=variable>atype</TT> <TT class=code>{style}</TT>)}</TT><SUP>*</SUP> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>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.</P><TT class=variable>name</TT><P> 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,
(see section&#XA0;<A HREF="#external-aliens">8.4.2</A>.)</P><TT class=variable>result-type</TT><P> is the Alien type of the return value. Each
remaining subform specifies an argument to the foreign function.
</P><TT class=variable>aname</TT><P> is the symbol name of the argument to the constructed
function (for documentation) and </P><TT class=variable>atype</TT><P> is the Alien type of
corresponding foreign argument. The semantics of the actual call
are the same as for <A NAME="@funs226"></A></P><TT class=code>alien-funcall</TT><P>. </P><TT class=variable>style</TT><P> should be
one of the following:

</P><DL CLASS="list"><DT CLASS="dt-list">

<TT class=code>:in</TT><BR>
</DT><DD CLASS="dd-list"> specifies that the argument is passed by value.
This is the default. <TT class=code>:in</TT> arguments have no corresponding
return value from the Lisp function.</DD><DT CLASS="dt-list"><TT class=code>:out</TT><BR>
</DT><DD CLASS="dd-list"> 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). <TT class=code>:out</TT> and <TT class=code>:in-out</TT>
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.</DD><DT CLASS="dt-list"><TT class=code>:copy</TT><BR>
</DT><DD CLASS="dd-list"> is similar to <TT class=code>:in</TT>, but the argument is copied
to a pre-allocated object and a pointer to this object is passed
to the foreign routine.</DD><DT CLASS="dt-list"><TT class=code>:in-out</TT><BR>
</DT><DD CLASS="dd-list"> is a combination of <TT class=code>:copy</TT> and <TT class=code>:out</TT>.
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.
</DD></DL><P>
Any efficiency-critical foreign interface function should be inline
expanded by preceding </P><TT class=code>def-alien-routine</TT><P> with:</P><BLOCKQUOTE CLASS=lisp> <PRE>
(declaim (inline <TT class=variable>lisp-name</TT>))
</PRE></BLOCKQUOTE><P>In addition to avoiding the Lisp call overhead, this allows
pointers, word-integers and floats to be passed using non-descriptor
representations, avoiding consing (see section&#XA0;<A HREF="#non-descriptor">5.11.2</A>.)
</P></BLOCKQUOTE><!--TOC subsection def-alien-routine Example-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc262">8.7.3</A>&#XA0;&#XA0;def-alien-routine Example</H3><!--SEC END --><P>Consider the C function </P><TT class=code>cfoo</TT><P> with the following calling convention:</P><BLOCKQUOTE class=example><PRE>
/* a for update
 * i out
 */
void cfoo (char *str, char *a, int *i);
</PRE></BLOCKQUOTE><P>which can be described by the following call to </P><TT class=code>def-alien-routine</TT><P>:</P><BLOCKQUOTE CLASS=lisp> <PRE>
(def-alien-routine "cfoo" void
  (str c-string)
  (a char :in-out)
  (i int :out))
</PRE></BLOCKQUOTE><P>The Lisp function </P><TT class=code>cfoo</TT><P> will have two arguments (</P><TT class=variable>str</TT><P> and </P><TT class=variable>a</TT><P>)
and two return values (</P><TT class=variable>a</TT><P> and </P><TT class=variable>i</TT><P>).</P><!--TOC subsection Calling Lisp from C-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc263">8.7.4</A>&#XA0;&#XA0;Calling Lisp from C</H3><!--SEC END --><P>CMUCL supports calling Lisp from C via the <A NAME="@funs227"></A></P><TT class=code>def-callback</TT><P>
macro:</P><P><BR>
<A NAME="@funs228"></A><A NAME="FN:def-callback"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>alien:</TT><TT class=function-name>def-callback</TT> <TT class=variable>name</TT> (<TT class=variable>return-type</TT>
<TT class=code>{(arg-name arg-type)}</TT><SUP>*</SUP>) <TT class=code>&amp;body</TT> body &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
This macro defines a Lisp function that can be called from C and a
Lisp variable. The arguments to the function must be alien types,
and the return type must also be an alien type. This Lisp function
can be accessed via the <A NAME="@funs229"></A><TT class=code>callback</TT> macro.<TT class=variable>name</TT><P> is the name of the Lisp function. It is also the name of
a variable to be used by the </P><TT class=code>callback</TT><P> macro.</P><TT class=variable>return-type</TT><P> is the return type of the function. This must be
a recognized alien type.</P><TT class=variable>arg-name</TT><P> specifies the name of the argument to the function,
and the argument has type </P><TT class=variable>arg-type</TT><P>, which must be an alien type.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs230"></A><A NAME="FN:callback"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>alien:</TT><TT class=function-name>callback</TT> <TT class=variable>callback-symbol</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
This macro extracts the appropriate information for the function
named <TT class=variable>callback-symbol</TT> so that it can be called by a C
function. <TT class=variable>callback-symbol</TT> must be a symbol created by the
<TT class=code>def-callback</TT> macro.
</BLOCKQUOTE><P><BR>
<A NAME="@funs231"></A><A NAME="FN:callback-funcall"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>alien:</TT><TT class=function-name>callback-funcall</TT> <TT class=variable>callback-name</TT> <TT class=code>&amp;rest</TT><TT class=variable>args</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
This macro does the necessary stuff to call the callback named
<TT class=variable>callback-name</TT> with the given arguments.
</BLOCKQUOTE><!--TOC subsection Callback Example-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc264">8.7.5</A>&#XA0;&#XA0;Callback Example</H3><!--SEC END --><P>Here is a simple example of using callbacks.
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(use-package :alien)
(use-package :c-call)

(def-callback foo (int (arg1 int) (arg2 int))
  (format t "~&amp;foo: ~S, ~S~%" arg1 arg2)
  (+ arg1 arg2))

(defun test-foo ()
  (callback-funcall foo 555 444444))
</PRE></BLOCKQUOTE><P>In this example, the callback function </P><TT class=code>foo</TT><P> is defined which
takes two C </P><TT class=code>int</TT><P> parameters and returns a </P><TT class=code>int</TT><P>. As this
shows, we can use arbitrary Lisp inside the function.</P><P>The function </P><TT class=code>test-foo</TT><P> shows how we can call this callback
function from Lisp. The macro </P><TT class=code>callback</TT><P> extracts the necessary
information for the callback function </P><TT class=code>foo</TT><P> which can be
converted into a pointer which we can call via </P><TT class=code>alien-funcall</TT><P>.</P><P>The following code is a more complete example where a foreign routine
calls our Lisp routine.
</P><BLOCKQUOTE CLASS=lisp> <PRE>
(use-package :alien)
(use-package :c-call)

(def-alien-routine qsort void
  (base (* t))
  (nmemb int)
  (size int)
  (compar (* (function int (* t) (* t)))))

(def-callback my&lt; (int (arg1 (* double))
                       (arg2 (* double)))
  (let ((a1 (deref arg1))
        (a2 (deref arg2)))
    (cond ((= a1 a2)  0)
          ((&lt; a1 a2) -1)
          (t         +1))))

(defun test-qsort ()
  (let ((a (make-array 10 :element-type &#X2019;double-float
                       :initial-contents &#X2019;(0.1d0 0.5d0 0.2d0 1.2d0 1.5d0
                                           2.5d0 0.0d0 0.1d0 0.2d0 0.3d0))))
    (print a)
    (qsort (sys:vector-sap a)
           (length a)
           (alien-size double :bytes)
           (alien:callback my&lt;))
    (print a)))
</PRE></BLOCKQUOTE><P>We define the alien routine, </P><TT class=code>qsort</TT><P>, and a callback, </P><TT class=code>my&lt;</TT><P>,
to determine whether two </P><TT class=code>double</TT><P>&#X2019;s are less than, greater than
or equal to each other.</P><P>The test function </P><TT class=code>test-qsort</TT><P> shows how we can call the alien
sort routine with our Lisp comparison routine to produce a sorted
array.</P><!--TOC subsection Accessing Lisp Arrays-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc265">8.7.6</A>&#XA0;&#XA0;Accessing Lisp Arrays</H3><!--SEC END --><P>Due to the way CMUCL manages memory, the amount of memory that can
be dynamically allocated by </P><TT class=code>malloc</TT><P> or <A NAME="@funs232"></A></P><TT class=code>make-alien</TT><P> is
limited<SUP><A NAME="text15" HREF="#note15">1</A></SUP>.</P><P>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.</P><P>This technique takes advantage of the fact that CMUCL has
specialized array types (see section&#XA0;<A HREF="#specialized-array-types">5.11.8</A>) that match
a typical C array. For example, a </P><TT class=code>(simple-array double-float
(100))</TT><P> is stored in memory in essentially the same way as the C
array </P><TT class=code>double x[100]</TT><P> would be. The following function allows us
to get the physical address of such a Lisp array:</P><BLOCKQUOTE class=example><PRE>
(defun array-data-address (array)
  "Return the physical address of where the actual data of an array is
stored.

ARRAY must be a specialized array type in CMUCL.  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 (simple-array (signed-byte 8))
                     (simple-array (signed-byte 16))
                     (simple-array (signed-byte 32))
                     (simple-array (unsigned-byte 8))
                     (simple-array (unsigned-byte 16))
                     (simple-array (unsigned-byte 32))
                     (simple-array single-float)
                     (simple-array double-float)
                     (simple-array (complex single-float))
                     (simple-array (complex 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
    ;;      ...         ...
    ;;
    (let ((addr (+ 8 (logandc1 7 (kernel:get-lisp-obj-address data))))
          (type-size
           (let ((type (array-element-type data)))
             (cond ((or (equal type &#X2019;(signed-byte 8))
                        (equal type &#X2019;(unsigned-byte 8)))
                    1)
                   ((or (equal type &#X2019;(signed-byte 16))
                        (equal type &#X2019;(unsigned-byte 16)))
                    2)
                   ((or (equal type &#X2019;(signed-byte 32))
                        (equal type &#X2019;(unsigned-byte 32)))
                    4)
                   ((equal type &#X2019;single-float)
                    4)
                   ((equal type &#X2019;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)))))))
</PRE></BLOCKQUOTE><P>We note, however, that the system function
<A NAME="@funs233"></A></P><TT class=code>system:vector-sap</TT><P> will do the same thing as above does.</P><P>Assume we have the C function below that we wish to use:</P><BLOCKQUOTE class=example><PRE>
  double dotprod(double* x, double* y, int n)
  {
    int k;
    double sum = 0;

    for (k = 0; k &lt; n; ++k) {
      sum += x[k] * y[k];
    }
    return sum;
  }
</PRE></BLOCKQUOTE><P>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 </P><TT class=code>malloc</TT><P> or </P><TT class=code>make-alien</TT><P> since we need about
16 MB of memory to hold the two arrays.</P><BLOCKQUOTE class=example><PRE>
  (alien:def-alien-routine "dotprod" c-call:double
    (x (* double-float) :in)
    (y (* double-float) :in)
    (n c-call:int :in))
    
  (defun test-dotprod ()
    (let ((x (make-array 10000 :element-type &#X2019;double-float 
                         :initial-element 2d0))
          (y (make-array 10000 :element-type &#X2019;double-float
                         :initial-element 10d0)))
        (sys:without-gcing
          (let ((x-addr (sys:vector-sap x))
                (y-addr (sys:vector-sap y)))
            (dotprod x-addr y-addr 10000)))))
</PRE></BLOCKQUOTE><P>In this example, we have used </P><TT class=code>sys:vector-sap</TT><P> instead of
</P><TT class=code>array-data-address</TT><P>, but we could have used </P><TT class=code>(sys:int-sap
(array-data-address x))</TT><P> as well.</P><P>Also, we have wrapped the inner </P><TT class=code>let</TT><P> expression in a
</P><TT class=code>sys:without-gcing</TT><P> that disables garbage collection for the
duration of the body. This will prevent garbage collection from
moving </P><TT class=code>x</TT><P> and </P><TT class=code>y</TT><P> arrays after we have obtained the (now
erroneous) addresses but before the call to </P><TT class=code>dotprod</TT><P> is made.</P><!--TOC section Step-by-Step Alien Example-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc266">8.8</A>&#XA0;&#XA0;Step-by-Step Alien Example</H2><!--SEC END --><P>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 </P><TT class=filename>test.c</TT><P>:</P><PRE CLASS="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-&gt;x = %d\n", r-&gt;x);
  printf("r-&gt;s = %s\n", r-&gt;s);
  for (j = 0; j &lt; 10; j++) printf("a[%d] = %d.\n", j, a[j]);
  r2 = (struct c_struct *) malloc (sizeof(struct c_struct));
  r2-&gt;x = i + 5;
  r2-&gt;s = "A C string";
  return(r2);
};
</PRE><P>It is possible to call this function from Lisp using the file </P><TT class=filename>test.lisp</TT><P>
whose contents is:</P><BLOCKQUOTE CLASS=lisp> <PRE>
;;; -*- 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 &#X2019;x) 20)
    (setf (slot c-struct &#X2019;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 &#X2019;x)
                  (slot res &#X2019;s))
        ;;              
        ;; Deallocate result <EM> after</EM> we are done using it.
        (free-alien res)))))
</PRE></BLOCKQUOTE><P>To execute the above example, it is necessary to compile the C routine as
follows:</P><BLOCKQUOTE class=example><PRE>
cc -c test.c
</PRE></BLOCKQUOTE><P>In order to enable incremental loading with some linkers, you may need to say:</P><BLOCKQUOTE class=example><PRE>
cc -G 0 -c test.c
</PRE></BLOCKQUOTE><P>Once the C code has been compiled, you can start up Lisp and load it in:</P><BLOCKQUOTE class=example><PRE>
% lisp
;;; Lisp should start up with its normal prompt.

;;; Compile the Lisp file.  This step can be done separately.  You don&#X2019;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
;;; of comments are actually the output of LOAD-FOREIGN.  Different linkers
;;; will give different warnings, but some warning about redefining the code
;;; size is typical.
* (load-foreign "test.o")

;;; Running library:load-foreign.csh...
;;; Loading object file...
;;; 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.
* (load "test")

;;; 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-&gt;x = 20
r-&gt;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"
*
</PRE></BLOCKQUOTE><P>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
</P><TT class=filename>/dev/null</TT><P> by default, so any output is discarded.
</P><!--NAME aliens.html-->
<!--BEGIN NOTES chapter-->
<HR CLASS="ffootnoterule"><DL CLASS="thefootnotes"><DT CLASS="dt-thefootnotes">
<A NAME="note15" HREF="#text15">1</A></DT><DD CLASS="dd-thefootnotes">CMUCL mmaps a large piece of memory for its own
use and this memory is typically about 256&#XA0;MB above the start of the C
heap. Thus, only about 256&#XA0;MB of memory can be dynamically allocated.
In earlier versions, this limit was closer to 8&#XA0;MB.
</DD></DL>
<!--END NOTES-->
<!--TOC chapter Interprocess Communication under LISP-->
<H1 CLASS="chapter"><!--SEC ANCHOR --><A NAME="htoc267">Chapter&#XA0;9</A>&#XA0;&#XA0;Interprocess Communication under LISP</H1><!--SEC END --><P>
<A NAME="remote"></A></P><DIV CLASS="center">
<B>by William Lott and Bill Chiles</B>
</DIV><P>CMUCL 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.</P><!--TOC section The REMOTE Package-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc268">9.1</A>&#XA0;&#XA0;The REMOTE Package</H2><!--SEC END --><P>The </P><TT class=code>remote</TT><P> 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,
</P><TT class=code>create-request-server</TT><P> and </P><TT class=code>connect-to-remote-server</TT><P>,
return </P><TT class=variable>wire</TT><P> structures. A wire maintains the current state of
a connection, and all the RPC forms require a wire to indicate where
to send requests.</P><!--TOC subsection Connecting Servers and Clients-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc269">9.1.1</A>&#XA0;&#XA0;Connecting Servers and Clients</H3><!--SEC END --><P>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 </P><TT class=code>VANCOUVER.SLISP.CS.CMU.EDU</TT><P> or a 32 bit unsigned integer. Port
numbers are 16 bit unsigned integers. Note: </P><TT class=variable>port</TT><P> in this context has
nothing to do with Mach ports and message passing.</P><P>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 </P><TT class=code>create-request-server</TT><P>. This
function signals an error if the chosen port is unusable. You will
probably want to write a loop using </P><TT class=code>handler-case</TT><P>, catching
conditions of type error, since this function does not signal more
specific conditions.</P><P><BR>
<A NAME="@funs234"></A><A NAME="FN:create-request-server"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>wire:</TT><TT class=function-name>create-request-server</TT> <TT class=variable>port</TT> <TT class=code>&amp;optional</TT> <TT class=variable>on-connect</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><TT class=code>create-request-server</TT><P> 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
</P><TT class=variable>on-connect</TT><P> function. Invoking this function has a couple of
purposes, and </P><TT class=variable>on-connect</TT><P> may be </P><TT class=code>nil</TT><P> in which case the
system foregoes invoking any function at connect time.</P><P>The </P><TT class=variable>on-connect</TT><P> 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 </P><TT class=variable>on-connect</TT><P> is </P><TT class=code>nil</TT><P>, the request server
allows all connections. When it is non-</P><TT class=code>nil</TT><P>, 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 </P><TT class=code>nil</TT><P>, but when the first value is </P><TT class=code>nil</TT><P>, the acceptance mechanism
destroys the wire.</P><TT class=code>create-request-server</TT><P> returns an object that
</P><TT class=code>destroy-request-server</TT><P> uses to terminate a connection.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs235"></A><A NAME="FN:destroy-request-server"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>wire:</TT><TT class=function-name>destroy-request-server</TT> <TT class=variable>server</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><TT class=code>destroy-request-server</TT><P> takes the result of
</P><TT class=code>create-request-server</TT><P> and terminates that server. Any
existing connections remain intact, but all additional connection
attempts will fail.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs236"></A><A NAME="FN:connect-to-remote-server"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>wire:</TT><TT class=function-name>connect-to-remote-server</TT> <TT class=variable>host</TT> <TT class=variable>port</TT> <TT class=code>&amp;optional</TT> <TT class=variable>on-death</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><TT class=code>connect-to-remote-server</TT><P> attempts to connect to a remote
server at the given </P><TT class=variable>port</TT><P> on </P><TT class=variable>host</TT><P> and returns a wire
structure if it is successful. If </P><TT class=variable>on-death</TT><P> is non-</P><TT class=code>nil</TT><P>, it is
a function the system invokes when this connection terminates.
</P></BLOCKQUOTE><!--TOC subsection Remote Evaluations-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc270">9.1.2</A>&#XA0;&#XA0;Remote Evaluations</H3><!--SEC END --><P>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.</P><P>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
</P><TT class=variable>remote-objects</TT><P> (see section&#XA0;<A HREF="#remote-objs">9.1.3</A>). The system sends symbols
as two strings, the package name and the symbol name, and if the
package doesn&#X2019;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 </P><TT class=code>prin1-to-string</TT><P> locally, send the string, and use
</P><TT class=code>read-from-string</TT><P> remotely.</P><P><BR>
<A NAME="@funs237"></A><A NAME="FN:remote"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>wire:</TT><TT class=function-name>remote</TT> <TT class=variable>wire</TT> <TT class=code>{call-specs}</TT><SUP>*</SUP> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>The </P><TT class=code>remote</TT><P> macro arranges for the process at the other end of
</P><TT class=variable>wire</TT><P> to invoke each of the functions in the </P><TT class=variable>call-specs</TT><P>.
To make sure the system sends the remote evaluation requests over
the wire, you must call </P><TT class=code>wire-force-output</TT><P>.</P><P>Each of </P><TT class=variable>call-specs</TT><P> 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. </P><TT class=code>remote</TT><P>
evaluates each of the argument subforms for each of the
</P><TT class=variable>call-specs</TT><P> locally in the current context, sending these
values as the arguments for the functions.</P><P>Consider the following example:</P><PRE CLASS="verbatim">(defun write-remote-string (str)
  (declare (simple-string str))
  (wire:remote wire
    (write-string str)))
</PRE><P>The value of </P><TT class=code>str</TT><P> in the local process is passed over the wire
with a request to invoke </P><TT class=code>write-string</TT><P> on the value. The
system does not expect to remotely evaluate </P><TT class=code>str</TT><P> for a value
in the remote process.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs238"></A><A NAME="FN:wire-force-output"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>wire:</TT><TT class=function-name>wire-force-output</TT> <TT class=variable>wire</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><TT class=code>wire-force-output</TT><P> flushes all internal buffers associated
with </P><TT class=variable>wire</TT><P>, sending the remote requests. This is necessary
after a call to </P><TT class=code>remote</TT><P>.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs239"></A><A NAME="FN:remote-value"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>wire:</TT><TT class=function-name>remote-value</TT> <TT class=variable>wire</TT> <TT class=variable>call-spec</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>The </P><TT class=code>remote-value</TT><P> macro is similar to the </P><TT class=code>remote</TT><P> macro.
</P><TT class=code>remote-value</TT><P> only takes one </P><TT class=variable>call-spec</TT><P>, 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 </P><TT class=code>wire-force-output</TT><P> in conjunction
with this interface.</P><P>If client unwinds past the call to </P><TT class=code>remote-value</TT><P>, the server
continues running, but the system ignores the value the server sends
back.</P><P>If the server unwinds past the remotely requested call, instead of
returning normally, </P><TT class=code>remote-value</TT><P> returns two values, </P><TT class=code>nil</TT><P>
and </P><TT class=code>t</TT><P>. Otherwise this returns the result of the remote
evaluation and </P><TT class=code>nil</TT><P>.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs240"></A><A NAME="FN:remote-value-bind"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>wire:</TT><TT class=function-name>remote-value-bind</TT> <TT class=variable>wire</TT> (<TT class=code>{variable}</TT><SUP>*</SUP>) remote-form
<TT class=code>{local-forms}</TT><SUP>*</SUP> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><TT class=code>remote-value-bind</TT><P> is similar to </P><TT class=code>multiple-value-bind</TT><P>
except the values bound come from </P><TT class=variable>remote-form</TT><P>&#X2019;s evaluation in
the remote process. The </P><TT class=variable>local-forms</TT><P> execute in an implicit
</P><TT class=code>progn</TT><P>.</P><P>If the client unwinds past the call to </P><TT class=code>remote-value-bind</TT><P>, the
server continues running, but the system ignores the values the
server sends back.</P><P>If the server unwinds past the remotely requested call, instead of
returning normally, the </P><TT class=variable>local-forms</TT><P> never execute, and
</P><TT class=code>remote-value-bind</TT><P> returns </P><TT class=code>nil</TT><P>.
</P></BLOCKQUOTE><!--TOC subsection Remote Objects-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc271">9.1.3</A>&#XA0;&#XA0;Remote Objects</H3><!--SEC END --><P>
<A NAME="remote-objs"></A></P><P>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 </P><TT class=variable>remote-objects</TT><P> 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.</P><P>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
(</P><TT class=code>eq</TT><P>) remote-object.</P><P><BR>
<A NAME="@funs241"></A><A NAME="FN:make-remote-object"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>wire:</TT><TT class=function-name>make-remote-object</TT> <TT class=variable>object</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><TT class=code>make-remote-object</TT><P> returns a remote-object that has
</P><TT class=variable>object</TT><P> as its value. The remote-object can be passed across
wires just like the directly supported wire data types.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs242"></A><A NAME="FN:remote-object-p"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>wire:</TT><TT class=function-name>remote-object-p</TT> <TT class=variable>object</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>The function </P><TT class=code>remote-object-p</TT><P> returns </P><TT class=code>t</TT><P> if </P><TT class=variable>object</TT><P>
is a remote object and </P><TT class=code>nil</TT><P> otherwise.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs243"></A><A NAME="FN:remote-object-local-p"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>wire:</TT><TT class=function-name>remote-object-local-p</TT> <TT class=variable>remote</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>The function </P><TT class=code>remote-object-local-p</TT><P> returns </P><TT class=code>t</TT><P> if
</P><TT class=variable>remote</TT><P> refers to an object in the local process. This is can
only occur if the local process created </P><TT class=variable>remote</TT><P> with
</P><TT class=code>make-remote-object</TT><P>.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs244"></A><A NAME="FN:remote-object-eq"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>wire:</TT><TT class=function-name>remote-object-eq</TT> <TT class=variable>obj1</TT> <TT class=variable>obj2</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>The function </P><TT class=code>remote-object-eq</TT><P> returns </P><TT class=code>t</TT><P> if </P><TT class=variable>obj1</TT><P> and
</P><TT class=variable>obj2</TT><P> refer to the same (</P><TT class=code>eq</TT><P>) lisp object, regardless of
which process created the remote-objects.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs245"></A><A NAME="FN:remote-object-value"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>wire:</TT><TT class=function-name>remote-object-value</TT> <TT class=variable>remote</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>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.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs246"></A><A NAME="FN:forget-remote-translation"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>wire:</TT><TT class=function-name>forget-remote-translation</TT> <TT class=variable>object</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function removes the information and storage necessary to
translate remote-objects back into </P><TT class=variable>object</TT><P>, so the next
</P><TT class=code>gc</TT><P> can reclaim the memory. You should use this when you no
longer expect to receive references to </P><TT class=variable>object</TT><P>. If some remote
process does send a reference to </P><TT class=variable>object</TT><P>,
</P><TT class=code>remote-object-value</TT><P> signals an error.
</P></BLOCKQUOTE><!--TOC section The WIRE Package-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc272">9.2</A>&#XA0;&#XA0;The WIRE Package</H2><!--SEC END --><P>The </P><TT class=code>wire</TT><P> package provides for sending data along wires. The
</P><TT class=code>remote</TT><P> 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 </P><TT class=code>wire-output-string</TT><P>, the remote process must know
to use </P><TT class=code>wire-get-string</TT><P>. To avoid rigid data transfers and
complicated code, the interface supports sending
</P><TT class=variable>tagged</TT><P> 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.</P><P>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.</P><!--TOC subsection Untagged Data-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc273">9.2.1</A>&#XA0;&#XA0;Untagged Data</H3><!--SEC END --><P>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:</P><UL CLASS="itemize"><LI CLASS="li-itemize">
8 bit unsigned bytes.</LI><LI CLASS="li-itemize">32 bit unsigned bytes.</LI><LI CLASS="li-itemize">32 bit integers.</LI><LI CLASS="li-itemize">simple-strings less than 65535 in length.
</LI></UL><P><BR>
<A NAME="@funs247"></A><A NAME="FN:wire-output-byte"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>wire:</TT><TT class=function-name>wire-output-byte</TT> <TT class=variable>wire</TT> <TT class=variable>byte</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
<P><A NAME="@funs248"></A><A NAME="FN:wire-get-byte"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>wire:</TT><TT class=function-name>wire-get-byte</TT> <TT class=variable>wire</TT> &nbsp;&nbsp;&nbsp;
</DIV><P><A NAME="@funs249"></A><A NAME="FN:wire-output-number"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>wire:</TT><TT class=function-name>wire-output-number</TT> <TT class=variable>wire</TT> <TT class=variable>number</TT> &nbsp;&nbsp;&nbsp;
</DIV><P><A NAME="@funs250"></A><A NAME="FN:wire-get-number"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>wire:</TT><TT class=function-name>wire-get-number</TT> <TT class=variable>wire</TT> <TT class=code>&amp;optional</TT>
<TT class=variable>signed</TT> &nbsp;&nbsp;&nbsp;
</DIV><P><A NAME="@funs251"></A><A NAME="FN:wire-output-string"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>wire:</TT><TT class=function-name>wire-output-string</TT> <TT class=variable>wire</TT> <TT class=variable>string</TT> &nbsp;&nbsp;&nbsp;
</DIV><P><A NAME="@funs252"></A><A NAME="FN:wire-get-string"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>wire:</TT><TT class=function-name>wire-get-string</TT> <TT class=variable>wire</TT> &nbsp;&nbsp;&nbsp;
</DIV><P>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.
</P></BLOCKQUOTE><!--TOC subsection Tagged Data-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc274">9.2.2</A>&#XA0;&#XA0;Tagged Data</H3><!--SEC END --><P>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 </P><TT class=variable>remote-objects</TT><P>
(see section&#XA0;<A HREF="#remote-objs">9.1.3</A>). The system sends symbols as two strings, the
package name and the symbol name, and if the package doesn&#X2019;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 </P><TT class=code>prin1-to-string</TT><P> locally, send the string, and use
</P><TT class=code>read-from-string</TT><P> remotely.</P><P><BR>
<A NAME="@funs253"></A><A NAME="FN:wire-output-object"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>wire:</TT><TT class=function-name>wire-output-object</TT> <TT class=variable>wire</TT> <TT class=variable>object</TT> <TT class=code>&amp;optional</TT> <TT class=variable>cache-it</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
<P><A NAME="@funs254"></A><A NAME="FN:wire-get-object"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>wire:</TT><TT class=function-name>wire-get-object</TT> <TT class=variable>wire</TT> &nbsp;&nbsp;&nbsp;
</DIV><P>The function </P><TT class=code>wire-output-object</TT><P> sends </P><TT class=variable>object</TT><P> over
</P><TT class=variable>wire</TT><P> preceded by a tag indicating its type.</P><P>If </P><TT class=variable>cache-it</TT><P> is non-</P><TT class=code>nil</TT><P>, this function only sends </P><TT class=variable>object</TT><P>
the first time it gets </P><TT class=variable>object</TT><P>. Each end of the wire
associates a token with </P><TT class=variable>object</TT><P>, similar to remote-objects,
allowing you to send the object more efficiently on successive
transmissions. </P><TT class=variable>cache-it</TT><P> defaults to </P><TT class=code>t</TT><P> for symbols and
</P><TT class=code>nil</TT><P> 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&#X2019; names repeatedly.</P><P>The function </P><TT class=code>wire-get-object</TT><P> reads the results of
</P><TT class=code>wire-output-object</TT><P> and returns that object.
</P></BLOCKQUOTE><!--TOC subsection Making Your Own Wires-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc275">9.2.3</A>&#XA0;&#XA0;Making Your Own Wires</H3><!--SEC END --><P>You can create wires manually in addition to the </P><TT class=code>remote</TT><P>
package&#X2019;s interface creating them for you. To create a wire, you need
a Unix <EM>file descriptor</EM>. If you are unfamiliar with Unix file
descriptors, see section 2 of the Unix manual pages.</P><P><BR>
<A NAME="@funs255"></A><A NAME="FN:make-wire"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>wire:</TT><TT class=function-name>make-wire</TT> <TT class=variable>descriptor</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>The function </P><TT class=code>make-wire</TT><P> creates a new wire when supplied with
the file descriptor to use for the underlying I/O operations.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs256"></A><A NAME="FN:wire-p"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>wire:</TT><TT class=function-name>wire-p</TT> <TT class=variable>object</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns </P><TT class=code>t</TT><P> if </P><TT class=variable>object</TT><P> is indeed a wire,
</P><TT class=code>nil</TT><P> otherwise.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs257"></A><A NAME="FN:wire-fd"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>wire:</TT><TT class=function-name>wire-fd</TT> <TT class=variable>wire</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns the file descriptor used by the </P><TT class=variable>wire</TT><P>.
</P></BLOCKQUOTE><!--TOC section Out-Of-Band Data-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc276">9.3</A>&#XA0;&#XA0;Out-Of-Band Data</H2><!--SEC END --><P>The TCP/IP protocol allows users to send data asynchronously, otherwise
known as </P><TT class=variable>out-of-band</TT><P> data. When using this feature, the operating
system interrupts the receiving process if this process has chosen to be
notified about out-of-band data. The receiver can grab this input
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.</P><P>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.</P><P>The Wire package is built on top of CMUCLs networking support. In
view of this, it is possible to use the routines described in section
<A HREF="#internet-oob">10.6</A> for handling and sending out-of-band data. These
all take a Unix file descriptor instead of a wire, but you can fetch a
wire&#X2019;s file descriptor with </P><TT class=code>wire-fd</TT><P>.
</P><!--NAME ipc.html-->
<!--TOC chapter Networking Support-->
<H1 CLASS="chapter"><!--SEC ANCHOR --><A NAME="htoc277">Chapter&#XA0;10</A>&#XA0;&#XA0;Networking Support</H1><!--SEC END --><P>
<A NAME="internet"></A></P><DIV CLASS="center">
<B>by Mario S. Mommer</B>
</DIV><P>This chapter documents the IPv4 networking and local sockets support
offered by CMUCL. It covers most of the basic sockets interface
functionality in a convenient and transparent way.</P><P>For reasons of space it would be impossible to include a thorough
introduction to network programming, so we assume some basic knowledge
of the matter.</P><!--TOC section Byte Order Converters-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc278">10.1</A>&#XA0;&#XA0;Byte Order Converters</H2><!--SEC END --><P>These are the functions that convert integers from host byte order to
network byte order (big-endian).</P><P><BR>
<A NAME="@funs258"></A><A NAME="FN:htonl"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>htonl</TT> <TT class=variable>integer</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>Converts a 32 bit integer from host byte order to network byte
order.</P></BLOCKQUOTE><P><BR>
<A NAME="@funs259"></A><A NAME="FN:htons"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>htons</TT> <TT class=variable>integer</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>Converts a 16 bit integer from host byte order to network byte
order.</P></BLOCKQUOTE><P><BR>
<A NAME="@funs260"></A><A NAME="FN:ntohs"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>ntohs</TT> <TT class=variable>integer</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>Converts a 32 bit integer from network byte order to host
byte order.</P></BLOCKQUOTE><P><BR>
<A NAME="@funs261"></A><A NAME="FN:ntohl"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>ntohl</TT> <TT class=variable>integer</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>Converts a 32 bit integer from network byte order to host byte
order.</P></BLOCKQUOTE><!--TOC section Domain Name Services (DNS)-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc279">10.2</A>&#XA0;&#XA0;Domain Name Services (DNS)</H2><!--SEC END --><P>The networking support of CMUCL includes the possibility of doing
DNS lookups. The function </P><P><BR>
<A NAME="@funs262"></A><A NAME="FN:lookup-host-entry"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>lookup-host-entry</TT> <TT class=variable>host</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>returns a structure of type </P><TT class=variable>host-entry</TT><P> (explained below) for
the given </P><TT class=variable>host</TT><P>. If </P><TT class=variable>host</TT><P> is an integer, it will be
assumed to be the IP address in host (byte-)order. If it is a string,
it can contain either the host name or the IP address in dotted
format.</P><P>This function works by completing the structure </P><TT class=variable>host-entry</TT><P>.
That is, if the user provides the IP address, then the structure will
contain that information and also the domain names. If the user
provides the domain name, the structure will be complemented with
the IP addresses along with the any aliases the host might have.</P></BLOCKQUOTE><P><BR>
<BR>
<A NAME="@types46"></A></P><DIV align=left>
[structure]<BR>
 <TT class=function-name>host-entry</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><TT class=variable>name</TT> <TT class=variable>aliases</TT>
<TT class=variable>addr-type</TT> <TT class=variable>addr-list</TT><P>This structure holds all information available at request time on a
given host. The entries are self-explanatory. Aliases is a list of
strings containing alternative names of the host, and addr-list a
list of addresses stored in host byte order. The field
</P><TT class=variable>addr-type</TT><P> contains the number of the address family, as
specified in <TT>socket.h</TT>, to which the addresses belong. Since
only addresses of the IPv4 family are currently supported, this slot
always has the value 2.</P></BLOCKQUOTE><P><BR>
<A NAME="@funs263"></A><A NAME="FN:ip-string"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>ip-string</TT> <TT class=variable>addr</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function takes an IP address in host order and returns a string
containing it in dotted format.</P></BLOCKQUOTE><!--TOC section Binding to Interfaces-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc280">10.3</A>&#XA0;&#XA0;Binding to Interfaces</H2><!--SEC END --><P>In this section, functions for creating sockets bound to an interface
are documented.</P><P><BR>
<A NAME="@funs264"></A><A NAME="FN:create-inet-listener"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>create-inet-listener</TT> <TT class=variable>port</TT> <TT class=code>&amp;optional</TT> <TT class=variable>kind</TT> <TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=code>:reuse-address</TT> <TT class=code>:backlog</TT> <TT class=code>:host</TT></SPAN> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>Creates a socket and binds it to a port, prepared to receive
connections of kind </P><TT class=variable>kind</TT><P> (which defaults to </P><TT class=code>:stream</TT><P>),
queuing up to </P><TT class=variable>backlog</TT><P> of them. If </P><TT class=code>:reuse-address</TT><TT class=variable>T</TT><P>
is used, the option SO_REUSEADDR is used in the call to </P><TT class=variable>bind</TT><P>.
If no value is given for </P><TT class=code>:host</TT><P>, it will try to bind to the
default IP address of the machine where the Lisp process is running.</P></BLOCKQUOTE><P><BR>
<A NAME="@funs265"></A><A NAME="FN:create-unix-listener"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>create-unix-listener</TT> <TT class=variable>path</TT> <TT class=code>&amp;optional</TT> <TT class=variable>kind</TT> <TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline">
<TT class=code>:backlog</TT></SPAN> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>Creates a socket and binds it to the file name given by </P><TT class=variable>path</TT><P>,
prepared to receive connections of kind </P><TT class=variable>kind</TT><P> (which defaults
to </P><TT class=code>:stream</TT><P>), queuing up to </P><TT class=variable>backlog</TT><P> of them.
</P></BLOCKQUOTE><!--TOC section Accepting Connections-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc281">10.4</A>&#XA0;&#XA0;Accepting Connections</H2><!--SEC END --><P>Once a socket is bound to its interface, we have to explicitly accept
connections. This task is performed by the functions we document here.</P><P><BR>
<A NAME="@funs266"></A><A NAME="FN:accept-tcp-connection"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>accept-tcp-connection</TT> <TT class=variable>unconnected</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>Waits until a connection arrives on the (internet family) socket
</P><TT class=variable>unconnected</TT><P>. Returns the file descriptor of the connection.
These can be conveniently encapsulated using file descriptor
streams; see <A HREF="#sec:fds">6.7</A>.</P></BLOCKQUOTE><P><BR>
<A NAME="@funs267"></A><A NAME="FN:accept-unix-connection"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>accept-unix-connection</TT> <TT class=variable>unconnected</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>Waits until a connection arrives on the (unix family) socket
</P><TT class=variable>unconnected</TT><P>. Returns the file descriptor of the connection.
These can be conveniently encapsulated using file descriptor
streams; see <A HREF="#sec:fds">6.7</A>.</P></BLOCKQUOTE><P><BR>
<A NAME="@funs268"></A><A NAME="FN:accept-network-stream"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>accept-network-stream</TT> <TT class=variable>socket</TT> <TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=code>:buffering</TT> <TT class=code>:timeout</TT> <TT class=code>:wait-max</TT></SPAN> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>Accept a connect from the specified </P><TT class=variable>socket</TT><P> and returns a stream 
connected to connection. 
</P></BLOCKQUOTE><!--TOC section Connecting-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc282">10.5</A>&#XA0;&#XA0;Connecting</H2><!--SEC END --><P>The task performed by the functions we present next is connecting to
remote hosts.</P><P><BR>
<A NAME="@funs269"></A><A NAME="FN:connect-to-inet-socket"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>connect-to-inet-socket</TT> <TT class=variable>host</TT> <TT class=variable>port</TT> <TT class=code>&amp;optional</TT> <TT class=variable>kind</TT>
<TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=code>:local-host</TT> <TT class=code>:local-port</TT></SPAN> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>Tries to open a connection to the remote host </P><TT class=variable>host</TT><P> (which may
be an IP address in host order, or a string with either a host name
or an IP address in dotted format) on port </P><TT class=variable>port</TT><P>. Returns the
file descriptor of the connection. The optional parameter
</P><TT class=variable>kind</TT><P> can be either </P><TT class=code>:stream</TT><P> (the default) or </P><TT class=code>:datagram</TT><P>.</P><P>If </P><TT class=variable>local-host</TT><P> and </P><TT class=variable>local-port</TT><P> are specified, the socket
that is created is also bound to the specified </P><TT class=variable>local-host</TT><P> and
</P><TT class=variable>port</TT><P>.</P></BLOCKQUOTE><P><BR>
<A NAME="@funs270"></A><A NAME="FN:connect-to-unix-socket"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>connect-to-unix-socket</TT> <TT class=variable>path</TT> <TT class=code>&amp;optional</TT> <TT class=variable>kind</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>Opens a connection to the unix &#X201C;address&#X201D; given by </P><TT class=variable>path</TT><P>.
Returns the file descriptor of the connection. The type of
connection is given by </P><TT class=variable>kind</TT><P>, which can be either </P><TT class=code>:stream</TT><P>
(the default) or </P><TT class=code>:datagram</TT><P>.</P></BLOCKQUOTE><P><BR>
<A NAME="@funs271"></A><A NAME="FN:open-network-stream"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>open-network-stream</TT> <TT class=variable>host</TT> <TT class=variable>port</TT> <TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=code>:buffering</TT> <TT class=code>:timeout</TT></SPAN> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>Return a stream connected to the specified </P><TT class=variable>port</TT><P> on the given </P><TT class=variable>host</TT><P>.
</P></BLOCKQUOTE><!--TOC section Out-of-Band Data-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc283">10.6</A>&#XA0;&#XA0;Out-of-Band Data</H2><!--SEC END --><P>
<A NAME="internet-oob"></A></P><P>Out-of-band data is data transmitted with a higher priority than
ordinary data. This is usually used by either side of the connection
to signal exceptional conditions. Due to the fact that most TCP/IP
implementations are broken in this respect, only single characters can
reliably be sent this way.</P><P><BR>
<A NAME="@funs272"></A><A NAME="FN:add-oob-handler"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>add-oob-handler</TT> <TT class=variable>fd</TT> <TT class=variable>char</TT> <TT class=variable>handler</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>Sets the function passed in </P><TT class=variable>handler</TT><P> as a handler for the
character </P><TT class=variable>char</TT><P> on the connection whose descriptor is </P><TT class=variable>fd</TT><P>.
In case this character arrives, the function in </P><TT class=variable>handler</TT><P> is
called without any argument.</P></BLOCKQUOTE><P><BR>
<A NAME="@funs273"></A><A NAME="FN:remove-oob-handler"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>remove-oob-handler</TT> <TT class=variable>fd</TT> <TT class=variable>char</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>Removes the handler for the character </P><TT class=variable>char</TT><P> from the connection
with the file descriptor </P><TT class=variable>fd</TT></BLOCKQUOTE><P><BR>
<A NAME="@funs274"></A><A NAME="FN:remove-all-oob-handlers"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>remove-all-oob-handlers</TT> <TT class=variable>fd</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>After calling this function, the connection whose descriptor is
</P><TT class=variable>fd</TT><P> will ignore any out-of-band character it receives.</P></BLOCKQUOTE><P><BR>
<A NAME="@funs275"></A><A NAME="FN:send-character-out-of-band"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>send-character-out-of-band</TT> <TT class=variable>fd</TT> <TT class=variable>char</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>Sends the character </P><TT class=variable>char</TT><P> through the connection </P><TT class=variable>fd</TT><P> out
of band.</P></BLOCKQUOTE><!--TOC section Unbound Sockets, Socket Options, and Closing Sockets-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc284">10.7</A>&#XA0;&#XA0;Unbound Sockets, Socket Options, and Closing Sockets</H2><!--SEC END --><P>These functions create unbound sockets. This is usually not necessary,
since connectors and listeners create their own.</P><P><BR>
<A NAME="@funs276"></A><A NAME="FN:create-unix-socket"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>create-unix-socket</TT> <TT class=code>&amp;optional</TT> <TT class=variable>type</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>Creates a unix socket for the unix address family, of type
</P><TT class=variable>:stream</TT><P> and (on success) returns its file descriptor.</P></BLOCKQUOTE><P><BR>
<A NAME="@funs277"></A><A NAME="FN:create-inet-socket"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>create-inet-socket</TT> <TT class=code>&amp;optional</TT> <TT class=variable>kind</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>Creates a unix socket for the internet address family, of type
</P><TT class=variable>:stream</TT><P> and (on success) returns its file descriptor.</P></BLOCKQUOTE><P>
<BR>
<BR>
</P><P>Once a socket is created, it is sometimes useful to bind the socket to a 
local address using </P><TT class=code>bind-inet-socket</TT><P>:</P><P><BR>
<A NAME="@funs278"></A><A NAME="FN:bind-inet-socket"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>bind-inet-socket</TT> <TT class=variable>socket</TT> <TT class=variable>host</TT> <TT class=variable>port</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>Bind the </P><TT class=variable>socket</TT><P> to a local interface address specified
by </P><TT class=variable>host</TT><P> and </P><TT class=variable>port</TT><P>. </P></BLOCKQUOTE><P>
<BR>
<BR>
</P><P>Further, it is desirable to be able to change socket options. This is
performed by the following two functions, which are essentially
wrappers for system calls to <TT>getsockopt</TT> and <TT>setsockopt</TT>.</P><P><BR>
<A NAME="@funs279"></A><A NAME="FN:get-socket-option"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>get-socket-option</TT> <TT class=variable>socket</TT> <TT class=variable>level</TT> <TT class=variable>optname</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>Gets the value of option </P><TT class=variable>optname</TT><P> from the socket </P><TT class=variable>socket</TT><P>.</P></BLOCKQUOTE><P><BR>
<A NAME="@funs280"></A><A NAME="FN:set-socket-option"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>set-socket-option</TT> <TT class=variable>socket</TT> <TT class=variable>level</TT> <TT class=variable>optname</TT> <TT class=variable>optval</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>Sets the value of option </P><TT class=variable>optname</TT><P> from the socket </P><TT class=variable>socket</TT><P>
to the value </P><TT class=variable>optval</TT><P>.</P></BLOCKQUOTE><P>
<BR>
<BR>
</P><P>For information on possible options and values we refer to the
manpages of <TT>getsockopt</TT> and <TT>setsockopt</TT>, and to <TT>socket.h</TT></P><P>Finally, the function</P><P><BR>
<A NAME="@funs281"></A><A NAME="FN:close-socket"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>close-socket</TT> <TT class=variable>socket</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>Closes the socket given by the file descriptor </P><TT class=variable>socket</TT><P>.</P></BLOCKQUOTE><!--TOC section Unix Datagrams-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc285">10.8</A>&#XA0;&#XA0;Unix Datagrams</H2><!--SEC END --><P>Datagram network is supported with the following functions.</P><P><BR>
<A NAME="@funs282"></A><A NAME="FN:inet-recvfrom"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>inet-recvfrom</TT> 	<TT class=variable>fd</TT> <TT class=variable>buffer</TT> <TT class=variable>size</TT>
	<TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=code>:flags</TT></SPAN> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
A simple interface to the Unix <TT class=code>recvfrom</TT> function. Returns
three values: bytecount, source address as integer, and source
port. Bytecount can of course be negative, to indicate faults.
</BLOCKQUOTE><P><BR>
<A NAME="@funs283"></A><A NAME="FN:inet-sendto"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>inet-sendto</TT> 	<TT class=variable>fd</TT> <TT class=variable>buffer</TT> <TT class=variable>size</TT> <TT class=variable>addr</TT> <TT class=variable>port</TT>
	<TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=code>:flags</TT></SPAN> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
A simple interface to the Unix <TT class=code>sendto</TT> function.
</BLOCKQUOTE><P><BR>
<A NAME="@funs284"></A><A NAME="FN:inet-shutdown"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>inet-shutdown</TT> 	<TT class=variable>fd</TT> <TT class=variable>level</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>A simple interface to the Unix </P><TT class=code>shutdown</TT><P> function. For
</P><TT class=code>level</TT><P>, you may use the following symbols to close one or
both ends of a socket: </P><TT class=code>shut-rd</TT><P>, </P><TT class=code>shut-wr</TT><P>,
</P><TT class=code>shut-rdwr</TT><P>.</P></BLOCKQUOTE><!--TOC section Errors-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc286">10.9</A>&#XA0;&#XA0;Errors</H2><!--SEC END --><P>Errors that occur during socket operations signal a
</P><TT class=code>socket-error</TT><P> condition, a subtype of the </P><TT class=code>error</TT><P>
condition. Currently this condition includes just the Unix
</P><TT class=code>errno</TT><P> associated with the error.
</P><!--NAME internet.html-->
<!--TOC chapter Debugger Programmer&#X2019;s Interface-->
<H1 CLASS="chapter"><!--SEC ANCHOR --><A NAME="htoc287">Chapter&#XA0;11</A>&#XA0;&#XA0;Debugger Programmer&#X2019;s Interface</H1><!--SEC END --><P>
<A NAME="debug-internals"></A></P><P>The debugger programmers interface is exported from from the
</P><TT class=code>DEBUG-INTERNALS</TT><P> or </P><TT class=code>DI</TT><P> package. This is a CMU
extension that allows debugging tools to be written without detailed
knowledge of the compiler or run-time system.</P><P>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 </P><TT class=variable>basic-code-location</TT><P>, it
takes either type, but when it specifically names the argument
</P><TT class=variable>code-location</TT><P>, the routine will signal an error if you give it an
unknown code-location.</P><!--TOC section DI Exceptional Conditions-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc288">11.1</A>&#XA0;&#XA0;DI Exceptional Conditions</H2><!--SEC END --><P>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
</P><TT class=code>serious-condition</TT><P>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.</P><!--TOC subsection Debug-conditions-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc289">11.1.1</A>&#XA0;&#XA0;Debug-conditions</H3><!--SEC END --><P>The debug internals interface signals conditions when it can&#X2019;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.</P><P><BR>
<BR>
<A NAME="@types47"></A></P><DIV align=left>
[Condition]<BR>
 <TT class=function-name>debug-condition</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This condition inherits from serious-condition, and all debug-conditions
inherit from this. These must be handled, but they are not programmer errors.
</P></BLOCKQUOTE><P><BR>
<BR>
<A NAME="@types48"></A></P><DIV align=left>
[Condition]<BR>
 <TT class=function-name>no-debug-info</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This condition indicates there is absolutely no debugging information
available.
</P></BLOCKQUOTE><P><BR>
<BR>
<A NAME="@types49"></A></P><DIV align=left>
[Condition]<BR>
 <TT class=function-name>no-debug-function-returns</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This condition indicates the system cannot return values from a frame since
its debug-function lacks debug information details about returning values.
</P></BLOCKQUOTE><P><BR>
<BR>
<A NAME="@types50"></A></P><DIV align=left>
[Condition]<BR>
 <TT class=function-name>no-debug-blocks</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
This condition indicates that a function was not compiled with debug-block
information, but this information is necessary necessary for some requested
operation.
</BLOCKQUOTE><P><BR>
<BR>
<A NAME="@types51"></A></P><DIV align=left>
[Condition]<BR>
 <TT class=function-name>no-debug-variables</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Similar to <TT class=code>no-debug-blocks</TT>, except that variable information was
requested.
</BLOCKQUOTE><P><BR>
<BR>
<A NAME="@types52"></A></P><DIV align=left>
[Condition]<BR>
 <TT class=function-name>lambda-list-unavailable</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Similar to <TT class=code>no-debug-blocks</TT>, except that lambda list information was
requested.
</BLOCKQUOTE><P><BR>
<BR>
<A NAME="@types53"></A></P><DIV align=left>
[Condition]<BR>
 <TT class=function-name>invalid-value</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This condition indicates a debug-variable has </P><TT class=code>:invalid</TT><P> or </P><TT class=code>:unknown</TT><P>
value in a particular frame.
</P></BLOCKQUOTE><P><BR>
<BR>
<A NAME="@types54"></A></P><DIV align=left>
[Condition]<BR>
 <TT class=function-name>ambiguous-variable-name</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This condition indicates a user supplied debug-variable name identifies more
than one valid variable in a particular frame.
</P></BLOCKQUOTE><!--TOC subsection Debug-errors-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc290">11.1.2</A>&#XA0;&#XA0;Debug-errors</H3><!--SEC END --><P>These are programmer errors resulting from misuse of the debugging tools&#X2019;
programmers&#X2019; 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.</P><P><BR>
<BR>
<A NAME="@types55"></A></P><DIV align=left>
[Condition]<BR>
 <TT class=function-name>debug-error</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
This condition inherits from error, and all user programming errors inherit
from this condition.
</BLOCKQUOTE><P><BR>
<BR>
<A NAME="@types56"></A></P><DIV align=left>
[Condition]<BR>
 <TT class=function-name>unhandled-condition</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
This error results from a signalled <TT class=code>debug-condition</TT> occurring
without anyone handling it.
</BLOCKQUOTE><P><BR>
<BR>
<A NAME="@types57"></A></P><DIV align=left>
[Condition]<BR>
 <TT class=function-name>unknown-code-location</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
This error indicates the invalid use of an unknown-code-location.
</BLOCKQUOTE><P><BR>
<BR>
<A NAME="@types58"></A></P><DIV align=left>
[Condition]<BR>
 <TT class=function-name>unknown-debug-variable</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This error indicates an attempt to use a debug-variable in conjunction with an
inappropriate debug-function; for example, checking the variable&#X2019;s validity
using a code-location in the wrong debug-function will signal this error.
</P></BLOCKQUOTE><P><BR>
<BR>
<A NAME="@types59"></A></P><DIV align=left>
[Condition]<BR>
 <TT class=function-name>frame-function-mismatch</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This error indicates you called a function returned by
</P><TT class=code>preprocess-for-eval</TT><P>
on a frame other than the one for which the function had been prepared.
</P></BLOCKQUOTE><!--TOC section Debug-variables-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc291">11.2</A>&#XA0;&#XA0;Debug-variables</H2><!--SEC END --><P>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.</P><P><BR>
<A NAME="@funs285"></A><A NAME="FN:debug-variable-name"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>debug-variable-name</TT> <TT class=variable>debug-variable</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns the name of the </P><TT class=variable>debug-variable</TT><P>. The
name is the name of the symbol used as an identifier when writing
the code.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs286"></A><A NAME="FN:debug-variable-package"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>debug-variable-package</TT> <TT class=variable>debug-variable</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns the package name of the </P><TT class=variable>debug-variable</TT><P>.
This is the package name of the symbol used as an identifier when
writing the code.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs287"></A><A NAME="FN:debug-variable-symbol"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>debug-variable-symbol</TT> <TT class=variable>debug-variable</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns the symbol from interning
</P><TT class=code>debug-variable-name</TT><P> in the package named by
</P><TT class=code>debug-variable-package</TT><P>.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs288"></A><A NAME="FN:debug-variable-id"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>debug-variable-id</TT> <TT class=variable>debug-variable</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns the integer that makes </P><TT class=variable>debug-variable</TT><P>&#X2019;s
name and package name unique with respect to other
</P><TT class=variable>debug-variable</TT><P>&#X2019;s in the same function.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs289"></A><A NAME="FN:debug-variable-validity"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>debug-variable-validity</TT> <TT class=variable>debug-variable</TT> <TT class=variable>basic-code-location</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns three values reflecting the validity of
</P><TT class=variable>debug-variable</TT><P>&#X2019;s value at </P><TT class=variable>basic-code-location</TT><P>:

</P><DL CLASS="list"><DT CLASS="dt-list">

<TT class=code>:valid</TT><BR>
</DT><DD CLASS="dd-list"> The value is known to be available.
</DD><DT CLASS="dt-list"><TT class=code>:invalid</TT><BR>
</DT><DD CLASS="dd-list"> The value is known to be unavailable.
</DD><DT CLASS="dt-list"><TT class=code>:unknown</TT><BR>
</DT><DD CLASS="dd-list"> The value&#X2019;s availability is unknown.
</DD></DL></BLOCKQUOTE><P><BR>
<A NAME="@funs290"></A><A NAME="FN:debug-variable-value"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>debug-variable-value</TT> <TT class=variable>debug-variable</TT>
<TT class=variable>frame</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns the value stored for </P><TT class=variable>debug-variable</TT><P> in
</P><TT class=variable>frame</TT><P>. The value may be invalid. This is </P><TT class=code>SETF</TT><P>&#X2019;able.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs291"></A><A NAME="FN:debug-variable-valid-value"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>debug-variable-valid-value</TT> <TT class=variable>debug-variable</TT> <TT class=variable>frame</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns the value stored for </P><TT class=variable>debug-variable</TT><P> in
</P><TT class=variable>frame</TT><P>. If the value is not </P><TT class=code>:valid</TT><P>, then this signals an
</P><TT class=code>invalid-value</TT><P> error.
</P></BLOCKQUOTE><!--TOC section Frames-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc292">11.3</A>&#XA0;&#XA0;Frames</H2><!--SEC END --><P>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.</P><TT class=code>top-frame</TT><P>, </P><TT class=code>frame-down</TT><P>, </P><TT class=code>frame-up</TT><P>, and
</P><TT class=code>frame-debug-function</TT><P> 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.</P><P><BR>
<A NAME="@funs292"></A><A NAME="FN:top-frame"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>top-frame</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function never returns the frame for itself, always the frame
before calling </P><TT class=code>top-frame</TT><P>.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs293"></A><A NAME="FN:frame-down"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>frame-down</TT> <TT class=variable>frame</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This returns the frame immediately below </P><TT class=variable>frame</TT><P> on the stack.
When </P><TT class=variable>frame</TT><P> is the bottom of the stack, this returns </P><TT class=code>nil</TT><P>.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs294"></A><A NAME="FN:frame-up"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>frame-up</TT> <TT class=variable>frame</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This returns the frame immediately above </P><TT class=variable>frame</TT><P> on the stack.
When </P><TT class=variable>frame</TT><P> is the top of the stack, this returns </P><TT class=code>nil</TT><P>.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs295"></A><A NAME="FN:frame-debug-function"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>frame-debug-function</TT> <TT class=variable>frame</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns the debug-function for the function whose call
</P><TT class=variable>frame</TT><P> represents.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs296"></A><A NAME="FN:frame-code-location"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>frame-code-location</TT> <TT class=variable>frame</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns the code-location where </P><TT class=variable>frame</TT><P>&#X2019;s
debug-function will continue running when program execution returns
to </P><TT class=variable>frame</TT><P>. If someone interrupted this frame, the result could
be an unknown code-location.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs297"></A><A NAME="FN:frame-catches"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>frame-catches</TT> <TT class=variable>frame</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns an a-list for all active catches in
</P><TT class=variable>frame</TT><P> mapping catch tags to the code-locations at which the
catch re-enters.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs298"></A><A NAME="FN:eval-in-frame"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>eval-in-frame</TT> <TT class=variable>frame</TT> <TT class=variable>form</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This evaluates </P><TT class=variable>form</TT><P> in </P><TT class=variable>frame</TT><P>&#X2019;s environment. This can
signal several different debug-conditions since its success relies
on a variety of inexact debug information: </P><TT class=code>invalid-value</TT><P>,
</P><TT class=code>ambiguous-variable-name</TT><P>, </P><TT class=code>frame-function-mismatch</TT><P>. See
also <A NAME="@funs299"></A></P><TT class=code>preprocess-for-eval</TT><P>.
</P></BLOCKQUOTE><!--TOC section Debug-functions-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc293">11.4</A>&#XA0;&#XA0;Debug-functions</H2><!--SEC END --><P>Debug-functions represent the static information about a function determined at
compile time&#X2014;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.</P><P><BR>
<A NAME="@funs300"></A><A NAME="FN:do-debug-function-blocks"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>do-debug-function-blocks</TT> (<TT class=variable>block-var</TT> <TT class=variable>debug-function</TT> <TT class=code>{result-form}</TT>)
<TT class=code>{form}</TT><SUP>*</SUP> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This executes the forms in a context with </P><TT class=variable>block-var</TT><P> bound to
each debug-block in </P><TT class=variable>debug-function</TT><P> successively.
</P><TT class=variable>Result-form</TT><P> is an optional form to execute for a return value,
and </P><TT class=code>do-debug-function-blocks</TT><P> returns </P><TT class=code>nil</TT><P>if there is no
</P><TT class=variable>result-form</TT><P>. This signals a </P><TT class=code>no-debug-blocks</TT><P> condition
when the </P><TT class=variable>debug-function</TT><P> lacks debug-block information.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs301"></A><A NAME="FN:debug-function-lambda-list"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>debug-function-lambda-list</TT> <TT class=variable>debug-function</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns a list representing the lambda-list for
</P><TT class=variable>debug-function</TT><P>. The list has the following structure:
</P><BLOCKQUOTE class=example><PRE>
    (required-var1 required-var2
    ...
    (:optional var3 suppliedp-var4)
    (:optional var5)
    ...
    (:rest var6) (:rest var7)
    ...
    (:keyword keyword-symbol var8 suppliedp-var9)
    (:keyword keyword-symbol var10)
    ...
    )
  </PRE></BLOCKQUOTE><P>
Each </P><TT class=code>var</TT><TT class=variable>n</TT><P> is a debug-variable; however, the symbol
</P><TT class=code>:deleted</TT><P> appears instead whenever the argument remains
unreferenced throughout </P><TT class=variable>debug-function</TT><P>.</P><P>If there is no lambda-list information, this signals a
</P><TT class=code>lambda-list-unavailable</TT><P> condition.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs302"></A><A NAME="FN:do-debug-function-variables"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>do-debug-function-variables</TT> (<TT class=variable>var</TT> <TT class=variable>debug-function</TT> <TT class=code>{result}</TT>)
<TT class=code>{form}</TT><SUP>*</SUP> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This macro executes each </P><TT class=variable>form</TT><P> in a context with </P><TT class=variable>var</TT><P>
bound to each debug-variable in </P><TT class=variable>debug-function</TT><P>. This returns
the value of executing </P><TT class=variable>result</TT><P> (defaults to </P><TT class=code>nil</TT><P>). This may
iterate over only some of </P><TT class=variable>debug-function</TT><P>&#X2019;s variables or none
depending on debug policy; for example, possibly the compilation
only preserved argument information.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs303"></A><A NAME="FN:debug-variable-info-available"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>debug-variable-info-available</TT> <TT class=variable>debug-function</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns whether there is any variable information for
</P><TT class=variable>debug-function</TT><P>. This is useful for distinguishing whether
there were no locals in a function or whether there was no variable
information. For example, if </P><TT class=code>do-debug-function-variables</TT><P>
executes its forms zero times, then you can use this function to
determine the reason.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs304"></A><A NAME="FN:debug-function-symbol-variables"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>debug-function-symbol-variables</TT> <TT class=variable>debug-function</TT> <TT class=variable>symbol</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns a list of debug-variables in
</P><TT class=variable>debug-function</TT><P> having the same name and package as
</P><TT class=variable>symbol</TT><P>. If </P><TT class=variable>symbol</TT><P> is uninterned, then this returns a
list of debug-variables without package names and with the same name
as </P><TT class=variable>symbol</TT><P>. The result of this function is limited to the
availability of variable information in </P><TT class=variable>debug-function</TT><P>; for
example, possibly </P><TT class=variable>debug-function</TT><P> only knows about its
arguments.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs305"></A><A NAME="FN:ambiguous-debug-variables"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>ambiguous-debug-variables</TT> <TT class=variable>debug-function</TT> <TT class=variable>name-prefix-string</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns a list of debug-variables in
</P><TT class=variable>debug-function</TT><P> whose names contain </P><TT class=variable>name-prefix-string</TT><P> as
an initial substring. The result of this function is limited to the
availability of variable information in </P><TT class=variable>debug-function</TT><P>; for
example, possibly </P><TT class=variable>debug-function</TT><P> only knows about its
arguments.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs306"></A><A NAME="FN:preprocess-for-eval"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>preprocess-for-eval</TT> <TT class=variable>form</TT> <TT class=variable>basic-code-location</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns a function of one argument that evaluates
</P><TT class=variable>form</TT><P> in the lexical context of </P><TT class=variable>basic-code-location</TT><P>.
This allows efficient repeated evaluation of </P><TT class=variable>form</TT><P> at a certain
place in a function which could be useful for conditional breaking.
This signals a </P><TT class=code>no-debug-variables</TT><P> condition when the
code-location&#X2019;s debug-function has no debug-variable information
available. The returned function takes a frame as an argument. See
also <A NAME="@funs307"></A></P><TT class=code>eval-in-frame</TT><P>.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs308"></A><A NAME="FN:function-debug-function"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>function-debug-function</TT> <TT class=variable>function</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns a debug-function that represents debug
information for </P><TT class=variable>function</TT><P>.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs309"></A><A NAME="FN:debug-function-kind"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>debug-function-kind</TT> <TT class=variable>debug-function</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns the kind of function </P><TT class=variable>debug-function</TT><P>
represents. The value is one of the following:

</P><DL CLASS="list"><DT CLASS="dt-list">

<TT class=code>:optional</TT><BR>
</DT><DD CLASS="dd-list"> This kind of function is an entry point to an
ordinary function. It handles optional defaulting, parsing
keywords, etc.
</DD><DT CLASS="dt-list"><TT class=code>:external</TT><BR>
</DT><DD CLASS="dd-list"> This kind of function is an entry point to an
ordinary function. It checks argument values and count and calls
the defined function.
</DD><DT CLASS="dt-list"><TT class=code>:top-level</TT><BR>
</DT><DD CLASS="dd-list"> This kind of function executes one or more
random top-level forms from a file.
</DD><DT CLASS="dt-list"><TT class=code>:cleanup</TT><BR>
</DT><DD CLASS="dd-list"> This kind of function represents the cleanup
forms in an <TT class=code>unwind-protect</TT>.
</DD><DT CLASS="dt-list"><TT class=code>nil</TT><BR>
</DT><DD CLASS="dd-list"> This kind of function is not one of the above; that is,
it is not specially marked in any way.
</DD></DL></BLOCKQUOTE><P><BR>
<A NAME="@funs310"></A><A NAME="FN:debug-function-function"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>debug-function-function</TT> <TT class=variable>debug-function</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns the Common Lisp function associated with the
</P><TT class=variable>debug-function</TT><P>. This returns </P><TT class=code>nil</TT><P> if the function is
unavailable or is non-existent as a user callable function object.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs311"></A><A NAME="FN:debug-function-name"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>debug-function-name</TT> <TT class=variable>debug-function</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns the name of the function represented by
</P><TT class=variable>debug-function</TT><P>. This may be a string or a cons; do not assume
it is a symbol.
</P></BLOCKQUOTE><!--TOC section Debug-blocks-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc294">11.5</A>&#XA0;&#XA0;Debug-blocks</H2><!--SEC END --><P>Debug-blocks contain information pertinent to a specific range of code in a
debug-function.</P><P><BR>
<A NAME="@funs312"></A><A NAME="FN:do-debug-block-locations"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>do-debug-block-locations</TT> (<TT class=variable>code-var</TT> <TT class=variable>debug-block</TT> <TT class=code>{result}</TT>)
<TT class=code>{form}</TT><SUP>*</SUP> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This macro executes each </P><TT class=variable>form</TT><P> in a context with </P><TT class=variable>code-var</TT><P>
bound to each code-location in </P><TT class=variable>debug-block</TT><P>. This returns the
value of executing </P><TT class=variable>result</TT><P> (defaults to </P><TT class=code>nil</TT><P>).
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs313"></A><A NAME="FN:debug-block-successors"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>debug-block-successors</TT> <TT class=variable>debug-block</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns the list of possible code-locations where
execution may continue when the basic-block represented by
</P><TT class=variable>debug-block</TT><P> completes its execution.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs314"></A><A NAME="FN:debug-block-elsewhere-p"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>debug-block-elsewhere-p</TT> <TT class=variable>debug-block</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns whether </P><TT class=variable>debug-block</TT><P> represents elsewhere
code. This is code the compiler has moved out of a function&#X2019;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.
</P></BLOCKQUOTE><!--TOC section Breakpoints-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc295">11.6</A>&#XA0;&#XA0;Breakpoints</H2><!--SEC END --><P>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.</P><P><BR>
<A NAME="@funs315"></A><A NAME="FN:make-breakpoint"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>make-breakpoint</TT> <TT class=variable>hook-function</TT> <TT class=variable>what</TT> <TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=code>:kind</TT> <TT class=code>:info</TT>
<TT class=code>:function-end-cookie</TT></SPAN> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function creates and returns a breakpoint. When program
execution encounters the breakpoint, the system calls
</P><TT class=variable>hook-function</TT><P>. </P><TT class=variable>hook-function</TT><P> takes the current frame
for the function in which the program is running and the breakpoint
object.</P><TT class=variable>what</TT><P> and </P><TT class=variable>kind</TT><P> determine where in a function the system
invokes </P><TT class=variable>hook-function</TT><P>. </P><TT class=variable>what</TT><P> is either a code-location
or a debug-function. </P><TT class=variable>kind</TT><P> is one of </P><TT class=code>:code-location</TT><P>,
</P><TT class=code>:function-start</TT><P>, or </P><TT class=code>:function-end</TT><P>. Since the starts and
ends of functions may not have code-locations representing them,
designate these places by supplying </P><TT class=variable>what</TT><P> as a debug-function
and </P><TT class=variable>kind</TT><P> indicating the </P><TT class=code>:function-start</TT><P> or
</P><TT class=code>:function-end</TT><P>. When </P><TT class=variable>what</TT><P> is a debug-function and
</P><TT class=variable>kind</TT><P> is </P><TT class=code>:function-end</TT><P>, then hook-function must take two
additional arguments, a list of values returned by the function and
a function-end-cookie.</P><TT class=variable>info</TT><P> is information supplied by and used by the user.</P><TT class=variable>function-end-cookie</TT><P> 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
the cookie when passed to the function-end-cookie function for later
comparison in the hook function.</P><P>This signals an error if </P><TT class=variable>what</TT><P> is an unknown code-location.</P><P><EM>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.)</EM></P></BLOCKQUOTE><P><BR>
<A NAME="@funs316"></A><A NAME="FN:activate-breakpoint"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>activate-breakpoint</TT> <TT class=variable>breakpoint</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function causes the system to invoke the </P><TT class=variable>breakpoint</TT><P>&#X2019;s
hook-function until the next call to </P><TT class=code>deactivate-breakpoint</TT><P> or
</P><TT class=code>delete-breakpoint</TT><P>. The system invokes breakpoint hook
functions in the opposite order that you activate them.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs317"></A><A NAME="FN:deactivate-breakpoint"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>deactivate-breakpoint</TT> <TT class=variable>breakpoint</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function stops the system from invoking the </P><TT class=variable>breakpoint</TT><P>&#X2019;s
hook-function.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs318"></A><A NAME="FN:breakpoint-active-p"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>breakpoint-active-p</TT> <TT class=variable>breakpoint</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This returns whether </P><TT class=variable>breakpoint</TT><P> is currently active.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs319"></A><A NAME="FN:breakpoint-hook-function"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>breakpoint-hook-function</TT> <TT class=variable>breakpoint</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns the </P><TT class=variable>breakpoint</TT><P>&#X2019;s function the system
calls when execution encounters </P><TT class=variable>breakpoint</TT><P>, and it is active.
This is </P><TT class=code>SETF</TT><P>&#X2019;able.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs320"></A><A NAME="FN:breakpoint-info"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>breakpoint-info</TT> <TT class=variable>breakpoint</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns </P><TT class=variable>breakpoint</TT><P>&#X2019;s information supplied by the
user. This is </P><TT class=code>SETF</TT><P>&#X2019;able.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs321"></A><A NAME="FN:breakpoint-kind"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>breakpoint-kind</TT> <TT class=variable>breakpoint</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns the </P><TT class=variable>breakpoint</TT><P>&#X2019;s kind specification.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs322"></A><A NAME="FN:breakpoint-what"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>breakpoint-what</TT> <TT class=variable>breakpoint</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns the </P><TT class=variable>breakpoint</TT><P>&#X2019;s what specification.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs323"></A><A NAME="FN:delete-breakpoint"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>delete-breakpoint</TT> <TT class=variable>breakpoint</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function frees system storage and removes computational
overhead associated with </P><TT class=variable>breakpoint</TT><P>. After calling this,
</P><TT class=variable>breakpoint</TT><P> is useless and can never become active again.
</P></BLOCKQUOTE><!--TOC section Code-locations-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc296">11.7</A>&#XA0;&#XA0;Code-locations</H2><!--SEC END --><P>Code-locations represent places in functions where the system has correct
information about the function&#X2019;s environment and where interesting operations
can occur&#X2014;asking for a local variable&#X2019;s value, setting breakpoints,
evaluating forms within the function&#X2019;s environment, etc.</P><P>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&#X2019; argument is
named </P><TT class=variable>basic-code-location</TT><P> indicating they take known and unknown
code-locations. If an operation names its argument
</P><TT class=variable>code-location</TT><P>, and you supply an unknown one, it will signal an
error. For example, </P><TT class=code>frame-code-location</TT><P> 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.</P><P><BR>
<A NAME="@funs324"></A><A NAME="FN:code-location-debug-function"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>code-location-debug-function</TT> <TT class=variable>basic-code-location</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns the debug-function representing information
about the function corresponding to the code-location.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs325"></A><A NAME="FN:code-location-debug-block"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>code-location-debug-block</TT> <TT class=variable>basic-code-location</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>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 </P><TT class=code>no-debug-blocks</TT><P>
condition.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs326"></A><A NAME="FN:code-location-top-level-form-offset"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>code-location-top-level-form-offset</TT> <TT class=variable>code-location</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns the number of top-level forms before the one
containing </P><TT class=variable>code-location</TT><P> as seen by the compiler in some
compilation unit. A compilation unit is not necessarily a single
file, see the section on debug-sources.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs327"></A><A NAME="FN:code-location-form-number"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>code-location-form-number</TT> <TT class=variable>code-location</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns the number of the form corresponding to
</P><TT class=variable>code-location</TT><P>. 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 <A NAME="@funs328"></A></P><TT class=code>form-number-translations</TT><P>.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs329"></A><A NAME="FN:code-location-debug-source"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>code-location-debug-source</TT> <TT class=variable>code-location</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns </P><TT class=variable>code-location</TT><P>&#X2019;s debug-source.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs330"></A><A NAME="FN:code-location-unknown-p"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>code-location-unknown-p</TT> <TT class=variable>basic-code-location</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns whether </P><TT class=variable>basic-code-location</TT><P> is unknown.
It returns </P><TT class=code>nil</TT><P> when the code-location is known.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs331"></A><A NAME="FN:code-location="></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>code-location=</TT> <TT class=variable>code-location1</TT>
<TT class=variable>code-location2</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns whether the two code-locations are the same.
</P></BLOCKQUOTE><!--TOC section Debug-sources-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc297">11.8</A>&#XA0;&#XA0;Debug-sources</H2><!--SEC END --><P>Debug-sources represent how to get back the source for some code. The
source is either a file (</P><TT class=code>compile-file</TT><P> or </P><TT class=code>load</TT><P>), a
lambda-expression (</P><TT class=code>compile</TT><P>, </P><TT class=code>defun</TT><P>, </P><TT class=code>defmacro</TT><P>), or
a stream (something particular to CMUCL, </P><TT class=code>compile-from-stream</TT><P>).</P><P>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 </P><TT class=code>code-location-top-level-form-offset</TT><P> returns an offset
that does not always start at zero for the code-location&#X2019;s
debug-source. The offset into a particular source is
</P><TT class=code>code-location-top-level-form-offset</TT><P> minus
</P><TT class=code>debug-source-root-number</TT><P>.</P><P>Inside a top-level form, a code-location&#X2019;s form number indicates the
subform corresponding to the code-location.</P><P><BR>
<A NAME="@funs332"></A><A NAME="FN:debug-source-from"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>debug-source-from</TT> <TT class=variable>debug-source</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns an indication of the type of source. The
following are the possible values:

</P><DL CLASS="list"><DT CLASS="dt-list">

<TT class=code>:file</TT><BR>
</DT><DD CLASS="dd-list"> from a file (obtained by <TT class=code>compile-file</TT> if
compiled).
</DD><DT CLASS="dt-list"><TT class=code>:lisp</TT><BR>
</DT><DD CLASS="dd-list"> from Lisp (obtained by <TT class=code>compile</TT> if
compiled).
</DD><DT CLASS="dt-list"><TT class=code>:stream</TT><BR>
</DT><DD CLASS="dd-list"> from a non-file stream (CMUCL supports
<TT class=code>compile-from-stream</TT>).
</DD></DL></BLOCKQUOTE><P><BR>
<A NAME="@funs333"></A><A NAME="FN:debug-source-name"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>debug-source-name</TT> <TT class=variable>debug-source</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns the actual source in some sense represented by
debug-source, which is related to </P><TT class=code>debug-source-from</TT><P>:

</P><DL CLASS="list"><DT CLASS="dt-list">

<TT class=code>:file</TT><BR>
</DT><DD CLASS="dd-list"> the pathname of the file.
</DD><DT CLASS="dt-list"><TT class=code>:lisp</TT><BR>
</DT><DD CLASS="dd-list"> a lambda-expression.
</DD><DT CLASS="dt-list"><TT class=code>:stream</TT><BR>
</DT><DD CLASS="dd-list"> some descriptive string that&#X2019;s otherwise
useless.
</DD></DL></BLOCKQUOTE><P><BR>
<A NAME="@funs334"></A><A NAME="FN:debug-source-created"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>debug-source-created</TT> <TT class=variable>debug-source</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns the universal time someone created the source.
This may be </P><TT class=code>nil</TT><P> if it is unavailable.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs335"></A><A NAME="FN:debug-source-compiled"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>debug-source-compiled</TT> <TT class=variable>debug-source</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns the time someone compiled the source. This is
</P><TT class=code>nil</TT><P> if the source is uncompiled.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs336"></A><A NAME="FN:debug-source-root-number"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>debug-source-root-number</TT> <TT class=variable>debug-source</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>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&#X2014;the compiler saw no other
top-level forms before it.
</P></BLOCKQUOTE><!--TOC section Source Translation Utilities-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc298">11.9</A>&#XA0;&#XA0;Source Translation Utilities</H2><!--SEC END --><P>These two functions provide a mechanism for converting the rather
obscure (but highly compact) representation of source locations into an
actual source form:</P><P><BR>
<A NAME="@funs337"></A><A NAME="FN:debug-source-start-positions"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>debug-source-start-positions</TT> <TT class=variable>debug-source</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns the file position of each top-level form as a
vector if </P><TT class=variable>debug-source</TT><P> is from a </P><TT class=code>:file</TT><P>. If
</P><TT class=code>debug-source-from</TT><P> is </P><TT class=code>:lisp</TT><P> or </P><TT class=code>:stream</TT><P>, or the file
is byte-compiled, then the result is </P><TT class=code>nil</TT><P>.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs338"></A><A NAME="FN:form-number-translations"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>form-number-translations</TT> <TT class=variable>form</TT>
<TT class=variable>tlf-number</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns a table mapping form numbers (see
</P><TT class=code>code-location-form-number</TT><P>) to source-paths. A source-path
indicates a descent into the top-level-form </P><TT class=variable>form</TT><P>, going
directly to the subform corresponding to a form number.
</P><TT class=variable>tlf-number</TT><P> is the top-level-form number of </P><TT class=variable>form</TT><P>.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs339"></A><A NAME="FN:source-path-context"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>source-path-context</TT> <TT class=variable>form</TT> <TT class=variable>path</TT> <TT class=variable>context</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>This function returns the subform of </P><TT class=variable>form</TT><P> indicated by the
source-path. </P><TT class=variable>Form</TT><P> is a top-level form, and </P><TT class=variable>path</TT><P> is a
source-path into it. </P><TT class=variable>Context</TT><P> is the number of enclosing forms
to return instead of directly returning the source-path form. When
</P><TT class=variable>context</TT><P> is non-zero, the form returned contains a marker,
</P><TT class=code>#:****HERE****</TT><P>, immediately before the form indicated by
</P><TT class=variable>path</TT><P>.
</P></BLOCKQUOTE><!--NAME debug-internals.html-->
<!--TOC chapter Cross-Referencing Facility-->
<H1 CLASS="chapter"><!--SEC ANCHOR --><A NAME="htoc299">Chapter&#XA0;12</A>&#XA0;&#XA0;Cross-Referencing Facility</H1><!--SEC END --><P>
<A NAME="xref"></A>
<A NAME="@concept297"></A>
</P><DIV CLASS="center">
<B>by Eric Marsden</B>
</DIV><P>The CMUCL cross-referencing facility (abbreviated XREF) assists in
the analysis of static dependency relationships in a program. It
provides introspection capabilities such as the ability to know which
functions may call a given function, and the program contexts in which
a particular global variable is used. The compiler populates a
database of cross-reference information, which can be queried by the
user to know:</P><UL CLASS="itemize"><LI CLASS="li-itemize">
the list of program contexts (functions, macros, top-level forms)
where a given function may be called at runtime, either directly or
indirectly (via its function-object);</LI><LI CLASS="li-itemize">the list of program contexts where a given global variable may be
read;</LI><LI CLASS="li-itemize">the list of program contexts that bind a global variable;</LI><LI CLASS="li-itemize">the list of program contexts where a given global variable may be
modified during the execution of the program.
</LI></UL><P>A global variable is either a dynamic variable or a constant variable,
for instance declared using </P><TT class=code>defvar</TT><P> or </P><TT class=code>defparameter</TT><P> or
</P><TT class=code>defconstant</TT><P>.</P><!--TOC section Populating the cross-reference database-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc300">12.1</A>&#XA0;&#XA0;Populating the cross-reference database</H2><!--SEC END --><P><BR>
<A NAME="@vars68"></A><A NAME="VR:record-xref-info"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>c:</TT><TT class=function-name>*record-xref-info*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
When non-NIL, code that is compiled (either using
<TT class=code>compile-file</TT>, or by calling <TT class=code>compile</TT> from the
listener), will be analyzed for cross-references. Defaults to
<TT class=code>nil</TT>.
</BLOCKQUOTE><P>Cross-referencing information is only generated by the compiler; the
interpreter does not populate the cross-reference database. XREF
analysis is independent of whether the compiler is generating native
code or byte code, and of whether it is compiling from a file, from a
stream, or is invoked interactively from the listener. </P><P>Alternatively, the </P><TT class=code>::xref</TT><P> option to </P><TT class=code>compile-file</TT><P> may be
specified to populate the cross-reference database when compiling a
file. In this case, loading the generated fasl file in a fresh lisp
will also populate the cross-reference database.</P><P><BR>
<A NAME="@funs340"></A><A NAME="FN:init-xref-database"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>xref:</TT><TT class=function-name>init-xref-database</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Reinitializes the database of cross-references. This can be used to
reclaim the space occupied by the database contents, or to discard
stale cross-reference information.
</BLOCKQUOTE><!--TOC section Querying the cross-reference database-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc301">12.2</A>&#XA0;&#XA0;Querying the cross-reference database</H2><!--SEC END --><P>CMUCL provides a number of functions in the XREF package that may
be used to query the cross-reference database:</P><P><BR>
<A NAME="@funs341"></A><A NAME="FN:who-calls"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>xref:</TT><TT class=function-name>who-calls</TT> <TT class=variable>function</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Returns the list of xref-contexts where <TT class=variable>function</TT> (either a
symbol that names a function, or a function object) may be called
at runtime. XREF does not record calls to macro-functions (such as
<TT class=code>defun</TT>) or to special forms (such as <TT class=code>eval-when</TT>).
</BLOCKQUOTE><P><BR>
<A NAME="@funs342"></A><A NAME="FN:who-references"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>xref:</TT><TT class=function-name>who-references</TT> <TT class=variable>global-variable</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Returns the list of program contexts that may reference
<TT class=variable>global-variable</TT>. 
</BLOCKQUOTE><P><BR>
<A NAME="@funs343"></A><A NAME="FN:who-binds"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>xref:</TT><TT class=function-name>who-binds</TT> <TT class=variable>global-variable</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Returns a list of program contexts where the specified global
variable may be bound at runtime (for example using <TT class=code>LET</TT>).
</BLOCKQUOTE><P><BR>
<A NAME="@funs344"></A><A NAME="FN:who-sets"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>xref:</TT><TT class=function-name>who-sets</TT> <TT class=variable>global-variable</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Returns a list of program contexts where the given global variable
may be modified at runtime (for example using <TT class=code>SETQ</TT>). 
</BLOCKQUOTE><P>An <I>xref-context</I> is the originating site of a cross-reference.
It identifies a portion of a program, and is defined by an
</P><TT class=code>xref-context</TT><P> structure, that comprises a name, a source file and a
source-path. </P><P><BR>
<A NAME="@funs345"></A><A NAME="FN:xref-context-name"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>xref:</TT><TT class=function-name>xref-context-name</TT> <TT class=variable>context</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Returns the name slot of an xref-context, which is one of:
<UL CLASS="itemize"><LI CLASS="li-itemize">
a global function, which is named by a symbol or by a list of the form
<TT class=code>(setf foo)</TT>. </LI><LI CLASS="li-itemize">a macro, named by a list <CODE>(:macro foo)</CODE>.</LI><LI CLASS="li-itemize">an inner function (<TT class=code>flet</TT>, <TT class=code>labels</TT>, or anonymous lambdas) that
is named by a list of the form <TT class=code>(:internal outer inner)</TT>.</LI><LI CLASS="li-itemize">a method, named by a list of the form
<CODE>(:method foo (specializer1 specializer2)</CODE>. </LI><LI CLASS="li-itemize">a string <CODE>"Top-Level Form"</CODE> that identifies a reference from a
top-level form. Note that multiple references from top-level forms
will only be listed once. </LI><LI CLASS="li-itemize">a compiler-macro, named by a string of the form
<CODE>(:compiler-macro foo)</CODE>. </LI><LI CLASS="li-itemize">a string such as <CODE>"DEFSTRUCT FOO"</CODE>, identifying a reference from
within a structure accessor or constructor or copier.</LI><LI CLASS="li-itemize">a string such as 
<PRE CLASS="verbatim">  "Creation Form for #&lt;KERNEL::CLASS-CELL STRUCT-FOO&gt;"
</PRE></LI><LI CLASS="li-itemize">a string such as <CODE>"defun foo"</CODE>, or <CODE>"defmethod bar (t)"</CODE>,
that identifies a reference from within code that has been generated
by the compiler for that form. For example, the compilation of a
<TT class=code>defclass</TT> form causes accessor functions to be generated by the
compiler; this code is compiler-generated (it does not appear in the
source file), and so is identified by the XREF facility by a string. 
</LI></UL>
</BLOCKQUOTE><P><BR>
<A NAME="@funs346"></A><A NAME="FN:xref-context-file"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>xref:</TT><TT class=function-name>xref-context-file</TT> context &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Return the truename (in the sense of the variable
<A NAME="@vars69"></A><TT class=code>*compile-file-truename*</TT>) of the source file from which the
referencing forms were compiled. This slot will be <TT class=code>nil</TT> if the
code was compiled from a stream, or interactively from the
listener.
</BLOCKQUOTE><P><BR>
<A NAME="@funs347"></A><A NAME="FN:xref-context-source-path"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>xref:</TT><TT class=function-name>xref-context-source-path</TT> context &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Return a list of positive integers identifying the form that
contains the cross-reference. The first integer in the source-path
is the number of the top-level form containing the cross-reference
(for example, 2 identifies the second top-level form in the source
file). The second integer in the source-path identifies the form
within this top-level form that contains the cross-reference, and so
on. This function will always return <TT class=code>nil</TT> if the file slot of an
xref-context is <TT class=code>nil</TT>.</BLOCKQUOTE><!--TOC section Example usage-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc302">12.3</A>&#XA0;&#XA0;Example usage</H2><!--SEC END --><P>In this section, we will illustrate use of the XREF facility on a
number of simple examples.</P><P>Consider the following program fragment, that defines a global
variable and a function.</P><PRE CLASS="verbatim">  (defvar *variable-one* 42)
  
  (defun function-one (x)
     (princ (* x *variable-one*)))
</PRE><P>We save this code in a file named </P><TT class=code>example.lisp</TT><P>, enable
cross-referencing, clear any previous cross-reference information,
compile the file, and can then query the cross-reference database
(output has been modified for readability).</P><PRE CLASS="verbatim">  USER&gt; (setf c:*record-xref-info* t)
  USER&gt; (xref:init-xref-database)
  USER&gt; (compile-file "example")
  USER&gt; (xref:who-calls 'princ)
  (#&lt;xref-context function-one in #p"example.lisp"&gt;)
  USER&gt; (xref:who-references '*variable-one*)
  (#&lt;xref-context function-one in #p"example.lisp"&gt;)
</PRE><P>From this example, we see that the compiler has noted the call to the
global function </P><TT class=code>princ</TT><P> in </P><TT class=code>function-one</TT><P>, and the reference
to the global variable </P><TT class=code>*variable-one*</TT><P>. </P><P>Suppose that we add the following code to the previous file. </P><PRE CLASS="verbatim">(defconstant +constant-one+ 1)
  
(defstruct struct-one
  slot-one
  (slot-two +constant-one+ :type integer)
  (slot-three 42 :read-only t))

(defmacro with-different-one (&amp;body body)
  `(let ((*variable-one* 666))
      ,@body))

(defun get-variable-one () *variable-one*)

(defun (setf get-variable-one) (new-value)
  (setq *variable-one* new-value))
</PRE><P>In the following example, we detect references x and y.</P><P>The following function illustrates the effect that various forms of
optimization carried out by the CMUCL compiler can have on the
cross-references that are reported for a particular program. The
compiler is able to detect that the evaluated condition is always
false, and that the first clause of the </P><TT class=code>if</TT><P> will never be taken
(this optimization is called dead-code elimination). XREF will
therefore not register a call to the function </P><TT class=code>sin</TT><P> from the
function </P><TT class=code>foo</TT><P>. Likewise, no calls to the functions </P><TT class=code>sqrt</TT><P>
and </P><TT class=code>&lt;</TT><P> are registered, because the compiler has eliminated the
code that evaluates the condition. Finally, no call to the function
</P><TT class=code>expt</TT><P> is generated, because the compiler was able to evaluate
the result of the expression </P><TT class=code>(expt 3 2)</TT><P> at compile-time (though
a process called constant-folding).</P><PRE CLASS="verbatim">;; zero call references are registered for this function!
(defun constantly-nine (x)
  (if (&lt; (sqrt x) 0)
      (sin x)
      (expt 3 2)))
</PRE><!--TOC section Limitations of the cross-referencing facility-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc303">12.4</A>&#XA0;&#XA0;Limitations of the cross-referencing facility</H2><!--SEC END --><P>No cross-reference information is available for interpreted functions.
The cross-referencing database is not persistent: unless you save an
image using </P><TT class=code>save-lisp</TT><P>, the database will be empty each time
CMUCL is restarted. There is no mechanism that saves
cross-reference information in FASL files, so loading a system from
compiled code will not populate the cross-reference database. The XREF
database currently accumulates &#X201C;stale&#X201D; information: when compiling a
file, it does not delete any cross-references that may have previously
been generated for that file. This latter limitation will be removed
in a future release. </P><P>The cross-referencing facility is only able to analyze the static
dependencies in a program; it does not provide any information about
runtime (dynamic) dependencies. For instance, XREF is able to identify
the list of program contexts where a given function may be called, but
is not able to determine which contexts will be activated when the
program is executed with a specific set of input parameters. However,
the static analysis that is performed by the CMUCL compiler does
allow XREF to provide more information than would be available from a
mere syntactic analysis of a program. References that occur from
within unreachable code will not be displayed by XREF, because the
CMUCL compiler deletes dead code before cross-references are
analyzed. Certain &#X201C;trivial&#X201D; function calls (where the result of the
function call can be evaluated at compile-time) may be eliminated by
optimizations carried out by the compiler; see the example below.</P><P>If you examine the entire database of cross-reference information (by
accessing undocumented internals of the XREF package), you will note
that XREF notes &#X201C;bogus&#X201D; cross-references to function calls that are
inserted by the compiler. For example, in safe code, the CMUCL
compiler inserts a call to an internal function called
</P><TT class=code>c::%verify-argument-count</TT><P>, so that the number of arguments
passed to the function is checked each time it is called. The XREF
facility does not distinguish between user code and these forms that
are introduced during compilation. This limitation should not be
visible if you use the documented functions in the XREF package. </P><P>As of the 18e release of CMUCL, the cross-referencing facility is
experimental; expect details of its implementation to change in future
releases. In particular, the names given to CLOS methods and to inner
functions will change in future releases. </P><!--NAME cross-referencing.html-->
<!--TOC chapter Internationalization-->
<H1 CLASS="chapter"><!--SEC ANCHOR --><A NAME="htoc304">Chapter&#XA0;13</A>&#XA0;&#XA0;Internationalization</H1><!--SEC END --><P>
<A NAME="i18n"></A>
<A NAME="@concept298"></A></P><P>CMUCL supports internationalization by supporting Unicode
characters internally and by adding support for external formats to
convert from the internal format to an appropriate external character
coding format.</P><P>To understand the support for Unicode, we refer the reader to the
<A HREF="http://www.unicode.org/">Unicode standard</A>.
</P><!--TOC section Changes-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc305">13.1</A>&#XA0;&#XA0;Changes</H2><!--SEC END --><P>To support internationalization, the following changes to Common Lisp
functions have been done.</P><!--TOC subsection Design Choices-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc306">13.1.1</A>&#XA0;&#XA0;Design Choices</H3><!--SEC END --><P>To support Unicode, there are many approaches. One choice is to
support both 8-bit </P><TT class=code>base-char</TT><P> and a 21-bit (or larger)
</P><TT class=code>character</TT><P> since Unicode codepoints use 21 bits. This generally
means strings are much larger, and complicates the compiler by having
to support both </P><TT class=code>base-char</TT><P> and </P><TT class=code>character</TT><P> types and the
corresponding string types. This also adds complexity for the user to
understand the difference between the different string and character
types.</P><P>Another choice is to have just one character and string type that can
hold the entire Unicode codepoint. While simplifying the compiler and
reducing the burden on the user, this significantly increases memory
usage for strings.</P><P>The solution chosen by CMUCL is to tradeoff the size and complexity
by having only 16-bit characters. Most of the important languages can
be encoded using only 16-bits. The rest of the codepoints are for
rare languages or ancient scripts. Thus, the memory usage is
significantly reduced while still supporting the the most important
languages. Compiler complexity is also reduced since </P><TT class=code>base-char</TT><P>
and </P><TT class=code>character</TT><P> are the same as are the string types.. But we
still want to support the full Unicode character set. This is
achieved by making strings be UTF-16 strings internally. Hence, Lisp
strings are UTF-16 strings, and Lisp characters are UTF-16 code-units.</P><!--TOC subsection Characters-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc307">13.1.2</A>&#XA0;&#XA0;Characters</H3><!--SEC END --><P>
<A NAME="sec:i18n:characters"></A></P><P>Characters are now 16 bits long instead of 8 bits, and </P><TT class=code>base-char</TT><P>
and </P><TT class=code>character</TT><P> types are the same. This difference is
naturally indicated by changing </P><TT class=code>char-code-limit</TT><P> from 256 to
65536.</P><!--TOC subsection Strings-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc308">13.1.3</A>&#XA0;&#XA0;Strings</H3><!--SEC END --><P>
<A NAME="sec:i18n:strings"></A></P><P>In CMUCL there is only one type of string&#X2014;</P><TT class=code>base-string</TT><P> and
</P><TT class=code>string</TT><P> are the same. </P><P>Internally, the strings are encoded using UTF-16. This means that in
some rare cases the number of Lisp characters in a string is not the
same as the number of codepoints in the string.</P><!--TOC section External Formats-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc309">13.2</A>&#XA0;&#XA0;External Formats</H2><!--SEC END --><P>To be able to communicate to the external world, CMUCL supports
external formats to convert to and from the external world to
CMUCL&#X2019;s string format. The external format is specified in several
ways. The standard streams </P><TT class=variable>*standard-input*</TT><P>,
</P><TT class=variable>*standard-output*</TT><P>, and </P><TT class=variable>*standard-error*</TT><P> take the format
from the value specified by </P><TT class=variable>*default-external-format*</TT><P>. The
default value of </P><TT class=variable>*default-external-format*</TT><P> is </P><TT class=code>:iso8859-1</TT><P>.</P><P>For files, </P><TT class=code>OPEN</TT><P> takes the </P><TT class=code>:external-format</TT><P>
parameter to specify the format. The default external format is
</P><TT class=code>:default</TT><P>. </P><!--TOC subsection Available External Formats-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc310">13.2.1</A>&#XA0;&#XA0;Available External Formats</H3><!--SEC END --><P>The available external formats are listed below in
Table&#XA0;<A HREF="#table:external-formats">13.1</A>. The first column gives the
external format, and the second column gives a list of aliases that
can be used for this format. The set of aliases can be changed by
changing the </P><TT class=filename>aliases</TT><P> file.</P><P>For all of these formats, if an illegal sequence is encountered, no
error or warning is signaled. Instead, the offending sequence is
silently replaced with the Unicode REPLACEMENT CHARACTER (U+FFFD).</P><BLOCKQUOTE CLASS="table"><DIV CLASS="center"><DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV>
<TABLE BORDER=1 CELLSPACING=0 CELLPADDING=1><TR><TD VALIGN=top ALIGN=left NOWRAP> <B>Format</B></TD><TD VALIGN=top ALIGN=left NOWRAP><B>Aliases</B></TD><TD VALIGN=top ALIGN=left><B>Description</B></TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP> <TT class=code>:iso8859-1</TT></TD><TD VALIGN=top ALIGN=left NOWRAP><TT class=code>:latin1</TT> <TT class=code>:latin-1</TT> <TT class=code>:iso-8859-1</TT></TD><TD VALIGN=top ALIGN=left>ISO8859-1</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP> <TT class=code>:iso8859-2</TT></TD><TD VALIGN=top ALIGN=left NOWRAP><TT class=code>:latin2</TT> <TT class=code>:latin-2</TT> <TT class=code>:iso-8859-2</TT></TD><TD VALIGN=top ALIGN=left>ISO8859-2</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP> <TT class=code>:iso8859-3</TT></TD><TD VALIGN=top ALIGN=left NOWRAP><TT class=code>:latin3</TT> <TT class=code>:latin-3</TT> <TT class=code>:iso-8859-3</TT></TD><TD VALIGN=top ALIGN=left>ISO8859-3</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP> <TT class=code>:iso8859-4</TT></TD><TD VALIGN=top ALIGN=left NOWRAP><TT class=code>:latin4</TT> <TT class=code>:latin-4</TT> <TT class=code>:iso-8859-4</TT></TD><TD VALIGN=top ALIGN=left>ISO8859-4</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP> <TT class=code>:iso8859-5</TT></TD><TD VALIGN=top ALIGN=left NOWRAP><TT class=code>:cyrillic</TT> <TT class=code>:iso-8859-5</TT></TD><TD VALIGN=top ALIGN=left>ISO8859-5</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP> <TT class=code>:iso8859-6</TT></TD><TD VALIGN=top ALIGN=left NOWRAP><TT class=code>:arabic</TT> <TT class=code>:iso-8859-6</TT></TD><TD VALIGN=top ALIGN=left>ISO8859-6</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP> <TT class=code>:iso8859-7</TT></TD><TD VALIGN=top ALIGN=left NOWRAP><TT class=code>:greek</TT> <TT class=code>:iso-8859-7</TT></TD><TD VALIGN=top ALIGN=left>ISO8859-7</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP> <TT class=code>:iso8859-8</TT></TD><TD VALIGN=top ALIGN=left NOWRAP><TT class=code>:hebrew</TT> <TT class=code>:iso-8859-8</TT></TD><TD VALIGN=top ALIGN=left>ISO8859-8</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP> <TT class=code>:iso8859-9</TT></TD><TD VALIGN=top ALIGN=left NOWRAP><TT class=code>:latin5</TT> <TT class=code>:latin-5</TT> <TT class=code>:iso-8859-9</TT></TD><TD VALIGN=top ALIGN=left>ISO8859-9</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP> <TT class=code>:iso8859-10</TT></TD><TD VALIGN=top ALIGN=left NOWRAP><TT class=code>:latin6</TT> <TT class=code>:latin-6</TT> <TT class=code>:iso-8859-10</TT></TD><TD VALIGN=top ALIGN=left>ISO8859-10</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP> <TT class=code>:iso8859-13</TT></TD><TD VALIGN=top ALIGN=left NOWRAP><TT class=code>:latin7</TT> <TT class=code>:latin-7</TT> <TT class=code>:iso-8859-13</TT></TD><TD VALIGN=top ALIGN=left>ISO8859-13</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP> <TT class=code>:iso8859-14</TT></TD><TD VALIGN=top ALIGN=left NOWRAP><TT class=code>:latin8</TT> <TT class=code>:latin-8</TT> <TT class=code>:iso-8859-14</TT></TD><TD VALIGN=top ALIGN=left>ISO8859-14</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP> <TT class=code>:iso8859-15</TT></TD><TD VALIGN=top ALIGN=left NOWRAP><TT class=code>:latin9</TT> <TT class=code>:latin-9</TT> <TT class=code>:iso-8859-15</TT></TD><TD VALIGN=top ALIGN=left>ISO8859-15</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP> <TT class=code>:utf-8</TT></TD><TD VALIGN=top ALIGN=left NOWRAP><TT class=code>:utf</TT> <TT class=code>:utf8</TT></TD><TD VALIGN=top ALIGN=left>UTF-8</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP> <TT class=code>:utf-16</TT></TD><TD VALIGN=top ALIGN=left NOWRAP><TT class=code>:utf16</TT></TD><TD VALIGN=top ALIGN=left>UTF-16 with optional BOM</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP> <TT class=code>:utf-16-be</TT></TD><TD VALIGN=top ALIGN=left NOWRAP><TT class=code>:utf-16be</TT> <TT class=code>:utf16-be</TT></TD><TD VALIGN=top ALIGN=left>UTF-16 big-endian (without BOM)</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP> <TT class=code>:utf-16-le</TT></TD><TD VALIGN=top ALIGN=left NOWRAP><TT class=code>:utf-16le</TT> <TT class=code>:utf16-le</TT></TD><TD VALIGN=top ALIGN=left>UTF-16 little-endian (without BOM)</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP> <TT class=code>:utf-32</TT></TD><TD VALIGN=top ALIGN=left NOWRAP><TT class=code>:utf32</TT></TD><TD VALIGN=top ALIGN=left>UTF-32 with optional BOM</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP> <TT class=code>:utf-32-be</TT></TD><TD VALIGN=top ALIGN=left NOWRAP><TT class=code>:utf-32be</TT> <TT class=code>:utf32-be</TT></TD><TD VALIGN=top ALIGN=left>UTF-32 big-endian (without BOM)</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP> <TT class=code>:utf-32-le</TT></TD><TD VALIGN=top ALIGN=left NOWRAP><TT class=code>:utf-32le</TT> <TT class=code>:utf32-le</TT></TD><TD VALIGN=top ALIGN=left>UTF-32 little-endian (without BOM)</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP> <TT class=code>:cp1250</TT></TD><TD VALIGN=top ALIGN=left NOWRAP>&nbsp;</TD><TD VALIGN=top ALIGN=left>&nbsp;</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP> <TT class=code>:cp1251</TT></TD><TD VALIGN=top ALIGN=left NOWRAP>&nbsp;</TD><TD VALIGN=top ALIGN=left>&nbsp;</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP> <TT class=code>:cp1252</TT></TD><TD VALIGN=top ALIGN=left NOWRAP><TT class=code>:windows-1252</TT> <TT class=code>:windows-cp1252</TT> <TT class=code>:windows-latin1</TT></TD><TD VALIGN=top ALIGN=left>&nbsp;</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP> <TT class=code>:cp1253</TT></TD><TD VALIGN=top ALIGN=left NOWRAP>&nbsp;</TD><TD VALIGN=top ALIGN=left>&nbsp;</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP> <TT class=code>:cp1254</TT></TD><TD VALIGN=top ALIGN=left NOWRAP>&nbsp;</TD><TD VALIGN=top ALIGN=left>&nbsp;</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP> <TT class=code>:cp1255</TT></TD><TD VALIGN=top ALIGN=left NOWRAP>&nbsp;</TD><TD VALIGN=top ALIGN=left>&nbsp;</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP> <TT class=code>:cp1256</TT></TD><TD VALIGN=top ALIGN=left NOWRAP>&nbsp;</TD><TD VALIGN=top ALIGN=left>&nbsp;</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP> <TT class=code>:cp1257</TT></TD><TD VALIGN=top ALIGN=left NOWRAP>&nbsp;</TD><TD VALIGN=top ALIGN=left>&nbsp;</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP> <TT class=code>:cp1258</TT></TD><TD VALIGN=top ALIGN=left NOWRAP>&nbsp;</TD><TD VALIGN=top ALIGN=left>&nbsp;</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP> <TT class=code>:koi8-r</TT></TD><TD VALIGN=top ALIGN=left NOWRAP>&nbsp;</TD><TD VALIGN=top ALIGN=left>&nbsp;</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP> <TT class=code>:mac-cyrillic</TT></TD><TD VALIGN=top ALIGN=left NOWRAP>&nbsp;</TD><TD VALIGN=top ALIGN=left>&nbsp;</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP> <TT class=code>:mac-greek</TT></TD><TD VALIGN=top ALIGN=left NOWRAP>&nbsp;</TD><TD VALIGN=top ALIGN=left>&nbsp;</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP> <TT class=code>:mac-icelandic</TT></TD><TD VALIGN=top ALIGN=left NOWRAP>&nbsp;</TD><TD VALIGN=top ALIGN=left>&nbsp;</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP> <TT class=code>:mac-latin2</TT></TD><TD VALIGN=top ALIGN=left NOWRAP>&nbsp;</TD><TD VALIGN=top ALIGN=left>&nbsp;</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP> <TT class=code>:mac-roman</TT></TD><TD VALIGN=top ALIGN=left NOWRAP>&nbsp;</TD><TD VALIGN=top ALIGN=left>&nbsp;</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP> <TT class=code>:mac-turkish</TT></TD><TD VALIGN=top ALIGN=left NOWRAP>&nbsp;</TD><TD VALIGN=top ALIGN=left>&nbsp;</TD></TR>
</TABLE>
<DIV CLASS="caption"><TABLE CELLSPACING=6 CELLPADDING=0><TR><TD VALIGN=top ALIGN=left>Table 13.1: External formats</TD></TR>
</TABLE></DIV>
<A NAME="table:external-formats"></A>
<DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV></DIV></BLOCKQUOTE><!--TOC subsection Composing External Formats-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc311">13.2.2</A>&#XA0;&#XA0;Composing External Formats</H3><!--SEC END --><P>A composing external format is an external format that converts between
one codepoint and another, rather than between codepoints and octets.
A composing external format must be used in conjunction with another
(octet-producing) external format. This is specified by
using a list as the external format. For example, we can use
</P><TT class=code>&#X2019;(<TT class=code>:latin1</TT> <TT class=code>:crlf</TT>)</TT><P> as the external format. In this
particular example, the external format is latin1, but whenever a
carriage-return/linefeed sequence is read, it is converted to the Lisp
</P><TT class=code>#\Newline</TT><P> character. Conversely, whenever a string is written,
a Lisp </P><TT class=code>#\Newline</TT><P> character is converted to a
carriage-return/linefeed sequence. Without the </P><TT class=code>:crlf</TT><P> composing
format, the carriage-return and linefeed will be read in as separate
characters, and on output the Lisp </P><TT class=code>#\Newline</TT><P> character is
output as a single linefeed character.</P><P>Table&#XA0;<A HREF="#table:composing-formats">13.2</A> lists the available composing formats.</P><BLOCKQUOTE CLASS="table"><DIV CLASS="center"><DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV>
<TABLE BORDER=1 CELLSPACING=0 CELLPADDING=1><TR><TD VALIGN=top ALIGN=left NOWRAP> <B>Format</B></TD><TD VALIGN=top ALIGN=left NOWRAP><B>Aliases</B></TD><TD VALIGN=top ALIGN=left><B>Description</B></TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP> <TT class=code>:crlf</TT></TD><TD VALIGN=top ALIGN=left NOWRAP><TT class=code>:dos</TT></TD><TD VALIGN=top ALIGN=left>Composing format for converting to/from DOS (CR/LF)
end-of-line sequence to <TT class=code>#\Newline</TT></TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP> <TT class=code>:cr</TT></TD><TD VALIGN=top ALIGN=left NOWRAP><TT class=code>:mac</TT></TD><TD VALIGN=top ALIGN=left>Composing format for converting to/from DOS (CR/LF)
end-of-line sequence to <TT class=code>#\Newline</TT></TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP> <TT class=code>:beta-gk</TT></TD><TD VALIGN=top ALIGN=left NOWRAP>&nbsp;</TD><TD VALIGN=top ALIGN=left>Composing format that translates (lower-case) Beta
code (an ASCII encoding of ancient Greek)</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP> <TT class=code>:final-sigma</TT></TD><TD VALIGN=top ALIGN=left NOWRAP>&nbsp;</TD><TD VALIGN=top ALIGN=left>Composing format that attempts to detect sigma in
word-final position and change it from U+3C3 to U+3C2</TD></TR>
</TABLE>
<DIV CLASS="caption"><TABLE CELLSPACING=6 CELLPADDING=0><TR><TD VALIGN=top ALIGN=left>Table 13.2: Composing external formats</TD></TR>
</TABLE></DIV>
<A NAME="table:composing-formats"></A>
<DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV></DIV></BLOCKQUOTE><!--TOC section Dictionary-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc312">13.3</A>&#XA0;&#XA0;Dictionary</H2><!--SEC END --><!--TOC subsection Variables-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc313">13.3.1</A>&#XA0;&#XA0;Variables</H3><!--SEC END --><P><BR>
<A NAME="@vars70"></A><A NAME="VR:default-external-format"></A>
</P><DIV align=left>
[Variable]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>*default-external-format*</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
This is the default external format to use for all newly opened
files. It is also the default format to use for
<TT class=variable>*standard-input*</TT>, <TT class=variable>*standard-output*</TT>, and
<TT class=variable>*standard-error*</TT>. The default value is <TT class=code>:iso8859-1</TT>.<P>Setting this will cause the standard streams to start using the new
format immediately. If a stream has been created with external
format </P><TT class=code>:default</TT><P>, then setting </P><TT class=variable>*default-external-format*</TT><P>
will cause all subsequent input and output to use the new value of
</P><TT class=variable>*default-external-format*</TT><P>.
</P></BLOCKQUOTE><!--TOC subsection Characters-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc314">13.3.2</A>&#XA0;&#XA0;Characters</H3><!--SEC END --><P>Remember that CMUCL&#X2019;s characters are only 16-bits long but Unicode
codepoints are up to 21 bits long. Hence there are codepoints that
cannot be represented via Lisp characters. Operating on individual
characters is not recommended. Operations on strings are better.
(This would be true even if CMUCL&#X2019;s characters could hold a
full Unicode codepoint.)</P><P><BR>
<A NAME="@funs348"></A><A NAME="FN:char-equal"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>char-equal</TT> <TT class=code>&amp;rest</TT> <TT class=variable>characters</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
<P><A NAME="@funs349"></A><A NAME="FN:char-not-equal"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>char-not-equal</TT> <TT class=code>&amp;rest</TT> <TT class=variable>characters</TT> &nbsp;&nbsp;&nbsp;
</DIV><P><A NAME="@funs350"></A><A NAME="FN:char-lessp"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>char-lessp</TT> <TT class=code>&amp;rest</TT> <TT class=variable>characters</TT> &nbsp;&nbsp;&nbsp;
</DIV><P><A NAME="@funs351"></A><A NAME="FN:char-greaterp"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>char-greaterp</TT> <TT class=code>&amp;rest</TT> <TT class=variable>characters</TT> &nbsp;&nbsp;&nbsp;
</DIV><P><A NAME="@funs352"></A><A NAME="FN:char-not-greaterp"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>char-not-greaterp</TT> <TT class=code>&amp;rest</TT> <TT class=variable>characters</TT> &nbsp;&nbsp;&nbsp;
</DIV><P><A NAME="@funs353"></A><A NAME="FN:char-not-lessp"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>char-not-lessp</TT> <TT class=code>&amp;rest</TT> <TT class=variable>characters</TT> &nbsp;&nbsp;&nbsp;
</DIV><P>
For the comparison, the characters are converted to lowercase and
the corresponding </P><TT class=code>char-code</TT><P> are compared.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs354"></A><A NAME="FN:alpha-char-p"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>alpha-char-p</TT> <TT class=variable>character</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Returns non-nil if the Unicode category is a letter category.
</BLOCKQUOTE><P><BR>
<A NAME="@funs355"></A><A NAME="FN:alphanumericp"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>alphanumericp</TT> <TT class=variable>character</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Returns non-nil if the Unicode category is a letter category or an ASCII
digit.
</BLOCKQUOTE><P><BR>
<A NAME="@funs356"></A><A NAME="FN:digit-char-p"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>digit-char-p</TT> <TT class=variable>character</TT> <TT class=code>&amp;optional</TT> <TT class=variable>radix</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Only recognizes ASCII digits (and ASCII letters if the radix is larger
than 10).
</BLOCKQUOTE><P><BR>
<A NAME="@funs357"></A><A NAME="FN:graphic-char-p"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>graphic-char-p</TT> <TT class=variable>character</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Returns non-nil if the Unicode category is a graphic category.
</BLOCKQUOTE><P><BR>
<A NAME="@funs358"></A><A NAME="FN:upper-case-p"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>upper-case-p</TT> <TT class=variable>character</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
<P><A NAME="@funs359"></A><A NAME="FN:lower-case-p"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>lower-case-p</TT> <TT class=variable>character</TT> &nbsp;&nbsp;&nbsp;
</DIV><P>
Returns non-nil if the Unicode category is an uppercase
(lowercase) character.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs360"></A><A NAME="FN:title-case-p"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>lisp:</TT><TT class=function-name>title-case-p</TT> <TT class=variable>character</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Returns non-nil if the Unicode category is a titlecase character.
</BLOCKQUOTE><P><BR>
<A NAME="@funs361"></A><A NAME="FN:both-case-p"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>both-case-p</TT> <TT class=variable>character</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Returns non-nil if the Unicode category is an uppercase,
lowercase, or titlecase character.
</BLOCKQUOTE><P><BR>
<A NAME="@funs362"></A><A NAME="FN:char-upcase"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>char-upcase</TT> <TT class=variable>character</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
<P><A NAME="@funs363"></A><A NAME="FN:char-downcase"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>char-downcase</TT> <TT class=variable>character</TT> &nbsp;&nbsp;&nbsp;
</DIV><P>
The Unicode uppercase (lowercase) letter is returned.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs364"></A><A NAME="FN:char-titlecase"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>lisp:</TT><TT class=function-name>char-titlecase</TT> <TT class=variable>character</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
The Unicode titlecase letter is returned.
</BLOCKQUOTE><P><BR>
<A NAME="@funs365"></A><A NAME="FN:char-name"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>char-name</TT> <TT class=variable>char</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
If possible the name of the character <TT class=variable>char</TT> is returned. If
there is a Unicode name, the Unicode name is returned, except
spaces are converted to underscores and the string is capitalized
via <TT class=code>string-capitalize</TT>. If there is no Unicode name, the
form <TT class=code>#\U+xxxx</TT> is returned where &#X201C;xxxx&#X201D; is the
<TT class=code>char-code</TT> of the character, in hexadecimal.
</BLOCKQUOTE><P><BR>
<A NAME="@funs366"></A><A NAME="FN:name-char"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>name-char</TT> <TT class=variable>name</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
The inverse to <TT class=code>char-name</TT>. If no character has the name
<TT class=variable>name</TT>, then <TT class=code>nil</TT> is returned. Unicode names are not
case-sensitive, and spaces and underscores are optional.
</BLOCKQUOTE><!--TOC subsection Strings-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc315">13.3.3</A>&#XA0;&#XA0;Strings</H3><!--SEC END --><P>Strings in CMUCL are UTF-16 strings. That is, for Unicode code
points greater than 65535, surrogate pairs are used. We refer the
reader to the Unicode standard for more information about surrogate
pairs. We just want to make a note that because of the UTF-16
encoding of strings, there is a distinction between Lisp characters
and Unicode codepoints. The standard string operations know about
this encoding and handle the surrogate pairs correctly.</P><P><BR>
<A NAME="@funs367"></A><A NAME="FN:string-upcase"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>string-upcase</TT> <TT class=variable>string</TT> <TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=code>:start</TT>
<TT class=code>:end</TT> <TT class=code>:casing</TT></SPAN> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
<P><A NAME="@funs368"></A><A NAME="FN:string-downcase"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>string-downcase</TT> <TT class=variable>string</TT> <TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=code>:start</TT>
<TT class=code>:end</TT> <TT class=code>:casing</TT></SPAN> &nbsp;&nbsp;&nbsp;
</DIV><P><A NAME="@funs369"></A><A NAME="FN:string-capitalize"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>string-capitalize</TT> <TT class=variable>string</TT> <TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=code>:start</TT>
<TT class=code>:end</TT> <TT class=code>:casing</TT></SPAN> &nbsp;&nbsp;&nbsp;
</DIV><P>
The case of the </P><TT class=variable>string</TT><P> is changed appropriately. Surrogate
pairs are handled correctly. The conversion to the appropriate case
is done based on the Unicode conversion. The additional argument
</P><TT class=code>:casing</TT><P> controls how case conversion is done. The default
value is </P><TT class=code>:simple</TT><P>, which uses simple Unicode case conversion.
If </P><TT class=code>:casing</TT><P> is </P><TT class=code>:full</TT><P>, then full Unicode case conversion is
done where the string may actually increase in length.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs370"></A><A NAME="FN:nstring-upcase"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>nstring-upcase</TT> <TT class=variable>string</TT> <TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=code>:start</TT> <TT class=code>:end</TT></SPAN> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
<P><A NAME="@funs371"></A><A NAME="FN:nstring-downcase"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>nstring-downcase</TT> <TT class=variable>string</TT> <TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=code>:start</TT> <TT class=code>:end</TT></SPAN> &nbsp;&nbsp;&nbsp;
</DIV><P><A NAME="@funs372"></A><A NAME="FN:nstring-capitalize"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>nstring-capitalize</TT> <TT class=variable>string</TT> <TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=code>:start</TT>
<TT class=code>:end</TT></SPAN> &nbsp;&nbsp;&nbsp;
</DIV><P>
The case of the </P><TT class=variable>string</TT><P> is changed appropriately. Surrogate
pairs are handled correctly. The conversion to the appropriate case
is done based on the Unicode conversion. (Full casing is not
available because the string length cannot be increased when needed.)
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs373"></A><A NAME="FN:string="></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>string=</TT> <TT class=variable>s1</TT> <TT class=variable>s2</TT> <TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=code>:start1</TT>
<TT class=code>:end1</TT> <TT class=code>:start2</TT> <TT class=code>:end2</TT></SPAN> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
<P><A NAME="@funs374"></A><A NAME="FN:string/="></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>string/=</TT> <TT class=variable>s1</TT> <TT class=variable>s2</TT> <TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=code>:start1</TT> <TT class=code>:end1</TT> <TT class=code>:start2</TT> <TT class=code>:end2</TT></SPAN> &nbsp;&nbsp;&nbsp;
</DIV><P><A NAME="@funs375"></A><A NAME="FN:string$></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>string&lt;</TT> <TT class=variable>s1</TT> <TT class=variable>s2</TT> <TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=code>:start1</TT> <TT class=code>:end1</TT> <TT class=code>:start2</TT> <TT class=code>:end2</TT></SPAN> &nbsp;&nbsp;&nbsp;
</DIV><P><A NAME="@funs376"></A><A NAME="FN:string$>$"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>string&gt;</TT> <TT class=variable>s1</TT> <TT class=variable>s2</TT> <TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=code>:start1</TT> <TT class=code>:end1</TT> <TT class=code>:start2</TT> <TT class=code>:end2</TT></SPAN> &nbsp;&nbsp;&nbsp;
</DIV><P><A NAME="@funs377"></A><A NAME="FN:string$></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>string&lt;=</TT> <TT class=variable>s1</TT> <TT class=variable>s2</TT> <TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=code>:start1</TT> <TT class=code>:end1</TT> <TT class=code>:start2</TT> <TT class=code>:end2</TT></SPAN> &nbsp;&nbsp;&nbsp;
</DIV><P><A NAME="@funs378"></A><A NAME="FN:string$>$="></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>string&gt;=</TT> <TT class=variable>s1</TT> <TT class=variable>s2</TT> <TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=code>:start1</TT> <TT class=code>:end1</TT> <TT class=code>:start2</TT> <TT class=code>:end2</TT></SPAN> &nbsp;&nbsp;&nbsp;
</DIV><P>
The string comparison is done in codepoint order. (This is
different from just comparing the order of the individual characters
due to surrogate pairs.) Unicode collation is not done.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs379"></A><A NAME="FN:string-equal"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>string-equal</TT> <TT class=variable>s1</TT> <TT class=variable>s2</TT> <TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=code>:start1</TT>
<TT class=code>:end1</TT> <TT class=code>:start2</TT> <TT class=code>:end2</TT></SPAN> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
<P><A NAME="@funs380"></A><A NAME="FN:string-not-equal"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>string-not-equal</TT> <TT class=variable>s1</TT> <TT class=variable>s2</TT> <TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=code>:start1</TT> <TT class=code>:end1</TT> <TT class=code>:start2</TT> <TT class=code>:end2</TT></SPAN> &nbsp;&nbsp;&nbsp;
</DIV><P><A NAME="@funs381"></A><A NAME="FN:string-lessp"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>string-lessp</TT> <TT class=variable>s1</TT> <TT class=variable>s2</TT> <TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=code>:start1</TT> <TT class=code>:end1</TT> <TT class=code>:start2</TT> <TT class=code>:end2</TT></SPAN> &nbsp;&nbsp;&nbsp;
</DIV><P><A NAME="@funs382"></A><A NAME="FN:string-greaterp"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>string-greaterp</TT> <TT class=variable>s1</TT> <TT class=variable>s2</TT> <TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=code>:start1</TT> <TT class=code>:end1</TT> <TT class=code>:start2</TT> <TT class=code>:end2</TT></SPAN> &nbsp;&nbsp;&nbsp;
</DIV><P><A NAME="@funs383"></A><A NAME="FN:string-not-greaterp"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>string-not-greaterp</TT> <TT class=variable>s1</TT> <TT class=variable>s2</TT> <TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=code>:start1</TT> <TT class=code>:end1</TT> <TT class=code>:start2</TT> <TT class=code>:end2</TT></SPAN> &nbsp;&nbsp;&nbsp;
</DIV><P><A NAME="@funs384"></A><A NAME="FN:string-not-lessp"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>string-not-lessp</TT> <TT class=variable>s1</TT> <TT class=variable>s2</TT> <TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=code>:start1</TT> <TT class=code>:end1</TT> <TT class=code>:start2</TT> <TT class=code>:end2</TT></SPAN> &nbsp;&nbsp;&nbsp;
</DIV><P>
Each codepoint in each string is converted to lowercase and the
appropriate comparison of the codepoint values is done. Unicode
collation is not done.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs385"></A><A NAME="FN:string-left-trim"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>string-left-trim</TT> <TT class=variable>bag</TT> <TT class=variable>string</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
<P><A NAME="@funs386"></A><A NAME="FN:string-right-trim"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>string-right-trim</TT> <TT class=variable>bag</TT> <TT class=variable>string</TT> &nbsp;&nbsp;&nbsp;
</DIV><P><A NAME="@funs387"></A><A NAME="FN:string-trim"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>string-trim</TT> <TT class=variable>bag</TT> <TT class=variable>string</TT> &nbsp;&nbsp;&nbsp;
</DIV><P>
Removes any characters in </P><TT class=code>bag</TT><P> from the left, right, or both
ends of the string </P><TT class=code>string</TT><P>, respectively. This has potential
problems if you want to remove a surrogate character from the
string, since a single character cannot represent a surrogate. As
an extension, if </P><TT class=code>bag</TT><P> is a string, we properly handle
surrogate characters in the </P><TT class=code>bag</TT><P>.
</P></BLOCKQUOTE><!--TOC subsection Sequences-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc316">13.3.4</A>&#XA0;&#XA0;Sequences</H3><!--SEC END --><P>Since strings are also sequences, the sequence functions can be used
on strings. We note here some issues with these functions. Most
issues are due to the fact that strings are UTF-16 strings and
characters are UTF-16 code units, not Unicode codepoints.</P><P><BR>
<A NAME="@funs388"></A><A NAME="FN:remove-duplicates"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>remove-duplicates</TT> <TT class=variable>sequence</TT>
<TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=code>:from-end</TT> <TT class=code>:test</TT> <TT class=code>:test-not</TT> <TT class=code>:start</TT>
<TT class=code>:end</TT> <TT class=code>:key</TT></SPAN> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
<P><A NAME="@funs389"></A><A NAME="FN:delete-duplicates"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>delete-duplicates</TT> <TT class=variable>sequence</TT>
<TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=code>:from-end</TT> <TT class=code>:test</TT> <TT class=code>:test-not</TT> <TT class=code>:start</TT>
<TT class=code>:end</TT> <TT class=code>:key</TT></SPAN> &nbsp;&nbsp;&nbsp;
</DIV><P>
Because of surrogate pairs these functions may remove a high or low
surrogate value, leaving the string in an invalid state. Use these
functions carefully with strings.
</P></BLOCKQUOTE><!--TOC subsection Reader-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc317">13.3.5</A>&#XA0;&#XA0;Reader</H3><!--SEC END --><P>To support Unicode characters, the reader has been extended to
recognize characters written in hexadecimal. Thus </P><TT class=code>#\U+41</TT><P> is
the ASCII capital letter &#X201C;A&#X201D;, since 41 is the hexadecimal code for
that letter. The Unicode name of the character is also recognized,
except spaces in the name are replaced by underscores.</P><P>Recall, however, that characters in CMUCL are only 16 bits long so
many Unicode characters cannot be represented. However, strings can
represent all Unicode characters.</P><P>When symbols are read, the symbol name is converted to Unicode NFC
form before interning the symbol into the package. Hence,
</P><TT class=code>symbol-name (intern &#X201C;string&#X201D;)</TT><P> may produce a string that is
not </P><TT class=code>string=</TT><P> to &#X201C;string&#X201D;. However, after conversion to NFC
form, the strings will be identical.</P><!--TOC subsection Printer-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc318">13.3.6</A>&#XA0;&#XA0;Printer</H3><!--SEC END --><P>When printing characters, if the character is a graphic character, the
character is printed. Thus </P><TT class=code>#\U+41</TT><P> is printed as
</P><TT class=code>#\A</TT><P>. If the character is not a graphic character, the Lisp
name (e.g., </P><TT class=code>#\Tab</TT><P>) is used if possible;
if there is no Lisp name, the Unicode name is used. If there is no
Unicode name, the hexadecimal char-code is
printed. For example, </P><TT class=code>#\U+34e</TT><P>, which is not a graphic
character, is printed as </P><TT class=code>#\Combining_Upwards_Arrow_Below</TT><P>,
and </P><TT class=code>#\U+9f</TT><P> which is not a graphic character and does not have a
Unicode name, is printed as </P><TT class=code>#\U+009F</TT><P>.</P><!--TOC subsection Miscellaneous-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc319">13.3.7</A>&#XA0;&#XA0;Miscellaneous</H3><!--SEC END --><!--TOC subsubsection Files-->
<H4 CLASS="subsubsection"><!--SEC ANCHOR -->13.3.7.1&#XA0;&#XA0;Files</H4><!--SEC END --><P>CMUCL loads external formats using the search-list
</P><TT class=filename>ext-formats:</TT><P>. The </P><TT class=filename>aliases</TT><P> file is also located using
this search-list.</P><P>The Unicode data base is stored in compressed form in the file
</P><TT class=filename>ext-formats:unidata.bin</TT><P>. If this file is not found, Unicode
support is severely reduced; you can only use ASCII characters.</P><P><BR>
<A NAME="@funs390"></A><A NAME="FN:open"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>open</TT> <TT class=variable>filename</TT> <TT class=code>&amp;rest</TT><TT class=variable>options</TT>
<TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=code>:direction</TT> <TT class=code>:element-type</TT> <TT class=code>:if-exists</TT>
<TT class=code>:if-does-not-exist</TT><BR>
 <TT class=code>:class</TT> <TT class=code>:mapped</TT>
<TT class=code>:input-handle</TT> <TT class=code>:output-handle</TT><BR>
 <TT class=code>:external-format</TT> <TT class=code>:decoding-error</TT>
<TT class=code>:encoding-error</TT></SPAN> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote"><P>The main options are covered elsewhere. Here we describe the
options specific to Unicode. The option </P><TT class=code>:external-format</TT><P>
specifies the external format to use for reading and writing the
file. The external format is a keyword.</P><P>The options </P><TT class=code>:decoding-error</TT><P> and </P><TT class=code>:encoding-error</TT><P> are used
to specify how encoding and decoding errors are handled. The
default value on </P><TT class=code>nil</TT><P>means the external format handles errors
itself and typically replaces invalid sequences with the Unicode
replacement character.</P><P>Otherwise, the value for </P><TT class=code>decoding-error</TT><P> is either a
character, a symbol or a function. If a character is
specified. it is used as the replacement character for any invalid
decoding. If a symbol or a function is given, it must be a
function of three arguments: a message string to be printed, the
offending octet, and the number of octets read. If the function
returns, it should return two values: the code point to use as the
replacement character and the number of octets read. In addition,
</P><TT class=code>t</TT><P> may be specified. This indicates that a continuable error
is signaled, which, if continued, the Unicode replacement
character is used.</P><P>For </P><TT class=code>encoding-error</TT><P>, a character, symbol, or function can be
specified, like </P><TT class=code>decoding-error</TT><P>, with the same meaning. The
function, however, takes two arguments: a format message string
and the incorrect codepoint. If the function returns, it should
be the replacement codepoint.
</P></BLOCKQUOTE><!--TOC subsubsection Utilities-->
<H4 CLASS="subsubsection"><!--SEC ANCHOR -->13.3.7.2&#XA0;&#XA0;Utilities</H4><!--SEC END --><P><BR>
<A NAME="@funs391"></A><A NAME="FN:set-system-external-format"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>stream:</TT><TT class=function-name>set-system-external-format</TT> <TT class=variable>terminal</TT> <TT class=code>&amp;optional</TT> <TT class=variable>filenames</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
This function changes the external format used for
<TT class=variable>*standard-input*</TT>, <TT class=variable>*standard-output*</TT>, and
<TT class=variable>*standard-error*</TT> to the external format specified by
<TT class=variable>terminal</TT>. Additionally, the Unix file name encoding can be
set to the value specified by <TT class=variable>filenames</TT> if non-<TT class=code>nil</TT>.
</BLOCKQUOTE><P><BR>
<A NAME="@funs392"></A><A NAME="FN:list-all-external-formats"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>list-all-external-formats</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
list all of the vailable external formats. A list is returned where
each element is a list of the external format name and a list of
aliases for the format. No distinction is made between external
formats and composing external formats.
</BLOCKQUOTE><P><BR>
<A NAME="@funs393"></A><A NAME="FN:describe-external-format"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>extensions:</TT><TT class=function-name>describe-external-format</TT> external-format &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Print a description of the given <TT class=variable>external-format</TT>. This may
cause the external format to be loaded (silently) if it is not
already loaded.
</BLOCKQUOTE><P>Since strings are UTF-16 and hence may contain surrogate pairs, some
utility functions are provided to make access easier.</P><P><BR>
<A NAME="@funs394"></A><A NAME="FN:codepoint"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>lisp:</TT><TT class=function-name>codepoint</TT> <TT class=variable>string</TT> <TT class=variable>i</TT>
<TT class=code>&amp;optional</TT> <TT class=variable>end</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Return the codepoint value from <TT class=variable>string</TT> at position <TT class=variable>i</TT>.
If code unit at that position is a surrogate value, it is combined
with either the previous or following code unit (when possible) to
compute the codepoint. The first return value is the codepoint
itself. The second return value is <TT class=code>nil</TT> if the position is not a
surrogate pair. Otherwise, +1 or &#X2212;1 is returned if the position
is the high (leading) or low (trailing) surrogate value, respectively.<P>This is useful for iterating through a string in codepoint sequence.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs395"></A><A NAME="FN:surrogates-to-codepoint"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>lisp:</TT><TT class=function-name>surrogates-to-codepoint</TT> <TT class=variable>hi</TT> <TT class=variable>lo</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Convert the given <TT class=variable>hi</TT> and <TT class=variable>lo</TT> surrogate characters to the
corresponding codepoint value
</BLOCKQUOTE><P><BR>
<A NAME="@funs396"></A><A NAME="FN:surrogates"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>lisp:</TT><TT class=function-name>surrogates</TT> <TT class=variable>codepoint</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Convert the given <TT class=variable>codepoint</TT> value to the corresponding high
and low surrogate characters. If the codepoint is less than 65536,
the second value is <TT class=code>nil</TT> since the codepoint does not need to be
represented as a surrogate pair.
</BLOCKQUOTE><P><BR>
<A NAME="@funs397"></A><A NAME="FN:string-encode"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>stream:</TT><TT class=function-name>string-encode</TT> <TT class=variable>string</TT>
<TT class=variable>external-format</TT> <TT class=code>&amp;optional</TT> (<TT class=variable>start</TT> 0) <TT class=variable>end</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
<TT class=code>string-encode</TT> encodes <TT class=variable>string</TT> using the format
<TT class=variable>external-format</TT>, producing an array of octets. Each octet is
converted to a character via <TT class=code>code-char</TT> and the resulting
string is returned.<P>The optional argument </P><TT class=variable>start</TT><P>, defaulting to 0, specifies the
starting index and </P><TT class=variable>end</TT><P>, defaulting to the length of the
string, is the end of the string.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs398"></A><A NAME="FN:string-decode"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>stream:</TT><TT class=function-name>string-decode</TT> <TT class=variable>string</TT>
<TT class=variable>external-format</TT> <TT class=code>&amp;optional</TT> (<TT class=variable>start</TT> 0) <TT class=variable>end</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
<TT class=code>string-decode</TT> decodes <TT class=variable>string</TT> using the format
<TT class=variable>external-format</TT> and produces a new string. Each character of
<TT class=variable>string</TT> is converted to octet (by <TT class=code>char-code</TT>) and the
resulting array of octets is used by the external format to produce
a string. This is the inverse of <TT class=code>string-encode</TT>.<P>The optional argument </P><TT class=variable>start</TT><P>, defaulting to 0, specifies the
starting index and </P><TT class=variable>end</TT><P>, defaulting to the length of the
string, is the end of the string.</P><TT class=variable>string</TT><P> must consist of characters whose </P><TT class=code>char-code</TT><P> is
less than 256.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs399"></A><A NAME="FN:string-to-octets"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>string-to-octets</TT> <TT class=variable>string</TT> <TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=code>:start</TT>
<TT class=code>:end</TT> <TT class=code>:external-format</TT> <TT class=code>:buffer</TT></SPAN> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
<TT class=code>string-to-octets</TT> converts <TT class=variable>string</TT> to a sequence of
octets according to the external format specified by
<TT class=variable>external-format</TT>. The string to be converted is bounded by
<TT class=variable>start</TT>, which defaults to 0, and <TT class=variable>end</TT>, which defaults to
the length of the string. If <TT class=variable>buffer</TT> is specified, the octets
are placed in <TT class=variable>buffer</TT>. If <TT class=variable>buffer</TT> is not specified, a new
array is allocated to hold the octets. In all cases the buffer is
returned.
</BLOCKQUOTE><P><BR>
<A NAME="@funs400"></A><A NAME="FN:octets-to-string"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>octets-to-string</TT> <TT class=variable>octets</TT> <TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=code>:start</TT>
<TT class=code>:end</TT> <TT class=code>:external-format</TT> <TT class=code>:string</TT> <TT class=code>:s-start</TT>
<TT class=code>:s-end</TT> <TT class=code>:state</TT></SPAN> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
<TT class=code>octets-to-string</TT> converts the sequence of octets in
<TT class=variable>octets</TT> to a string. <TT class=variable>octets</TT> must be a
<TT class=code>(simple-array (unsigned-byte 8) (*))</TT>. The octets to be
converted are bounded by <TT class=variable>start</TT> and <TT class=variable>end</TT>, which default to
0 and the length of the array, respectively. The conversion is
performed according to the external format specified by
<TT class=variable>external-format</TT>. If <TT class=variable>string</TT> is specified, the octets are
converted and stored in <TT class=variable>string</TT>, starting at <TT class=variable>s-start</TT>
(defaulting to 0) and ending just before <TT class=variable>s-end</TT> (defaulting to
the end of <TT class=variable>string</TT>. <TT class=variable>string</TT> must be <TT class=code>simple-string</TT>.
If the bounded string is not large enough to hold all of the
characters, then some octets will not be converted. If <TT class=variable>string</TT>
is not specified, a new string is created.<P>The </P><TT class=variable>state</TT><P> is used as the initial state of for the external
format. This is useful when converting buffers of octets where the
buffers are not on character boundaries, and state information is
needed between buffers.</P><P>Four values are returned: the string, the number of characters
written to the string, and the number of octets consumed to produce
the characters, and the final state of external format after
converting the octets.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs401"></A><A NAME="FN:list-all-external-formats"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>list-all-external-formats</TT>  &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
<TT class=code>list-all-external-formats</TT> produces a list of all known
external formats and the known aliases for for them. Each element
of the list is a list consisting of the name of the external format
and a list of the known aliases for the format.
</BLOCKQUOTE><P><BR>
<A NAME="@funs402"></A><A NAME="FN:describe-external-format"></A></P><DIV align=left>
[Function]<BR>
 <TT class=function-name>describe-external-format</TT> <TT class=variable>external-format</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
<TT class=code>describe-external-format</TT> prints a description of the
specified external-format.
</BLOCKQUOTE><!--TOC section Writing External Formats-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc320">13.4</A>&#XA0;&#XA0;Writing External Formats</H2><!--SEC END --><!--TOC subsection External Formats-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc321">13.4.1</A>&#XA0;&#XA0;External Formats</H3><!--SEC END --><P>
Users may write their own external formats. It is probably easiest to
look at existing external formats to see how do this.</P><P>An external format basically needs two functions:
</P><TT class=code>octets-to-code</TT><P> to convert octets to Unicode codepoints and
</P><TT class=code>code-to-octets</TT><P> to convert Unicode codepoints to octets. The
external format is defined using the macro
</P><TT class=code>stream::define-external-format</TT><P>.</P><P><BR>
<A NAME="@funs403"></A><A NAME="FN:b"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>[</TT><TT class=function-name>b</TT> a &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">se]stream:define-external-format<TT class=variable>name</TT>
(<TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=variable>base</TT> <TT class=variable>min</TT> <TT class=variable>max</TT> <TT class=variable>size</TT>
<TT class=variable>documentation</TT></SPAN>)
(<TT class=code>&amp;rest</TT> <TT class=variable>slots</TT>)<BR>
 <TT class=variable>octets-to-code</TT> <TT class=variable>code-to-octets</TT>
<TT class=variable>flush-state</TT> <TT class=variable>copy-state</TT><P>If </P><TT class=code>:base</TT><P> is not given, this defines a new external format of
the name </P><TT class=code>:name</TT><P>. </P><TT class=variable>min</TT><P>, </P><TT class=variable>max</TT><P>, and </P><TT class=variable>size</TT><P> are the
minimum and maximum number of octets that make up a character.
(</P><TT class=code><TT class=code>:size</TT> n</TT><P> is just a short cut for </P><TT class=code><TT class=code>:min</TT> n
<TT class=code>:max</TT> n</TT><P>.) The description of the external format can be
given using </P><TT class=code>:documentation</TT><P>. The arguments </P><TT class=variable>octets-to-code</TT><P>
and </P><TT class=variable>code-to-octets</TT><P> are not optional in this case. They
specify how to convert octets to codepoints and vice versa,
respectively. These should be backquoted forms for the body of a
function to do the conversion. See the description below for these
functions. Some good examples are the external format for
</P><TT class=code>:utf-8</TT><P> or </P><TT class=code>:utf-16</TT><P>. The </P><TT class=code>:slots</TT><P> argument is a list of
read-only slots, similar to defstruct. The slot names are available
as local variables inside the </P><TT class=variable>code-to-octets</TT><P> and
</P><TT class=variable>octets-to-code</TT><P> bodies. </P><P>If </P><TT class=code>:base</TT><P> is given, then an external format is defined with the
name </P><TT class=code>:name</TT><P> that is based on a previously defined format
</P><TT class=code>:base</TT><P>. The </P><TT class=variable>slots</TT><P> are inherited from the </P><TT class=code>:base</TT><P> format
by default, although the definition may alter their values and add
new slots. See, for example, the </P><TT class=code>:mac-greek</TT><P> external format. </P></BLOCKQUOTE><P><BR>
<A NAME="@funs404"></A><A NAME="FN:octets-to-code"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>octets-to-code</TT> <TT class=variable>state</TT> <TT class=variable>input</TT>
<TT class=variable>unput</TT> <TT class=variable>error</TT> <TT class=code>&amp;rest</TT> <TT class=variable>args</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
This defines a form to be used by an external format to convert
octets to a code point. <TT class=variable>state</TT> is a form that can be used by
the body to access the state variable of a stream. This can be used
for any reason to hold anything needed by <TT class=code>octets-to-code</TT>.
<TT class=variable>input</TT> is a form that returns one octet from the input stream.
<TT class=variable>unput</TT> will put back <TT class=variable>N</TT> octets to the stream. <TT class=variable>args</TT> is a
list of variables that need to be defined for any symbols in the
body of the macro.<TT class=variable>error</TT><P> controls how errors are handled. If </P><TT class=code>nil</TT><P>, some suitable
replacement character is used. That is, any errors are silently
ignored and replaced by some replacement character. If non-</P><TT class=code>nil</TT><P>,
</P><TT class=variable>error</TT><P> is a symbol or function that is called to handle the
error. This function takes three arguments: a message string, the
invalid octet (or </P><TT class=code>nil</TT><P>), and a count of the number of octets that
have been read so far. If the function returns, it should be the
codepoint of the desired replacement character.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs405"></A><A NAME="FN:code-to-octets"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>code-to-octets</TT> <TT class=variable>code</TT> <TT class=variable>state</TT>
<TT class=variable>output</TT> <TT class=variable>error</TT> <TT class=code>&amp;rest</TT> <TT class=variable>args</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Defines a form to be used by the external format to convert a code
point to octets for output. <TT class=variable>code</TT> is the code point to be
converted. <TT class=variable>state</TT> is a form to access the current value of the
stream&#X2019;s state variable. <TT class=variable>output</TT> is a form that writes one
octet to the output stream.<P>Similar to </P><TT class=code>octets-to-code</TT><P>, </P><TT class=variable>error</TT><P> indicates how errors
should be handled. If </P><TT class=code>nil</TT><P>, some default replacement character is
substituted. If non-</P><TT class=code>nil</TT><P>, </P><TT class=variable>error</TT><P> should be a symbol or
function. This function takes two arguments: a message string and
the invalid codepoint. If the function returns, it should be the
codepoint that will be substituted for the invalid codepoint.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs406"></A><A NAME="FN:flush-state"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>flush-state</TT> <TT class=variable>state</TT>
<TT class=variable>output</TT> <TT class=variable>error</TT> <TT class=code>&amp;rest</TT> <TT class=variable>args</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Defines a form to be used by the external format to flush out
any state when an output stream is closed. Similar to
<TT class=code>code-to-octets</TT>, but there is no code point to be output. The
<TT class=variable>error</TT> argument indicates how to handle errors. If <TT class=code>nil</TT>, some
default replacement character is used. Otherwise, <TT class=variable>error</TT> is a
symbol or function that will be called with a message string and
codepoint of the offending state. If the function returns, it
should be the codepoint of a suitable replacement.<P>If </P><TT class=code>flush-state</TT><P> is </P><TT class=code>nil</TT><P>, then nothing special is needed to
flush the state to the output.</P><P>This is called only when an output character stream is being closed.
</P></BLOCKQUOTE><P><BR>
<A NAME="@funs407"></A><A NAME="FN:copy-state"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>copy-state</TT> <TT class=variable>state</TT> <TT class=code>&amp;rest</TT> <TT class=variable>args</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
Defines a form to copy any state needed by the external format.
This should probably be a deep copy so that if the original
state is modified, the copy is not.<P>If not given, then nothing special is needed to copy the state
either because there is no state for the external format or that no
special copier is needed.
</P></BLOCKQUOTE><!--TOC subsection Composing External Formats-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc322">13.4.2</A>&#XA0;&#XA0;Composing External Formats</H3><!--SEC END --><P><BR>
<A NAME="@funs408"></A><A NAME="FN:define-composing-external-format"></A></P><DIV align=left>
[Macro]<BR>
 <TT class=function-name>stream:</TT><TT class=function-name>define-composing-external-format</TT> <TT class=variable>name</TT>
(<TT class=code>&amp;key</TT> <SPAN style="text-decoration:overline"><TT class=variable>min</TT> <TT class=variable>max</TT> <TT class=variable>size</TT> <TT class=variable>documentation</TT></SPAN>) <TT class=variable>input</TT>
<TT class=variable>output</TT> &nbsp;&nbsp;&nbsp;
</DIV><BLOCKQUOTE CLASS="quote">
This is the same as <TT class=code>define-external-format</TT>, except that a
composing external format is created.
</BLOCKQUOTE><!--NAME unicode.html-->
<P><A NAME="@concept299"></A>
</P><!--TOC chapter Function Index-->
<H1 CLASS="chapter"><!--SEC ANCHOR -->Function Index</H1><!--SEC END --><P></P><TABLE CELLSPACING=6 CELLPADDING=0><TR><TD VALIGN=top ALIGN=left><UL CLASS="indexenv"><LI CLASS="li-indexenv">
-, <A HREF="#@funs23"><B>2.7</B></A>, <A HREF="#@funs26"><B>2.7.2</B></A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">accept-network-stream, <A HREF="#@funs268"><B>10.4</B></A>
</LI><LI CLASS="li-indexenv">accept-tcp-connection, <A HREF="#@funs266"><B>10.4</B></A>
</LI><LI CLASS="li-indexenv">accept-unix-connection, <A HREF="#@funs267"><B>10.4</B></A>
</LI><LI CLASS="li-indexenv">activate-breakpoint, <A HREF="#@funs316"><B>11.6</B></A>
</LI><LI CLASS="li-indexenv">add-fd-handler, <A HREF="#@funs190"><B>7.3</B></A>
</LI><LI CLASS="li-indexenv">add-oob-handler, <A HREF="#@funs272"><B>10.6</B></A>
</LI><LI CLASS="li-indexenv">add-xwindow-object, <A HREF="#@funs187"><B>7.1</B></A>
</LI><LI CLASS="li-indexenv">addr, <A HREF="#@funs209"><B>8.3.2</B></A>
</LI><LI CLASS="li-indexenv">alien-funcall, <A HREF="#@funs206">8.2.3</A>, <A HREF="#@funs223"><B>8.7.1</B></A>, <A HREF="#@funs226">8.7.2</A>
</LI><LI CLASS="li-indexenv">alien-sap, <A HREF="#@funs213"><B>8.3.2</B></A>
</LI><LI CLASS="li-indexenv">alpha-char-p, <A HREF="#@funs354"><B>13.3.2</B></A>
</LI><LI CLASS="li-indexenv">alphanumericp, <A HREF="#@funs355"><B>13.3.2</B></A>
</LI><LI CLASS="li-indexenv">ambiguous-debug-variables, <A HREF="#@funs305"><B>11.4</B></A>
</LI><LI CLASS="li-indexenv">ambiguous-files, <A HREF="#@funs70"><B>2.17.2</B></A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">b, <A HREF="#@funs403"><B>13.4.1</B></A>
</LI><LI CLASS="li-indexenv">bind-inet-socket, <A HREF="#@funs278"><B>10.7</B></A>
</LI><LI CLASS="li-indexenv">both-case-p, <A HREF="#@funs361"><B>13.3.2</B></A>
</LI><LI CLASS="li-indexenv">break, <A HREF="#@funs110">3.1</A>
</LI><LI CLASS="li-indexenv">breakpoint-active-p, <A HREF="#@funs318"><B>11.6</B></A>
</LI><LI CLASS="li-indexenv">breakpoint-hook-function, <A HREF="#@funs319"><B>11.6</B></A>
</LI><LI CLASS="li-indexenv">breakpoint-info, <A HREF="#@funs320"><B>11.6</B></A>
</LI><LI CLASS="li-indexenv">breakpoint-kind, <A HREF="#@funs321"><B>11.6</B></A>
</LI><LI CLASS="li-indexenv">breakpoint-what, <A HREF="#@funs322"><B>11.6</B></A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">callback, <A HREF="#@funs229">8.7.4</A>, <A HREF="#@funs230"><B>8.7.4</B></A>
</LI><LI CLASS="li-indexenv">callback-funcall, <A HREF="#@funs231"><B>8.7.4</B></A>
</LI><LI CLASS="li-indexenv">cancel-finalization, <A HREF="#@funs34"><B>2.7.4</B></A>
</LI><LI CLASS="li-indexenv">cast, <A HREF="#@funs211"><B>8.3.2</B></A>
</LI><LI CLASS="li-indexenv">ceiling, <A HREF="#@funs9">2.1.2.5</A>
</LI><LI CLASS="li-indexenv">char-downcase, <A HREF="#@funs363"><B>13.3.2</B></A>
</LI><LI CLASS="li-indexenv">char-equal, <A HREF="#@funs348"><B>13.3.2</B></A>
</LI><LI CLASS="li-indexenv">char-greaterp, <A HREF="#@funs351"><B>13.3.2</B></A>
</LI><LI CLASS="li-indexenv">char-lessp, <A HREF="#@funs350"><B>13.3.2</B></A>
</LI><LI CLASS="li-indexenv">char-name, <A HREF="#@funs365"><B>13.3.2</B></A>
</LI><LI CLASS="li-indexenv">char-not-equal, <A HREF="#@funs349"><B>13.3.2</B></A>
</LI><LI CLASS="li-indexenv">char-not-greaterp, <A HREF="#@funs352"><B>13.3.2</B></A>
</LI><LI CLASS="li-indexenv">char-not-lessp, <A HREF="#@funs353"><B>13.3.2</B></A>
</LI><LI CLASS="li-indexenv">char-titlecase, <A HREF="#@funs364"><B>13.3.2</B></A>
</LI><LI CLASS="li-indexenv">char-upcase, <A HREF="#@funs362"><B>13.3.2</B></A>
</LI><LI CLASS="li-indexenv">clear-search-list, <A HREF="#@funs65"><B>2.16.6</B></A>
</LI><LI CLASS="li-indexenv">close-socket, <A HREF="#@funs281"><B>10.7</B></A>
</LI><LI CLASS="li-indexenv">cmd-switch-arg, <A HREF="#@funs159"><B>6.1</B></A>
</LI><LI CLASS="li-indexenv">cmd-switch-name, <A HREF="#@funs156"><B>6.1</B></A>
</LI><LI CLASS="li-indexenv">cmd-switch-value, <A HREF="#@funs157"><B>6.1</B></A>
</LI><LI CLASS="li-indexenv">cmd-switch-words, <A HREF="#@funs158"><B>6.1</B></A>
</LI><LI CLASS="li-indexenv">code-location-debug-block, <A HREF="#@funs325"><B>11.7</B></A>
</LI><LI CLASS="li-indexenv">code-location-debug-function, <A HREF="#@funs324"><B>11.7</B></A>
</LI><LI CLASS="li-indexenv">code-location-debug-source, <A HREF="#@funs329"><B>11.7</B></A>
</LI><LI CLASS="li-indexenv">code-location-form-number, <A HREF="#@funs327"><B>11.7</B></A>
</LI><LI CLASS="li-indexenv">code-location-top-level-form-offset, <A HREF="#@funs326"><B>11.7</B></A>
</LI><LI CLASS="li-indexenv">code-location-unknown-p, <A HREF="#@funs330"><B>11.7</B></A>
</LI><LI CLASS="li-indexenv">code-location=, <A HREF="#@funs331"><B>11.7</B></A>
</LI><LI CLASS="li-indexenv">code-to-octets, <A HREF="#@funs405"><B>13.4.1</B></A>
</LI><LI CLASS="li-indexenv">codepoint, <A HREF="#@funs394"><B>13.3.7.2</B></A>
</LI><LI CLASS="li-indexenv">compile, <A HREF="#@funs121"><B>4.2</B></A>
</LI><LI CLASS="li-indexenv">compile-file, <A HREF="#@funs113">3.5.1</A>, <A HREF="#@funs122"><B>4.2</B></A>, <A HREF="#@funs144">5.7.3</A>, <A HREF="#@funs146">5.9</A>
</LI><LI CLASS="li-indexenv">compile-from-stream, <A HREF="#@funs123"><B>4.2</B></A>
</LI><LI CLASS="li-indexenv">complete-file, <A HREF="#@funs69"><B>2.17.2</B></A>
</LI><LI CLASS="li-indexenv">connect-to-inet-socket, <A HREF="#@funs269"><B>10.5</B></A>
</LI><LI CLASS="li-indexenv">connect-to-remote-server, <A HREF="#@funs236"><B>9.1.1</B></A>
</LI><LI CLASS="li-indexenv">connect-to-unix-socket, <A HREF="#@funs270"><B>10.5</B></A>
</LI><LI CLASS="li-indexenv">constantly, <A HREF="#@funs84"><B>2.24.1</B></A>
</LI><LI CLASS="li-indexenv">copy-state, <A HREF="#@funs407"><B>13.4.1</B></A>
</LI><LI CLASS="li-indexenv">create-inet-listener, <A HREF="#@funs264"><B>10.3</B></A>
</LI><LI CLASS="li-indexenv">create-inet-socket, <A HREF="#@funs277"><B>10.7</B></A>
</LI><LI CLASS="li-indexenv">create-request-server, <A HREF="#@funs234"><B>9.1.1</B></A>
</LI><LI CLASS="li-indexenv">create-unix-listener, <A HREF="#@funs265"><B>10.3</B></A>
</LI><LI CLASS="li-indexenv">create-unix-socket, <A HREF="#@funs276"><B>10.7</B></A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">deactivate-breakpoint, <A HREF="#@funs317"><B>11.6</B></A>
</LI><LI CLASS="li-indexenv">debug, <A HREF="#@funs111">3.1</A>
</LI><LI CLASS="li-indexenv">debug-block-elsewhere-p, <A HREF="#@funs314"><B>11.5</B></A>
</LI><LI CLASS="li-indexenv">debug-block-successors, <A HREF="#@funs313"><B>11.5</B></A>
</LI><LI CLASS="li-indexenv">debug-function-function, <A HREF="#@funs310"><B>11.4</B></A>
</LI><LI CLASS="li-indexenv">debug-function-kind, <A HREF="#@funs309"><B>11.4</B></A>
</LI><LI CLASS="li-indexenv">debug-function-lambda-list, <A HREF="#@funs301"><B>11.4</B></A>
</LI><LI CLASS="li-indexenv">debug-function-name, <A HREF="#@funs311"><B>11.4</B></A>
</LI><LI CLASS="li-indexenv">debug-function-symbol-variables, <A HREF="#@funs304"><B>11.4</B></A>
</LI><LI CLASS="li-indexenv">debug-source-compiled, <A HREF="#@funs335"><B>11.8</B></A>
</LI><LI CLASS="li-indexenv">debug-source-created, <A HREF="#@funs334"><B>11.8</B></A>
</LI><LI CLASS="li-indexenv">debug-source-from, <A HREF="#@funs332"><B>11.8</B></A>
</LI><LI CLASS="li-indexenv">debug-source-name, <A HREF="#@funs333"><B>11.8</B></A>
</LI><LI CLASS="li-indexenv">debug-source-root-number, <A HREF="#@funs336"><B>11.8</B></A>
</LI><LI CLASS="li-indexenv">debug-source-start-positions, <A HREF="#@funs337"><B>11.9</B></A>
</LI><LI CLASS="li-indexenv">debug-variable-id, <A HREF="#@funs288"><B>11.2</B></A>
</LI><LI CLASS="li-indexenv">debug-variable-info-available, <A HREF="#@funs303"><B>11.4</B></A>
</LI><LI CLASS="li-indexenv">debug-variable-name, <A HREF="#@funs285"><B>11.2</B></A>
</LI><LI CLASS="li-indexenv">debug-variable-package, <A HREF="#@funs286"><B>11.2</B></A>
</LI><LI CLASS="li-indexenv">debug-variable-symbol, <A HREF="#@funs287"><B>11.2</B></A>
</LI><LI CLASS="li-indexenv">debug-variable-valid-value, <A HREF="#@funs291"><B>11.2</B></A>
</LI><LI CLASS="li-indexenv">debug-variable-validity, <A HREF="#@funs289"><B>11.2</B></A>
</LI><LI CLASS="li-indexenv">debug-variable-value, <A HREF="#@funs290"><B>11.2</B></A>
</LI><LI CLASS="li-indexenv">def-alien-routine, <A HREF="#@funs218">8.4.2</A>, <A HREF="#@funs225"><B>8.7.2</B></A>
</LI><LI CLASS="li-indexenv">def-alien-type, <A HREF="#@funs202"><B>8.2.1</B></A>, <A HREF="#@funs204">8.2.3</A>
</LI><LI CLASS="li-indexenv">def-alien-variable, <A HREF="#@funs219"><B>8.4.2</B></A>
</LI><LI CLASS="li-indexenv">def-callback, <A HREF="#@funs227">8.7.4</A>, <A HREF="#@funs228"><B>8.7.4</B></A>
</LI><LI CLASS="li-indexenv">def-source-context, <A HREF="#@funs125"><B>4.4.7</B></A>
</LI><LI CLASS="li-indexenv">default-directory, <A HREF="#@funs71"><B>2.17.3</B></A>
</LI><LI CLASS="li-indexenv">default-interrupt, <A HREF="#@funs184"><B>6.8.1</B></A>
</LI><LI CLASS="li-indexenv">define-composing-external-format, <A HREF="#@funs408"><B>13.4.2</B></A>
</LI><LI CLASS="li-indexenv">define-function-name-syntax, <A HREF="#@funs77"><B>2.22</B></A>
</LI><LI CLASS="li-indexenv">define-fwrapper, <A HREF="#@funs85"><B>2.25</B></A>
</LI><LI CLASS="li-indexenv">define-hash-table-test, <A HREF="#@funs15"><B>2.1.6</B></A>
</LI><LI CLASS="li-indexenv">defmodule, <A HREF="#@funs96"><B>2.28</B></A>
</LI><LI CLASS="li-indexenv">defstruct, <A HREF="#@funs132">5.2.11</A>, <A HREF="#@funs147">5.10.2</A>
</LI><LI CLASS="li-indexenv">defswitch, <A HREF="#@funs161"><B>6.1</B></A>
</LI><LI CLASS="li-indexenv">deftype, <A HREF="#@funs131">5.2.11</A>
</LI><LI CLASS="li-indexenv">defun, <A HREF="#@funs143">5.7</A>
</LI><LI CLASS="li-indexenv">delete-breakpoint, <A HREF="#@funs323"><B>11.6</B></A>
</LI><LI CLASS="li-indexenv">delete-duplicates, <A HREF="#@funs389"><B>13.3.4</B></A>
</LI><LI CLASS="li-indexenv">delete-fwrapper, <A HREF="#@funs94"><B>2.25</B></A>
</LI><LI CLASS="li-indexenv">deref, <A HREF="#@funs207"><B>8.3.1</B></A>
</LI><LI CLASS="li-indexenv">describe, <A HREF="#@funs35"><B>2.8</B></A>, <A HREF="#@funs114">3.6</A>
</LI><LI CLASS="li-indexenv">describe-external-format, <A HREF="#@funs393"><B>13.3.7.2</B></A>, <A HREF="#@funs402"><B>13.3.7.2</B></A>
</LI><LI CLASS="li-indexenv">destroy-request-server, <A HREF="#@funs235"><B>9.1.1</B></A>
</LI><LI CLASS="li-indexenv">dgettext, <A HREF="#@funs104"><B>2.29.1</B></A>
</LI><LI CLASS="li-indexenv">digit-char-p, <A HREF="#@funs356"><B>13.3.2</B></A>
</LI><LI CLASS="li-indexenv">directory, <A HREF="#@funs67"><B>2.17.1</B></A>
</LI><LI CLASS="li-indexenv">disable-clx-event-handling, <A HREF="#@funs198"><B>7.4.1</B></A>
</LI><LI CLASS="li-indexenv">dngettext, <A HREF="#@funs106"><B>2.29.1</B></A>
</LI><LI CLASS="li-indexenv">do-debug-block-locations, <A HREF="#@funs312"><B>11.5</B></A>
</LI><LI CLASS="li-indexenv">do-debug-function-blocks, <A HREF="#@funs300"><B>11.4</B></A>
</LI><LI CLASS="li-indexenv">do-debug-function-variables, <A HREF="#@funs302"><B>11.4</B></A>
</LI><LI CLASS="li-indexenv">do-fwrappers, <A HREF="#@funs95"><B>2.25</B></A>
</LI><LI CLASS="li-indexenv">dump-pot-files, <A HREF="#@funs107"><B>2.29.1</B></A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">ed, <A HREF="#@funs0">1.2</A>
</LI><LI CLASS="li-indexenv">enable-clx-event-handling, <A HREF="#@funs197"><B>7.4.1</B></A>
</LI><LI CLASS="li-indexenv">enable-interrupt, <A HREF="#@funs182"><B>6.8.1</B></A>
</LI><LI CLASS="li-indexenv">encapsulate, <A HREF="#@funs118"><B>3.10.1</B></A>
</LI><LI CLASS="li-indexenv">encapsulated-p, <A HREF="#@funs120"><B>3.10.1</B></A>
</LI><LI CLASS="li-indexenv">enumerate-search-list, <A HREF="#@funs66"><B>2.16.6</B></A>
</LI><LI CLASS="li-indexenv">error, <A HREF="#@funs109">3.1</A>
</LI><LI CLASS="li-indexenv">eval-in-frame, <A HREF="#@funs298"><B>11.3</B></A>, <A HREF="#@funs307">11.4</A>
</LI><LI CLASS="li-indexenv">extern-alien, <A HREF="#@funs210">8.3.2</A>, <A HREF="#@funs220"><B>8.4.2</B></A>, <A HREF="#@funs224">8.7.1</A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">fd-stream-fd, <A HREF="#@funs177"><B>6.7</B></A>
</LI><LI CLASS="li-indexenv">fd-stream-p, <A HREF="#@funs176"><B>6.7</B></A>
</LI><LI CLASS="li-indexenv">fdefinition, <A HREF="#@funs117">3.10.1</A>
</LI><LI CLASS="li-indexenv">file-writable, <A HREF="#@funs72"><B>2.17.3</B></A>
</LI><LI CLASS="li-indexenv">finalize, <A HREF="#@funs33"><B>2.7.4</B></A>
</LI><LI CLASS="li-indexenv">find-fwrapper, <A HREF="#@funs88"><B>2.25</B></A>
</LI><LI CLASS="li-indexenv">flet, <A HREF="#@funs138">5.6</A>
</LI><LI CLASS="li-indexenv">float-denormalized-p, <A HREF="#@funs7"><B>2.1.2.3</B></A>
</LI><LI CLASS="li-indexenv">float-digits, <A HREF="#@funs6">2.1.2.3</A>
</LI><LI CLASS="li-indexenv">float-infinity-p, <A HREF="#@funs1"><B>2.1.2.1</B></A>
</LI><LI CLASS="li-indexenv">float-nan-p, <A HREF="#@funs2"><B>2.1.2.1</B></A>
</LI><LI CLASS="li-indexenv">float-precision, <A HREF="#@funs5">2.1.2.3</A>
</LI><LI CLASS="li-indexenv">float-sign, <A HREF="#@funs4">2.1.2.2</A>
</LI><LI CLASS="li-indexenv">float-trapping-nan-p, <A HREF="#@funs3"><B>2.1.2.1</B></A>
</LI><LI CLASS="li-indexenv">floor, <A HREF="#@funs10">2.1.2.5</A>
</LI><LI CLASS="li-indexenv">flush-display-events, <A HREF="#@funs196"><B>7.4</B></A>
</LI><LI CLASS="li-indexenv">flush-emf-cache, <A HREF="#@funs81"><B>2.23.4</B></A>
</LI><LI CLASS="li-indexenv">flush-state, <A HREF="#@funs406"><B>13.4.1</B></A>
</LI><LI CLASS="li-indexenv">forget-remote-translation, <A HREF="#@funs246"><B>9.1.3</B></A>
</LI><LI CLASS="li-indexenv">form-number-translations, <A HREF="#@funs328">11.7</A>, <A HREF="#@funs338"><B>11.9</B></A>
</LI><LI CLASS="li-indexenv">format-decoded-time, <A HREF="#@funs76"><B>2.18</B></A>
</LI><LI CLASS="li-indexenv">format-universal-time, <A HREF="#@funs75"><B>2.18</B></A>
</LI><LI CLASS="li-indexenv">frame-catches, <A HREF="#@funs297"><B>11.3</B></A>
</LI><LI CLASS="li-indexenv">frame-code-location, <A HREF="#@funs296"><B>11.3</B></A>
</LI><LI CLASS="li-indexenv">frame-debug-function, <A HREF="#@funs295"><B>11.3</B></A>
</LI><LI CLASS="li-indexenv">frame-down, <A HREF="#@funs293"><B>11.3</B></A>
</LI><LI CLASS="li-indexenv">frame-up, <A HREF="#@funs294"><B>11.3</B></A>
</LI><LI CLASS="li-indexenv">free-alien, <A HREF="#@funs163">6.4</A>, <A HREF="#@funs215"><B>8.3.3</B></A>
</LI><LI CLASS="li-indexenv">function, <A HREF="#@funs129">5.2.6</A>
</LI><LI CLASS="li-indexenv">function-debug-function, <A HREF="#@funs308"><B>11.4</B></A>
</LI><LI CLASS="li-indexenv">funwrap, <A HREF="#@funs87"><B>2.25</B></A>
</LI><LI CLASS="li-indexenv">fwrap, <A HREF="#@funs86"><B>2.25</B></A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">gc-off, <A HREF="#@funs24"><B>2.7</B></A>
</LI><LI CLASS="li-indexenv">gc-on, <A HREF="#@funs25"><B>2.7</B></A>
</LI><LI CLASS="li-indexenv">gencgc-stats, <A HREF="#@funs27"><B>2.7.2</B></A>
</LI><LI CLASS="li-indexenv">get-bytes-consed, <A HREF="#@funs154"><B>5.14.6</B></A>
</LI><LI CLASS="li-indexenv">get-command-line-switch, <A HREF="#@funs160"><B>6.1</B></A>
</LI><LI CLASS="li-indexenv">get-floating-point-modes, <A HREF="#@funs13"><B>2.1.2.6</B></A>
</LI><LI CLASS="li-indexenv">get-internal-run-time, <A HREF="#@funs155">5.14.6</A>
</LI><LI CLASS="li-indexenv">get-socket-option, <A HREF="#@funs279"><B>10.7</B></A>
</LI><LI CLASS="li-indexenv">get-unix-error-msg, <A HREF="#@funs173"><B>6.6</B></A>
</LI><LI CLASS="li-indexenv">gettext, <A HREF="#@funs103"><B>2.29.1</B></A>
</LI><LI CLASS="li-indexenv">graphic-char-p, <A HREF="#@funs357"><B>13.3.2</B></A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">hash-table-test, <A HREF="#@funs17">2.1.6</A>
</LI><LI CLASS="li-indexenv">htonl, <A HREF="#@funs258"><B>10.1</B></A>
</LI><LI CLASS="li-indexenv">htons, <A HREF="#@funs259"><B>10.1</B></A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">if, <A HREF="#@funs136">5.3.5</A>, <A HREF="#@funs137">5.4.4</A>
</LI><LI CLASS="li-indexenv">ignore-interrupt, <A HREF="#@funs183"><B>6.8.1</B></A>
</LI><LI CLASS="li-indexenv">inet-recvfrom, <A HREF="#@funs282"><B>10.8</B></A>
</LI><LI CLASS="li-indexenv">inet-sendto, <A HREF="#@funs283"><B>10.8</B></A>
</LI><LI CLASS="li-indexenv">inet-shutdown, <A HREF="#@funs284"><B>10.8</B></A>
</LI><LI CLASS="li-indexenv">init-xref-database, <A HREF="#@funs340"><B>12.1</B></A>
</LI><LI CLASS="li-indexenv">inspect, <A HREF="#@funs36"><B>2.9</B></A>, <A HREF="#@funs38">2.9.1</A>
</LI></UL></TD><TD VALIGN=top ALIGN=left><UL CLASS="indexenv"><LI CLASS="li-indexenv">install, <A HREF="#@funs108"><B>2.29.1</B></A>
</LI><LI CLASS="li-indexenv">int-sap, <A HREF="#@funs165"><B>6.5</B></A>
</LI><LI CLASS="li-indexenv">invalidate-descriptor, <A HREF="#@funs194"><B>7.3</B></A>
</LI><LI CLASS="li-indexenv">ip-string, <A HREF="#@funs263"><B>10.2</B></A>
</LI><LI CLASS="li-indexenv">iterate, <A HREF="#@funs141"><B>5.6.4</B></A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">labels, <A HREF="#@funs139">5.6</A>, <A HREF="#@funs142">5.6.4</A>
</LI><LI CLASS="li-indexenv">let, <A HREF="#@funs134">5.2.11</A>
</LI><LI CLASS="li-indexenv">lisp-control-panel, <A HREF="#@funs37"><B>2.9.1</B></A>
</LI><LI CLASS="li-indexenv">list-all-external-formats, <A HREF="#@funs392"><B>13.3.7.2</B></A>, <A HREF="#@funs401"><B>13.3.7.2</B></A>
</LI><LI CLASS="li-indexenv">list-fwrappers, <A HREF="#@funs92"><B>2.25</B></A>
</LI><LI CLASS="li-indexenv">load, <A HREF="#@funs39"><B>2.10</B></A>
</LI><LI CLASS="li-indexenv">load-foreign, <A HREF="#@funs222"><B>8.6</B></A>
</LI><LI CLASS="li-indexenv">load-logical-pathname-translations, <A HREF="#@funs62">2.16.3</A>
</LI><LI CLASS="li-indexenv">lookup-host-entry, <A HREF="#@funs262"><B>10.2</B></A>
</LI><LI CLASS="li-indexenv">lower-case-p, <A HREF="#@funs359"><B>13.3.2</B></A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">make-alien, <A HREF="#@funs162">6.4</A>, <A HREF="#@funs203">8.2.3</A>, <A HREF="#@funs214"><B>8.3.3</B></A>, <A HREF="#@funs232">8.7.6</A>
</LI><LI CLASS="li-indexenv">make-breakpoint, <A HREF="#@funs315"><B>11.6</B></A>
</LI><LI CLASS="li-indexenv">make-fd-stream, <A HREF="#@funs41">2.12</A>, <A HREF="#@funs175"><B>6.7</B></A>
</LI><LI CLASS="li-indexenv">make-hash-table, <A HREF="#@funs16">2.1.6</A>, <A HREF="#@funs18"><B>2.1.6</B></A>
</LI><LI CLASS="li-indexenv">make-object-set, <A HREF="#@funs185"><B>7.1</B></A>
</LI><LI CLASS="li-indexenv">make-remote-object, <A HREF="#@funs241"><B>9.1.3</B></A>
</LI><LI CLASS="li-indexenv">make-weak-pointer, <A HREF="#@funs31"><B>2.7.3</B></A>
</LI><LI CLASS="li-indexenv">make-wire, <A HREF="#@funs255"><B>9.2.3</B></A>
</LI><LI CLASS="li-indexenv">module-provide-cmucl-defmodule, <A HREF="#@funs97"><B>2.28</B></A>
</LI><LI CLASS="li-indexenv">module-provide-cmucl-library, <A HREF="#@funs98"><B>2.28</B></A>
</LI><LI CLASS="li-indexenv">multiple-value-bind, <A HREF="#@funs135">5.3.1</A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">name-char, <A HREF="#@funs366"><B>13.3.2</B></A>
</LI><LI CLASS="li-indexenv">ngettext, <A HREF="#@funs105"><B>2.29.1</B></A>
</LI><LI CLASS="li-indexenv">no-primary-method, <A HREF="#@funs79"><B>2.23.1</B></A>, <A HREF="#@funs80"><B>2.23.1</B></A>
</LI><LI CLASS="li-indexenv">nstring-capitalize, <A HREF="#@funs372"><B>13.3.3</B></A>
</LI><LI CLASS="li-indexenv">nstring-downcase, <A HREF="#@funs371"><B>13.3.3</B></A>
</LI><LI CLASS="li-indexenv">nstring-upcase, <A HREF="#@funs370"><B>13.3.3</B></A>
</LI><LI CLASS="li-indexenv">ntohl, <A HREF="#@funs261"><B>10.1</B></A>
</LI><LI CLASS="li-indexenv">ntohs, <A HREF="#@funs260"><B>10.1</B></A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">object-set-event-handler, <A HREF="#@funs200"><B>7.4.2</B></A>
</LI><LI CLASS="li-indexenv">object-set-operation, <A HREF="#@funs186"><B>7.1</B></A>
</LI><LI CLASS="li-indexenv">octets-to-code, <A HREF="#@funs404"><B>13.4.1</B></A>
</LI><LI CLASS="li-indexenv">octets-to-string, <A HREF="#@funs400"><B>13.3.7.2</B></A>
</LI><LI CLASS="li-indexenv">open, <A HREF="#@funs390"><B>13.3.7.1</B></A>
</LI><LI CLASS="li-indexenv">open-clx-display, <A HREF="#@funs195"><B>7.4</B></A>
</LI><LI CLASS="li-indexenv">open-network-stream, <A HREF="#@funs271"><B>10.5</B></A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">package-definition-lock, <A HREF="#@funs20"><B>2.5.2</B></A>
</LI><LI CLASS="li-indexenv">package-lock, <A HREF="#@funs19"><B>2.5.2</B></A>
</LI><LI CLASS="li-indexenv">parse-time, <A HREF="#@funs74"><B>2.18</B></A>
</LI><LI CLASS="li-indexenv">preprocess-for-eval, <A HREF="#@funs299">11.3</A>, <A HREF="#@funs306"><B>11.4</B></A>
</LI><LI CLASS="li-indexenv">print-directory, <A HREF="#@funs68"><B>2.17.1</B></A>
</LI><LI CLASS="li-indexenv">process-alive-p, <A HREF="#@funs56"><B>2.14.1</B></A>
</LI><LI CLASS="li-indexenv">process-close, <A HREF="#@funs57"><B>2.14.1</B></A>
</LI><LI CLASS="li-indexenv">process-core-dumped, <A HREF="#@funs47"><B>2.14.1</B></A>
</LI><LI CLASS="li-indexenv">process-error, <A HREF="#@funs51"><B>2.14.1</B></A>
</LI><LI CLASS="li-indexenv">process-exit-code, <A HREF="#@funs46"><B>2.14.1</B></A>
</LI><LI CLASS="li-indexenv">process-input, <A HREF="#@funs49"><B>2.14.1</B></A>
</LI><LI CLASS="li-indexenv">process-kill, <A HREF="#@funs55"><B>2.14.1</B></A>
</LI><LI CLASS="li-indexenv">process-output, <A HREF="#@funs50"><B>2.14.1</B></A>
</LI><LI CLASS="li-indexenv">process-p, <A HREF="#@funs43"><B>2.14.1</B></A>
</LI><LI CLASS="li-indexenv">process-pid, <A HREF="#@funs44"><B>2.14.1</B></A>
</LI><LI CLASS="li-indexenv">process-plist, <A HREF="#@funs53"><B>2.14.1</B></A>
</LI><LI CLASS="li-indexenv">process-pty, <A HREF="#@funs48"><B>2.14.1</B></A>
</LI><LI CLASS="li-indexenv">process-status, <A HREF="#@funs45"><B>2.14.1</B></A>
</LI><LI CLASS="li-indexenv">process-status-hook, <A HREF="#@funs52"><B>2.14.1</B></A>
</LI><LI CLASS="li-indexenv">process-wait, <A HREF="#@funs54"><B>2.14.1</B></A>
</LI><LI CLASS="li-indexenv">profile, <A HREF="#@funs148"><B>5.14.1</B></A>
</LI><LI CLASS="li-indexenv">profile-all, <A HREF="#@funs150"><B>5.14.1</B></A>
</LI><LI CLASS="li-indexenv">purify, <A HREF="#@funs59">2.15</A>, <A HREF="#@funs60">2.15</A>, <A HREF="#@funs61"><B>2.15</B></A>
</LI><LI CLASS="li-indexenv">push-fwrapper, <A HREF="#@funs93"><B>2.25</B></A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">read-n-bytes, <A HREF="#@funs40"><B>2.12</B></A>, <A HREF="#@funs174">6.7</A>
</LI><LI CLASS="li-indexenv">remote, <A HREF="#@funs237"><B>9.1.2</B></A>
</LI><LI CLASS="li-indexenv">remote-object-eq, <A HREF="#@funs244"><B>9.1.3</B></A>
</LI><LI CLASS="li-indexenv">remote-object-local-p, <A HREF="#@funs243"><B>9.1.3</B></A>
</LI><LI CLASS="li-indexenv">remote-object-p, <A HREF="#@funs242"><B>9.1.3</B></A>
</LI><LI CLASS="li-indexenv">remote-object-value, <A HREF="#@funs245"><B>9.1.3</B></A>
</LI><LI CLASS="li-indexenv">remote-value, <A HREF="#@funs239"><B>9.1.2</B></A>
</LI><LI CLASS="li-indexenv">remote-value-bind, <A HREF="#@funs240"><B>9.1.2</B></A>
</LI><LI CLASS="li-indexenv">remove-all-oob-handlers, <A HREF="#@funs274"><B>10.6</B></A>
</LI><LI CLASS="li-indexenv">remove-duplicates, <A HREF="#@funs388"><B>13.3.4</B></A>
</LI><LI CLASS="li-indexenv">remove-fd-handler, <A HREF="#@funs191"><B>7.3</B></A>
</LI><LI CLASS="li-indexenv">remove-oob-handler, <A HREF="#@funs273"><B>10.6</B></A>
</LI><LI CLASS="li-indexenv">report-time, <A HREF="#@funs151"><B>5.14.1</B></A>
</LI><LI CLASS="li-indexenv">required-argument, <A HREF="#@funs126"><B>4.5.1</B></A>, <A HREF="#@funs128">5.2.5</A>
</LI><LI CLASS="li-indexenv">reset-time, <A HREF="#@funs152"><B>5.14.1</B></A>
</LI><LI CLASS="li-indexenv">round, <A HREF="#@funs8">2.1.2.5</A>
</LI><LI CLASS="li-indexenv">run-program, <A HREF="#@funs42"><B>2.14</B></A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">sap+, <A HREF="#@funs166"><B>6.5</B></A>
</LI><LI CLASS="li-indexenv">sap-alien, <A HREF="#@funs212"><B>8.3.2</B></A>
</LI><LI CLASS="li-indexenv">sap-int, <A HREF="#@funs164"><B>6.5</B></A>
</LI><LI CLASS="li-indexenv">sap-ref-16, <A HREF="#@funs168"><B>6.5</B></A>
</LI><LI CLASS="li-indexenv">sap-ref-32, <A HREF="#@funs169"><B>6.5</B></A>
</LI><LI CLASS="li-indexenv">sap-ref-8, <A HREF="#@funs167"><B>6.5</B></A>
</LI><LI CLASS="li-indexenv">save-lisp, <A HREF="#@funs58"><B>2.15</B></A>, <A HREF="#@funs221">8.6</A>
</LI><LI CLASS="li-indexenv">seal, <A HREF="#@funs82"><B>2.23.6</B></A>
</LI><LI CLASS="li-indexenv">search-list, <A HREF="#@funs63"><B>2.16.6</B></A>
</LI><LI CLASS="li-indexenv">search-list-defined-p, <A HREF="#@funs64"><B>2.16.6</B></A>
</LI><LI CLASS="li-indexenv">send-character-out-of-band, <A HREF="#@funs275"><B>10.6</B></A>
</LI><LI CLASS="li-indexenv">serve-all-events, <A HREF="#@funs189"><B>7.2</B></A>
</LI><LI CLASS="li-indexenv">serve-event, <A HREF="#@funs188"><B>7.2</B></A>
</LI><LI CLASS="li-indexenv">set-floating-point-modes, <A HREF="#@funs12"><B>2.1.2.6</B></A>
</LI><LI CLASS="li-indexenv">set-fwrappers, <A HREF="#@funs91"><B>2.25</B></A>
</LI><LI CLASS="li-indexenv">set-gc-trigger, <A HREF="#@funs28"><B>2.7.2</B></A>
</LI><LI CLASS="li-indexenv">set-min-mem-age, <A HREF="#@funs30"><B>2.7.2</B></A>
</LI><LI CLASS="li-indexenv">set-socket-option, <A HREF="#@funs280"><B>10.7</B></A>
</LI><LI CLASS="li-indexenv">set-system-external-format, <A HREF="#@funs391"><B>13.3.7.2</B></A>
</LI><LI CLASS="li-indexenv">set-trigger-age, <A HREF="#@funs29"><B>2.7.2</B></A>
</LI><LI CLASS="li-indexenv">setlocale, <A HREF="#@funs101"><B>2.29.1</B></A>
</LI><LI CLASS="li-indexenv">signed-sap-ref-16, <A HREF="#@funs171"><B>6.5</B></A>
</LI><LI CLASS="li-indexenv">signed-sap-ref-32, <A HREF="#@funs172"><B>6.5</B></A>
</LI><LI CLASS="li-indexenv">signed-sap-ref-8, <A HREF="#@funs170"><B>6.5</B></A>
</LI><LI CLASS="li-indexenv">slot, <A HREF="#@funs208"><B>8.3.1</B></A>
</LI><LI CLASS="li-indexenv">source-path-context, <A HREF="#@funs339"><B>11.9</B></A>
</LI><LI CLASS="li-indexenv">string&lt;, <A HREF="#@funs375"><B>13.3.3</B></A>
</LI><LI CLASS="li-indexenv">string&lt;=, <A HREF="#@funs377"><B>13.3.3</B></A>
</LI><LI CLASS="li-indexenv">string&gt;, <A HREF="#@funs376"><B>13.3.3</B></A>
</LI><LI CLASS="li-indexenv">string&gt;=, <A HREF="#@funs378"><B>13.3.3</B></A>
</LI><LI CLASS="li-indexenv">string-capitalize, <A HREF="#@funs369"><B>13.3.3</B></A>
</LI><LI CLASS="li-indexenv">string-decode, <A HREF="#@funs398"><B>13.3.7.2</B></A>
</LI><LI CLASS="li-indexenv">string-downcase, <A HREF="#@funs368"><B>13.3.3</B></A>
</LI><LI CLASS="li-indexenv">string-encode, <A HREF="#@funs397"><B>13.3.7.2</B></A>
</LI><LI CLASS="li-indexenv">string-equal, <A HREF="#@funs379"><B>13.3.3</B></A>
</LI><LI CLASS="li-indexenv">string-greaterp, <A HREF="#@funs382"><B>13.3.3</B></A>
</LI><LI CLASS="li-indexenv">string-left-trim, <A HREF="#@funs385"><B>13.3.3</B></A>
</LI><LI CLASS="li-indexenv">string-lessp, <A HREF="#@funs381"><B>13.3.3</B></A>
</LI><LI CLASS="li-indexenv">string-not-equal, <A HREF="#@funs380"><B>13.3.3</B></A>
</LI><LI CLASS="li-indexenv">string-not-greaterp, <A HREF="#@funs383"><B>13.3.3</B></A>
</LI><LI CLASS="li-indexenv">string-not-lessp, <A HREF="#@funs384"><B>13.3.3</B></A>
</LI><LI CLASS="li-indexenv">string-right-trim, <A HREF="#@funs386"><B>13.3.3</B></A>
</LI><LI CLASS="li-indexenv">string-to-octets, <A HREF="#@funs399"><B>13.3.7.2</B></A>
</LI><LI CLASS="li-indexenv">string-trim, <A HREF="#@funs387"><B>13.3.3</B></A>
</LI><LI CLASS="li-indexenv">string-upcase, <A HREF="#@funs367"><B>13.3.3</B></A>
</LI><LI CLASS="li-indexenv">string/=, <A HREF="#@funs374"><B>13.3.3</B></A>
</LI><LI CLASS="li-indexenv">string=, <A HREF="#@funs373"><B>13.3.3</B></A>
</LI><LI CLASS="li-indexenv">surrogates, <A HREF="#@funs396"><B>13.3.7.2</B></A>
</LI><LI CLASS="li-indexenv">surrogates-to-codepoint, <A HREF="#@funs395"><B>13.3.7.2</B></A>
</LI><LI CLASS="li-indexenv">system:vector-sap, <A HREF="#@funs233">8.7.6</A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">textdomain, <A HREF="#@funs102"><B>2.29.1</B></A>
</LI><LI CLASS="li-indexenv">the, <A HREF="#@funs130">5.2.7</A>, <A HREF="#@funs133">5.2.11</A>
</LI><LI CLASS="li-indexenv">time, <A HREF="#@funs153"><B>5.14.6</B></A>
</LI><LI CLASS="li-indexenv">title-case-p, <A HREF="#@funs360"><B>13.3.2</B></A>
</LI><LI CLASS="li-indexenv">top-frame, <A HREF="#@funs292"><B>11.3</B></A>
</LI><LI CLASS="li-indexenv">trace, <A HREF="#@funs115"><B>3.10</B></A>, <A HREF="#@funs140">5.6.1</A>
</LI><LI CLASS="li-indexenv">translation-disable, <A HREF="#@funs100"><B>2.29.1</B></A>
</LI><LI CLASS="li-indexenv">translation-enable, <A HREF="#@funs99"><B>2.29.1</B></A>
</LI><LI CLASS="li-indexenv">truncate, <A HREF="#@funs11">2.1.2.5</A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">unencapsulate, <A HREF="#@funs119"><B>3.10.1</B></A>
</LI><LI CLASS="li-indexenv">unix-namestring, <A HREF="#@funs73"><B>2.17.3</B></A>
</LI><LI CLASS="li-indexenv">unlock-all-packages, <A HREF="#@funs22"><B>2.5.2</B></A>
</LI><LI CLASS="li-indexenv">unprofile, <A HREF="#@funs149"><B>5.14.1</B></A>
</LI><LI CLASS="li-indexenv">unseal, <A HREF="#@funs83"><B>2.23.6</B></A>
</LI><LI CLASS="li-indexenv">untrace, <A HREF="#@funs116"><B>3.10</B></A>
</LI><LI CLASS="li-indexenv">update-fwrapper, <A HREF="#@funs89"><B>2.25</B></A>
</LI><LI CLASS="li-indexenv">update-fwrappers, <A HREF="#@funs90"><B>2.25</B></A>
</LI><LI CLASS="li-indexenv">upper-case-p, <A HREF="#@funs358"><B>13.3.2</B></A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">valid-function-name-p, <A HREF="#@funs78"><B>2.22</B></A>
</LI><LI CLASS="li-indexenv">var, <A HREF="#@funs112"><B>3.4</B></A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">wait-until-fd-usable, <A HREF="#@funs193"><B>7.3</B></A>
</LI><LI CLASS="li-indexenv">weak-pointer-value, <A HREF="#@funs32"><B>2.7.3</B></A>
</LI><LI CLASS="li-indexenv">who-binds, <A HREF="#@funs343"><B>12.2</B></A>
</LI><LI CLASS="li-indexenv">who-calls, <A HREF="#@funs341"><B>12.2</B></A>
</LI><LI CLASS="li-indexenv">who-references, <A HREF="#@funs342"><B>12.2</B></A>
</LI><LI CLASS="li-indexenv">who-sets, <A HREF="#@funs344"><B>12.2</B></A>
</LI><LI CLASS="li-indexenv">wire-fd, <A HREF="#@funs257"><B>9.2.3</B></A>
</LI><LI CLASS="li-indexenv">wire-force-output, <A HREF="#@funs238"><B>9.1.2</B></A>
</LI><LI CLASS="li-indexenv">wire-get-byte, <A HREF="#@funs248"><B>9.2.1</B></A>
</LI><LI CLASS="li-indexenv">wire-get-number, <A HREF="#@funs250"><B>9.2.1</B></A>
</LI><LI CLASS="li-indexenv">wire-get-object, <A HREF="#@funs254"><B>9.2.2</B></A>
</LI><LI CLASS="li-indexenv">wire-get-string, <A HREF="#@funs252"><B>9.2.1</B></A>
</LI><LI CLASS="li-indexenv">wire-output-byte, <A HREF="#@funs247"><B>9.2.1</B></A>
</LI><LI CLASS="li-indexenv">wire-output-number, <A HREF="#@funs249"><B>9.2.1</B></A>
</LI><LI CLASS="li-indexenv">wire-output-object, <A HREF="#@funs253"><B>9.2.2</B></A>
</LI><LI CLASS="li-indexenv">wire-output-string, <A HREF="#@funs251"><B>9.2.1</B></A>
</LI><LI CLASS="li-indexenv">wire-p, <A HREF="#@funs256"><B>9.2.3</B></A>
</LI><LI CLASS="li-indexenv">with-alien, <A HREF="#@funs201">8.2.1</A>, <A HREF="#@funs205">8.2.3</A>, <A HREF="#@funs216">8.3.3</A>, <A HREF="#@funs217"><B>8.4.1</B></A>
</LI><LI CLASS="li-indexenv">with-clx-event-handling, <A HREF="#@funs199"><B>7.4.1</B></A>
</LI><LI CLASS="li-indexenv">with-compilation-unit, <A HREF="#@funs124"><B>4.3</B></A>, <A HREF="#@funs127">4.7.2</A>, <A HREF="#@funs145">5.7.5</A>
</LI><LI CLASS="li-indexenv">with-enabled-interrupts, <A HREF="#@funs178"><B>6.8.1</B></A>
</LI><LI CLASS="li-indexenv">with-fd-handler, <A HREF="#@funs192"><B>7.3</B></A>
</LI><LI CLASS="li-indexenv">with-float-traps-masked, <A HREF="#@funs14"><B>2.1.2.6</B></A>
</LI><LI CLASS="li-indexenv">with-interrupts, <A HREF="#@funs180"><B>6.8.1</B></A>
</LI><LI CLASS="li-indexenv">without-hemlock, <A HREF="#@funs181"><B>6.8.1</B></A>
</LI><LI CLASS="li-indexenv">without-interrupts, <A HREF="#@funs179"><B>6.8.1</B></A>
</LI><LI CLASS="li-indexenv">without-package-locks, <A HREF="#@funs21"><B>2.5.2</B></A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">xref-context-file, <A HREF="#@funs346"><B>12.2</B></A>
</LI><LI CLASS="li-indexenv">xref-context-name, <A HREF="#@funs345"><B>12.2</B></A>
</LI><LI CLASS="li-indexenv">xref-context-source-path, <A HREF="#@funs347"><B>12.2</B></A>
</LI></UL></TD></TR>
</TABLE><!--NAME cmu-user.hfnd.html-->
<P><A NAME="@concept300"></A>
</P><!--TOC chapter Variable Index-->
<H1 CLASS="chapter"><!--SEC ANCHOR -->Variable Index</H1><!--SEC END --><P></P><TABLE CELLSPACING=6 CELLPADDING=0><TR><TD VALIGN=top ALIGN=left><UL CLASS="indexenv"><LI CLASS="li-indexenv">
*max-emf-precomputation-methods*, <A HREF="#@vars21"><B>2.23.5</B></A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">after-gc-hooks, <A HREF="#@vars8"><B>2.7.1</B></A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">before-gc-hooks, <A HREF="#@vars7"><B>2.7.1</B></A>
</LI><LI CLASS="li-indexenv">block-compile-default, <A HREF="#@vars49">5.7.3</A>, <A HREF="#@vars50"><B>5.7.3</B></A>, <A HREF="#@vars51">5.7.4</A>
</LI><LI CLASS="li-indexenv">byte-compile-default, <A HREF="#@vars38">4.2</A>, <A HREF="#@vars53"><B>5.9</B></A>
</LI><LI CLASS="li-indexenv">byte-compile-top-level, <A HREF="#@vars52"><B>5.9</B></A>
</LI><LI CLASS="li-indexenv">bytes-consed-between-gcs, <A HREF="#@vars2"><B>2.7.1</B></A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">command-line-strings, <A HREF="#@vars59"><B>6.1</B></A>
</LI><LI CLASS="li-indexenv">command-line-switches, <A HREF="#@vars62"><B>6.1</B></A>
</LI><LI CLASS="li-indexenv">command-line-utility-name, <A HREF="#@vars60"><B>6.1</B></A>
</LI><LI CLASS="li-indexenv">command-line-words, <A HREF="#@vars61"><B>6.1</B></A>
</LI><LI CLASS="li-indexenv">compile-file-truename, <A HREF="#@vars69">12.2</A>
</LI><LI CLASS="li-indexenv">compile-interpreted-methods-p, <A HREF="#@vars22"><B>2.23.8</B></A>
</LI><LI CLASS="li-indexenv">compile-print, <A HREF="#@vars36">4.2</A>, <A HREF="#@vars40"><B>4.2</B></A>
</LI><LI CLASS="li-indexenv">compile-progress, <A HREF="#@vars37">4.2</A>, <A HREF="#@vars41"><B>4.2</B></A>
</LI><LI CLASS="li-indexenv">compile-verbose, <A HREF="#@vars35">4.2</A>, <A HREF="#@vars39"><B>4.2</B></A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">debug-print-length, <A HREF="#@vars26">3.3.2</A>, <A HREF="#@vars29">3.10</A>, <A HREF="#@vars34"><B>3.11</B></A>
</LI><LI CLASS="li-indexenv">debug-print-level, <A HREF="#@vars28">3.10</A>, <A HREF="#@vars33"><B>3.11</B></A>
</LI><LI CLASS="li-indexenv">default-external-format, <A HREF="#@vars70"><B>13.3.1</B></A>
</LI><LI CLASS="li-indexenv">derive-function-types, <A HREF="#@vars48"><B>5.3.3</B></A>
</LI><LI CLASS="li-indexenv">describe-indentation, <A HREF="#@vars10"><B>2.8</B></A>
</LI><LI CLASS="li-indexenv">describe-level, <A HREF="#@vars9"><B>2.8</B></A>
</LI><LI CLASS="li-indexenv">describe-print-length, <A HREF="#@vars12"><B>2.8</B></A>
</LI><LI CLASS="li-indexenv">describe-print-level, <A HREF="#@vars11"><B>2.8</B></A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">efficiency-note-cost-threshold, <A HREF="#@vars44">4.4.7</A>, <A HREF="#@vars54">5.13.3</A>, <A HREF="#@vars55"><B>5.13.4</B></A>
</LI><LI CLASS="li-indexenv">efficiency-note-limit, <A HREF="#@vars56"><B>5.13.4</B></A>
</LI><LI CLASS="li-indexenv">enclosing-source-cutoff, <A HREF="#@vars45"><B>4.4.7</B></A>
</LI><LI CLASS="li-indexenv">environment-list, <A HREF="#@vars67"><B>6.2</B></A>
</LI><LI CLASS="li-indexenv">error-print-length, <A HREF="#@vars46"><B>4.4.7</B></A>
</LI><LI CLASS="li-indexenv">error-print-level, <A HREF="#@vars47"><B>4.4.7</B></A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">gc-inhibit-hook, <A HREF="#@vars6"><B>2.7.1</B></A>
</LI></UL></TD><TD VALIGN=top ALIGN=left><UL CLASS="indexenv"><LI CLASS="li-indexenv">gc-notify-after, <A HREF="#@vars5"><B>2.7.1</B></A>
</LI><LI CLASS="li-indexenv">gc-notify-before, <A HREF="#@vars4"><B>2.7.1</B></A>
</LI><LI CLASS="li-indexenv">gc-run-time, <A HREF="#@vars58"><B>5.14.6</B></A>
</LI><LI CLASS="li-indexenv">gc-verbose, <A HREF="#@vars3"><B>2.7.1</B></A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">hash-table-tests, <A HREF="#@vars1">2.1.6</A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">ignore-extra-close-parentheses, <A HREF="#@vars17"><B>2.11.2</B></A>
</LI><LI CLASS="li-indexenv">inline-methods-in-emfs, <A HREF="#@vars20"><B>2.23.4</B></A>
</LI><LI CLASS="li-indexenv">interface-style, <A HREF="#@vars13"><B>2.9.1</B></A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">load-if-source-newer, <A HREF="#@vars16"><B>2.10</B></A>
</LI><LI CLASS="li-indexenv">load-object-types, <A HREF="#@vars15"><B>2.10</B></A>
</LI><LI CLASS="li-indexenv">load-source-types, <A HREF="#@vars14"><B>2.10</B></A>
</LI><LI CLASS="li-indexenv">locale-directories, <A HREF="#@vars25"><B>2.29.1</B></A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">max-trace-indentation, <A HREF="#@vars31"><B>3.10</B></A>
</LI><LI CLASS="li-indexenv">module-provider-functions, <A HREF="#@vars24"><B>2.28</B></A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">optimize-inline-slot-access-p, <A HREF="#@vars19"><B>2.23.3.2</B></A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">read-default-float-format, <A HREF="#@vars0">2.1.2</A>
</LI><LI CLASS="li-indexenv">record-xref-info, <A HREF="#@vars68"><B>12.1</B></A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">stderr, <A HREF="#@vars65"><B>6.2</B></A>
</LI><LI CLASS="li-indexenv">stdin, <A HREF="#@vars63"><B>6.2</B></A>
</LI><LI CLASS="li-indexenv">stdout, <A HREF="#@vars64"><B>6.2</B></A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">timed-functions, <A HREF="#@vars57"><B>5.14.1</B></A>
</LI><LI CLASS="li-indexenv">trace-encapsulate-package-names, <A HREF="#@vars32"><B>3.10</B></A>
</LI><LI CLASS="li-indexenv">trace-output, <A HREF="#@vars27">3.10</A>
</LI><LI CLASS="li-indexenv">traced-function-list, <A HREF="#@vars30"><B>3.10</B></A>
</LI><LI CLASS="li-indexenv">trust-dynamic-extent-declarations, <A HREF="#@vars23"><B>2.26</B></A>
</LI><LI CLASS="li-indexenv">tty, <A HREF="#@vars66"><B>6.2</B></A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">undefined-warning-limit, <A HREF="#@vars42"><B>4.3.1</B></A>, <A HREF="#@vars43">4.4.7</A>
</LI><LI CLASS="li-indexenv">use-slot-types-p, <A HREF="#@vars18"><B>2.23.2</B></A>
</LI></UL></TD></TR>
</TABLE><!--NAME cmu-user.hvnd.html-->
<P><A NAME="@concept301"></A>
</P><!--TOC chapter Type Index-->
<H1 CLASS="chapter"><!--SEC ANCHOR -->Type Index</H1><!--SEC END --><P></P><TABLE CELLSPACING=6 CELLPADDING=0><TR><TD VALIGN=top ALIGN=left><UL CLASS="indexenv"><LI CLASS="li-indexenv">
*, <A HREF="#@types31"><B>8.2.3</B></A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">ambiguous-variable-name, <A HREF="#@types54"><B>11.1.1</B></A>
</LI><LI CLASS="li-indexenv">and, <A HREF="#@types29">5.3.1</A>
</LI><LI CLASS="li-indexenv">array, <A HREF="#@types32"><B>8.2.3</B></A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">base-character, <A HREF="#@types9">2.1.4</A>
</LI><LI CLASS="li-indexenv">bignum, <A HREF="#@types1">2.1.1</A>
</LI><LI CLASS="li-indexenv">boolean, <A HREF="#@types39"><B>8.2.3</B></A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">c-string, <A HREF="#@types45"><B>8.2.4</B></A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">debug-condition, <A HREF="#@types47"><B>11.1.1</B></A>
</LI><LI CLASS="li-indexenv">debug-error, <A HREF="#@types55"><B>11.1.2</B></A>
</LI><LI CLASS="li-indexenv">divide-by-zero, <A HREF="#@types7">2.1.2.4</A>
</LI><LI CLASS="li-indexenv">double-double-float, <A HREF="#@types4">2.1.2</A>
</LI><LI CLASS="li-indexenv">double-float, <A HREF="#@types3">2.1.2</A>, <A HREF="#@types41"><B>8.2.3</B></A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">end-of-file, <A HREF="#@types16">2.12</A>
</LI><LI CLASS="li-indexenv">enum, <A HREF="#@types35"><B>8.2.3</B></A>
</LI><LI CLASS="li-indexenv">error, <A HREF="#@types19">4.2</A>
</LI><LI CLASS="li-indexenv">extensions:double-double-float, <A HREF="#@types8"><B>2.1.3</B></A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">fixnum, <A HREF="#@types0">2.1.1</A>, <A HREF="#@types14">2.8</A>, <A HREF="#@types24">5.2.2</A>
</LI><LI CLASS="li-indexenv">floating-point-overflow, <A HREF="#@types6">2.1.2.4</A>
</LI><LI CLASS="li-indexenv">floating-point-underflow, <A HREF="#@types5">2.1.2.4</A>
</LI><LI CLASS="li-indexenv">frame-function-mismatch, <A HREF="#@types59"><B>11.1.2</B></A>
</LI><LI CLASS="li-indexenv">ftype, <A HREF="#@types30">5.3.3</A>
</LI><LI CLASS="li-indexenv">function, <A HREF="#@types13">2.8</A>, <A HREF="#@types42"><B>8.2.3</B></A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">hash-table, <A HREF="#@types12">2.8</A>
</LI><LI CLASS="li-indexenv">hash-tables, <A HREF="#@types11">2.1.6</A>
</LI><LI CLASS="li-indexenv">host-entry, <A HREF="#@types46"><B>10.2</B></A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">integer, <A HREF="#@types37"><B>8.2.3</B></A>
</LI></UL></TD><TD VALIGN=top ALIGN=left><UL CLASS="indexenv"><LI CLASS="li-indexenv">invalid-value, <A HREF="#@types53"><B>11.1.1</B></A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">lambda-list-unavailable, <A HREF="#@types52"><B>11.1.1</B></A>
</LI><LI CLASS="li-indexenv">list, <A HREF="#@types23">5.2.2</A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">member, <A HREF="#@types25">5.2.3</A>, <A HREF="#@types27">5.2.11</A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">no-debug-blocks, <A HREF="#@types50"><B>11.1.1</B></A>
</LI><LI CLASS="li-indexenv">no-debug-function-returns, <A HREF="#@types49"><B>11.1.1</B></A>
</LI><LI CLASS="li-indexenv">no-debug-info, <A HREF="#@types48"><B>11.1.1</B></A>
</LI><LI CLASS="li-indexenv">no-debug-variables, <A HREF="#@types51"><B>11.1.1</B></A>
</LI><LI CLASS="li-indexenv">null, <A HREF="#@types22">5.2.2</A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">or, <A HREF="#@types26">5.2.4</A>, <A HREF="#@types28">5.2.11</A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">pathname, <A HREF="#@types17">2.16</A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">serious-condition, <A HREF="#@types18">3.1</A>
</LI><LI CLASS="li-indexenv">signed, <A HREF="#@types36"><B>8.2.3</B></A>
</LI><LI CLASS="li-indexenv">single-float, <A HREF="#@types2">2.1.2</A>, <A HREF="#@types40"><B>8.2.3</B></A>
</LI><LI CLASS="li-indexenv">string-char, <A HREF="#@types10">2.1.4</A>
</LI><LI CLASS="li-indexenv">struct, <A HREF="#@types33"><B>8.2.3</B></A>
</LI><LI CLASS="li-indexenv">style-warning, <A HREF="#@types21">4.2</A>
</LI><LI CLASS="li-indexenv">symbol, <A HREF="#@types15">2.8</A>
</LI><LI CLASS="li-indexenv">system-area-pointer, <A HREF="#@types43"><B>8.2.3</B></A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">unhandled-condition, <A HREF="#@types56"><B>11.1.2</B></A>
</LI><LI CLASS="li-indexenv">union, <A HREF="#@types34"><B>8.2.3</B></A>
</LI><LI CLASS="li-indexenv">unknown-code-location, <A HREF="#@types57"><B>11.1.2</B></A>
</LI><LI CLASS="li-indexenv">unknown-debug-variable, <A HREF="#@types58"><B>11.1.2</B></A>
</LI><LI CLASS="li-indexenv">unsigned, <A HREF="#@types38"><B>8.2.3</B></A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">void, <A HREF="#@types44"><B>8.2.4</B></A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">warning, <A HREF="#@types20">4.2</A>
</LI></UL></TD></TR>
</TABLE><!--NAME cmu-user.htnd.html-->
<P><A NAME="@concept302"></A>
</P><!--TOC chapter Concept Index-->
<H1 CLASS="chapter"><!--SEC ANCHOR -->Concept Index</H1><!--SEC END --><P></P><TABLE CELLSPACING=6 CELLPADDING=0><TR><TD VALIGN=top ALIGN=left><UL CLASS="indexenv"><LI CLASS="li-indexenv">
actual source, <A HREF="#@concept97">4.4.2</A>
</LI><LI CLASS="li-indexenv">advising, <A HREF="#@concept90">3.10.1</A>
</LI><LI CLASS="li-indexenv">aliens, <A HREF="#@concept288">6.4</A>
</LI><LI CLASS="li-indexenv">argument syntax<UL CLASS="indexenv"><LI CLASS="li-indexenv">
efficiency, <A HREF="#@concept253">5.12.3</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">arithmetic<UL CLASS="indexenv"><LI CLASS="li-indexenv">
generic, <A HREF="#@concept231">5.11.4</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">arithmetic type inference, <A HREF="#@concept157">5.3.4</A>
</LI><LI CLASS="li-indexenv">array types<UL CLASS="indexenv"><LI CLASS="li-indexenv">
specialized, <A HREF="#@concept238">5.11.8</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">arrays<UL CLASS="indexenv"><LI CLASS="li-indexenv">
efficiency of, <A HREF="#@concept215">5.10.3</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">assembly listing, <A HREF="#@concept259">5.12.5</A>
</LI><LI CLASS="li-indexenv">availability of debug variables, <A HREF="#@concept68">3.4.1</A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">benchmarking techniques, <A HREF="#@concept287">5.14.8</A>
</LI><LI CLASS="li-indexenv">bignums, <A HREF="#@concept234">5.11.5</A>
</LI><LI CLASS="li-indexenv">bit-vectors<UL CLASS="indexenv"><LI CLASS="li-indexenv">
efficiency of, <A HREF="#@concept217">5.10.5</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">block<UL CLASS="indexenv"><LI CLASS="li-indexenv">
basic, <A HREF="#@concept74">3.5.2</A>
</LI><LI CLASS="li-indexenv">start location, <A HREF="#@concept75">3.5.2</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">block compilation, <A HREF="#@concept193">5.7</A>
<UL CLASS="indexenv"><LI CLASS="li-indexenv">
debugger implications, <A HREF="#@concept56">3.3.4</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">breakpoints, <A HREF="#@concept81">3.9</A>
<UL CLASS="indexenv"><LI CLASS="li-indexenv">
errors, <A HREF="#@concept85">3.10</A>
</LI><LI CLASS="li-indexenv">function-end, <A HREF="#@concept88">3.10</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">byte coded compilation, <A HREF="#@concept208">5.9</A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">Concept Index, <A HREF="#@concept302">13.4.2</A>
</LI><LI CLASS="li-indexenv">CPU time<UL CLASS="indexenv"><LI CLASS="li-indexenv">
interpretation of, <A HREF="#@concept284">5.14.7</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">call<UL CLASS="indexenv"><LI CLASS="li-indexenv">
inline, <A HREF="#@concept203">5.8</A>
</LI><LI CLASS="li-indexenv">local, <A HREF="#@concept185">5.6</A>
</LI><LI CLASS="li-indexenv">numeric operands, <A HREF="#@concept243">5.11.10</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">canonicalization of types, <A HREF="#@concept134">5.2.2</A>
</LI><LI CLASS="li-indexenv">characters, <A HREF="#@concept245">5.11.11</A>
</LI><LI CLASS="li-indexenv">cleanup<UL CLASS="indexenv"><LI CLASS="li-indexenv">
stack frame kind, <A HREF="#@concept59">3.3.4</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">closures, <A HREF="#@concept188">5.6.3</A>
</LI><LI CLASS="li-indexenv">command line options, <A HREF="#@concept0">1.2</A>
</LI><LI CLASS="li-indexenv">compatibility with other Lisps, <A HREF="#@concept116">4.6</A>
</LI><LI CLASS="li-indexenv">compilation<UL CLASS="indexenv"><LI CLASS="li-indexenv">
block, <A HREF="#@concept194">5.7</A>
</LI><LI CLASS="li-indexenv">units, <A HREF="#@concept92">4.3</A>
</LI><LI CLASS="li-indexenv">why to, <A HREF="#@concept248">5.12.1</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">compilation-speed optimization
quality, <A HREF="#@concept122">4.7.1</A>
</LI><LI CLASS="li-indexenv">compile time type errors, <A HREF="#@concept108">4.5.1</A>
</LI><LI CLASS="li-indexenv">compile-file<UL CLASS="indexenv"><LI CLASS="li-indexenv">
block compilation arguments, <A HREF="#@concept198">5.7.3</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">compiler error messages, <A HREF="#@concept95">4.4</A>
</LI><LI CLASS="li-indexenv">compiler error severity, <A HREF="#@concept102">4.4.4</A>
</LI><LI CLASS="li-indexenv">compiler policy, <A HREF="#@concept118">4.7</A>
</LI><LI CLASS="li-indexenv">compiling, <A HREF="#@concept91">4.2</A>
</LI><LI CLASS="li-indexenv">complemented type checks, <A HREF="#@concept164">5.3.6</A>
</LI><LI CLASS="li-indexenv">conditional type inference, <A HREF="#@concept160">5.3.5</A>
</LI><LI CLASS="li-indexenv">consing, <A HREF="#@concept249">5.12.2</A>, <A HREF="#@concept282">5.14</A>
<UL CLASS="indexenv"><LI CLASS="li-indexenv">
overhead of, <A HREF="#@concept224">5.11.1</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">constant folding, <A HREF="#@concept168">5.4.2</A>
</LI><LI CLASS="li-indexenv">constant-function declaration, <A HREF="#@concept170">5.4.2</A>
</LI><LI CLASS="li-indexenv">context sensitive declarations, <A HREF="#@concept199">5.7.5</A>
</LI><LI CLASS="li-indexenv">continuations<UL CLASS="indexenv"><LI CLASS="li-indexenv">
implicit representation, <A HREF="#@concept263">5.12.5</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">control optimization, <A HREF="#@concept173">5.4.4</A>
</LI><LI CLASS="li-indexenv">cross-referencing, <A HREF="#@concept297">12</A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">dead code elimination, <A HREF="#@concept172">5.4.3</A>, <A HREF="#@concept176">5.4.5</A>
</LI><LI CLASS="li-indexenv">debug optimization quality, <A HREF="#@concept70">3.4.1</A>, <A HREF="#@concept73">3.5.2</A>, <A HREF="#@concept77">3.6</A>, <A HREF="#@concept124">4.7.1</A>
</LI><LI CLASS="li-indexenv">debug variables, <A HREF="#@concept67">3.4</A>
</LI><LI CLASS="li-indexenv">debugger, <A HREF="#@concept48">3</A>
</LI><LI CLASS="li-indexenv">declarations<UL CLASS="indexenv"><LI CLASS="li-indexenv">
<TT class=code>optimize-interface</TT>, <A HREF="#@concept128">4.7.2</A>
</LI><LI CLASS="li-indexenv"><TT class=code>optimize</TT>, <A HREF="#@concept120">4.7.1</A>
</LI><LI CLASS="li-indexenv">block compilation, <A HREF="#@concept195">5.7.2</A>
</LI><LI CLASS="li-indexenv">context-sensitive, <A HREF="#@concept200">5.7.5</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">defstruct types, <A HREF="#@concept146">5.2.8</A>
</LI><LI CLASS="li-indexenv">derivation of types, <A HREF="#@concept153">5.3</A>
</LI><LI CLASS="li-indexenv">descriptor representations<UL CLASS="indexenv"><LI CLASS="li-indexenv">
forcing of, <A HREF="#@concept277">5.13.3</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">descriptors<UL CLASS="indexenv"><LI CLASS="li-indexenv">
object, <A HREF="#@concept221">5.11.1</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">dynamic type inference, <A HREF="#@concept159">5.3.5</A>
</LI><LI CLASS="li-indexenv">dynamic-extent, <A HREF="#@concept41">2.26</A>
<UL CLASS="indexenv"><LI CLASS="li-indexenv">
closures, <A HREF="#@concept43">2.26.2</A>
</LI><LI CLASS="li-indexenv">known CL functions, <A HREF="#@concept44">2.26.2</A>
</LI><LI CLASS="li-indexenv">list, list*, cons, <A HREF="#@concept45">2.26.3</A>
</LI><LI CLASS="li-indexenv">rest lists, <A HREF="#@concept42">2.26.1</A>
</LI></UL>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">effective method, <A HREF="#@concept21">2.23.4</A>
<UL CLASS="indexenv"><LI CLASS="li-indexenv">
inlining of methods, <A HREF="#@concept23">2.23.4</A>
</LI><LI CLASS="li-indexenv">precomputation, <A HREF="#@concept25">2.23.5</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">efficiency<UL CLASS="indexenv"><LI CLASS="li-indexenv">
general hints, <A HREF="#@concept247">5.12</A>
</LI><LI CLASS="li-indexenv">of argument syntax, <A HREF="#@concept254">5.12.3</A>
</LI><LI CLASS="li-indexenv">of memory use, <A HREF="#@concept252">5.12.2</A>
</LI><LI CLASS="li-indexenv">of numeric variables, <A HREF="#@concept229">5.11.3</A>
</LI><LI CLASS="li-indexenv">of objects, <A HREF="#@concept212">5.10</A>
</LI><LI CLASS="li-indexenv">of type checking, <A HREF="#@concept270">5.13.2</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">efficiency notes, <A HREF="#@concept264">5.13</A>
<UL CLASS="indexenv"><LI CLASS="li-indexenv">
for representation, <A HREF="#@concept273">5.13.3</A>
</LI><LI CLASS="li-indexenv">verbosity, <A HREF="#@concept279">5.13.4</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">empty type<UL CLASS="indexenv"><LI CLASS="li-indexenv">
the, <A HREF="#@concept140">5.2.5</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">encapsulation, <A HREF="#@concept89">3.10.1</A>
</LI><LI CLASS="li-indexenv">end-block declaration, <A HREF="#@concept197">5.7.2</A>
</LI><LI CLASS="li-indexenv">entry points<UL CLASS="indexenv"><LI CLASS="li-indexenv">
external, <A HREF="#@concept55">3.3.4</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">equivalence of types, <A HREF="#@concept135">5.2.2</A>
</LI><LI CLASS="li-indexenv">error messages<UL CLASS="indexenv"><LI CLASS="li-indexenv">
compiler, <A HREF="#@concept94">4.4</A>
</LI><LI CLASS="li-indexenv">verbosity, <A HREF="#@concept105">4.4.7</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">errors<UL CLASS="indexenv"><LI CLASS="li-indexenv">
breakpoints, <A HREF="#@concept86">3.10</A>
</LI><LI CLASS="li-indexenv">result type of, <A HREF="#@concept141">5.2.5</A>
</LI><LI CLASS="li-indexenv">run-time, <A HREF="#@concept65">3.3.6</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">evaluation<UL CLASS="indexenv"><LI CLASS="li-indexenv">
debugger, <A HREF="#@concept49">3.2</A>, <A HREF="#@concept71">3.4.2</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">existing programs<UL CLASS="indexenv"><LI CLASS="li-indexenv">
to run, <A HREF="#@concept114">4.6</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">expansion<UL CLASS="indexenv"><LI CLASS="li-indexenv">
inline, <A HREF="#@concept202">5.8</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">external<UL CLASS="indexenv"><LI CLASS="li-indexenv">
stack frame kind, <A HREF="#@concept57">3.3.4</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">external entry points, <A HREF="#@concept54">3.3.4</A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">Function Index, <A HREF="#@concept299">13.4.2</A>
</LI><LI CLASS="li-indexenv">fixnums, <A HREF="#@concept233">5.11.5</A>
</LI><LI CLASS="li-indexenv">floating point efficiency, <A HREF="#@concept236">5.11.7</A>
</LI><LI CLASS="li-indexenv">folding<UL CLASS="indexenv"><LI CLASS="li-indexenv">
constant, <A HREF="#@concept169">5.4.2</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">frames<UL CLASS="indexenv"><LI CLASS="li-indexenv">
stack, <A HREF="#@concept51">3.3</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">free<UL CLASS="indexenv"><LI CLASS="li-indexenv">
C function, <A HREF="#@concept293">6.5</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">freeze-type declaration, <A HREF="#@concept148">5.2.9</A>
</LI><LI CLASS="li-indexenv">function<UL CLASS="indexenv"><LI CLASS="li-indexenv">
names, <A HREF="#@concept52">3.3.3</A>
</LI><LI CLASS="li-indexenv">tracing, <A HREF="#@concept83">3.10</A>
</LI><LI CLASS="li-indexenv">type inference, <A HREF="#@concept155">5.3.3</A>
</LI><LI CLASS="li-indexenv">types, <A HREF="#@concept142">5.2.6</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">function call<UL CLASS="indexenv"><LI CLASS="li-indexenv">
inline, <A HREF="#@concept204">5.8</A>
</LI><LI CLASS="li-indexenv">local, <A HREF="#@concept186">5.6</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">function wrappers, <A HREF="#@concept39">2.25</A>
</LI><LI CLASS="li-indexenv">function-end breakpoints, <A HREF="#@concept87">3.10</A>
</LI><LI CLASS="li-indexenv">fwrappers, <A HREF="#@concept40">2.25</A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">garbage collection, <A HREF="#@concept250">5.12.2</A>
</LI><LI CLASS="li-indexenv">generic arithmetic, <A HREF="#@concept230">5.11.4</A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">hash-tables<UL CLASS="indexenv"><LI CLASS="li-indexenv">
efficiency of, <A HREF="#@concept218">5.10.6</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">hierarchical packages, <A HREF="#@concept1">2.4</A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">Internationalization, <A HREF="#@concept298">13</A>
</LI><LI CLASS="li-indexenv">implicit continuation representation (IR1), <A HREF="#@concept262">5.12.5</A>
</LI><LI CLASS="li-indexenv">inference of types, <A HREF="#@concept152">5.3</A>
</LI><LI CLASS="li-indexenv">inhibit-warnings
optimization quality, <A HREF="#@concept126">4.7.1</A>
</LI><LI CLASS="li-indexenv">inline, <A HREF="#@concept24">2.23.4</A>
</LI><LI CLASS="li-indexenv">inline expansion, <A HREF="#@concept79">3.6</A>, <A HREF="#@concept130">4.8</A>, <A HREF="#@concept201">5.8</A>
</LI><LI CLASS="li-indexenv">interpretation of run time, <A HREF="#@concept286">5.14.7</A>
</LI><LI CLASS="li-indexenv">interrupts, <A HREF="#@concept64">3.3.6</A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">keyword argument efficiency, <A HREF="#@concept255">5.12.3</A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">let optimization, <A HREF="#@concept166">5.4.1</A>
</LI><LI CLASS="li-indexenv">lisp threads, <A HREF="#@concept11">2.20</A>
</LI><LI CLASS="li-indexenv">listing files<UL CLASS="indexenv"><LI CLASS="li-indexenv">
trace, <A HREF="#@concept260">5.12.5</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">lists<UL CLASS="indexenv"><LI CLASS="li-indexenv">
efficiency of, <A HREF="#@concept213">5.10.1</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">local call, <A HREF="#@concept184">5.6</A>
<UL CLASS="indexenv"><LI CLASS="li-indexenv">
numeric operands, <A HREF="#@concept242">5.11.10</A>
</LI><LI CLASS="li-indexenv">return values, <A HREF="#@concept192">5.6.5</A>
</LI><LI CLASS="li-indexenv">type inference, <A HREF="#@concept154">5.3.2</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">locations<UL CLASS="indexenv"><LI CLASS="li-indexenv">
unknown, <A HREF="#@concept63">3.3.6</A>
</LI></UL>
</LI></UL></TD><TD VALIGN=top ALIGN=left><UL CLASS="indexenv"><LI CLASS="li-indexenv">logical pathnames, <A HREF="#@concept5">2.16.3</A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">macroexpansion, <A HREF="#@concept99">4.4.3</A>
<UL CLASS="indexenv"><LI CLASS="li-indexenv">
errors during, <A HREF="#@concept103">4.4.5</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">malloc<UL CLASS="indexenv"><LI CLASS="li-indexenv">
C function, <A HREF="#@concept292">6.5</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">mapping<UL CLASS="indexenv"><LI CLASS="li-indexenv">
efficiency of, <A HREF="#@concept257">5.12.4</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">maybe-inline declaration, <A HREF="#@concept207">5.8.3</A>
</LI><LI CLASS="li-indexenv">member types, <A HREF="#@concept136">5.2.3</A>
</LI><LI CLASS="li-indexenv">memory allocation, <A HREF="#@concept251">5.12.2</A>
</LI><LI CLASS="li-indexenv">methods, <A HREF="#@concept18">2.23.3.3</A>
<UL CLASS="indexenv"><LI CLASS="li-indexenv">
auto-compilation, <A HREF="#@concept19">2.23.3.3</A>
</LI><LI CLASS="li-indexenv">emf precomputation, <A HREF="#@concept27">2.23.5</A>
</LI><LI CLASS="li-indexenv">inlining in effective methods, <A HREF="#@concept22">2.23.4</A>
</LI><LI CLASS="li-indexenv">interpreted, <A HREF="#@concept38">2.23.8</A>
</LI><LI CLASS="li-indexenv">load time, <A HREF="#@concept26">2.23.5</A>
</LI><LI CLASS="li-indexenv">profiling, <A HREF="#@concept37">2.23.7</A>
</LI><LI CLASS="li-indexenv">sealing, <A HREF="#@concept31">2.23.6</A>
</LI><LI CLASS="li-indexenv">tracing, <A HREF="#@concept36">2.23.7</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">modular-arith, <A HREF="#@concept46">2.27</A>
</LI><LI CLASS="li-indexenv">multiple value optimization, <A HREF="#@concept177">5.4.6</A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">NIL type, <A HREF="#@concept139">5.2.5</A>
</LI><LI CLASS="li-indexenv">names<UL CLASS="indexenv"><LI CLASS="li-indexenv">
function, <A HREF="#@concept53">3.3.3</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">non-descriptor representations, <A HREF="#@concept225">5.11.2</A>, <A HREF="#@concept276">5.13.3</A>
</LI><LI CLASS="li-indexenv">notes<UL CLASS="indexenv"><LI CLASS="li-indexenv">
efficiency, <A HREF="#@concept265">5.13</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">numbers in local call, <A HREF="#@concept244">5.11.10</A>
</LI><LI CLASS="li-indexenv">numeric<UL CLASS="indexenv"><LI CLASS="li-indexenv">
operation efficiency, <A HREF="#@concept232">5.11.4</A>
</LI><LI CLASS="li-indexenv">type inference, <A HREF="#@concept158">5.3.4</A>
</LI><LI CLASS="li-indexenv">types, <A HREF="#@concept219">5.11</A>
</LI></UL>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">object representation, <A HREF="#@concept210">5.10</A>, <A HREF="#@concept222">5.11.1</A>
</LI><LI CLASS="li-indexenv">object representation efficiency notes, <A HREF="#@concept274">5.13.3</A>
</LI><LI CLASS="li-indexenv">object sets, <A HREF="#@concept296">7.1</A>
</LI><LI CLASS="li-indexenv">open-coding, <A HREF="#@concept129">4.8</A>
</LI><LI CLASS="li-indexenv">operation specific type inference, <A HREF="#@concept156">5.3.4</A>
</LI><LI CLASS="li-indexenv">optimization, <A HREF="#@concept165">5.4</A>
<UL CLASS="indexenv"><LI CLASS="li-indexenv">
control, <A HREF="#@concept174">5.4.4</A>
</LI><LI CLASS="li-indexenv">function call, <A HREF="#@concept205">5.8</A>
</LI><LI CLASS="li-indexenv">let, <A HREF="#@concept167">5.4.1</A>
</LI><LI CLASS="li-indexenv">multiple value, <A HREF="#@concept178">5.4.6</A>
</LI><LI CLASS="li-indexenv">type check, <A HREF="#@concept163">5.3.6</A>, <A HREF="#@concept271">5.13.2</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">optimize declaration, <A HREF="#@concept78">3.6</A>, <A HREF="#@concept119">4.7.1</A>
</LI><LI CLASS="li-indexenv">optimize-interface declaration, <A HREF="#@concept127">4.7.2</A>
</LI><LI CLASS="li-indexenv">optional<UL CLASS="indexenv"><LI CLASS="li-indexenv">
stack frame kind, <A HREF="#@concept58">3.3.4</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">or (union) types, <A HREF="#@concept138">5.2.4</A>
</LI><LI CLASS="li-indexenv">original source, <A HREF="#@concept96">4.4.2</A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">package locks, <A HREF="#@concept2">2.5</A>
</LI><LI CLASS="li-indexenv">pointers, <A HREF="#@concept291">6.5</A>
</LI><LI CLASS="li-indexenv">policy<UL CLASS="indexenv"><LI CLASS="li-indexenv">
compiler, <A HREF="#@concept117">4.7</A>
</LI><LI CLASS="li-indexenv">debugger, <A HREF="#@concept76">3.6</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">precise type checking, <A HREF="#@concept110">4.5.2</A>
</LI><LI CLASS="li-indexenv">primary method, <A HREF="#@concept12">2.23.1</A>
</LI><LI CLASS="li-indexenv">processing path, <A HREF="#@concept98">4.4.3</A>
</LI><LI CLASS="li-indexenv">profiling, <A HREF="#@concept34">2.23.7</A>, <A HREF="#@concept280">5.14</A>
<UL CLASS="indexenv"><LI CLASS="li-indexenv">
methods, <A HREF="#@concept35">2.23.7</A>
</LI></UL>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">random number generation, <A HREF="#@concept9">2.19</A>
<UL CLASS="indexenv"><LI CLASS="li-indexenv">
MT-19937 generator, <A HREF="#@concept10">2.19.1</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">read errors<UL CLASS="indexenv"><LI CLASS="li-indexenv">
compiler, <A HREF="#@concept104">4.4.6</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">recording of inline expansions, <A HREF="#@concept206">5.8.1</A>
</LI><LI CLASS="li-indexenv">recursion, <A HREF="#@concept183">5.5</A>
<UL CLASS="indexenv"><LI CLASS="li-indexenv">
self, <A HREF="#@concept187">5.6.1</A>
</LI><LI CLASS="li-indexenv">tail, <A HREF="#@concept61">3.3.5</A>, <A HREF="#@concept190">5.6.4</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">representation<UL CLASS="indexenv"><LI CLASS="li-indexenv">
object, <A HREF="#@concept211">5.10</A>, <A HREF="#@concept223">5.11.1</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">representation efficiency notes, <A HREF="#@concept272">5.13.3</A>
</LI><LI CLASS="li-indexenv">require, <A HREF="#@concept47">2.28</A>
</LI><LI CLASS="li-indexenv">rest argument efficiency, <A HREF="#@concept256">5.12.3</A>
</LI><LI CLASS="li-indexenv">return values<UL CLASS="indexenv"><LI CLASS="li-indexenv">
local call, <A HREF="#@concept191">5.6.5</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">run time<UL CLASS="indexenv"><LI CLASS="li-indexenv">
interpretation of, <A HREF="#@concept285">5.14.7</A>
</LI></UL>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">safety optimization quality, <A HREF="#@concept125">4.7.1</A>
</LI><LI CLASS="li-indexenv">sealing, <A HREF="#@concept28">2.23.6</A>
<UL CLASS="indexenv"><LI CLASS="li-indexenv">
methods, <A HREF="#@concept30">2.23.6</A>
</LI><LI CLASS="li-indexenv">subclasses, <A HREF="#@concept29">2.23.6</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">search lists, <A HREF="#@concept6">2.16.4</A>
</LI><LI CLASS="li-indexenv">semi-inline expansion, <A HREF="#@concept80">3.6</A>
</LI><LI CLASS="li-indexenv">severity of compiler errors, <A HREF="#@concept101">4.4.4</A>
</LI><LI CLASS="li-indexenv">signals, <A HREF="#@concept295">6.8</A>
</LI><LI CLASS="li-indexenv">simple-streams, <A HREF="#@concept3">2.13</A>
</LI><LI CLASS="li-indexenv">slot access optimization, <A HREF="#@concept14">2.23.3</A>
</LI><LI CLASS="li-indexenv">slot declaration<UL CLASS="indexenv"><LI CLASS="li-indexenv">
inline, <A HREF="#@concept17">2.23.3.2</A>
</LI><LI CLASS="li-indexenv">method recompilation, <A HREF="#@concept20">2.23.3.3</A>
</LI><LI CLASS="li-indexenv">slot-boundp, <A HREF="#@concept16">2.23.3.1</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">slot declarations, <A HREF="#@concept15">2.23.3</A>
</LI><LI CLASS="li-indexenv">slot type checking, <A HREF="#@concept13">2.23.2</A>
</LI><LI CLASS="li-indexenv">source location printing<UL CLASS="indexenv"><LI CLASS="li-indexenv">
debugger, <A HREF="#@concept72">3.5</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">source-to-source transformation, <A HREF="#@concept100">4.4.3</A>, <A HREF="#@concept179">5.4.7</A>
</LI><LI CLASS="li-indexenv">space optimization, <A HREF="#@concept209">5.9</A>
</LI><LI CLASS="li-indexenv">space optimization quality, <A HREF="#@concept123">4.7.1</A>
</LI><LI CLASS="li-indexenv">specialized array types, <A HREF="#@concept237">5.11.8</A>
</LI><LI CLASS="li-indexenv">specialized structure slots, <A HREF="#@concept241">5.11.9</A>
</LI><LI CLASS="li-indexenv">speed optimization quality, <A HREF="#@concept121">4.7.1</A>
</LI><LI CLASS="li-indexenv">stack frames, <A HREF="#@concept50">3.3</A>
</LI><LI CLASS="li-indexenv">stack numbers, <A HREF="#@concept226">5.11.2</A>, <A HREF="#@concept275">5.13.3</A>
</LI><LI CLASS="li-indexenv">start-block declaration, <A HREF="#@concept196">5.7.2</A>
</LI><LI CLASS="li-indexenv">static functions, <A HREF="#@concept131">4.8</A>
</LI><LI CLASS="li-indexenv">strings, <A HREF="#@concept246">5.11.11</A>
</LI><LI CLASS="li-indexenv">structure types, <A HREF="#@concept145">5.2.8</A>
<UL CLASS="indexenv"><LI CLASS="li-indexenv">
efficiency of, <A HREF="#@concept214">5.10.2</A>
</LI><LI CLASS="li-indexenv">numeric slots, <A HREF="#@concept240">5.11.9</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">style recommendations, <A HREF="#@concept150">5.2.11</A>, <A HREF="#@concept181">5.4.8</A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">Type Index, <A HREF="#@concept301">13.4.2</A>
</LI><LI CLASS="li-indexenv">tail recursion, <A HREF="#@concept60">3.3.5</A>, <A HREF="#@concept182">5.5</A>, <A HREF="#@concept189">5.6.4</A>
</LI><LI CLASS="li-indexenv">time formatting, <A HREF="#@concept8">2.18</A>
</LI><LI CLASS="li-indexenv">time parsing, <A HREF="#@concept7">2.18</A>
</LI><LI CLASS="li-indexenv">timing, <A HREF="#@concept281">5.14</A>
</LI><LI CLASS="li-indexenv">trace files, <A HREF="#@concept258">5.12.5</A>
</LI><LI CLASS="li-indexenv">tracing, <A HREF="#@concept32">2.23.7</A>, <A HREF="#@concept82">3.10</A>
<UL CLASS="indexenv"><LI CLASS="li-indexenv">
errors, <A HREF="#@concept84">3.10</A>
</LI><LI CLASS="li-indexenv">methods, <A HREF="#@concept33">2.23.7</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">transformation<UL CLASS="indexenv"><LI CLASS="li-indexenv">
source-to-source, <A HREF="#@concept180">5.4.7</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">tuning, <A HREF="#@concept266">5.13</A>, <A HREF="#@concept283">5.14</A>
</LI><LI CLASS="li-indexenv">type checking<UL CLASS="indexenv"><LI CLASS="li-indexenv">
at compile time, <A HREF="#@concept109">4.5.1</A>
</LI><LI CLASS="li-indexenv">efficiency of, <A HREF="#@concept269">5.13.2</A>
</LI><LI CLASS="li-indexenv">optimization, <A HREF="#@concept162">5.3.6</A>
</LI><LI CLASS="li-indexenv">precise, <A HREF="#@concept111">4.5.2</A>
</LI><LI CLASS="li-indexenv">weakened, <A HREF="#@concept113">4.5.3</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">type declarations<UL CLASS="indexenv"><LI CLASS="li-indexenv">
variable, <A HREF="#@concept228">5.11.3</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">type inference, <A HREF="#@concept151">5.3</A>
<UL CLASS="indexenv"><LI CLASS="li-indexenv">
dynamic, <A HREF="#@concept161">5.3.5</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">types<UL CLASS="indexenv"><LI CLASS="li-indexenv">
alien, <A HREF="#@concept289">6.4</A>
</LI><LI CLASS="li-indexenv">equivalence, <A HREF="#@concept133">5.2.2</A>
</LI><LI CLASS="li-indexenv">foreign language, <A HREF="#@concept290">6.4</A>
</LI><LI CLASS="li-indexenv">function, <A HREF="#@concept143">5.2.6</A>
</LI><LI CLASS="li-indexenv">in python, <A HREF="#@concept107">4.5</A>, <A HREF="#@concept132">5.2</A>
</LI><LI CLASS="li-indexenv">numeric, <A HREF="#@concept220">5.11</A>
</LI><LI CLASS="li-indexenv">portability, <A HREF="#@concept115">4.6</A>
</LI><LI CLASS="li-indexenv">restrictions on, <A HREF="#@concept149">5.2.10</A>
</LI><LI CLASS="li-indexenv">specialized array, <A HREF="#@concept239">5.11.8</A>
</LI><LI CLASS="li-indexenv">structure, <A HREF="#@concept147">5.2.8</A>
</LI><LI CLASS="li-indexenv">uncertainty, <A HREF="#@concept267">5.13.1</A>
</LI></UL>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">uncertainty of types, <A HREF="#@concept268">5.13.1</A>
</LI><LI CLASS="li-indexenv">undefined warnings, <A HREF="#@concept93">4.3.1</A>
</LI><LI CLASS="li-indexenv">union (<TT class=code>or</TT>) types, <A HREF="#@concept137">5.2.4</A>
</LI><LI CLASS="li-indexenv">unix<UL CLASS="indexenv"><LI CLASS="li-indexenv">
pathnames, <A HREF="#@concept4">2.16.1</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">unix signals, <A HREF="#@concept294">6.8</A>
</LI><LI CLASS="li-indexenv">unknown code locations, <A HREF="#@concept62">3.3.6</A>
</LI><LI CLASS="li-indexenv">unreachable code deletion, <A HREF="#@concept175">5.4.5</A>
</LI><LI CLASS="li-indexenv">unused expression elimination, <A HREF="#@concept171">5.4.3</A>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">Variable Index, <A HREF="#@concept300">13.4.2</A>
</LI><LI CLASS="li-indexenv">Virtual Machine (VM, or IR2) representation, <A HREF="#@concept261">5.12.5</A>
</LI><LI CLASS="li-indexenv">validity of debug variables, <A HREF="#@concept69">3.4.1</A>
</LI><LI CLASS="li-indexenv">values declaration, <A HREF="#@concept144">5.2.7</A>
</LI><LI CLASS="li-indexenv">variables<UL CLASS="indexenv"><LI CLASS="li-indexenv">
debugger access, <A HREF="#@concept66">3.4</A>
</LI><LI CLASS="li-indexenv">non-descriptor, <A HREF="#@concept227">5.11.3</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">vectors<UL CLASS="indexenv"><LI CLASS="li-indexenv">
efficiency of, <A HREF="#@concept216">5.10.4</A>
</LI></UL>
</LI><LI CLASS="li-indexenv">verbosity<UL CLASS="indexenv"><LI CLASS="li-indexenv">
of efficiency notes, <A HREF="#@concept278">5.13.4</A>
</LI><LI CLASS="li-indexenv">of error messages, <A HREF="#@concept106">4.4.7</A>
</LI></UL>
<BR>
<BR>
</LI><LI CLASS="li-indexenv">weakened type checking, <A HREF="#@concept112">4.5.3</A>
</LI><LI CLASS="li-indexenv">word integers, <A HREF="#@concept235">5.11.6</A>
</LI></UL></TD></TR>
</TABLE><!--NAME cmu-user.hcnd.html-->
<!--CUT END -->
<!--HTMLFOOT-->
<!--ENDHTML-->
<!--FOOTER-->
<HR SIZE=2><BLOCKQUOTE CLASS="quote"><EM>This document was translated from L<sup>A</sup>T<sub>E</sub>X by
</EM><A HREF="http://hevea.inria.fr/index.html"><EM>H</EM><EM><FONT SIZE=2><sup>E</sup></FONT></EM><EM>V</EM><EM><FONT SIZE=2><sup>E</sup></FONT></EM><EM>A</EM></A><EM>.</EM></BLOCKQUOTE></BODY>
</HTML>
cmucl-docs 20c-2 / usr / share / doc / cmucl-docs / cmu-user.html
