2 @comment node-name, next, previous, up
5 This chapter will discuss most compiler issues other than efficiency,
6 including compiler error messages, the SBCL compiler's unusual
7 approach to type safety in the presence of type declarations, the
8 effects of various compiler optimization policies, and the way that
9 inlining and open coding may cause optimized code to differ from a
10 naive translation. Efficiency issues are sufficiently varied and
11 separate that they have their own chapter, @ref{Efficiency}.
14 * Diagnostic Messages::
18 * Open Coding and Inline Expansion::
21 @node Diagnostic Messages
22 @comment node-name, next, previous, up
23 @section Diagnostic Messages
24 @cindex Messages, Compiler
25 @cindex Compiler messages
28 * Controlling Verbosity::
29 * Diagnostic Severity::
30 * Understanding Compiler Diagnostics::
33 @node Controlling Verbosity
34 @comment node-name, next, previous, up
35 @subsection Controlling Verbosity
37 The compiler can be quite verbose in its diagnostic reporting, rather
38 more then some users would prefer -- the amount of noise emitted can
39 be controlled, however.
41 To control emission of compiler diagnostics (of any severity other
42 than @code{error}: @pxref{Diagnostic Severity}) use the
43 @code{sb-ext:muffle-conditions} and @code{sb-ext:unmuffle-conditions}
44 declarations, specifying the type of condition that is to be muffled
45 (the muffling is done using an associated @code{muffle-warning} restart).
49 ;;; Muffle compiler-notes globally
50 (declaim (sb-ext:muffle-conditions sb-ext:compiler-note))
55 ;;; Muffle compiler-notes based on lexical scope
57 (declare (optimize speed) (fixnum x)
58 (sb-ext:muffle-conditions sb-ext:compiler-note))
59 (values (* x 5) ; no compiler note from this
61 (declare (sb-ext:unmuffle-conditions sb-ext:compiler-note))
62 ;; this one gives a compiler note
66 @deffn {Declaration} sb-ext:muffle-conditions
69 Muffles the diagnostic messages that would be caused by compile-time
70 signals of given types.
73 @deffn {Declaration} sb-ext:unmuffle-conditions
76 Cancels the effect of a previous @code{sb-ext:muffle-condition}
80 Various details of @emph{how} the compiler messages are printed can be
81 controlled via the alist
82 @code{sb-ext:*compiler-print-variable-alist*}.
84 @include var-sb-ext-star-compiler-print-variable-alist-star.texinfo
86 @c <!-- FIXME: How much control over error messages is in SBCL?
87 @c _ How much should be? How much of this documentation should
88 @c _ we save or adapt?
90 @c _ %%\node Error Message Parameterization, , Read Errors, Interpreting Error Messages
91 @c _ \subsection{Error Message Parameterization}
92 @c _ \cpsubindex{error messages}{verbosity}
93 @c _ \cpsubindex{verbosity}{of error messages}
95 @c _ There is some control over the verbosity of error messages. See also
96 @c _ \varref{undefined-warning-limit}, \code{*efficiency-note-limit*} and
97 @c _ \varref{efficiency-note-cost-threshold}.
99 @c _ \begin{defvar}{}{enclosing-source-cutoff}
101 @c _ This variable specifies the number of enclosing actual source forms
102 @c _ that are printed in full, rather than in the abbreviated processing
103 @c _ path format. Increasing the value from its default of \code{1}
104 @c _ allows you to see more of the guts of the macroexpanded source,
105 @c _ which is useful when debugging macros.
108 @c _ \begin{defmac}{extensions:}{define-source-context}{%
109 @c _ \args{\var{name} \var{lambda-list} \mstar{form}}}
111 @c _ This macro defines how to extract an abbreviated source context from
112 @c _ the \var{name}d form when it appears in the compiler input.
113 @c _ \var{lambda-list} is a \code{defmacro} style lambda-list used to
114 @c _ parse the arguments. The \var{body} should return a list of
115 @c _ subforms that can be printed on about one line. There are
116 @c _ predefined methods for \code{defstruct}, \code{defmethod}, etc. If
117 @c _ no method is defined, then the first two subforms are returned.
118 @c _ Note that this facility implicitly determines the string name
119 @c _ associated with anonymous functions.
124 @node Diagnostic Severity
125 @comment node-name, next, previous, up
126 @subsection Diagnostic Severity
127 @cindex Severity of compiler messages
128 @cindex compiler diagnostic severity
131 @tindex style-warning
132 @tindex compiler-note
133 @tindex code-deletion-note
135 There are four levels of compiler diagnostic severity:
144 The first three levels correspond to condition classes which are
145 defined in the ANSI standard for Common Lisp and which have special
146 significance to the @code{compile} and @code{compile-file} functions.
147 These levels of compiler error severity occur when the compiler
148 handles conditions of these classes.
150 The fourth level of compiler error severity, @emph{note}, corresponds
151 to the @code{sb-ext:compiler-note}, and is used for problems which are
152 too mild for the standard condition classes, typically hints about how
153 efficiency might be improved. The @code{sb-ext:code-deletion-note}, a
154 subtype of @code{compiler-note}, is signalled when the compiler
155 deletes user-supplied code, usually after proving that the code in
156 question is unreachable.
158 Future work for SBCL includes expanding this hierarchy of types to
159 allow more fine-grained control over emission of diagnostic messages.
161 @include condition-sb-ext-compiler-note.texinfo
162 @include condition-sb-ext-code-deletion-note.texinfo
165 @node Understanding Compiler Diagnostics
166 @comment node-name, next, previous, up
167 @subsection Understanding Compile Diagnostics
169 The messages emitted by the compiler contain a lot of detail in a
170 terse format, so they may be confusing at first. The messages will be
171 illustrated using this example program:
175 `(roq (ploq (+ ,x 3))))
182 The main problem with this program is that it is trying to add
183 @code{3} to a symbol. Note also that the functions @code{roq} and
184 @code{ploq} aren't defined anywhere.
187 * The Parts of a Compiler Diagnostic::
188 * The Original and Actual Source::
189 * The Processing Path::
192 @node The Parts of a Compiler Diagnostic
193 @comment node-name, next, previous, up
194 @subsubsection The Parts of a Compiler Diagnostic
196 When processing this program, the compiler will produce this warning:
199 ; file: /tmp/foo.lisp
207 ; Asserted type NUMBER conflicts with derived type (VALUES SYMBOL &OPTIONAL).
210 In this example we see each of the six possible parts of a compiler
216 @findex with-compilation-unit
217 @samp{file: /tmp/foo.lisp} This is the name of the file that the
218 compiler read the relevant code from. The file name is displayed
219 because it may not be immediately obvious when there is an error
220 during compilation of a large system, especially when
221 @code{with-compilation-unit} is used to delay undefined warnings.
224 @samp{in: DEFUN FOO} This is the definition top level form responsible
225 for the diagnostic. It is obtained by taking the first two elements of
226 the enclosing form whose first element is a symbol beginning with
227 ``@samp{def}''. If there is no such enclosing ``@samp{def}'' form,
228 then the outermost form is used. If there are multiple @samp{def}
229 forms, then they are all printed from the outside in, separated by
230 @samp{=>}'s. In this example, the problem was in the @code{defun} for
234 @cindex Original Source
235 @samp{(ZOQ Y)} This is the @dfn{original source} form responsible for
236 the diagnostic. Original source means that the form directly appeared
237 in the original input to the compiler, i.e. in the lambda passed to
238 @code{compile} or in the top level form read from the source file. In
239 this example, the expansion of the @code{zoq} macro was responsible
243 @cindex Processing Path
244 @samp{--> ROQ PLOQ} This is the @dfn{processing path} that the
245 compiler used to produce the code that caused the message to be
246 emitted. The processing path is a representation of the evaluated
247 forms enclosing the actual source that the compiler encountered when
248 processing the original source. The path is the first element of each
249 form, or the form itself if the form is not a list. These forms result
250 from the expansion of macros or source-to-source transformation done
251 by the compiler. In this example, the enclosing evaluated forms are
252 the calls to @code{roq} and @code{ploq}. These calls resulted from the
253 expansion of the @code{zoq} macro.
256 @cindex Actual Source
257 @samp{==> (+ Y 3)} This is the @dfn{actual source} responsible for the
258 diagnostic. If the actual source appears in the explanation, then we
259 print the next enclosing evaluated form, instead of printing the
260 actual source twice. (This is the form that would otherwise have been
261 the last form of the processing path.) In this example, the problem is
262 with the evaluation of the reference to the variable @code{y}.
265 @samp{caught WARNING: Asserted type NUMBER conflicts with derived type
266 (VALUES SYMBOL &OPTIONAL).} This is the @dfn{explanation} of the
267 problem. In this example, the problem is that, while the call to
268 @code{+} requires that its arguments are all of type @code{number},
269 the compiler has derived that @code{y} will evaluate to a
270 @code{symbol}. Note that @samp{(VALUES SYMBOL &OPTIONAL)} expresses
271 that @code{y} evaluates to precisely one value.
275 Note that each part of the message is distinctively marked:
280 @samp{file:} and @samp{in:} mark the file and definition,
284 The original source is an indented form with no prefix.
287 Each line of the processing path is prefixed with @samp{-->}
290 The actual source form is indented like the original source, but is
291 marked by a preceding @samp{==>} line.
292 @comment no it isn't.
295 The explanation is prefixed with the diagnostic severity, which can be
296 @samp{caught ERROR:}, @samp{caught WARNING:}, @samp{caught
297 STYLE-WARNING:}, or @samp{note:}.
301 Each part of the message is more specific than the preceding one. If
302 consecutive messages are for nearby locations, then the front part of
303 the messages would be the same. In this case, the compiler omits as
304 much of the second message as in common with the first. For example:
307 ; file: /tmp/foo.lisp
314 ; caught STYLE-WARNING:
315 ; undefined function: PLOQ
318 ; (ROQ (PLOQ (+ Y 3)))
320 ; caught STYLE-WARNING:
321 ; undefined function: ROQ
323 @comment fixing that weird blank line might be good
325 In this example, the file, definition and original source are
326 identical for the two messages, so the compiler omits them in the
327 second message. If consecutive messages are entirely identical, then
328 the compiler prints only the first message, followed by: @samp{[Last
329 message occurs @var{repeats} times]} where @var{repeats} is the number
330 of times the message was given.
332 If the source was not from a file, then no file line is printed. If
333 the actual source is the same as the original source, then the
334 processing path and actual source will be omitted. If no forms
335 intervene between the original source and the actual source, then the
336 processing path will also be omitted.
339 @node The Original and Actual Source
340 @comment node-name, next, previous, up
341 @subsubsection The Original and Actual Source
342 @cindex Original Source
343 @cindex Actual Source
345 The @emph{original source} displayed will almost always be a list. If
346 the actual source for an message is a symbol, the original source will
347 be the immediately enclosing evaluated list form. So even if the
348 offending symbol does appear in the original source, the compiler will
349 print the enclosing list and then print the symbol as the actual
350 source (as though the symbol were introduced by a macro.)
352 When the @emph{actual source} is displayed (and is not a symbol), it
353 will always be code that resulted from the expansion of a macro or a
354 source-to-source compiler optimization. This is code that did not
355 appear in the original source program; it was introduced by the
358 Keep in mind that when the compiler displays a source form in an
359 diagnostic message, it always displays the most specific (innermost)
360 responsible form. For example, compiling this function
370 gives this error message
373 ; file: /tmp/foo.lisp
376 ; (DECLARE (FIXNUM A))
381 ; Asserted type FIXNUM conflicts with derived type (VALUES NULL &OPTIONAL).
384 This message is not saying ``there is a problem somewhere in this
385 @code{let}'' -- it is saying that there is a problem with the
386 @code{let} itself. In this example, the problem is that @code{a}'s
387 @code{nil} initial value is not a @code{fixnum}.
389 @node The Processing Path
390 @comment node-name, next, previous, up
391 @subsubsection The Processing Path
392 @cindex Processing path
393 @cindex Macroexpansion
394 @cindex Source-to-source transformation
396 The processing path is mainly useful for debugging macros, so if you
397 don't write macros, you can probably ignore it. Consider this example:
401 (dotimes (i n *undefined*)))
404 Compiling results in this error message:
408 ; (DOTIMES (I N *UNDEFINED*))
409 ; --> DO BLOCK LET TAGBODY RETURN-FROM
411 ; (PROGN *UNDEFINED*)
414 ; undefined variable: *UNDEFINED*
417 Note that @code{do} appears in the processing path. This is because
418 @code{dotimes} expands into:
421 (do ((i 0 (1+ i)) (#:g1 n))
422 ((>= i #:g1) *undefined*)
423 (declare (type unsigned-byte i)))
426 The rest of the processing path results from the expansion of
431 (let ((i 0) (#:g1 n))
432 (declare (type unsigned-byte i))
434 #:g2 (psetq i (1+ i))
435 #:g3 (unless (>= i #:g1) (go #:g2))
436 (return-from nil (progn *undefined*)))))
439 In this example, the compiler descended into the @code{block},
440 @code{let}, @code{tagbody} and @code{return-from} to reach the
441 @code{progn} printed as the actual source. This is a place where the
442 ``actual source appears in explanation'' rule was applied. The
443 innermost actual source form was the symbol @code{*undefined*} itself,
444 but that also appeared in the explanation, so the compiler backed out
451 @node Handling of Types
452 @comment node-name, next, previous, up
453 @section Handling of Types
455 The most unusual features of the SBCL compiler (which is very
456 similar to the original CMUCL compiler, also known as @dfn{Python})
457 is its unusually sophisticated understanding of the Common Lisp type
458 system and its unusually conservative approach to the implementation
459 of type declarations.
461 These two features reward the use of type declarations throughout
462 development, even when high performance is not a concern. Also, as
463 discussed in the chapter on performance (@pxref{Efficiency}), the use
464 of appropriate type declarations can be very important for performance
468 The SBCL compiler also has a greater knowledge of the Common Lisp
469 type system than other compilers. Support is incomplete only for types
470 involving the @code{satisfies} type specifier.
472 @c <!-- FIXME: See also sections \ref{advanced-type-stuff}
473 @c and \ref{type-inference}, once we snarf them from the
474 @c CMU CL manual. -->
476 @c Also see my paper on improving Baker, when I get round to it.
481 * Declarations as Assertions::
482 * Precise Type Checking::
483 * Getting Existing Programs to Run::
484 * Implementation Limitations::
487 @node Declarations as Assertions
488 @comment node-name, next, previous, up
489 @subsection Declarations as Assertions
492 The SBCL compiler treats type declarations differently from most
493 other Lisp compilers. Under default compilation policy the compiler
494 doesn't blindly believe type declarations, but considers them
495 assertions about the program that should be checked: all type
496 declarations that have not been proven to always hold are asserted at
500 @emph{Remaining bugs in the compiler's handling of types unfortunately
501 provide some exceptions to this rule, see @ref{Implementation
505 There are three type checking policies available in SBCL,
506 selectable via @code{optimize} declarations.
510 @c FIXME: This should be properly integrated with general policy
511 @c stuff, once that gets cleaned up.
513 @item Full Type Checks
514 All declarations are considered assertions to be checked at runtime,
515 and all type checks are precise.
517 Used when @code{(>= safety (max speed space compilation-speed)}. The
518 default compilation policy provides full type checks.
520 @item Weak Type Checks
521 Any or all type declarations may be believed without runtime
522 assertions, and assertions that are done may be imprecise.
524 Used when @code{(< 0 safety (max speed space compilation-speed)}.
527 All declarations are believed without assertions. Also disables
528 argument count and array bounds checking.
530 Used when @code{(= safety 0)}.
534 @node Precise Type Checking
535 @comment node-name, next, previous, up
536 @subsection Precise Type Checking
537 @cindex Precise type checking
538 @cindex Type checking, precise
540 Precise checking means that the check is done as though @code{typep}
541 had been called with the exact type specifier that appeared in the
544 If a variable is declared to be @code{(integer 3 17)} then its value
545 must always be an integer between @code{3} and @code{17}. If multiple
546 type declarations apply to a single variable, then all the
547 declarations must be correct; it is as though all the types were
548 intersected producing a single @code{and} type specifier.
550 To gain maximum benefit from the compiler's type checking, you should
551 always declare the types of function arguments and structure slots as
552 precisely as possible. This often involves the use of @code{or},
553 @code{member}, and other list-style type specifiers.
556 @node Getting Existing Programs to Run
557 @comment node-name, next, previous, up
558 @subsection Getting Existing Programs to Run
559 @cindex Existing programs, to run
560 @cindex Types, portability
561 @cindex Compatibility with other Lisps
562 @c (should also have an entry in the non-ANSI-isms section)-->
564 Since SBCL's compiler does much more comprehensive type checking than
565 most Lisp compilers, SBCL may detect type errors in programs that have
566 been debugged using other compilers. These errors are mostly incorrect
567 declarations, although compile-time type errors can find actual bugs
568 if parts of the program have never been tested.
570 Some incorrect declarations can only be detected by run-time type
571 checking. It is very important to initially compile a program with
572 full type checks (high @code{safety} optimization) and then test this
573 safe version. After the checking version has been tested, then you can
574 consider weakening or eliminating type checks. @emph{This applies
575 even to previously debugged programs,} because the SBCL compiler does
576 much more type inference than other Common Lisp compilers, so an
577 incorrect declaration can do more damage.
579 The most common problem is with variables whose constant initial value
580 doesn't match the type declaration. Incorrect constant initial values
581 will always be flagged by a compile-time type error, and they are
582 simple to fix once located. Consider this code fragment:
586 (declare (fixnum foo))
591 Here @code{foo} is given an initial value of @code{nil}, but is
592 declared to be a @code{fixnum}. Even if it is never read, the initial
593 value of a variable must match the declared type. There are two ways
594 to fix this problem. Change the declaration
598 (declare (type (or fixnum null) foo))
603 or change the initial value
607 (declare (fixnum foo))
612 It is generally preferable to change to a legal initial value rather
613 than to weaken the declaration, but sometimes it is simpler to weaken
614 the declaration than to try to make an initial value of the
617 Another declaration problem occasionally encountered is incorrect
618 declarations on @code{defmacro} arguments. This can happen when a
619 function is converted into a macro. Consider this macro:
624 `(the fixnum (1+ ,x)))
627 Although legal and well-defined Common Lisp code, this meaning of this
628 definition is almost certainly not what the writer intended. For
629 example, this call is illegal:
635 This call is illegal because the argument to the macro is @code{(+ 4
636 5)}, which is a @code{list}, not a @code{fixnum}. Because of macro
637 semantics, it is hardly ever useful to declare the types of macro
638 arguments. If you really want to assert something about the type of
639 the result of evaluating a macro argument, then put a @code{the} in
644 `(the fixnum (1+ (the fixnum ,x))))
647 In this case, it would be stylistically preferable to change this
648 macro back to a function and declare it inline.
649 @c <!--FIXME: <xref>inline-expansion, once we crib the
650 @c relevant text from the CMU CL manual.-->
652 Some more subtle problems are caused by incorrect declarations that
653 can't be detected at compile time. Consider this code:
656 (do ((pos 0 (position #\a string :start (1+ pos))))
658 (declare (fixnum pos))
662 Although @code{pos} is almost always a @code{fixnum}, it is @code{nil}
663 at the end of the loop. If this example is compiled with full type
664 checks (the default), then running it will signal a type error at the
665 end of the loop. If compiled without type checks, the program will go
666 into an infinite loop (or perhaps @code{position} will complain
667 because @code{(1+ nil)} isn't a sensible start.) Why? Because if you
668 compile without type checks, the compiler just quietly believes the
669 type declaration. Since the compiler believes that @code{pos} is
670 always a @code{fixnum}, it believes that @code{pos} is never
671 @code{nil}, so @code{(null pos)} is never true, and the loop exit test
672 is optimized away. Such errors are sometimes flagged by unreachable
673 code notes, but it is still important to initially compile and test
674 any system with full type checks, even if the system works fine when
675 compiled using other compilers.
677 In this case, the fix is to weaken the type declaration to @code{(or
678 fixnum null)} @footnote{Actually, this declaration is unnecessary in
679 SBCL, since it already knows that @code{position} returns a
680 non-negative @code{fixnum} or @code{nil}.}.
682 Note that there is usually little performance penalty for weakening a
683 declaration in this way. Any numeric operations in the body can still
684 assume that the variable is a @code{fixnum}, since @code{nil} is not a
685 legal numeric argument. Another possible fix would be to say:
688 (do ((pos 0 (position #\a string :start (1+ pos))))
691 (declare (fixnum pos))
695 This would be preferable in some circumstances, since it would allow a
696 non-standard representation to be used for the local @code{pos}
697 variable in the loop body.
698 @c <!-- FIXME: <xref>ND-variables, once we crib the text from the
699 @c CMU CL manual. -->
701 @node Implementation Limitations
702 @comment node-name, next, previous, up
703 @subsection Implementation Limitations
705 Ideally, the compiler would consider @emph{all} type declarations to
706 be assertions, so that adding type declarations to a program, no
707 matter how incorrect they might be, would @emph{never} cause undefined
708 behavior. However, the compiler is known to fall short of this goal in
714 @emph{Proclaimed} constraints on argument and result types of a
715 function are supposed to be checked by the function. If the function
716 type is proclaimed before function definition, type checks are
717 inserted by the compiler, but the standard allows the reversed order,
718 in which case the compiler will trust the declaration.
721 The compiler cannot check types of an unknown number of values; if the
722 number of generated values is unknown, but the number of consumed is
723 known, only consumed values are checked.
729 (the integer (bar x)))
732 causes the following compiler diagnostic to be emitted:
735 ; note: type assertion too complex to check:
736 ; (VALUES INTEGER &REST T).
739 A partial workaround is instead write:
743 (the (values integer &optional) (bar x)))
748 These are important issues, but are not necessarily easy to fix, so
749 they may, alas, remain in the system for a while.
751 @node Compiler Policy
752 @comment node-name, next, previous, up
753 @section Compiler Policy
755 Compiler policy is controlled by the @code{optimize} declaration,
756 supporting all ANSI optimization qualities (@code{debug},
757 @code{safety}, @code{space}, and @code{speed}).@footnote{A deprecated
758 extension @code{sb-ext:inhibit-warnings} is still supported, but
759 liable to go away at any time.}
761 For effects of various optimization qualities on type-safety and
762 debuggability see @ref{Declarations as Assertions} and @ref{Debugger
765 Ordinarily, when the @code{speed} quality is high, the compiler emits
766 notes to notify the programmer about its inability to apply various
767 optimizations. For selective muffling of these notes @xref{Controlling
770 The value of @code{space} mostly influences the compiler's decision
771 whether to inline operations, which tend to increase the size of
772 programs. Use the value @code{0} with caution, since it can cause the
773 compiler to inline operations so indiscriminately that the net effect
774 is to slow the program by causing cache misses or even swapping.
776 @c <!-- FIXME: old CMU CL compiler policy, should perhaps be adapted
777 @c _ for SBCL. (Unfortunately, the CMU CL docs are out of sync with the
778 @c _ CMU CL code, so adapting this requires not only reformatting
779 @c _ the documentation, but rooting out code rot.)
781 @c _<sect2 id="compiler-policy"><title>Compiler Policy</1000
782 @c _ INDEX {policy}{compiler}
783 @c _ INDEX compiler policy
785 @c _<para>The policy is what tells the compiler <emphasis>how</emphasis> to
786 @c _compile a program. This is logically (and often textually) distinct
787 @c _from the program itself. Broad control of policy is provided by the
788 @c _<parameter>optimize</parameter> declaration; other declarations and variables
789 @c _control more specific aspects of compilation.
792 @c _* The Optimize Declaration::
793 @c _* The Optimize-Interface Declaration::
796 @c _%%\node The Optimize Declaration, The Optimize-Interface Declaration, Compiler Policy, Compiler Policy
797 @c _\subsection{The Optimize Declaration}
798 @c _\label{optimize-declaration}
799 @c _\cindex{optimize declaration}
800 @c _\cpsubindex{declarations}{\code{optimize}}
802 @c _The \code{optimize} declaration recognizes six different
803 @c _\var{qualities}. The qualities are conceptually independent aspects
804 @c _of program performance. In reality, increasing one quality tends to
805 @c _have adverse effects on other qualities. The compiler compares the
806 @c _relative values of qualities when it needs to make a trade-off; i.e.,
807 @c _if \code{speed} is greater than \code{safety}, then improve speed at
808 @c _the cost of safety.
810 @c _The default for all qualities (except \code{debug}) is \code{1}.
811 @c _Whenever qualities are equal, ties are broken according to a broad
812 @c _idea of what a good default environment is supposed to be. Generally
813 @c _this downplays \code{speed}, \code{compile-speed} and \code{space} in
814 @c _favor of \code{safety} and \code{debug}. Novice and casual users
815 @c _should stick to the default policy. Advanced users often want to
816 @c _improve speed and memory usage at the cost of safety and
819 @c _If the value for a quality is \code{0} or \code{3}, then it may have a
820 @c _special interpretation. A value of \code{0} means ``totally
821 @c _unimportant'', and a \code{3} means ``ultimately important.'' These
822 @c _extreme optimization values enable ``heroic'' compilation strategies
823 @c _that are not always desirable and sometimes self-defeating.
824 @c _Specifying more than one quality as \code{3} is not desirable, since
825 @c _it doesn't tell the compiler which quality is most important.
828 @c _These are the optimization qualities:
831 @c _\item[\code{speed}] \cindex{speed optimization quality}How fast the
832 @c _ program should is run. \code{speed 3} enables some optimizations
833 @c _ that hurt debuggability.
835 @c _\item[\code{compilation-speed}] \cindex{compilation-speed optimization
836 @c _ quality}How fast the compiler should run. Note that increasing
837 @c _ this above \code{safety} weakens type checking.
839 @c _\item[\code{space}] \cindex{space optimization quality}How much space
840 @c _ the compiled code should take up. Inline expansion is mostly
841 @c _ inhibited when \code{space} is greater than \code{speed}. A value
842 @c _ of \code{0} enables indiscriminate inline expansion. Wide use of a
843 @c _ \code{0} value is not recommended, as it may waste so much space
844 @c _ that run time is slowed. \xlref{inline-expansion} for a discussion
845 @c _ of inline expansion.
847 @c _\item[\code{debug}] \cindex{debug optimization quality}How debuggable
848 @c _ the program should be. The quality is treated differently from the
849 @c _ other qualities: each value indicates a particular level of debugger
850 @c _ information; it is not compared with the other qualities.
851 @c _ \xlref{debugger-policy} for more details.
853 @c _\item[\code{safety}] \cindex{safety optimization quality}How much
854 @c _ error checking should be done. If \code{speed}, \code{space} or
855 @c _ \code{compilation-speed} is more important than \code{safety}, then
856 @c _ type checking is weakened (\pxlref{weakened-type-checks}). If
857 @c _ \code{safety} if \code{0}, then no run time error checking is done.
858 @c _ In addition to suppressing type checks, \code{0} also suppresses
859 @c _ argument count checking, unbound-symbol checking and array bounds
861 @c _ ... and checking of tag existence in RETURN-FROM and GO.
863 @c _\item[\code{extensions:inhibit-warnings}] \cindex{inhibit-warnings
864 @c _ optimization quality}This is a CMU extension that determines how
865 @c _ little (or how much) diagnostic output should be printed during
866 @c _ compilation. This quality is compared to other qualities to
867 @c _ determine whether to print style notes and warnings concerning those
868 @c _ qualities. If \code{speed} is greater than \code{inhibit-warnings},
869 @c _ then notes about how to improve speed will be printed, etc. The
870 @c _ default value is \code{1}, so raising the value for any standard
871 @c _ quality above its default enables notes for that quality. If
872 @c _ \code{inhibit-warnings} is \code{3}, then all notes and most
873 @c _ non-serious warnings are inhibited. This is useful with
874 @c _ \code{declare} to suppress warnings about unavoidable problems.
877 @c _%%\node The Optimize-Interface Declaration, , The Optimize Declaration, Compiler Policy
878 @c _\subsection{The Optimize-Interface Declaration}
879 @c _\label{optimize-interface-declaration}
880 @c _\cindex{optimize-interface declaration}
881 @c _\cpsubindex{declarations}{\code{optimize-interface}}
883 @c _The \code{extensions:optimize-interface} declaration is identical in
884 @c _syntax to the \code{optimize} declaration, but it specifies the policy
885 @c _used during compilation of code the compiler automatically generates
886 @c _to check the number and type of arguments supplied to a function. It
887 @c _is useful to specify this policy separately, since even thoroughly
888 @c _debugged functions are vulnerable to being passed the wrong arguments.
889 @c _The \code{optimize-interface} declaration can specify that arguments
890 @c _should be checked even when the general \code{optimize} policy is
893 @c _Note that this argument checking is the checking of user-supplied
894 @c _arguments to any functions defined within the scope of the
895 @c _declaration, \code{not} the checking of arguments to \llisp{}
896 @c _primitives that appear in those definitions.
898 @c _The idea behind this declaration is that it allows the definition of
899 @c _functions that appear fully safe to other callers, but that do no
900 @c _internal error checking. Of course, it is possible that arguments may
901 @c _be invalid in ways other than having incorrect type. Functions
902 @c _compiled unsafely must still protect themselves against things like
903 @c _user-supplied array indices that are out of bounds and improper lists.
904 @c _See also the \kwd{context-declarations} option to
905 @c _\macref{with-compilation-unit}.
907 @c _(end of section on compiler policy)
910 @node Compiler Errors
911 @comment node-name, next, previous, up
912 @section Compiler Errors
915 * Type Errors at Compile Time::
916 * Errors During Macroexpansion::
920 @node Type Errors at Compile Time
921 @comment node-name, next, previous, up
922 @subsection Type Errors at Compile Time
923 @cindex Compile time type errors
924 @cindex Type checking, at compile time
926 If the compiler can prove at compile time that some portion of the
927 program cannot be executed without a type error, then it will give a
928 warning at compile time.
930 It is possible that the offending code would never actually be
931 executed at run-time due to some higher level consistency constraint
932 unknown to the compiler, so a type warning doesn't always indicate an
935 For example, consider this code fragment:
947 Compilation produces this warning:
951 ; (CASE FOO (:THIS 13) (:THAT 9) (:THE-OTHER 42))
952 ; --> LET COND IF COND IF COND IF
957 ; This is not a FIXNUM:
961 In this case, the warning means that if @code{foo} isn't any of
962 @code{:this}, @code{:that} or @code{:the-other}, then @code{x} will be
963 initialized to @code{nil}, which the @code{fixnum} declaration makes
964 illegal. The warning will go away if @code{ecase} is used instead of
965 @code{case}, or if @code{:the-other} is changed to @code{t}.
967 This sort of spurious type warning happens moderately often in the
968 expansion of complex macros and in inline functions. In such cases,
969 there may be dead code that is impossible to correctly execute. The
970 compiler can't always prove this code is dead (could never be
971 executed), so it compiles the erroneous code (which will always signal
972 an error if it is executed) and gives a warning.
974 @node Errors During Macroexpansion
975 @comment node-name, next, previous, up
976 @subsection Errors During Macroexpansion
977 @cindex Macroexpansion, errors during
979 The compiler handles errors that happen during macroexpansion, turning
980 them into compiler errors. If you want to debug the error (to debug a
981 macro), you can set @code{*break-on-signals*} to @code{error}. For
982 example, this definition:
986 (do ((current l (cdr current))
987 ((atom current) nil))
988 (when (eq (car current) e) (return current))))
995 ; (DO ((CURRENT L (CDR CURRENT))
996 ; ((ATOM CURRENT) NIL))
997 ; (WHEN (EQ (CAR CURRENT) E) (RETURN CURRENT)))
1000 ; (in macroexpansion of (DO # #))
1001 ; (hint: For more precise location, try *BREAK-ON-SIGNALS*.)
1002 ; DO step variable is not a symbol: (ATOM CURRENT)
1007 @comment node-name, next, previous, up
1008 @subsection Read Errors
1009 @cindex Read errors, compiler
1011 SBCL's compiler does not attempt to recover from read errors when
1012 reading a source file, but instead just reports the offending
1013 character position and gives up on the entire source file.
1015 @node Open Coding and Inline Expansion
1016 @comment node-name, next, previous, up
1017 @section Open Coding and Inline Expansion
1019 @cindex inline expansion
1020 @cindex static functions
1022 Since Common Lisp forbids the redefinition of standard functions, the
1023 compiler can have special knowledge of these standard functions
1024 embedded in it. This special knowledge is used in various ways (open
1025 coding, inline expansion, source transformation), but the implications
1026 to the user are basically the same:
1031 Attempts to redefine standard functions may be frustrated, since the
1032 function may never be called. Although it is technically illegal to
1033 redefine standard functions, users sometimes want to implicitly
1034 redefine these functions when they are debugging using the
1035 @code{trace} macro. Special-casing of standard functions can be
1036 inhibited using the @code{notinline} declaration, but even then some
1037 phases of analysis such as type inferencing are applied by the
1041 The compiler can have multiple alternate implementations of standard
1042 functions that implement different trade-offs of speed, space and
1043 safety. This selection is based on the compiler policy, @ref{Compiler
1048 When a function call is @emph{open coded}, inline code whose effect is
1049 equivalent to the function call is substituted for that function
1050 call. When a function call is @emph{closed coded}, it is usually left
1051 as is, although it might be turned into a call to a different function
1052 with different arguments. As an example, if @code{nthcdr} were to be
1062 (cdr (cdr (cdr (cdr foobar))))
1069 (list foobar (cdr foobar)))
1073 If @code{nth} is closed coded, then
1079 might stay the same, or turn into something like
1085 In general, open coding sacrifices space for speed, but some functions
1086 (such as @code{car}) are so simple that they are always
1087 open-coded. Even when not open-coded, a call to a standard function
1088 may be transformed into a different function call (as in the last
1089 example) or compiled as @emph{static call}. Static function call uses
1090 a more efficient calling convention that forbids redefinition.