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