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::
20 * Advanced Compiler Use and Efficiency Hints::
23 @node Diagnostic Messages
24 @comment node-name, next, previous, up
25 @section Diagnostic Messages
26 @cindex Messages, Compiler
27 @cindex Compiler messages
30 * Controlling Verbosity::
31 * Diagnostic Severity::
32 * Understanding Compiler Diagnostics::
35 @node Controlling Verbosity
36 @comment node-name, next, previous, up
37 @subsection Controlling Verbosity
39 The compiler can be quite verbose in its diagnostic reporting, rather
40 more then some users would prefer -- the amount of noise emitted can
41 be controlled, however.
43 To control emission of compiler diagnostics (of any severity other
44 than @code{error}: @pxref{Diagnostic Severity}) use the
45 @code{sb-ext:muffle-conditions} and @code{sb-ext:unmuffle-conditions}
46 declarations, specifying the type of condition that is to be muffled
47 (the muffling is done using an associated @code{muffle-warning} restart).
51 ;;; Muffle compiler-notes globally
52 (declaim (sb-ext:muffle-conditions sb-ext:compiler-note))
57 ;;; Muffle compiler-notes based on lexical scope
59 (declare (optimize speed) (fixnum x)
60 (sb-ext:muffle-conditions sb-ext:compiler-note))
61 (values (* x 5) ; no compiler note from this
63 (declare (sb-ext:unmuffle-conditions sb-ext:compiler-note))
64 ;; this one gives a compiler note
68 @deffn {Declaration} @sbext{muffle-conditions}
71 Muffles the diagnostic messages that would be caused by compile-time
72 signals of given types.
75 @deffn {Declaration} @sbext{unmuffle-conditions}
78 Cancels the effect of a previous @code{sb-ext:muffle-conditions}
82 Various details of @emph{how} the compiler messages are printed can be
83 controlled via the alist
84 @code{sb-ext:*compiler-print-variable-alist*}.
86 @include var-sb-ext-star-compiler-print-variable-alist-star.texinfo
88 For information about muffling warnings signaled outside of the
89 compiler, see @ref{Customization Hooks for Users}.
91 @c <!-- FIXME: How much control over error messages is in SBCL?
92 @c _ How much should be? How much of this documentation should
93 @c _ we save or adapt?
95 @c _ %%\node Error Message Parameterization, , Read Errors, Interpreting Error Messages
96 @c _ \subsection{Error Message Parameterization}
97 @c _ \cpsubindex{error messages}{verbosity}
98 @c _ \cpsubindex{verbosity}{of error messages}
100 @c _ There is some control over the verbosity of error messages. See also
101 @c _ \varref{undefined-warning-limit}, \code{*efficiency-note-limit*} and
102 @c _ \varref{efficiency-note-cost-threshold}.
104 @c _ \begin{defvar}{}{enclosing-source-cutoff}
106 @c _ This variable specifies the number of enclosing actual source forms
107 @c _ that are printed in full, rather than in the abbreviated processing
108 @c _ path format. Increasing the value from its default of \code{1}
109 @c _ allows you to see more of the guts of the macroexpanded source,
110 @c _ which is useful when debugging macros.
113 @c _ \begin{defmac}{extensions:}{define-source-context}{%
114 @c _ \args{\var{name} \var{lambda-list} \mstar{form}}}
116 @c _ This macro defines how to extract an abbreviated source context from
117 @c _ the \var{name}d form when it appears in the compiler input.
118 @c _ \var{lambda-list} is a \code{defmacro} style lambda-list used to
119 @c _ parse the arguments. The \var{body} should return a list of
120 @c _ subforms that can be printed on about one line. There are
121 @c _ predefined methods for \code{defstruct}, \code{defmethod}, etc. If
122 @c _ no method is defined, then the first two subforms are returned.
123 @c _ Note that this facility implicitly determines the string name
124 @c _ associated with anonymous functions.
129 @node Diagnostic Severity
130 @comment node-name, next, previous, up
131 @subsection Diagnostic Severity
132 @cindex Severity of compiler messages
133 @cindex Compiler Diagnostic Severity
136 @tindex @cl{style-warning}
137 @tindex @sbext{compiler-note}
138 @tindex @sbext{code-deletion-note}
140 There are four levels of compiler diagnostic severity:
149 The first three levels correspond to condition classes which are
150 defined in the ANSI standard for Common Lisp and which have special
151 significance to the @code{compile} and @code{compile-file} functions.
152 These levels of compiler error severity occur when the compiler
153 handles conditions of these classes.
155 The fourth level of compiler error severity, @emph{note}, corresponds
156 to the @code{sb-ext:compiler-note}, and is used for problems which are
157 too mild for the standard condition classes, typically hints about how
158 efficiency might be improved. The @code{sb-ext:code-deletion-note}, a
159 subtype of @code{compiler-note}, is signalled when the compiler
160 deletes user-supplied code after proving that the code in question is
163 Future work for SBCL includes expanding this hierarchy of types to
164 allow more fine-grained control over emission of diagnostic messages.
166 @include condition-sb-ext-compiler-note.texinfo
167 @include condition-sb-ext-code-deletion-note.texinfo
170 @node Understanding Compiler Diagnostics
171 @comment node-name, next, previous, up
172 @subsection Understanding Compile Diagnostics
174 The messages emitted by the compiler contain a lot of detail in a
175 terse format, so they may be confusing at first. The messages will be
176 illustrated using this example program:
180 `(roq (ploq (+ ,x 3))))
187 The main problem with this program is that it is trying to add
188 @code{3} to a symbol. Note also that the functions @code{roq} and
189 @code{ploq} aren't defined anywhere.
192 * The Parts of a Compiler Diagnostic::
193 * The Original and Actual Source::
194 * The Processing Path::
197 @node The Parts of a Compiler Diagnostic
198 @comment node-name, next, previous, up
199 @subsubsection The Parts of a Compiler Diagnostic
201 When processing this program, the compiler will produce this warning:
204 ; file: /tmp/foo.lisp
212 ; Asserted type NUMBER conflicts with derived type (VALUES SYMBOL &OPTIONAL).
215 In this example we see each of the six possible parts of a compiler
221 @findex @cl{with-compilation-unit}
222 @samp{file: /tmp/foo.lisp} This is the name of the file that the
223 compiler read the relevant code from. The file name is displayed
224 because it may not be immediately obvious when there is an error
225 during compilation of a large system, especially when
226 @code{with-compilation-unit} is used to delay undefined warnings.
229 @samp{in: DEFUN FOO} This is the definition top level form responsible
230 for the diagnostic. It is obtained by taking the first two elements of
231 the enclosing form whose first element is a symbol beginning with
232 ``@samp{def}''. If there is no such enclosing ``@samp{def}'' form,
233 then the outermost form is used. If there are multiple @samp{def}
234 forms, then they are all printed from the outside in, separated by
235 @samp{=>}'s. In this example, the problem was in the @code{defun} for
239 @cindex Original Source
240 @samp{(ZOQ Y)} This is the @dfn{original source} form responsible for
241 the diagnostic. Original source means that the form directly appeared
242 in the original input to the compiler, i.e. in the lambda passed to
243 @code{compile} or in the top level form read from the source file. In
244 this example, the expansion of the @code{zoq} macro was responsible
248 @cindex Processing Path
249 @samp{--> ROQ PLOQ} This is the @dfn{processing path} that the
250 compiler used to produce the code that caused the message to be
251 emitted. The processing path is a representation of the evaluated
252 forms enclosing the actual source that the compiler encountered when
253 processing the original source. The path is the first element of each
254 form, or the form itself if the form is not a list. These forms result
255 from the expansion of macros or source-to-source transformation done
256 by the compiler. In this example, the enclosing evaluated forms are
257 the calls to @code{roq} and @code{ploq}. These calls resulted from the
258 expansion of the @code{zoq} macro.
261 @cindex Actual Source
262 @samp{==> (+ Y 3)} This is the @dfn{actual source} responsible for the
263 diagnostic. If the actual source appears in the explanation, then we
264 print the next enclosing evaluated form, instead of printing the
265 actual source twice. (This is the form that would otherwise have been
266 the last form of the processing path.) In this example, the problem is
267 with the evaluation of the reference to the variable @code{y}.
270 @samp{caught WARNING: Asserted type NUMBER conflicts with derived type
271 (VALUES SYMBOL &OPTIONAL).} This is the @dfn{explanation} of the
272 problem. In this example, the problem is that, while the call to
273 @code{+} requires that its arguments are all of type @code{number},
274 the compiler has derived that @code{y} will evaluate to a
275 @code{symbol}. Note that @samp{(VALUES SYMBOL &OPTIONAL)} expresses
276 that @code{y} evaluates to precisely one value.
280 Note that each part of the message is distinctively marked:
285 @samp{file:} and @samp{in:} mark the file and definition,
289 The original source is an indented form with no prefix.
292 Each line of the processing path is prefixed with @samp{-->}
295 The actual source form is indented like the original source, but is
296 marked by a preceding @samp{==>} line.
297 @comment no it isn't.
300 The explanation is prefixed with the diagnostic severity, which can be
301 @samp{caught ERROR:}, @samp{caught WARNING:}, @samp{caught
302 STYLE-WARNING:}, or @samp{note:}.
306 Each part of the message is more specific than the preceding one. If
307 consecutive messages are for nearby locations, then the front part of
308 the messages would be the same. In this case, the compiler omits as
309 much of the second message as in common with the first. For example:
312 ; file: /tmp/foo.lisp
319 ; caught STYLE-WARNING:
320 ; undefined function: PLOQ
323 ; (ROQ (PLOQ (+ Y 3)))
325 ; caught STYLE-WARNING:
326 ; undefined function: ROQ
328 @comment fixing that weird blank line might be good
330 In this example, the file, definition and original source are
331 identical for the two messages, so the compiler omits them in the
332 second message. If consecutive messages are entirely identical, then
333 the compiler prints only the first message, followed by: @samp{[Last
334 message occurs @var{repeats} times]} where @var{repeats} is the number
335 of times the message was given.
337 If the source was not from a file, then no file line is printed. If
338 the actual source is the same as the original source, then the
339 processing path and actual source will be omitted. If no forms
340 intervene between the original source and the actual source, then the
341 processing path will also be omitted.
344 @node The Original and Actual Source
345 @comment node-name, next, previous, up
346 @subsubsection The Original and Actual Source
347 @cindex Original Source
348 @cindex Actual Source
350 The @emph{original source} displayed will almost always be a list. If
351 the actual source for an message is a symbol, the original source will
352 be the immediately enclosing evaluated list form. So even if the
353 offending symbol does appear in the original source, the compiler will
354 print the enclosing list and then print the symbol as the actual
355 source (as though the symbol were introduced by a macro.)
357 When the @emph{actual source} is displayed (and is not a symbol), it
358 will always be code that resulted from the expansion of a macro or a
359 source-to-source compiler optimization. This is code that did not
360 appear in the original source program; it was introduced by the
363 Keep in mind that when the compiler displays a source form in an
364 diagnostic message, it always displays the most specific (innermost)
365 responsible form. For example, compiling this function
375 gives this error message
378 ; file: /tmp/foo.lisp
381 ; (DECLARE (FIXNUM A))
386 ; Asserted type FIXNUM conflicts with derived type (VALUES NULL &OPTIONAL).
389 This message is not saying ``there is a problem somewhere in this
390 @code{let}'' -- it is saying that there is a problem with the
391 @code{let} itself. In this example, the problem is that @code{a}'s
392 @code{nil} initial value is not a @code{fixnum}.
394 @node The Processing Path
395 @comment node-name, next, previous, up
396 @subsubsection The Processing Path
397 @cindex Processing Path
398 @cindex Macroexpansion
399 @cindex Source-to-source transformation
401 The processing path is mainly useful for debugging macros, so if you
402 don't write macros, you can probably ignore it. Consider this example:
406 (dotimes (i n *undefined*)))
409 Compiling results in this error message:
413 ; (DOTIMES (I N *UNDEFINED*))
414 ; --> DO BLOCK LET TAGBODY RETURN-FROM
416 ; (PROGN *UNDEFINED*)
419 ; undefined variable: *UNDEFINED*
422 Note that @code{do} appears in the processing path. This is because
423 @code{dotimes} expands into:
426 (do ((i 0 (1+ i)) (#:g1 n))
427 ((>= i #:g1) *undefined*)
428 (declare (type unsigned-byte i)))
431 The rest of the processing path results from the expansion of
436 (let ((i 0) (#:g1 n))
437 (declare (type unsigned-byte i))
439 #:g2 (psetq i (1+ i))
440 #:g3 (unless (>= i #:g1) (go #:g2))
441 (return-from nil (progn *undefined*)))))
444 In this example, the compiler descended into the @code{block},
445 @code{let}, @code{tagbody} and @code{return-from} to reach the
446 @code{progn} printed as the actual source. This is a place where the
447 ``actual source appears in explanation'' rule was applied. The
448 innermost actual source form was the symbol @code{*undefined*} itself,
449 but that also appeared in the explanation, so the compiler backed out
456 @node Handling of Types
457 @comment node-name, next, previous, up
458 @section Handling of Types
460 One of the most important features of the SBCL compiler (similar to
461 the original CMUCL compiler, also known as @dfn{Python}) is its fairly
462 sophisticated understanding of the Common Lisp type system and its
463 conservative approach to the implementation of type declarations.
465 These two features reward the use of type declarations throughout
466 development, even when high performance is not a concern. Also, as
467 discussed in the chapter on performance (@pxref{Efficiency}), the use
468 of appropriate type declarations can be very important for performance
471 @findex @cl{satisfies}
472 The SBCL compiler also has a greater knowledge of the Common Lisp
473 type system than other compilers. Support is incomplete only for types
474 involving the @code{satisfies} type specifier.
476 @c <!-- FIXME: See also sections \ref{advanced-type-stuff}
477 @c and \ref{type-inference}, once we snarf them from the
478 @c CMU CL manual. -->
480 @c Also see my paper on improving Baker, when I get round to it.
485 * Declarations as Assertions::
486 * Precise Type Checking::
487 * Getting Existing Programs to Run::
488 * Implementation Limitations::
491 @node Declarations as Assertions
492 @comment node-name, next, previous, up
493 @subsection Declarations as Assertions
494 @cindex Safety optimization quality
496 The SBCL compiler treats type declarations differently from most other
497 Lisp compilers. Under default compilation policy the compiler doesn't
498 blindly believe type declarations, but considers them assertions about
499 the program that should be checked: all type declarations that have
500 not been proven to always hold are asserted at runtime.
503 @emph{Remaining bugs in the compiler's handling of types unfortunately
504 provide some exceptions to this rule, see @ref{Implementation
508 CLOS slot types form a notable exception. Types declared using the
509 @code{:type} slot option in @code{defclass} are asserted if and only
510 if the class was defined in @emph{safe code} and the slot access
511 location is in @emph{safe code} as well. This laxness does not pose
512 any internal consistency issues, as the CLOS slot types are not
513 available for the type inferencer, nor do CLOS slot types provide any
516 There are three type checking policies available in SBCL, selectable
517 via @code{optimize} declarations.
521 @c FIXME: This should be properly integrated with general policy
522 @c stuff, once that gets cleaned up.
524 @item Full Type Checks
525 All declarations are considered assertions to be checked at runtime,
526 and all type checks are precise. The default compilation policy
527 provides full type checks.
529 Used when @code{(or (>= safety 2) (>= safety speed 1))}.
531 @item Weak Type Checks
532 Declared types may be simplified into faster to check supertypes: for
533 example, @code{(or (integer -17 -7) (integer 7 17))} is simplified
534 into @code{(integer -17 17)}.
536 @strong{Note}: it is relatively easy to corrupt the heap when weak
537 type checks are used if the program contains type-errors.
539 Used when @code{(and (< safety 2) (< safety speed))}
542 All declarations are believed without assertions. Also disables
543 argument count and array bounds checking.
545 @strong{Note}: any type errors in code where type checks are not
546 performed are liable to corrupt the heap.
548 Used when @code{(= safety 0)}.
552 @node Precise Type Checking
553 @comment node-name, next, previous, up
554 @subsection Precise Type Checking
555 @cindex Precise type checking
556 @cindex Type checking, precise
558 Precise checking means that the check is done as though @code{typep}
559 had been called with the exact type specifier that appeared in the
562 If a variable is declared to be @code{(integer 3 17)} then its value
563 must always be an integer between @code{3} and @code{17}. If multiple
564 type declarations apply to a single variable, then all the
565 declarations must be correct; it is as though all the types were
566 intersected producing a single @code{and} type specifier.
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.
574 @node Getting Existing Programs to Run
575 @comment node-name, next, previous, up
576 @subsection Getting Existing Programs to Run
577 @cindex Existing programs, to run
578 @cindex Types, portability
579 @cindex Compatibility with other Lisps
580 @c (should also have an entry in the non-ANSI-isms section)-->
582 Since SBCL's compiler does much more comprehensive type checking than
583 most Lisp compilers, SBCL may detect type errors in programs that have
584 been debugged using other compilers. These errors are mostly incorrect
585 declarations, although compile-time type errors can find actual bugs
586 if parts of the program have never been tested.
588 Some incorrect declarations can only be detected by run-time type
589 checking. It is very important to initially compile a program with
590 full type checks (high @code{safety} optimization) and then test this
591 safe version. After the checking version has been tested, then you can
592 consider weakening or eliminating type checks. @emph{This applies
593 even to previously debugged programs,} because the SBCL compiler does
594 much more type inference than other Common Lisp compilers, so an
595 incorrect declaration can do more damage.
597 The most common problem is with variables whose constant initial value
598 doesn't match the type declaration. Incorrect constant initial values
599 will always be flagged by a compile-time type error, and they are
600 simple to fix once located. Consider this code fragment:
604 (declare (fixnum foo))
609 Here @code{foo} is given an initial value of @code{nil}, but is
610 declared to be a @code{fixnum}. Even if it is never read, the initial
611 value of a variable must match the declared type. There are two ways
612 to fix this problem. Change the declaration
616 (declare (type (or fixnum null) foo))
621 or change the initial value
625 (declare (fixnum foo))
630 It is generally preferable to change to a legal initial value rather
631 than to weaken the declaration, but sometimes it is simpler to weaken
632 the declaration than to try to make an initial value of the
635 Another declaration problem occasionally encountered is incorrect
636 declarations on @code{defmacro} arguments. This can happen when a
637 function is converted into a macro. Consider this macro:
642 `(the fixnum (1+ ,x)))
645 Although legal and well-defined Common Lisp code, this meaning of this
646 definition is almost certainly not what the writer intended. For
647 example, this call is illegal:
653 This call is illegal because the argument to the macro is @code{(+ 4
654 5)}, which is a @code{list}, not a @code{fixnum}. Because of macro
655 semantics, it is hardly ever useful to declare the types of macro
656 arguments. If you really want to assert something about the type of
657 the result of evaluating a macro argument, then put a @code{the} in
662 `(the fixnum (1+ (the fixnum ,x))))
665 In this case, it would be stylistically preferable to change this
666 macro back to a function and declare it inline.
667 @c <!--FIXME: <xref>inline-expansion, once we crib the
668 @c relevant text from the CMU CL manual.-->
670 Some more subtle problems are caused by incorrect declarations that
671 can't be detected at compile time. Consider this code:
674 (do ((pos 0 (position #\a string :start (1+ pos))))
676 (declare (fixnum pos))
680 Although @code{pos} is almost always a @code{fixnum}, it is @code{nil}
681 at the end of the loop. If this example is compiled with full type
682 checks (the default), then running it will signal a type error at the
683 end of the loop. If compiled without type checks, the program will go
684 into an infinite loop (or perhaps @code{position} will complain
685 because @code{(1+ nil)} isn't a sensible start.) Why? Because if you
686 compile without type checks, the compiler just quietly believes the
687 type declaration. Since the compiler believes that @code{pos} is
688 always a @code{fixnum}, it believes that @code{pos} is never
689 @code{nil}, so @code{(null pos)} is never true, and the loop exit test
690 is optimized away. Such errors are sometimes flagged by unreachable
691 code notes, but it is still important to initially compile and test
692 any system with full type checks, even if the system works fine when
693 compiled using other compilers.
695 In this case, the fix is to weaken the type declaration to @code{(or
696 fixnum null)} @footnote{Actually, this declaration is unnecessary in
697 SBCL, since it already knows that @code{position} returns a
698 non-negative @code{fixnum} or @code{nil}.}.
700 Note that there is usually little performance penalty for weakening a
701 declaration in this way. Any numeric operations in the body can still
702 assume that the variable is a @code{fixnum}, since @code{nil} is not a
703 legal numeric argument. Another possible fix would be to say:
706 (do ((pos 0 (position #\a string :start (1+ pos))))
709 (declare (fixnum pos))
713 This would be preferable in some circumstances, since it would allow a
714 non-standard representation to be used for the local @code{pos}
715 variable in the loop body.
716 @c <!-- FIXME: <xref>ND-variables, once we crib the text from the
717 @c CMU CL manual. -->
719 @node Implementation Limitations
720 @comment node-name, next, previous, up
721 @subsection Implementation Limitations
723 Ideally, the compiler would consider @emph{all} type declarations to
724 be assertions, so that adding type declarations to a program, no
725 matter how incorrect they might be, would @emph{never} cause undefined
726 behavior. However, the compiler is known to fall short of this goal in
732 @emph{Proclaimed} constraints on argument and result types of a
733 function are supposed to be checked by the function. If the function
734 type is proclaimed before function definition, type checks are
735 inserted by the compiler, but the standard allows the reversed order,
736 in which case the compiler will trust the declaration.
739 The compiler cannot check types of an unknown number of values; if the
740 number of generated values is unknown, but the number of consumed is
741 known, only consumed values are checked.
747 (the integer (bar x)))
750 causes the following compiler diagnostic to be emitted:
753 ; note: type assertion too complex to check:
754 ; (VALUES INTEGER &REST T).
757 A partial workaround is instead write:
761 (the (values integer &optional) (bar x)))
766 These are important issues, but are not necessarily easy to fix, so
767 they may, alas, remain in the system for a while.
769 @node Compiler Policy
770 @comment node-name, next, previous, up
771 @section Compiler Policy
773 Compiler policy is controlled by the @code{optimize} declaration,
774 supporting all ANSI optimization qualities (@code{debug},
775 @code{safety}, @code{space}, and @code{speed}).@footnote{A deprecated
776 extension @code{sb-ext:inhibit-warnings} is still supported, but
777 liable to go away at any time.}
779 For effects of various optimization qualities on type-safety and
780 debuggability see @ref{Declarations as Assertions} and @ref{Debugger
783 Ordinarily, when the @code{speed} quality is high, the compiler emits
784 notes to notify the programmer about its inability to apply various
785 optimizations. For selective muffling of these notes @xref{Controlling
788 The value of @code{space} mostly influences the compiler's decision
789 whether to inline operations, which tend to increase the size of
790 programs. Use the value @code{0} with caution, since it can cause the
791 compiler to inline operations so indiscriminately that the net effect
792 is to slow the program by causing cache misses or even swapping.
794 @c <!-- FIXME: old CMU CL compiler policy, should perhaps be adapted
795 @c _ for SBCL. (Unfortunately, the CMU CL docs are out of sync with the
796 @c _ CMU CL code, so adapting this requires not only reformatting
797 @c _ the documentation, but rooting out code rot.)
799 @c _<sect2 id="compiler-policy"><title>Compiler Policy</1000
800 @c _ INDEX {policy}{compiler}
801 @c _ INDEX compiler policy
803 @c _<para>The policy is what tells the compiler <emphasis>how</emphasis> to
804 @c _compile a program. This is logically (and often textually) distinct
805 @c _from the program itself. Broad control of policy is provided by the
806 @c _<parameter>optimize</parameter> declaration; other declarations and variables
807 @c _control more specific aspects of compilation.
810 @c _* The Optimize Declaration::
811 @c _* The Optimize-Interface Declaration::
814 @c _%%\node The Optimize Declaration, The Optimize-Interface Declaration, Compiler Policy, Compiler Policy
815 @c _\subsection{The Optimize Declaration}
816 @c _\label{optimize-declaration}
817 @c _\cindex{optimize declaration}
818 @c _\cpsubindex{declarations}{\code{optimize}}
820 @c _The \code{optimize} declaration recognizes six different
821 @c _\var{qualities}. The qualities are conceptually independent aspects
822 @c _of program performance. In reality, increasing one quality tends to
823 @c _have adverse effects on other qualities. The compiler compares the
824 @c _relative values of qualities when it needs to make a trade-off; i.e.,
825 @c _if \code{speed} is greater than \code{safety}, then improve speed at
826 @c _the cost of safety.
828 @c _The default for all qualities (except \code{debug}) is \code{1}.
829 @c _Whenever qualities are equal, ties are broken according to a broad
830 @c _idea of what a good default environment is supposed to be. Generally
831 @c _this downplays \code{speed}, \code{compile-speed} and \code{space} in
832 @c _favor of \code{safety} and \code{debug}. Novice and casual users
833 @c _should stick to the default policy. Advanced users often want to
834 @c _improve speed and memory usage at the cost of safety and
837 @c _If the value for a quality is \code{0} or \code{3}, then it may have a
838 @c _special interpretation. A value of \code{0} means ``totally
839 @c _unimportant'', and a \code{3} means ``ultimately important.'' These
840 @c _extreme optimization values enable ``heroic'' compilation strategies
841 @c _that are not always desirable and sometimes self-defeating.
842 @c _Specifying more than one quality as \code{3} is not desirable, since
843 @c _it doesn't tell the compiler which quality is most important.
846 @c _These are the optimization qualities:
849 @c _\item[\code{speed}] \cindex{speed optimization quality}How fast the
850 @c _ program should is run. \code{speed 3} enables some optimizations
851 @c _ that hurt debuggability.
853 @c _\item[\code{compilation-speed}] \cindex{compilation-speed optimization
854 @c _ quality}How fast the compiler should run. Note that increasing
855 @c _ this above \code{safety} weakens type checking.
857 @c _\item[\code{space}] \cindex{space optimization quality}How much space
858 @c _ the compiled code should take up. Inline expansion is mostly
859 @c _ inhibited when \code{space} is greater than \code{speed}. A value
860 @c _ of \code{0} enables indiscriminate inline expansion. Wide use of a
861 @c _ \code{0} value is not recommended, as it may waste so much space
862 @c _ that run time is slowed. \xlref{inline-expansion} for a discussion
863 @c _ of inline expansion.
865 @c _\item[\code{debug}] \cindex{debug optimization quality}How debuggable
866 @c _ the program should be. The quality is treated differently from the
867 @c _ other qualities: each value indicates a particular level of debugger
868 @c _ information; it is not compared with the other qualities.
869 @c _ \xlref{debugger-policy} for more details.
871 @c _\item[\code{safety}] \cindex{safety optimization quality}How much
872 @c _ error checking should be done. If \code{speed}, \code{space} or
873 @c _ \code{compilation-speed} is more important than \code{safety}, then
874 @c _ type checking is weakened (\pxlref{weakened-type-checks}). If
875 @c _ \code{safety} if \code{0}, then no run time error checking is done.
876 @c _ In addition to suppressing type checks, \code{0} also suppresses
877 @c _ argument count checking, unbound-symbol checking and array bounds
879 @c _ ... and checking of tag existence in RETURN-FROM and GO.
881 @c _\item[\code{extensions:inhibit-warnings}] \cindex{inhibit-warnings
882 @c _ optimization quality}This is a CMU extension that determines how
883 @c _ little (or how much) diagnostic output should be printed during
884 @c _ compilation. This quality is compared to other qualities to
885 @c _ determine whether to print style notes and warnings concerning those
886 @c _ qualities. If \code{speed} is greater than \code{inhibit-warnings},
887 @c _ then notes about how to improve speed will be printed, etc. The
888 @c _ default value is \code{1}, so raising the value for any standard
889 @c _ quality above its default enables notes for that quality. If
890 @c _ \code{inhibit-warnings} is \code{3}, then all notes and most
891 @c _ non-serious warnings are inhibited. This is useful with
892 @c _ \code{declare} to suppress warnings about unavoidable problems.
895 @c _%%\node The Optimize-Interface Declaration, , The Optimize Declaration, Compiler Policy
896 @c _\subsection{The Optimize-Interface Declaration}
897 @c _\label{optimize-interface-declaration}
898 @c _\cindex{optimize-interface declaration}
899 @c _\cpsubindex{declarations}{\code{optimize-interface}}
901 @c _The \code{extensions:optimize-interface} declaration is identical in
902 @c _syntax to the \code{optimize} declaration, but it specifies the policy
903 @c _used during compilation of code the compiler automatically generates
904 @c _to check the number and type of arguments supplied to a function. It
905 @c _is useful to specify this policy separately, since even thoroughly
906 @c _debugged functions are vulnerable to being passed the wrong arguments.
907 @c _The \code{optimize-interface} declaration can specify that arguments
908 @c _should be checked even when the general \code{optimize} policy is
911 @c _Note that this argument checking is the checking of user-supplied
912 @c _arguments to any functions defined within the scope of the
913 @c _declaration, \code{not} the checking of arguments to \llisp{}
914 @c _primitives that appear in those definitions.
916 @c _The idea behind this declaration is that it allows the definition of
917 @c _functions that appear fully safe to other callers, but that do no
918 @c _internal error checking. Of course, it is possible that arguments may
919 @c _be invalid in ways other than having incorrect type. Functions
920 @c _compiled unsafely must still protect themselves against things like
921 @c _user-supplied array indices that are out of bounds and improper lists.
922 @c _See also the \kwd{context-declarations} option to
923 @c _\macref{with-compilation-unit}.
925 @c _(end of section on compiler policy)
928 @include fun-sb-ext-describe-compiler-policy.texinfo
929 @include fun-sb-ext-restrict-compiler-policy.texinfo
930 @include macro-common-lisp-with-compilation-unit.texinfo
932 @node Compiler Errors
933 @comment node-name, next, previous, up
934 @section Compiler Errors
937 * Type Errors at Compile Time::
938 * Errors During Macroexpansion::
942 @node Type Errors at Compile Time
943 @comment node-name, next, previous, up
944 @subsection Type Errors at Compile Time
945 @cindex Compile time type errors
946 @cindex Type checking, at compile time
948 If the compiler can prove at compile time that some portion of the
949 program cannot be executed without a type error, then it will give a
950 warning at compile time.
952 It is possible that the offending code would never actually be
953 executed at run-time due to some higher level consistency constraint
954 unknown to the compiler, so a type warning doesn't always indicate an
957 For example, consider this code fragment:
969 Compilation produces this warning:
973 ; (CASE FOO (:THIS 13) (:THAT 9) (:THE-OTHER 42))
974 ; --> LET COND IF COND IF COND IF
979 ; This is not a FIXNUM:
983 In this case, the warning means that if @code{foo} isn't any of
984 @code{:this}, @code{:that} or @code{:the-other}, then @code{x} will be
985 initialized to @code{nil}, which the @code{fixnum} declaration makes
986 illegal. The warning will go away if @code{ecase} is used instead of
987 @code{case}, or if @code{:the-other} is changed to @code{t}.
989 This sort of spurious type warning happens moderately often in the
990 expansion of complex macros and in inline functions. In such cases,
991 there may be dead code that is impossible to correctly execute. The
992 compiler can't always prove this code is dead (could never be
993 executed), so it compiles the erroneous code (which will always signal
994 an error if it is executed) and gives a warning.
996 @node Errors During Macroexpansion
997 @comment node-name, next, previous, up
998 @subsection Errors During Macroexpansion
999 @cindex Macroexpansion, errors during
1001 The compiler handles errors that happen during macroexpansion, turning
1002 them into compiler errors. If you want to debug the error (to debug a
1003 macro), you can set @code{*break-on-signals*} to @code{error}. For
1004 example, this definition:
1008 (do ((current l (cdr current))
1009 ((atom current) nil))
1010 (when (eq (car current) e) (return current))))
1017 ; (DO ((CURRENT L (CDR CURRENT))
1018 ; ((ATOM CURRENT) NIL))
1019 ; (WHEN (EQ (CAR CURRENT) E) (RETURN CURRENT)))
1022 ; (in macroexpansion of (DO # #))
1023 ; (hint: For more precise location, try *BREAK-ON-SIGNALS*.)
1024 ; DO step variable is not a symbol: (ATOM CURRENT)
1029 @comment node-name, next, previous, up
1030 @subsection Read Errors
1031 @cindex Read errors, compiler
1033 SBCL's compiler does not attempt to recover from read errors when
1034 reading a source file, but instead just reports the offending
1035 character position and gives up on the entire source file.
1037 @node Open Coding and Inline Expansion
1038 @comment node-name, next, previous, up
1039 @section Open Coding and Inline Expansion
1041 @cindex Inline expansion
1042 @cindex Static functions
1044 Since Common Lisp forbids the redefinition of standard functions, the
1045 compiler can have special knowledge of these standard functions
1046 embedded in it. This special knowledge is used in various ways (open
1047 coding, inline expansion, source transformation), but the implications
1048 to the user are basically the same:
1053 Attempts to redefine standard functions may be frustrated, since the
1054 function may never be called. Although it is technically illegal to
1055 redefine standard functions, users sometimes want to implicitly
1056 redefine these functions when they are debugging using the
1057 @code{trace} macro. Special-casing of standard functions can be
1058 inhibited using the @code{notinline} declaration, but even then some
1059 phases of analysis such as type inferencing are applied by the
1063 The compiler can have multiple alternate implementations of standard
1064 functions that implement different trade-offs of speed, space and
1065 safety. This selection is based on the compiler policy, @ref{Compiler
1070 When a function call is @emph{open coded}, inline code whose effect is
1071 equivalent to the function call is substituted for that function
1072 call. When a function call is @emph{closed coded}, it is usually left
1073 as is, although it might be turned into a call to a different function
1074 with different arguments. As an example, if @code{nthcdr} were to be
1084 (cdr (cdr (cdr (cdr foobar))))
1091 (list foobar (cdr foobar)))
1095 If @code{nth} is closed coded, then
1101 might stay the same, or turn into something like
1107 In general, open coding sacrifices space for speed, but some functions
1108 (such as @code{car}) are so simple that they are always
1109 open-coded. Even when not open-coded, a call to a standard function
1110 may be transformed into a different function call (as in the last
1111 example) or compiled as @emph{static call}. Static function call uses
1112 a more efficient calling convention that forbids redefinition.
1115 @comment node-name, next, previous, up
1116 @section Interpreter
1119 @vindex @sbext{@earmuffs{evaluator-mode}}
1121 By default SBCL implements @code{eval} by calling the native code
1124 SBCL also includes an interpreter for use in special cases where using
1125 the compiler is undesirable, for example due to compilation overhead.
1126 Unlike in some other Lisp implementations, in SBCL interpreted code is
1127 not safer or more debuggable than compiled code.
1129 @include var-sb-ext-star-evaluator-mode-star.texinfo
1131 @node Advanced Compiler Use and Efficiency Hints
1132 @comment node-name, next, previous, up
1133 @section Advanced Compiler Use and Efficiency Hints
1134 For more advanced usages of the compiler, please see the chapter of the
1135 same name in the CMUCL manual. Many aspects of the compiler have stayed
1136 exactly the same, and there is a much more detailed explanation of the
1137 compiler's behavior and how to maximally optimize code in their
1138 manual. In particular, while SBCL no longer supports byte-code
1139 compilation, it does support CMUCL's block compilation facility allowing
1140 whole program optimization and increased use of the local call
1143 Unlike CMUCL, SBCL is able to open-code forward-referenced type tests
1144 while block compiling. This helps for mutually referential
1145 @code{defstruct}s in particular.