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