0.6.11.5:
[sbcl.git] / doc / compiler.sgml
1 <chapter id="compiler"><title>The Compiler</>
2
3 <para>This chapter will discuss most compiler issues other than
4 efficiency, including compiler error messages, the &SBCL compiler's
5 unusual approach to type safety in the presence of type declarations,
6 the effects of various compiler optimization policies, and the way
7 that inlining and open coding may cause optimized code to differ from
8 a naive translation. Efficiency issues are sufficiently varied and
9 separate that they have <link linkend="efficiency">their own
10 chapter</link>.</para>
11
12 <sect1><title>Error Messages</>
13 <!--INDEX {error messages}{compiler}-->
14 <!--INDEX {compiler error messages}-->
15
16 <para>The compiler supplies a large amount of source location
17 information in error messages. The error messages contain a lot of
18 detail in a terse format, so they may be confusing at first. Error
19 messages will be illustrated using this example program:
20 <programlisting>(defmacro zoq (x)
21   `(roq (ploq (+ ,x 3))))
22
23 (defun foo (y)
24   (declare (symbol y))
25   (zoq y))</programlisting>
26 The main problem with this program is that it is trying to add
27 <literal>3</> to a symbol. Note also that the functions
28 <function>roq</> and <function>ploq</> aren't defined anywhere.
29 </para>
30
31 <sect2><title>The Parts of the Error Message</>
32
33 <para>When processing this program, the compiler will produce this warning:
34 <screen>file: /tmp/foo.lisp
35
36 in: DEFUN FOO
37   (ZOQ Y)
38 --> ROQ PLOQ + 
39 ==>
40   Y
41 caught WARNING:
42   Result is a SYMBOL, not a NUMBER.</screen>
43 In this example we see each of the six possible parts of a compiler error
44 message:
45 <orderedlist>
46   <listitem><para><computeroutput>File: /tmp/foo.lisp</>
47     This is the name of the file that the compiler read the
48     relevant code from.  The file name is displayed because it
49     may not be immediately obvious when there is an
50     error during compilation of a large system, especially when
51     <function>with-compilation-unit</> is used to delay undefined
52     warnings.</para></listitem>
53   <listitem><para><computeroutput>in: DEFUN FOO</> This is the
54     definition top-level form responsible for the error. It is
55     obtained by taking the first two elements of the enclosing form
56     whose first element is a symbol beginning with <quote><literal>def</></>.
57     If there is no such enclosing <quote><literal>def</></> form, then the 
58     outermost form is used.  If there are multiple <literal>def</>
59     forms, then they are all printed from the outside in, separated by
60     <literal>=></>'s.  In this example, the problem was in the
61     <function>defun</> for <function>foo</>.</para></listitem>
62   <listitem><para><computeroutput>(ZOQ Y)</> This is the
63     <emphasis>original source</> form responsible for the error.
64     Original source means that the form directly appeared in the
65     original input to the compiler, i.e. in the lambda passed to
66     <function>compile</> or in the top-level form read from the
67     source file. In this example, the expansion of the <function>zoq</>
68     macro was responsible for the error.</para></listitem>
69   <listitem><para><computeroutput>--> ROQ PLOQ +</> This is the
70     <emphasis>processing path</> that the compiler used to produce
71     the errorful code.  The processing path is a representation of
72     the evaluated forms enclosing the actual source that the
73     compiler encountered when processing the original source.
74     The path is the first element of each form, or the form itself
75     if the form is not a list.  These forms result from the
76     expansion of macros or source-to-source transformation done
77     by the compiler.  In this example, the enclosing evaluated forms
78     are the calls to <function>roq</>, <function>ploq</> and
79     <function>+</>.  These calls resulted from the expansion of
80     the <function>zoq</> macro.</para></listitem>
81   <listitem><para><computeroutput>==> Y</> This is the
82     <emphasis>actual source</> responsible for the error. If
83     the actual source appears in the explanation, then
84     we print the next enclosing evaluated form, instead of
85     printing the actual source twice.  (This is the form
86     that would otherwise have been the last form of the processing
87     path.) In this example, the problem is with the evaluation of
88     the reference to the variable <varname>y</>.</para></listitem>
89   <listitem><para>
90     <computeroutput>caught WARNING: Result is a SYMBOL, not a NUMBER.</>
91     This is the <emphasis>explanation</> of the problem. In this
92     example, the problem is that <varname>y</> evaluates to a symbol,
93     but is in a context where a number is required (the argument
94     to <function>+</>).</para></listitem>
95 </orderedlist>
96
97 Note that each part of the error message is distinctively marked:
98
99 <itemizedlist>
100   <listitem><para> <computeroutput>file:</> and <computeroutput>in:</>
101     mark the file and definition, respectively.</para></listitem>
102   <listitem><para> The original source is an indented form with no
103     prefix.</para></listitem>
104   <listitem><para> Each line of the processing path is prefixed with
105    <computeroutput>--></computeroutput></para></listitem>
106   <listitem><para> The actual source form is indented like the original
107     source, but is marked by a preceding <computeroutput>==></> line.
108     </para></listitem>
109   <listitem><para> The explanation is prefixed with the error
110     severity, which can be <computeroutput>caught ERROR:</>,
111     <computeroutput>caught WARNING:</>,
112     <computeroutput>caught STYLE-WARNING:</>, or
113     <computeroutput>note:</>. </para></listitem>
114 </itemizedlist>
115 </para>
116
117 <para>Each part of the error message is more specific than the preceding
118 one.  If consecutive error messages are for nearby locations, then the
119 front part of the error messages would be the same.  In this case, the
120 compiler omits as much of the second message as in common with the
121 first.  For example:
122 <screen>file: /tmp/foo.lisp
123
124 in: DEFUN FOO
125   (ZOQ Y)
126 --> ROQ
127 ==>
128   (PLOQ (+ Y 3))
129 caught STYLE-WARNING:
130   undefined function: PLOQ
131
132 ==>
133   (ROQ (PLOQ (+ Y 3)))
134 caught STYLE-WARNING:
135   undefined function: ROQ</screen>
136 In this example, the file, definition and original source are
137 identical for the two messages, so the compiler omits them in the
138 second message.  If consecutive messages are entirely identical, then
139 the compiler prints only the first message, followed by:
140 <computeroutput>[Last message occurs <replaceable>repeats</> times]</>
141 where <replaceable>repeats</> is the number of times the message
142 was given.</para>
143
144 <para>If the source was not from a file, then no file line is printed.
145 If the actual source is the same as the original source, then the
146 processing path and actual source will be omitted. If no forms
147 intervene between the original source and the actual source, then the
148 processing path will also be omitted.</para>
149
150 </sect2>
151
152 <sect2><title>The Original and Actual Source</>
153
154 <para>The <emphasis>original source</> displayed will almost always be
155 a list. If the actual source for an error message is a symbol, the
156 original source will be the immediately enclosing evaluated list form.
157 So even if the offending symbol does appear in the original source,
158 the compiler will print the enclosing list and then print the symbol
159 as the actual source (as though the symbol were introduced by a
160 macro.)</para>
161
162 <para>When the <emphasis>actual source</> is displayed
163 (and is not a symbol), it will always
164 be code that resulted from the expansion of a macro or a source-to-source
165 compiler optimization.  This is code that did not appear in the original
166 source program; it was introduced by the compiler.</para>
167
168 <para>Keep in mind that when the compiler displays a source form
169 in an error message, it always displays the most specific (innermost)
170 responsible form.  For example, compiling this function
171 <programlisting>(defun bar (x)
172   (let (a)
173     (declare (fixnum a))
174     (setq a (foo x))
175     a))</programlisting>
176 gives this error message
177 <screen>in: DEFUN BAR
178   (LET (A) (DECLARE (FIXNUM A)) (SETQ A (FOO X)) A)
179 caught WARNING: The binding of A is not a FIXNUM:
180   NIL</screen>
181 This error message is not saying <quote>there is a problem somewhere in
182 this <function>let</></quote> &mdash; it is saying that there is a
183 problem with the <function>let</> itself. In this example, the problem
184 is that <varname>a</>'s <literal>nil</> initial value is not a
185 <type>fixnum</>.</para>
186
187 </sect2>
188
189 <sect2><title>The Processing Path</>
190 <!--INDEX processing path-->
191 <!--INDEX macroexpansion-->
192 <!--INDEX source-to-source transformation-->
193
194 <para>The processing path is mainly useful for debugging macros, so if
195 you don't write macros, you can probably ignore it. Consider this
196 example:
197
198 <programlisting>(defun foo (n)
199   (dotimes (i n *undefined*)))
200 </programlisting>
201
202 Compiling results in this error message:
203
204 <screen>in: DEFUN FOO
205   (DOTIMES (I N *UNDEFINED*))
206 --> DO BLOCK LET TAGBODY RETURN-FROM
207 ==>
208   (PROGN *UNDEFINED*)
209 caught STYLE-WARNING:
210   undefined variable: *UNDEFINED*</screen>
211
212 Note that <function>do</> appears in the processing path. This is because
213 <function>dotimes</> expands into:
214
215 <programlisting>(do ((i 0 (1+ i)) (#:g1 n))
216     ((>= i #:g1) *undefined*)
217   (declare (type unsigned-byte i)))</programlisting>
218
219 The rest of the processing path results from the expansion
220 of <function>do</>:
221
222 <programlisting>
223 (block nil
224   (let ((i 0) (#:g1 n))
225     (declare (type unsigned-byte i))
226     (tagbody (go #:g3)
227      #:g2    (psetq i (1+ i))
228      #:g3    (unless (>= i #:g1) (go #:g2))
229              (return-from nil (progn *undefined*)))))
230 </programlisting>
231
232 In this example, the compiler descended into the <function>block</>,
233 <function>let</>, <function>tagbody</> and <function>return-from</> to
234 reach the <function>progn</> printed as the actual source. This is a
235 place where the <quote>actual source appears in explanation</> rule
236 was applied. The innermost actual source form was the symbol
237 <varname>*undefined*</> itself, but that also appeared in the
238 explanation, so the compiler backed out one level.</para>
239
240 </sect2>
241
242 <sect2><title>Error Severity</>
243 <!--INDEX severity of compiler errors -->
244 <!--INDEX compiler error severity -->
245
246 <para>There are four levels of compiler error severity:
247 <wordasword>error</>, <wordasword>warning</>, <wordasword>style
248 warning</>, and <wordasword>note</>. The first three levels correspond
249 to condition classes which are defined in the &ANSI; standard for
250 &CommonLisp; and which have special significance to the
251 <function>compile</> and <function>compile-file</> functions. These
252 levels of compiler error severity occur when the compiler handles
253 conditions of these classes. The fourth level of compiler error
254 severity, <wordasword>note</>, is used for problems which are too mild
255 for the standard condition classes, typically hints about how
256 efficiency might be improved.</para>
257
258 </sect2>
259
260 <sect2><title>Errors During Macroexpansion</>
261 <!--INDEX {macroexpansion}{errors during}-->
262
263 <para>The compiler handles errors that happen during macroexpansion,
264 turning them into compiler errors. If you want to debug the error (to
265 debug a macro), you can set <varname>*break-on-signals*</> to
266 <literal>error</>. For example, this definition:
267
268 <programlisting>(defun foo (e l)
269   (do ((current l (cdr current))
270        ((atom current) nil))
271       (when (eq (car current) e) (return current))))</programlisting>
272
273 gives this error:
274
275 <screen>in: DEFUN FOO
276   (DO ((CURRENT L #) (# NIL)) (WHEN (EQ # E) (RETURN CURRENT)) )
277 caught ERROR: (during macroexpansion)
278
279 error in function LISP::DO-DO-BODY:
280    DO step variable is not a symbol: (ATOM CURRENT)</screen>
281 </para>
282
283 </sect2>
284
285 <sect2><title>Read Errors</>
286 <!--INDEX {read errors}{compiler}-->
287
288 <para>&SBCL;'s compiler (unlike &CMUCL;'s) does not attempt to recover
289 from read errors when reading a source file, but instead just reports
290 the offending character position and gives up on the entire source
291 file.</para>
292
293 </sect2>
294
295 <!-- FIXME: How much control over error messages is in SBCL?
296 _     How much should be? How much of this documentation should
297 _     we save or adapt? 
298
299 _ %%\node Error Message Parameterization,  , Read Errors, Interpreting Error Messages
300 _ \subsection{Error Message Parameterization}
301 _ \cpsubindex{error messages}{verbosity}
302 _ \cpsubindex{verbosity}{of error messages}
303
304 _ There is some control over the verbosity of error messages.  See also
305 _ \varref{undefined-warning-limit}, \code{*efficiency-note-limit*} and
306 _ \varref{efficiency-note-cost-threshold}.
307
308 _ \begin{defvar}{}{enclosing-source-cutoff}
309
310 _   This variable specifies the number of enclosing actual source forms
311 _   that are printed in full, rather than in the abbreviated processing
312 _   path format.  Increasing the value from its default of \code{1}
313 _   allows you to see more of the guts of the macroexpanded source,
314 _   which is useful when debugging macros.
315 _ \end{defvar}
316
317 _ \begin{defvar}{}{error-print-length}
318 _   \defvarx{error-print-level}
319
320 _   These variables are the print level and print length used in
321 _   printing error messages.  The default values are \code{5} and
322 _   \code{3}.  If null, the global values of \code{*print-level*} and
323 _   \code{*print-length*} are used.
324 _ \end{defvar}
325
326 _ \begin{defmac}{extensions:}{def-source-context}{%
327 _     \args{\var{name} \var{lambda-list} \mstar{form}}}
328
329 _   This macro defines how to extract an abbreviated source context from
330 _   the \var{name}d form when it appears in the compiler input.
331 _   \var{lambda-list} is a \code{defmacro} style lambda-list used to
332 _   parse the arguments.  The \var{body} should return a list of
333 _   subforms that can be printed on about one line.  There are
334 _   predefined methods for \code{defstruct}, \code{defmethod}, etc.  If
335 _   no method is defined, then the first two subforms are returned.
336 _   Note that this facility implicitly determines the string name
337 _   associated with anonymous functions.
338 _ \end{defmac}
339
340 _ -->
341
342 </sect1>
343
344 <sect1><title>The Compiler's Handling of Types</>
345
346 <para>The most unusual features of the &SBCL; compiler (which is
347 very similar to the original &CMUCL compiler, also known as
348 &Python;) is its unusually sophisticated understanding of the
349 &CommonLisp; type system and its unusually conservative approach to
350 the implementation of type declarations. These two features reward the
351 use of type declarations throughout development, even when high
352 performance is not a concern. (Also, as discussed <link
353 linkend="efficiency">in the chapter on performance</>, the use of
354 appropriate type declarations can be very important for performance as
355 well.)</para>
356
357 <para>The &SBCL; compiler, like the related compiler in &CMUCL;,
358 treats type declarations much differently than other Lisp compilers.
359 By default (<emphasis>i.e.</>, at ordinary levels of the
360 <parameter>safety</> compiler optimization parameter), the compiler
361 doesn't blindly believe most type declarations; it considers them
362 assertions about the program that should be checked.</para>
363
364 <para>The &SBCL; compiler also has a greater knowledge of the
365 &CommonLisp; type system than other compilers.  Support is incomplete
366 only for the <type>not</>, <type>and</> and <type>satisfies</>
367 types.
368 <!-- FIXME: See also sections \ref{advanced-type-stuff}
369      and \ref{type-inference}, once we snarf them from the
370      CMU CL manual. -->
371 </para>
372
373 <sect2 id=compiler-impl-limitations><title>Implementation Limitations</>
374
375 <para>
376 Ideally, the compiler would consider <emphasis>all</> type declarations to
377 be assertions, so that adding type declarations to a program, no
378 matter how incorrect they might be, would <emphasis>never</> cause
379 undefined behavior. As of &SBCL; version 0.6.4, the compiler is known to
380 fall short of this goal in two areas:
381 <itemizedlist>
382   <listitem><para>The compiler trusts function return values which 
383     have been established with <function>proclaim</>.</para></listitem>
384   <listitem><para>There are a few poorly characterized but apparently
385     very uncommon situations where a type declaration in an unexpected
386     location will be trusted and never checked by the
387     compiler.</para></listitem>
388 </itemizedlist></para>
389
390 <para>These are important bugs, but are not necessarily easy to fix,
391 so they may, alas, remain in the system for a while.</para>
392
393 </sect2>
394
395 <sect2><title>Type Errors at Compile Time</>
396 <!--INDEX compile time type errors-->
397 <!--INDEX type checking}{at compile time}-->
398
399 <para>If the compiler can prove at compile time that some portion of
400 the program cannot be executed without a type error, then it will give
401 a warning at compile time. It is possible that the offending code
402 would never actually be executed at run-time due to some higher level
403 consistency constraint unknown to the compiler, so a type warning
404 doesn't always indicate an incorrect program. For example, consider
405 this code fragment:
406
407 <programlisting>(defun raz (foo)
408   (let ((x (case foo
409              (:this 13)
410              (:that 9)
411              (:the-other 42))))
412     (declare (fixnum x))
413     (foo x)))
414 </programlisting>
415
416 Compilation produces this warning:
417
418 <screen>in: DEFUN RAZ
419   (CASE FOO (:THIS 13) (:THAT 9) (:THE-OTHER 42))
420 --> LET COND IF COND IF COND IF
421 ==>
422   (COND)
423 caught WARNING: This is not a FIXNUM:
424   NIL</screen>
425
426 In this case, the warning means that if <varname>foo</> isn't any of
427 <literal>:this</>, <literal>:that</> or <literal>:the-other</>, then
428 <varname>x</> will be initialized to <literal>nil</>, which the
429 <type>fixnum</> declaration makes illegal. The warning will go away if
430 <function>ecase</> is used instead of <function>case</>, or if
431 <literal>:the-other</> is changed to <literal>t</>.</para>
432
433 <para>This sort of spurious type warning happens moderately often in
434 the expansion of complex macros and in inline functions. In such
435 cases, there may be dead code that is impossible to correctly execute.
436 The compiler can't always prove this code is dead (could never be
437 executed), so it compiles the erroneous code (which will always signal
438 an error if it is executed) and gives a warning.</para>
439
440 <para>
441 Type warnings are inhibited when the
442 <parameter>extensions:inhibit-warnings</> optimization quality is
443 <literal>3</>. (See <link linkend="compiler-policy">the section 
444 on compiler policy</>.) This can be used in a local declaration
445 to inhibit type warnings in a code fragment that has spurious
446 warnings.</para>
447
448 </sect2>
449
450 <sect2><title>Precise Type Checking</>
451 <!--INDEX precise type checking-->
452 <!--INDEX {type checking}{precise}-->
453
454 <para>With the default compilation policy, all type declarations are
455 precisely checked, except in a few situations (such as using
456 <function>the</> to constrain the argument type passed to a function)
457 where they are simply ignored instead. Precise checking means that the
458 check is done as though <function>typep</> had been called with the
459 exact type specifier that appeared in the declaration. In &SBCL;,
460 adding type declarations makes code safer. (Except that as noted <link
461 linkend="compiler-impl-limitations">elsewhere</link>, remaining bugs in
462 the compiler's handling of types unfortunately provide some exceptions to
463 this rule.)</para>
464
465 <para>If a variable is declared to be
466 <type>(integer 3 17)</>
467 then its
468 value must always always be an integer between <literal>3</>
469 and <literal>17</>.
470 If multiple type declarations apply to a single variable, then all the
471 declarations must be correct; it is as though all the types were
472 intersected producing a single <type>and</> type specifier.</para>
473
474 <para>Argument type declarations are automatically enforced. If you declare
475 the type of a function argument, a type check will be done when that
476 function is called. In a function call, the called function does the
477 argument type checking, which means that a more restrictive type
478 assertion in the calling function (e.g., from <function>the</>) may be
479 lost.</para>
480
481 <para>The types of structure slots are also checked. The value of a
482 structure slot must always be of the type indicated in any
483 <literal>:type</> slot option. </para>
484
485 <para>In traditional &CommonLisp; compilers, not all type assertions
486 are checked, and type checks are not precise. Traditional compilers
487 blindly trust explicit type declarations, but may check the argument
488 type assertions for built-in functions. Type checking is not precise,
489 since the argument type checks will be for the most general type legal
490 for that argument. In many systems, type declarations suppress what
491 little type checking is being done, so adding type declarations makes
492 code unsafe. This is a problem since it discourages writing type
493 declarations during initial coding. In addition to being more error
494 prone, adding type declarations during tuning also loses all the
495 benefits of debugging with checked type assertions.</para>
496
497 <para>To gain maximum benefit from the compiler's type checking, you
498 should always declare the types of function arguments and structure
499 slots as precisely as possible. This often involves the use of
500 <type>or</>, <type>member</>, and other list-style type specifiers.</para>
501
502 </sect2>
503
504 <sect2 id="weakened-type-checking"><title>Weakened Type Checking</>
505 <!--INDEX weakened type checking-->
506 <!--INDEX {type checking}{weakened}-->
507
508 <para>At one time, &CMUCL; supported another level of type checking,
509 <quote>weakened type checking</>, when the value for the
510 <parameter>speed</> optimization quality is greater than
511 <parameter>safety</>, and <parameter>safety</> is not <literal>0</>.
512 The &CMUCL; manual still has a description of it, but the code no
513 longer corresponds to the manual. It sounds like a good thing to have,
514 and we might someday be able to restore it in &SBCL; but in the
515 meantime, if you ask the compiler to optimize <parameter>speed</> to a
516 higher level than <parameter>safety</>, your program is performing
517 without a safety net, because &SBCL; may believe any or all type
518 declarations without any runtime checking at all.</para>
519
520 <!-- (beginning of text adapted from out-of-date CMUCL manual, describing
521 _    features it would be nice for SBCL to restore someday)
522
523 _ <para>When the value for the <parameter>speed</> optimization quality
524 _ is greater than <parameter>safety</>, and <parameter>safety</> is not
525 _ <literal>0</>, then type checking is weakened to reduce the speed and
526 _ space penalty. In structure-intensive code this can double the speed,
527 _ yet still catch most type errors. Weakened type checks provide a level
528 _ of safety similar to that of <quote>safe</> code in other &CommonLisp;
529 _ compilers.</para>
530
531 _ <para>A type check is weakened by changing the check to be for some
532 _ convenient supertype of the asserted type. For example, <type>(integer
533 _ 3 17)</> is changed to <type>fixnum</>, <type>(simple-vector 17)</> to
534 _ <type>simple-vector</>, and structure types are changed to
535 _ <type>structure-object</>. A test for a complex type like <type>(or node hunk
536 _ (member :foo :bar :baz))</> will be omitted entirely (i.e., the type
537 _ is weakened to <type>*</>.) If a precise check can be done for no
538 _ extra cost, then no weakening is done.</para>
539
540 _ <para>Although weakened type checking is similar to type checking done
541 _ by other compilers, it is sometimes safer and sometimes less safe.
542 _ Weakened checks are done in the same places is precise checks, so all
543 _ the preceding discussion about where checking is done still applies.
544 _ Weakened checking is sometimes somewhat unsafe because although the
545 _ check is weakened, the precise type is still input into type
546 _ inference. In some contexts this will result in type inferences not
547 _ justified by the weakened check, and hence deletion of some type
548 _ checks that would be done by conventional compilers.</para>
549
550 _ <para>For example, if this code was compiled with weakened checks
551
552 _ <programlisting>(defstruct foo
553 _   (a nil :type simple-string))
554
555 _ (defstruct bar
556 _   (a nil :type single-float))
557
558 _ (defun myfun (x)
559 _   (declare (type bar x))
560 _   (* (bar-a x) 3.0))</programlisting>
561
562 _ and <function>myfun</> was passed a value of
563 _ type <type>foo</>, then no type error would be
564 _ signaled, and we would try to multiply a <type>simple-vector</> as
565 _ though it were a <type>single-float</> (with unpredictable results.)
566 _ This is because the check for <type>bar</> was weakened to
567 _ <type>structure-object</>, yet when compiling the call to <type>bar-a</>, the
568 _ compiler thinks it knows it has a <type>bar</>.</para>
569
570 _ <para>Note that normally even weakened type checks report the precise
571 _ type in error messages. For example, if <function>myfun</>'s
572 _ <type>bar</> check is weakened to <type>structure-object</>, and the argument
573 _ is <literal>nil</>, then the error will be:
574
575 _ <screen>Type-error in MYFUN:
576 _   NIL is not of type BAR</screen>
577
578 _ However, there is some speed and space cost for signaling a precise
579 _ error, so the weakened type is reported if the <parameter>speed</>
580 _ optimization quality is <literal>3</> or <parameter>debug</>
581 _ quality is less than <literal>1</>:
582
583 _ <screen>Type-error in MYFUN:
584 _   NIL is not of type STRUCTURE-OBJECT</screen>
585
586 _ </para>
587
588 _ (end of text adapted from out-of-date CMUCL manual, describing
589 _ features it would be nice for SBCL to restore someday) -->
590
591 </sect2>
592
593 <sect2><title>Getting Existing Programs to Run</>
594 <!--INDEX {existing programs}{to run}-->
595 <!--INDEX {types}{portability}-->
596 <!--INDEX {compatibility with other Lisps}
597     (should also have an entry in the non-&ANSI;-isms section)-->
598
599 <para>Since &SBCL;'s compiler does much more comprehensive type
600 checking than other Lisp compilers, &SBCL; will detect type errors in
601 many programs that have been debugged using other compilers. These
602 errors are mostly incorrect declarations, although compile-time type
603 errors can find actual bugs if parts of the program have never been
604 tested.</para>
605
606 <para>Some incorrect declarations can only be detected by run-time
607 type checking. It is very important to initially compile programs with
608 full type checks and then test this version. After the checking
609 version has been tested, then you can consider weakening or
610 eliminating type checks. <emphasis>This applies even to previously
611 debugged programs,</emphasis> because the &SBCL; compiler does much
612 more type inference than other &CommonLisp; compilers, so an incorrect
613 declaration can do more damage.</para>
614
615 <para>The most common problem is with variables whose constant initial
616 value doesn't match the type declaration. Incorrect constant initial
617 values will always be flagged by a compile-time type error, and they
618 are simple to fix once located. Consider this code fragment:
619
620 <programlisting>(prog (foo)
621   (declare (fixnum foo))
622   (setq foo ...)
623   ...)</programlisting>
624
625 Here <varname>foo</> is given an initial value of <literal>nil</>, but
626 is declared to be a <type>fixnum</>.  Even if it is never read, the
627 initial value of a variable must match the declared type.  There are
628 two ways to fix this problem. Change the declaration
629
630 <programlisting>(prog (foo)
631   (declare (type (or fixnum null) foo))
632   (setq foo ...)
633   ...)</programlisting>
634
635 or change the initial value
636
637 <programlisting>(prog ((foo 0))
638   (declare (fixnum foo))
639   (setq foo ...)
640   ...)</programlisting>
641
642 It is generally preferable to change to a legal initial value rather
643 than to weaken the declaration, but sometimes it is simpler to weaken
644 the declaration than to try to make an initial value of the
645 appropriate type.</para>
646
647 <para>Another declaration problem occasionally encountered is
648 incorrect declarations on <function>defmacro</> arguments. This can happen
649 when a function is converted into a macro. Consider this macro:
650
651 <programlisting>(defmacro my-1+ (x)
652   (declare (fixnum x))
653   `(the fixnum (1+ ,x)))</programlisting>
654
655 Although legal and well-defined &CommonLisp; code, this meaning of
656 this definition is almost certainly not what the writer intended. For
657 example, this call is illegal:
658
659 <programlisting>(my-1+ (+ 4 5))</>
660
661 This call is illegal because the argument to the macro is
662 <literal>(+ 4 5)</>, which is a <type>list</>, not a
663 <type>fixnum</>.  Because of
664 macro semantics, it is hardly ever useful to declare the types of
665 macro arguments.  If you really want to assert something about the
666 type of the result of evaluating a macro argument, then put a
667 <function>the</> in the expansion:
668
669 <programlisting>(defmacro my-1+ (x)
670   `(the fixnum (1+ (the fixnum ,x))))</programlisting>
671
672 In this case, it would be stylistically preferable to change this
673 macro back to a function and declare it inline. Macros have no
674 efficiency advantage over inline functions when using the
675 &SBCL; compiler.
676 <!--FIXME: <xref>inline-expansion</>, once we crib the 
677     relevant text from the CMU CL manual.-->
678 </para>
679
680 <para>
681 Some more subtle problems are caused by incorrect declarations that
682 can't be detected at compile time.  Consider this code:
683
684 <programlisting>(do ((pos 0 (position #\a string :start (1+ pos))))
685     ((null pos))
686   (declare (fixnum pos))
687   ...)</programlisting>
688
689 Although <varname>pos</> is almost always a <varname>fixnum</>, it is
690 <literal>nil</> at the end of the loop. If this example is compiled
691 with full type checks (the default), then running it will signal a
692 type error at the end of the loop. If compiled without type checks,
693 the program will go into an infinite loop (or perhaps
694 <function>position</> will complain because <literal>(1+ nil)</> isn't
695 a sensible start.) Why? Because if you compile without type checks,
696 the compiler just quietly believes the type declaration. Since the
697 compiler believes that <varname>pos</> is always a <type>fixnum</>, it
698 believes that <varname>pos</> is never <literal>nil</>, so
699 <literal>(null pos)</> is never true, and the loop exit test is
700 optimized away. Such errors are sometimes flagged by unreachable code
701 notes, but it is still important to initially compile and test any
702 system with full type checks, even if the system works fine when
703 compiled using other compilers.</para>
704
705 <para>In this case, the fix is to weaken the type declaration to
706 <type>(or fixnum null)</>.
707 <footnote><para>Actually, this declaration is unnecessary
708   unnecessary in &SBCL;, since it already knows <function>position</>
709   returns a non-negative <type>fixnum</> or <literal>nil</>.
710   </para></footnote>
711
712 Note that there is usually little performance penalty for weakening a
713 declaration in this way.  Any numeric operations in the body can still
714 assume the variable is a <type>fixnum</>, since <literal>nil</> is not a legal
715 numeric argument.  Another possible fix would be to say:
716
717 <programlisting>(do ((pos 0 (position #\a string :start (1+ pos))))
718     ((null pos))
719   (let ((pos pos))
720     (declare (fixnum pos))
721     ...))</programlisting>
722
723 This would be preferable in some circumstances, since it would allow a
724 non-standard representation to be used for the local <varname>pos</>
725 variable in the loop body.
726 <!-- FIXME: <xref>ND-variables</>, once we crib the text from the 
727      CMU CL manual. -->
728 </para>
729
730 <para>In summary, remember that <emphasis>all</> values that a variable
731 <emphasis>ever</> has must be of the declared type, and that you
732 should test using safe compilation options initially.</para>
733
734 </sect2>
735
736 </sect1>
737
738 <sect1 id="compiler-policy"><title>Compiler Policy</>
739
740 <para>As of version 0.6.4, &SBCL; still uses most of the &CMUCL; code
741 for compiler policy. Thi &CMUCL; code has many features and high-quality
742 documentation, but the two unfortunately do not match. So this area of
743 the compiler and its interface needs to be cleaned up. Meanwhile, here
744 is some rudimentary documentation on the current behavior of the
745 system.</para>
746
747 <para>Compiler policy is controlled by the <parameter>optimize</>
748 declaration. The compiler supports the &ANSI; optimization qualities,
749 and also an extension <parameter>sb-ext:inhibit-warnings</>.</para>
750
751 <para>Ordinarily, when the <parameter>speed</> quality is high, the
752 compiler emits notes to notify the programmer about its inability to
753 apply various optimizations. Setting
754 <parameter>sb-ext:inhibit-warnings</> to a value at least as large as
755 the <parameter>speed</> quality inhibits this notification. This can
756 be useful to suppress notes about code which is known to be
757 unavoidably inefficient. (For example, the compiler issues notes about
758 having to use generic arithmetic instead of fixnum arithmetic, which
759 is not useful for code which truly can't guarantee that its arguments
760 will always be fixnums.)</para>
761
762 <note><para>The basic functionality of the <parameter>optimize
763 inhibit-warnings</> extension will probably be supported in all future
764 versions of the system, but it will probably be renamed when the
765 compiler and its interface are cleaned up. The current name is
766 misleading, because it mostly inhibits optimization notes, not
767 warnings. And making it an optimization quality is misleading, because
768 it shouldn't affect the resulting code at all. It may become a
769 declaration identifier with a name like SB-EXT:INHIBIT-NOTES, so that
770 what's currently written
771
772 <programlisting>(declaim (optimize (sb-ext:inhibit-warnings 2)))</>
773
774 would become something like
775
776 <programlisting>(declaim (sb-ext:inhibit-notes 2))</>
777
778 </para></note>
779
780 <para>When <parameter>speed</> is zero, the compiler emits byte code
781 instead of native code. Byte code can be substantially more compact
782 than native code (on the order of a factor of 2) and is usually much,
783 much slower than native code (on the order of a factor of 50).</para>
784
785 <para>When <parameter>safety</> is zero, almost all runtime checking
786 of types, array bounds, and so forth is suppressed.</para>
787
788 <para>When <parameter>safety</> is less than <parameter>speed</>, any
789 and all type checks may be suppressed. At some point in the past,
790 &CMUCL; had <link linkend="weakened-type-checking">a more nuanced
791 interpretation of this.</link> At some point in the future, &SBCL; may
792 restore that interpretation, or something like it. Until then, setting
793 <parameter>safety</> less than <parameter>speed</> may have roughly
794 the same effect as setting <parameter>safety</> to zero.</para>
795
796 <para>The value of <parameter>space</> mostly influences the
797 compiler's decision whether to inline operations, which tend to
798 increase the size of programs. Use the value <literal>0</> with
799 caution, since it can cause the compiler to inline operations so
800 promiscuously that the net effect is to slow the program by causing
801 cache misses or swapping.</para>
802
803 <!-- FIXME: old CMU CL compiler policy, should perhaps be adapted
804 _    for SBCL. (Unfortunately, the CMU CL docs are out of sync with the
805 _    CMU CL code, so adapting this requires not only reformatting
806 _    the documentation, but rooting out code rot.)
807 _
808 _<sect2 id="compiler-policy"><title>Compiler Policy</>
809 _  INDEX {policy}{compiler}
810 _  INDEX compiler policy
811 _
812 _<para>The policy is what tells the compiler <emphasis>how</> to
813 _compile a program. This is logically (and often textually) distinct
814 _from the program itself. Broad control of policy is provided by the
815 _<parameter>optimize</> declaration; other declarations and variables
816 _control more specific aspects of compilation.</para>
817 _
818 _\begin{comment}
819 _* The Optimize Declaration::
820 _* The Optimize-Interface Declaration::
821 _\end{comment}
822 _
823 _%%\node The Optimize Declaration, The Optimize-Interface Declaration, Compiler Policy, Compiler Policy
824 _\subsection{The Optimize Declaration}
825 _\label{optimize-declaration}
826 _\cindex{optimize declaration}
827 _\cpsubindex{declarations}{\code{optimize}}
828 _
829 _The \code{optimize} declaration recognizes six different
830 _\var{qualities}.  The qualities are conceptually independent aspects
831 _of program performance.  In reality, increasing one quality tends to
832 _have adverse effects on other qualities.  The compiler compares the
833 _relative values of qualities when it needs to make a trade-off; i.e.,
834 _if \code{speed} is greater than \code{safety}, then improve speed at
835 _the cost of safety.
836 _
837 _The default for all qualities (except \code{debug}) is \code{1}.
838 _Whenever qualities are equal, ties are broken according to a broad
839 _idea of what a good default environment is supposed to be.  Generally
840 _this downplays \code{speed}, \code{compile-speed} and \code{space} in
841 _favor of \code{safety} and \code{debug}.  Novice and casual users
842 _should stick to the default policy.  Advanced users often want to
843 _improve speed and memory usage at the cost of safety and
844 _debuggability.
845 _
846 _If the value for a quality is \code{0} or \code{3}, then it may have a
847 _special interpretation.  A value of \code{0} means ``totally
848 _unimportant'', and a \code{3} means ``ultimately important.''  These
849 _extreme optimization values enable ``heroic'' compilation strategies
850 _that are not always desirable and sometimes self-defeating.
851 _Specifying more than one quality as \code{3} is not desirable, since
852 _it doesn't tell the compiler which quality is most important.
853 _
854 _
855 _These are the optimization qualities:
856 _\begin{Lentry}
857 _
858 _\item[\code{speed}] \cindex{speed optimization quality}How fast the
859 _  program should is run.  \code{speed 3} enables some optimizations
860 _  that hurt debuggability.
861 _
862 _\item[\code{compilation-speed}] \cindex{compilation-speed optimization
863 _    quality}How fast the compiler should run.  Note that increasing
864 _  this above \code{safety} weakens type checking.
865 _
866 _\item[\code{space}] \cindex{space optimization quality}How much space
867 _  the compiled code should take up.  Inline expansion is mostly
868 _  inhibited when \code{space} is greater than \code{speed}.  A value
869 _  of \code{0} enables promiscuous inline expansion.  Wide use of a
870 _  \code{0} value is not recommended, as it may waste so much space
871 _  that run time is slowed.  \xlref{inline-expansion} for a discussion
872 _  of inline expansion.
873 _
874 _\item[\code{debug}] \cindex{debug optimization quality}How debuggable
875 _  the program should be.  The quality is treated differently from the
876 _  other qualities: each value indicates a particular level of debugger
877 _  information; it is not compared with the other qualities.
878 _  \xlref{debugger-policy} for more details.
879 _
880 _\item[\code{safety}] \cindex{safety optimization quality}How much
881 _  error checking should be done.  If \code{speed}, \code{space} or
882 _  \code{compilation-speed} is more important than \code{safety}, then
883 _  type checking is weakened (\pxlref{weakened-type-checks}).  If
884 _  \code{safety} if \code{0}, then no run time error checking is done.
885 _  In addition to suppressing type checks, \code{0} also suppresses
886 _  argument count checking, unbound-symbol checking and array bounds
887 _  checks.
888 _
889 _\item[\code{extensions:inhibit-warnings}] \cindex{inhibit-warnings
890 _    optimization quality}This is a CMU extension that determines how
891 _  little (or how much) diagnostic output should be printed during
892 _  compilation.  This quality is compared to other qualities to
893 _  determine whether to print style notes and warnings concerning those
894 _  qualities.  If \code{speed} is greater than \code{inhibit-warnings},
895 _  then notes about how to improve speed will be printed, etc.  The
896 _  default value is \code{1}, so raising the value for any standard
897 _  quality above its default enables notes for that quality.  If
898 _  \code{inhibit-warnings} is \code{3}, then all notes and most
899 _  non-serious warnings are inhibited.  This is useful with
900 _  \code{declare} to suppress warnings about unavoidable problems.
901 _\end{Lentry}
902 _
903 _%%\node The Optimize-Interface Declaration,  , The Optimize Declaration, Compiler Policy
904 _\subsection{The Optimize-Interface Declaration}
905 _\label{optimize-interface-declaration}
906 _\cindex{optimize-interface declaration}
907 _\cpsubindex{declarations}{\code{optimize-interface}}
908 _
909 _The \code{extensions:optimize-interface} declaration is identical in
910 _syntax to the \code{optimize} declaration, but it specifies the policy
911 _used during compilation of code the compiler automatically generates
912 _to check the number and type of arguments supplied to a function.  It
913 _is useful to specify this policy separately, since even thoroughly
914 _debugged functions are vulnerable to being passed the wrong arguments.
915 _The \code{optimize-interface} declaration can specify that arguments
916 _should be checked even when the general \code{optimize} policy is
917 _unsafe.
918 _
919 _Note that this argument checking is the checking of user-supplied
920 _arguments to any functions defined within the scope of the
921 _declaration, \code{not} the checking of arguments to \llisp{}
922 _primitives that appear in those definitions.
923 _
924 _The idea behind this declaration is that it allows the definition of
925 _functions that appear fully safe to other callers, but that do no
926 _internal error checking.  Of course, it is possible that arguments may
927 _be invalid in ways other than having incorrect type.  Functions
928 _compiled unsafely must still protect themselves against things like
929 _user-supplied array indices that are out of bounds and improper lists.
930 _See also the \kwd{context-declarations} option to
931 _\macref{with-compilation-unit}.
932 _
933 _(end of section on compiler policy)
934 _-->
935
936 </sect1>
937
938 <sect1><title>Open Coding and Inline Expansion</>
939 <!--INDEX open-coding-->
940 <!--INDEX inline expansion-->
941 <!--INDEX static functions-->
942
943 <para>Since &CommonLisp; forbids the redefinition of standard
944 functions, the compiler can have special knowledge of these standard
945 functions embedded in it. This special knowledge is used in various
946 ways (open coding, inline expansion, source transformation), but the
947 implications to the user are basically the same:
948 <itemizedlist>
949   <listitem><para> Attempts to redefine standard functions may
950     be frustrated, since the function may never be called. Although
951     it is technically illegal to redefine standard functions, users
952     sometimes want to implicitly redefine these functions when they
953     are debugging using the <function>trace</> macro.  Special-casing
954     of standard functions can be inhibited using the
955     <parameter>notinline</> declaration.</para></listitem>
956   <listitem><para> The compiler can have multiple alternate
957     implementations of standard functions that implement different
958     trade-offs of speed, space and safety.  This selection is
959     based on the <link linkend="compiler-policy">compiler policy</link>.
960     </para></listitem>
961 </itemizedlist>
962 </para>
963
964 <para>When a function call is <emphasis>open coded</>, inline code whose
965 effect is equivalent to the function call is substituted for that
966 function call. When a function call is <emphasis>closed coded</>, it
967 is usually left as is, although it might be turned into a call to a
968 different function with different arguments. As an example, if
969 <function>nthcdr</> were to be open coded, then
970
971 <programlisting>(nthcdr 4 foobar)</programlisting>
972
973 might turn into
974
975 <programlisting>(cdr (cdr (cdr (cdr foobar))))</>
976
977 or even
978
979 <programlisting>(do ((i 0 (1+ i))
980      (list foobar (cdr foobar)))
981     ((= i 4) list))</programlisting>
982
983 If <function>nth</> is closed coded, then
984
985 <programlisting>
986 (nth x l)
987 </programlisting>
988
989 might stay the same, or turn into something like
990
991 <programlisting>
992 (car (nthcdr x l))
993 </programlisting>
994 </para>
995
996 <para>In general, open coding sacrifices space for speed, but some
997 functions (such as <function>car</>) are so simple that they are always
998 open-coded. Even when not open-coded, a call to a standard function
999 may be transformed into a different function call (as in the last
1000 example) or compiled as <emphasis>static call</>. Static function call
1001 uses a more efficient calling convention that forbids
1002 redefinition.</para>
1003
1004 </sect1>
1005
1006 </chapter>