1 @node The Compiler, The Debugger, Introduction, Top
2 @comment node-name, next, previous, up
5 This chapter will discuss most compiler issues other than
6 efficiency, including compiler error messages, the SBCL compiler's
7 unusual approach to type safety in the presence of type declarations,
8 the effects of various compiler optimization policies, and the way
9 that inlining and open coding may cause optimized code to differ from
10 a naive translation. Efficiency issues are sufficiently varied and
11 separate that they have their own chapter, @ref{Efficiency}.
17 * Open Coding and Inline Expansion::
20 @node Error Messages, Handling of Types, The Compiler, The Compiler
21 @comment node-name, next, previous, up
22 @section Error Messages
23 @cindex Error messages, Compiler
24 @cindex Compiler error messages
26 The compiler supplies a large amount of source location information in
27 error messages. The error messages contain a lot of detail in a terse
28 format, so they may be confusing at first. Error messages will be
29 illustrated using this example program:
33 `(roq (ploq (+ ,x 3))))
40 The main problem with this program is that it is trying to add
41 @code{3} to a symbol. Note also that the functions @code{roq} and
42 @code{ploq} aren't defined anywhere.
46 * The Parts of the Error Message::
47 * The Original and Actual Source::
49 * Errors During Macroexpansion::
53 @node The Parts of the Error Message, The Original and Actual Source, Error Messages, Error Messages
54 @comment node-name, next, previous, up
55 @subsection The Parts of the Error Message
57 When processing this program, the compiler will produce this warning:
68 Result is a SYMBOL, not a NUMBER.
71 In this example we see each of the six possible parts of a compiler
77 @samp{File: /tmp/foo.lisp} This is the name of the file that the
78 compiler read the relevant code from. The file name is displayed
79 because it may not be immediately obvious when there is an error
80 during compilation of a large system, especially when
81 @code{with-compilation-unit} is used to delay undefined warnings.
84 @samp{in: DEFUN FOO} This is the definition top level form responsible
85 for the error. It is obtained by taking the first two elements of the
86 enclosing form whose first element is a symbol beginning with
87 ``@samp{def}''. If there is no such enclosing ``@samp{def}'' form,
88 then the outermost form is used. If there are multiple @samp{def}
89 forms, then they are all printed from the outside in, separated by
90 @samp{=>}'s. In this example, the problem was in the @code{defun} for
94 @samp{(ZOQ Y)} This is the @dfn{original source} form responsible for
95 the error. Original source means that the form directly appeared in
96 the original input to the compiler, i.e. in the lambda passed to
97 @code{compile} or in the top level form read from the source file. In
98 this example, the expansion of the @code{zoq} macro was responsible
102 @samp{--> ROQ PLOQ +} This is the @dfn{processing path} that the
103 compiler used to produce the errorful code. The processing path is a
104 representation of the evaluated forms enclosing the actual source that
105 the compiler encountered when processing the original source. The
106 path is the first element of each form, or the form itself if the form
107 is not a list. These forms result from the expansion of macros or
108 source-to-source transformation done by the compiler. In this
109 example, the enclosing evaluated forms are the calls to @code{roq},
110 @code{ploq} and @code{+}. These calls resulted from the expansion of
111 the @code{zoq} macro.
114 @samp{==> Y} 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: Result is a SYMBOL, not a NUMBER.} This is the
123 @dfn{explanation} of the problem. In this example, the problem is that
124 @code{y} evaluates to a symbol, but is in a context where a number is
125 required (the argument to @code{+}).
129 Note that each part of the error message is distinctively marked:
134 @samp{file:} and @samp{in:} mark the file and definition,
138 The original source is an indented form with no prefix.
141 Each line of the processing path is prefixed with @samp{-->}
144 The actual source form is indented like the original source, but is
145 marked by a preceding @samp{==>} line.
149 The explanation is prefixed with the error severity, which can be
150 @samp{caught ERROR:}, @samp{caught WARNING:}, @samp{caught
151 STYLE-WARNING:}, or @samp{note:}.
155 Each part of the error message is more specific than the preceding
156 one. If consecutive error messages are for nearby locations, then the
157 front part of the error messages would be the same. In this case, the
158 compiler omits as much of the second message as in common with the
169 caught STYLE-WARNING:
170 undefined function: PLOQ
174 caught STYLE-WARNING:
175 undefined function: ROQ
178 In this example, the file, definition and original source are
179 identical for the two messages, so the compiler omits them in the
180 second message. If consecutive messages are entirely identical, then
181 the compiler prints only the first message, followed by: @samp{[Last
182 message occurs @var{repeats} times]} where @var{repeats} is the number
183 of times the message was given.
185 If the source was not from a file, then no file line is printed. If
186 the actual source is the same as the original source, then the
187 processing path and actual source will be omitted. If no forms
188 intervene between the original source and the actual source, then the
189 processing path will also be omitted.
192 @node The Original and Actual Source, Error Severity, The Parts of the Error Message, Error Messages
193 @comment node-name, next, previous, up
194 @subsection The Original and Actual Source
196 The @emph{original source} displayed will almost always be a list. If
197 the actual source for an error message is a symbol, the original
198 source will be the immediately enclosing evaluated list form. So even
199 if the offending symbol does appear in the original source, the
200 compiler will print the enclosing list and then print the symbol as
201 the actual source (as though the symbol were introduced by a macro.)
203 When the @emph{actual source} is displayed (and is not a symbol), it
204 will always be code that resulted from the expansion of a macro or a
205 source-to-source compiler optimization. This is code that did not
206 appear in the original source program; it was introduced by the
209 Keep in mind that when the compiler displays a source form in an error
210 message, it always displays the most specific (innermost) responsible
211 form. For example, compiling this function
221 gives this error message
225 (LET (A) (DECLARE (FIXNUM A)) (SETQ A (FOO X)) A)
226 caught WARNING: The binding of A is not a FIXNUM:
230 This error message is not saying ``there is a problem somewhere in
231 this @code{let}'' -- it is saying that there is a problem with the
232 @code{let} itself. In this example, the problem is that @code{a}'s
233 @code{nil} initial value is not a @code{fixnum}.
236 @subsection The Processing Path
237 @cindex Processing path
238 @cindex Macroexpansion
239 @cindex Source-to-source transformation
241 The processing path is mainly useful for debugging macros, so if you
242 don't write macros, you can probably ignore it. Consider this example:
246 (dotimes (i n *undefined*)))
249 Compiling results in this error message:
253 (DOTIMES (I N *UNDEFINED*))
254 --> DO BLOCK LET TAGBODY RETURN-FROM
257 caught STYLE-WARNING:
258 undefined variable: *UNDEFINED*
261 Note that @code{do} appears in the processing path. This is because
262 @code{dotimes} expands into:
265 (do ((i 0 (1+ i)) (#:g1 n))
266 ((>= i #:g1) *undefined*)
267 (declare (type unsigned-byte i)))
270 The rest of the processing path results from the expansion of
275 (let ((i 0) (#:g1 n))
276 (declare (type unsigned-byte i))
278 #:g2 (psetq i (1+ i))
279 #:g3 (unless (>= i #:g1) (go #:g2))
280 (return-from nil (progn *undefined*)))))
283 In this example, the compiler descended into the @code{block},
284 @code{let}, @code{tagbody} and @code{return-from} to
285 reach the @code{progn} printed as the actual source. This is a
286 place where the ``actual source appears in explanation'' rule
287 was applied. The innermost actual source form was the symbol
288 @code{*undefined*} itself, but that also appeared in the
289 explanation, so the compiler backed out one level.
292 @node Error Severity, Errors During Macroexpansion, The Original and Actual Source, Error Messages
293 @comment node-name, next, previous, up
294 @subsection Error Severity
295 @cindex Severity of compiler errors
296 @cindex compiler error severity
298 There are four levels of compiler error severity: @emph{error},
299 @emph{warning}, @emph{style warning}, and @emph{note}. The first three
300 levels correspond to condition classes which are defined in the ANSI
301 standard for Common Lisp and which have special significance to the
302 @code{compile} and @code{compile-file} functions. These levels of
303 compiler error severity occur when the compiler handles conditions of
304 these classes. The fourth level of compiler error severity,
305 @emph{note}, is used for problems which are too mild for the standard
306 condition classes, typically hints about how efficiency might be
310 @node Errors During Macroexpansion, Read Errors, Error Severity, Error Messages
311 @comment node-name, next, previous, up
312 @subsection Errors During Macroexpansion
313 @cindex Macroexpansion, errors during
315 The compiler handles errors that happen during macroexpansion, turning
316 them into compiler errors. If you want to debug the error (to debug a
317 macro), you can set @code{*break-on-signals*} to @code{error}. For
318 example, this definition:
322 (do ((current l (cdr current))
323 ((atom current) nil))
324 (when (eq (car current) e) (return current))))
331 (DO ((CURRENT L #) (# NIL)) (WHEN (EQ # E) (RETURN CURRENT)) )
333 (in macroexpansion of (DO # #))
334 (hint: For more precise location, try *BREAK-ON-SIGNALS*.)
335 DO step variable is not a symbol: (ATOM CURRENT)
339 @node Read Errors, , Errors During Macroexpansion, Error Messages
340 @comment node-name, next, previous, up
341 @subsection Read Errors
342 @cindex Read errors, compiler
344 SBCL's compiler (unlike CMUCL's) does not attempt to recover from read
345 errors when reading a source file, but instead just reports the
346 offending character position and gives up on the entire source file.
349 @c <!-- FIXME: How much control over error messages is in SBCL?
350 @c _ How much should be? How much of this documentation should
351 @c _ we save or adapt?
353 @c _ %%\node Error Message Parameterization, , Read Errors, Interpreting Error Messages
354 @c _ \subsection{Error Message Parameterization}
355 @c _ \cpsubindex{error messages}{verbosity}
356 @c _ \cpsubindex{verbosity}{of error messages}
358 @c _ There is some control over the verbosity of error messages. See also
359 @c _ \varref{undefined-warning-limit}, \code{*efficiency-note-limit*} and
360 @c _ \varref{efficiency-note-cost-threshold}.
362 @c _ \begin{defvar}{}{enclosing-source-cutoff}
364 @c _ This variable specifies the number of enclosing actual source forms
365 @c _ that are printed in full, rather than in the abbreviated processing
366 @c _ path format. Increasing the value from its default of \code{1}
367 @c _ allows you to see more of the guts of the macroexpanded source,
368 @c _ which is useful when debugging macros.
371 @c _ \begin{defvar}{}{error-print-length}
372 @c _ \defvarx{error-print-level}
374 @c _ These variables are the print level and print length used in
375 @c _ printing error messages. The default values are \code{5} and
376 @c _ \code{3}. If null, the global values of \code{*print-level*} and
377 @c _ \code{*print-length*} are used.
380 @c _ \begin{defmac}{extensions:}{define-source-context}{%
381 @c _ \args{\var{name} \var{lambda-list} \mstar{form}}}
383 @c _ This macro defines how to extract an abbreviated source context from
384 @c _ the \var{name}d form when it appears in the compiler input.
385 @c _ \var{lambda-list} is a \code{defmacro} style lambda-list used to
386 @c _ parse the arguments. The \var{body} should return a list of
387 @c _ subforms that can be printed on about one line. There are
388 @c _ predefined methods for \code{defstruct}, \code{defmethod}, etc. If
389 @c _ no method is defined, then the first two subforms are returned.
390 @c _ Note that this facility implicitly determines the string name
391 @c _ associated with anonymous functions.
397 @node Handling of Types, Compiler Policy, Error Messages, The Compiler
398 @comment node-name, next, previous, up
399 @section The Compiler's Handling of Types
401 The most unusual features of the SBCL compiler (which is very similar
402 to the original CMUCL compiler, also known as @dfn{Python}) is its
403 unusually sophisticated understanding of the Common Lisp type system
404 and its unusually conservative approach to the implementation of type
405 declarations. These two features reward the use of type declarations
406 throughout development, even when high performance is not a
407 concern. Also, as discussed in the chapter on performance
408 (@pxref{Efficiency}), the use of appropriate type declarations can be
409 very important for performance as well.
411 The SBCL compiler, like the related compiler in CMUCL, treats type
412 declarations much differently than other Lisp compilers. By default
413 (@emph{i.e.}, at ordinary levels of the @code{safety} compiler
414 optimization parameter), the compiler doesn't blindly believe most
415 type declarations; it considers them assertions about the program that
418 The SBCL compiler also has a greater knowledge of the
419 Common Lisp type system than other compilers. Support is incomplete
420 only for the @code{not}, @code{and} and @code{satisfies}
423 @c <!-- FIXME: See also sections \ref{advanced-type-stuff}
424 @c and \ref{type-inference}, once we snarf them from the
425 @c CMU CL manual. -->
429 * Implementation Limitations::
430 * Type Errors at Compile Time::
431 * Precise Type Checking::
432 * Weakened Type Checking::
433 * Getting Existing Programs to Run::
436 @node Implementation Limitations, Type Errors at Compile Time, Handling of Types, Handling of Types
437 @comment node-name, next, previous, up
438 @subsection Implementation Limitations
441 Ideally, the compiler would consider @emph{all} type declarations to
442 be assertions, so that adding type declarations to a program, no
443 matter how incorrect they might be, would @emph{never} cause undefined
444 behavior. As of SBCL version 0.8.1, the compiler is known to fall
445 short of this goal in two areas:
450 @code{Proclaim}ed constraints on argument and result types of a
451 function are supposed to be checked by the function. If the function
452 type is proclaimed before function definition, type checks are
453 inserted by the compiler, but the standard allows the reversed order,
454 in which case the compiler will trust the declaration.
457 The compiler cannot check types of an unknown number of values; if the
458 number of generated values is unknown, but the number of consumed is
459 known, only consumed values are checked.
462 There are a few poorly characterized but apparently very uncommon
463 situations where a type declaration in an unexpected location will be
464 trusted and never checked by the compiler.
468 These are important bugs, but are not necessarily easy to fix, so they
469 may, alas, remain in the system for a while.
472 @node Type Errors at Compile Time, Precise Type Checking, Implementation Limitations, Handling of Types
473 @comment node-name, next, previous, up
474 @subsection Type Errors at Compile Time
475 @cindex Compile time type errors
476 @cindex Type checking, at compile time
478 If the compiler can prove at compile time that some portion of the
479 program cannot be executed without a type error, then it will give a
480 warning at compile time. It is possible that the offending code would
481 never actually be executed at run-time due to some higher level
482 consistency constraint unknown to the compiler, so a type warning
483 doesn't always indicate an incorrect program. For example, consider
497 Compilation produces this warning:
501 (CASE FOO (:THIS 13) (:THAT 9) (:THE-OTHER 42))
502 --> LET COND IF COND IF COND IF
505 caught WARNING: This is not a FIXNUM:
509 In this case, the warning means that if @code{foo} isn't any of
510 @code{:this}, @code{:that} or @code{:the-other}, then @code{x} will be
511 initialized to @code{nil}, which the @code{fixnum} declaration makes
512 illegal. The warning will go away if @code{ecase} is used instead of
513 @code{case}, or if @code{:the-other} is changed to @code{t}.
515 This sort of spurious type warning happens moderately often in the
516 expansion of complex macros and in inline functions. In such cases,
517 there may be dead code that is impossible to correctly execute. The
518 compiler can't always prove this code is dead (could never be
519 executed), so it compiles the erroneous code (which will always signal
520 an error if it is executed) and gives a warning.
523 Type warnings are inhibited when the @code{sb-ext:inhibit-warnings}
524 optimization quality is @code{3}. @xref{Compiler Policy}. This
525 can be used in a local declaration to inhibit type warnings in a code
526 fragment that has spurious warnings.
529 @node Precise Type Checking, Weakened Type Checking, Type Errors at Compile Time, Handling of Types
530 @comment node-name, next, previous, up
531 @subsection Precise Type Checking
532 @cindex Precise type checking
533 @cindex Type checking, precise
535 With the default compilation policy, all type declarations are
536 precisely checked, except in a few situations where they are simply
537 ignored instead. Precise checking means that the check is done as
538 though @code{typep} had been called with the exact type specifier that
539 appeared in the declaration. In SBCL, adding type declarations makes
540 code safer. (Except that remaining bugs in the compiler's handling of
541 types unfortunately provide some exceptions to this rule, see
542 @ref{Implementation Limitations}).
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 Argument and result type declarations are automatically enforced. If
551 you declare the type of a function argument, a type check will be done
552 when that function is called. In a function call, the called function
553 does the argument type checking.
555 The types of structure slots are also checked. The value of a
556 structure slot must always be of the type indicated in any
557 @code{:type} slot option.
559 In traditional Common Lisp compilers, not all type assertions are
560 checked, and type checks are not precise. Traditional compilers
561 blindly trust explicit type declarations, but may check the argument
562 type assertions for built-in functions. Type checking is not precise,
563 since the argument type checks will be for the most general type legal
564 for that argument. In many systems, type declarations suppress what
565 little type checking is being done, so adding type declarations makes
566 code unsafe. This is a problem since it discourages writing type
567 declarations during initial coding. In addition to being more error
568 prone, adding type declarations during tuning also loses all the
569 benefits of debugging with checked type assertions.
571 To gain maximum benefit from the compiler's type checking, you should
572 always declare the types of function arguments and structure slots as
573 precisely as possible. This often involves the use of @code{or},
574 @code{member}, and other list-style type specifiers.
577 @node Weakened Type Checking, Getting Existing Programs to Run, Precise Type Checking, Handling of Types
578 @comment node-name, next, previous, up
579 @subsection Weakened Type Checking
580 @cindex Weakened type checking
581 @cindex Type checking, weakened
583 At one time, CMUCL supported another level of type checking,
584 ``weakened type checking'', when the value for the @code{speed}
585 optimization quality is greater than @code{safety}, and @code{safety}
586 is not @code{0}. The CMUCL manual still has a description of it, but
587 even the CMU CL code no longer corresponds to the manual. Some of this
588 partial safety checking lingers on in SBCL, but it's not a supported
589 feature, and should not be relied on. If you ask the compiler to
590 optimize @code{speed} to a higher level than @code{safety}, your
591 program is performing without a safety net, because SBCL may at its
592 option believe any or all type declarations with either partial or
593 nonexistent runtime checking.
596 @node Getting Existing Programs to Run, , Weakened Type Checking, Handling of Types
597 @comment node-name, next, previous, up
598 @subsection Getting Existing Programs to Run
599 @cindex Existing programs, to run
600 @cindex Types, portability
601 @cindex Compatibility with other Lisps
602 @c (should also have an entry in the non-ANSI-isms section)-->
604 Since SBCL's compiler, like CMUCL's compiler, does much more
605 comprehensive type checking than most Lisp compilers, SBCL may detect
606 type errors in programs that have been debugged using other
607 compilers. These errors are mostly incorrect declarations, although
608 compile-time type errors can find actual bugs if parts of the program
609 have never been tested.
611 Some incorrect declarations can only be detected by run-time type
612 checking. It is very important to initially compile a program with
613 full type checks (high @code{safety} optimization) and then test this
614 safe version. After the checking version has been tested, then you can
615 consider weakening or eliminating type checks. @emph{This applies
616 even to previously debugged programs,} because the SBCL compiler does
617 much more type inference than other Common Lisp compilers, so an
618 incorrect declaration can do more damage.
620 The most common problem is with variables whose constant initial value
621 doesn't match the type declaration. Incorrect constant initial values
622 will always be flagged by a compile-time type error, and they are
623 simple to fix once located. Consider this code fragment:
627 (declare (fixnum foo))
632 Here @code{foo} is given an initial value of @code{nil}, but is
633 declared to be a @code{fixnum}. Even if it is never read, the initial
634 value of a variable must match the declared type. There are two ways
635 to fix this problem. Change the declaration
639 (declare (type (or fixnum null) foo))
644 or change the initial value
648 (declare (fixnum foo))
653 It is generally preferable to change to a legal initial value rather
654 than to weaken the declaration, but sometimes it is simpler to weaken
655 the declaration than to try to make an initial value of the
658 Another declaration problem occasionally encountered is incorrect
659 declarations on @code{defmacro} arguments. This can happen when a
660 function is converted into a macro. Consider this macro:
665 `(the fixnum (1+ ,x)))
668 Although legal and well-defined Common Lisp code, this meaning of this
669 definition is almost certainly not what the writer intended. For
670 example, this call is illegal:
676 This call is illegal because the argument to the macro is @code{(+ 4
677 5)}, which is a @code{list}, not a @code{fixnum}. Because of macro
678 semantics, it is hardly ever useful to declare the types of macro
679 arguments. If you really want to assert something about the type of
680 the result of evaluating a macro argument, then put a @code{the} in
685 `(the fixnum (1+ (the fixnum ,x))))
688 In this case, it would be stylistically preferable to change this
689 macro back to a function and declare it inline.
690 @c <!--FIXME: <xref>inline-expansion, once we crib the
691 @c relevant text from the CMU CL manual.-->
693 Some more subtle problems are caused by incorrect declarations that
694 can't be detected at compile time. Consider this code:
697 (do ((pos 0 (position #\a string :start (1+ pos))))
699 (declare (fixnum pos))
703 Although @code{pos} is almost always a @code{fixnum}, it is @code{nil}
704 at the end of the loop. If this example is compiled with full type
705 checks (the default), then running it will signal a type error at the
706 end of the loop. If compiled without type checks, the program will go
707 into an infinite loop (or perhaps @code{position} will complain
708 because @code{(1+ nil)} isn't a sensible start.) Why? Because if you
709 compile without type checks, the compiler just quietly believes the
710 type declaration. Since the compiler believes that @code{pos} is
711 always a @code{fixnum}, it believes that @code{pos} is never
712 @code{nil}, so @code{(null pos)} is never true, and the loop exit test
713 is optimized away. Such errors are sometimes flagged by unreachable
714 code notes, but it is still important to initially compile and test
715 any system with full type checks, even if the system works fine when
716 compiled using other compilers.
718 In this case, the fix is to weaken the type declaration to @code{(or
719 fixnum null)} @footnote{Actually, this declaration is unnecessary in
720 SBCL, since it already knows that @code{position} returns a
721 non-negative @code{fixnum} or @code{nil}.}.
723 Note that there is usually little performance penalty for weakening a
724 declaration in this way. Any numeric operations in the body can still
725 assume that the variable is a @code{fixnum}, since @code{nil} is not a
726 legal numeric argument. Another possible fix would be to say:
729 (do ((pos 0 (position #\a string :start (1+ pos))))
732 (declare (fixnum pos))
736 This would be preferable in some circumstances, since it would allow a
737 non-standard representation to be used for the local @code{pos}
738 variable in the loop body.
739 @c <!-- FIXME: <xref>ND-variables, once we crib the text from the
740 @c CMU CL manual. -->
743 @node Compiler Policy, Open Coding and Inline Expansion, Handling of Types, The Compiler
744 @comment node-name, next, previous, up
745 @section Compiler Policy
747 As of version 0.6.4, SBCL still uses most of the CMUCL code for
748 compiler policy. The CMUCL code has many features and high-quality
749 documentation, but the two unfortunately do not match. So this area of
750 the compiler and its interface needs to be cleaned up. Meanwhile, here
751 is some rudimentary documentation on the current behavior of the
754 Compiler policy is controlled by the @code{optimize} declaration. The
755 compiler supports the ANSI optimization qualities, and also an
756 extension @code{sb-ext:inhibit-warnings}.
758 Ordinarily, when the @code{speed} quality is high, the compiler emits
759 notes to notify the programmer about its inability to apply various
760 optimizations. Setting @code{sb-ext:inhibit-warnings} to a value at
761 least as large as the @code{speed} quality inhibits this
762 notification. This can be useful to suppress notes about code which is
763 known to be unavoidably inefficient. (For example, the compiler issues
764 notes about having to use generic arithmetic instead of fixnum
765 arithmetic, which is not helpful for code which by design supports
766 arbitrary-sized integers instead of being limited to fixnums.)
769 Note: The basic functionality of the @code{optimize
770 inhibit-warnings} extension will probably be supported in all future
771 versions of the system, but it will probably be renamed when the
772 compiler and its interface are cleaned up. The current name is
773 misleading, because it mostly inhibits optimization notes, not
774 warnings. And making it an optimization quality is misleading, because
775 it shouldn't affect the resulting code at all. It may become a
776 declaration identifier with a name like
777 @code{sb-ext:inhibit-notes}, so that what's currently written.
780 (declaim (optimize (sb-ext:inhibit-warnings 2)))
783 would become something like
786 (declaim (sb-ext:inhibit-notes 2))
791 In early versions of SBCL, a @code{speed} value of zero was used to
792 enable byte compilation, but since version 0.7.0, SBCL only supports
795 When @code{safety} is zero, almost all runtime checking of types,
796 array bounds, and so forth is suppressed.
798 When @code{safety} is less than @code{speed}, any and all type checks
799 may be suppressed. At some point in the past, CMUCL had a more nuanced
800 interpretation of this (@pxref{Weakened Type Checking}). However, SBCL
801 doesn't support that interpretation, and setting @code{safety} less
802 than @code{speed} may have roughly the same effect as setting
803 @code{safety} to zero.
805 The value of @code{space} mostly influences the compiler's decision
806 whether to inline operations, which tend to increase the size of
807 programs. Use the value @code{0} with caution, since it can cause the
808 compiler to inline operations so indiscriminately that the net effect
809 is to slow the program by causing cache misses or swapping.
811 @c <!-- FIXME: old CMU CL compiler policy, should perhaps be adapted
812 @c _ for SBCL. (Unfortunately, the CMU CL docs are out of sync with the
813 @c _ CMU CL code, so adapting this requires not only reformatting
814 @c _ the documentation, but rooting out code rot.)
816 @c _<sect2 id="compiler-policy"><title>Compiler Policy</1000
817 @c _ INDEX {policy}{compiler}
818 @c _ INDEX compiler policy
820 @c _<para>The policy is what tells the compiler <emphasis>how</emphasis> to
821 @c _compile a program. This is logically (and often textually) distinct
822 @c _from the program itself. Broad control of policy is provided by the
823 @c _<parameter>optimize</parameter> declaration; other declarations and variables
824 @c _control more specific aspects of compilation.
827 @c _* The Optimize Declaration::
828 @c _* The Optimize-Interface Declaration::
831 @c _%%\node The Optimize Declaration, The Optimize-Interface Declaration, Compiler Policy, Compiler Policy
832 @c _\subsection{The Optimize Declaration}
833 @c _\label{optimize-declaration}
834 @c _\cindex{optimize declaration}
835 @c _\cpsubindex{declarations}{\code{optimize}}
837 @c _The \code{optimize} declaration recognizes six different
838 @c _\var{qualities}. The qualities are conceptually independent aspects
839 @c _of program performance. In reality, increasing one quality tends to
840 @c _have adverse effects on other qualities. The compiler compares the
841 @c _relative values of qualities when it needs to make a trade-off; i.e.,
842 @c _if \code{speed} is greater than \code{safety}, then improve speed at
843 @c _the cost of safety.
845 @c _The default for all qualities (except \code{debug}) is \code{1}.
846 @c _Whenever qualities are equal, ties are broken according to a broad
847 @c _idea of what a good default environment is supposed to be. Generally
848 @c _this downplays \code{speed}, \code{compile-speed} and \code{space} in
849 @c _favor of \code{safety} and \code{debug}. Novice and casual users
850 @c _should stick to the default policy. Advanced users often want to
851 @c _improve speed and memory usage at the cost of safety and
854 @c _If the value for a quality is \code{0} or \code{3}, then it may have a
855 @c _special interpretation. A value of \code{0} means ``totally
856 @c _unimportant'', and a \code{3} means ``ultimately important.'' These
857 @c _extreme optimization values enable ``heroic'' compilation strategies
858 @c _that are not always desirable and sometimes self-defeating.
859 @c _Specifying more than one quality as \code{3} is not desirable, since
860 @c _it doesn't tell the compiler which quality is most important.
863 @c _These are the optimization qualities:
866 @c _\item[\code{speed}] \cindex{speed optimization quality}How fast the
867 @c _ program should is run. \code{speed 3} enables some optimizations
868 @c _ that hurt debuggability.
870 @c _\item[\code{compilation-speed}] \cindex{compilation-speed optimization
871 @c _ quality}How fast the compiler should run. Note that increasing
872 @c _ this above \code{safety} weakens type checking.
874 @c _\item[\code{space}] \cindex{space optimization quality}How much space
875 @c _ the compiled code should take up. Inline expansion is mostly
876 @c _ inhibited when \code{space} is greater than \code{speed}. A value
877 @c _ of \code{0} enables indiscriminate inline expansion. Wide use of a
878 @c _ \code{0} value is not recommended, as it may waste so much space
879 @c _ that run time is slowed. \xlref{inline-expansion} for a discussion
880 @c _ of inline expansion.
882 @c _\item[\code{debug}] \cindex{debug optimization quality}How debuggable
883 @c _ the program should be. The quality is treated differently from the
884 @c _ other qualities: each value indicates a particular level of debugger
885 @c _ information; it is not compared with the other qualities.
886 @c _ \xlref{debugger-policy} for more details.
888 @c _\item[\code{safety}] \cindex{safety optimization quality}How much
889 @c _ error checking should be done. If \code{speed}, \code{space} or
890 @c _ \code{compilation-speed} is more important than \code{safety}, then
891 @c _ type checking is weakened (\pxlref{weakened-type-checks}). If
892 @c _ \code{safety} if \code{0}, then no run time error checking is done.
893 @c _ In addition to suppressing type checks, \code{0} also suppresses
894 @c _ argument count checking, unbound-symbol checking and array bounds
897 @c _\item[\code{extensions:inhibit-warnings}] \cindex{inhibit-warnings
898 @c _ optimization quality}This is a CMU extension that determines how
899 @c _ little (or how much) diagnostic output should be printed during
900 @c _ compilation. This quality is compared to other qualities to
901 @c _ determine whether to print style notes and warnings concerning those
902 @c _ qualities. If \code{speed} is greater than \code{inhibit-warnings},
903 @c _ then notes about how to improve speed will be printed, etc. The
904 @c _ default value is \code{1}, so raising the value for any standard
905 @c _ quality above its default enables notes for that quality. If
906 @c _ \code{inhibit-warnings} is \code{3}, then all notes and most
907 @c _ non-serious warnings are inhibited. This is useful with
908 @c _ \code{declare} to suppress warnings about unavoidable problems.
911 @c _%%\node The Optimize-Interface Declaration, , The Optimize Declaration, Compiler Policy
912 @c _\subsection{The Optimize-Interface Declaration}
913 @c _\label{optimize-interface-declaration}
914 @c _\cindex{optimize-interface declaration}
915 @c _\cpsubindex{declarations}{\code{optimize-interface}}
917 @c _The \code{extensions:optimize-interface} declaration is identical in
918 @c _syntax to the \code{optimize} declaration, but it specifies the policy
919 @c _used during compilation of code the compiler automatically generates
920 @c _to check the number and type of arguments supplied to a function. It
921 @c _is useful to specify this policy separately, since even thoroughly
922 @c _debugged functions are vulnerable to being passed the wrong arguments.
923 @c _The \code{optimize-interface} declaration can specify that arguments
924 @c _should be checked even when the general \code{optimize} policy is
927 @c _Note that this argument checking is the checking of user-supplied
928 @c _arguments to any functions defined within the scope of the
929 @c _declaration, \code{not} the checking of arguments to \llisp{}
930 @c _primitives that appear in those definitions.
932 @c _The idea behind this declaration is that it allows the definition of
933 @c _functions that appear fully safe to other callers, but that do no
934 @c _internal error checking. Of course, it is possible that arguments may
935 @c _be invalid in ways other than having incorrect type. Functions
936 @c _compiled unsafely must still protect themselves against things like
937 @c _user-supplied array indices that are out of bounds and improper lists.
938 @c _See also the \kwd{context-declarations} option to
939 @c _\macref{with-compilation-unit}.
941 @c _(end of section on compiler policy)
945 @node Open Coding and Inline Expansion, , Compiler Policy, The Compiler
946 @comment node-name, next, previous, up
947 @section Open Coding and Inline Expansion
949 @cindex inline expansion
950 @cindex static functions
952 Since Common Lisp forbids the redefinition of standard functions, the
953 compiler can have special knowledge of these standard functions
954 embedded in it. This special knowledge is used in various ways (open
955 coding, inline expansion, source transformation), but the implications
956 to the user are basically the same:
961 Attempts to redefine standard functions may be frustrated, since the
962 function may never be called. Although it is technically illegal to
963 redefine standard functions, users sometimes want to implicitly
964 redefine these functions when they are debugging using the
965 @code{trace} macro. Special-casing of standard functions can be
966 inhibited using the @code{notinline} declaration.
969 The compiler can have multiple alternate implementations of standard
970 functions that implement different trade-offs of speed, space and
971 safety. This selection is based on the compiler policy, @ref{Compiler
976 When a function call is @emph{open coded}, inline code whose effect is
977 equivalent to the function call is substituted for that function
978 call. When a function call is @emph{closed coded}, it is usually left
979 as is, although it might be turned into a call to a different function
980 with different arguments. As an example, if @code{nthcdr} were to be
990 (cdr (cdr (cdr (cdr foobar))))
997 (list foobar (cdr foobar)))
1001 If @code{nth} is closed coded, then
1007 might stay the same, or turn into something like
1013 In general, open coding sacrifices space for speed, but some functions
1014 (such as @code{car}) are so simple that they are always
1015 open-coded. Even when not open-coded, a call to a standard function
1016 may be transformed into a different function call (as in the last
1017 example) or compiled as @emph{static call}. Static function call uses
1018 a more efficient calling convention that forbids redefinition.