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