From 2a4fabe1541b905591fbd6b83122209df6a48fab Mon Sep 17 00:00:00 2001 From: Nikodemus Siivola Date: Tue, 17 Aug 2004 18:34:27 +0000 Subject: [PATCH] 0.8.13.71: CORRECT DOCUMENTATION * Slightly less, but hopefully more representative of reality, documentation for type checking policies. * Generally reorganize the Compiler chapter a bit, moving and renaming some sections -- eg. split "Compiler Errors" --> "Compiler Diagnostics" and "Compiler Errors". * Back out a bogus lifting of chapter @nodes into sbcl.texinfo which leaked in accidentally. * Remove references to INHIBIT-WARNINGS, leaving only a footnote. --- contrib/sb-bsd-sockets/sb-bsd-sockets.texinfo | 6 +- doc/manual/beyond-ansi.texinfo | 4 + doc/manual/compiler.texinfo | 790 ++++++++++++++----------- doc/manual/contrib-modules.texinfo | 4 + doc/manual/debugger.texinfo | 3 + doc/manual/efficiency.texinfo | 3 + doc/manual/ffi.texinfo | 4 + doc/manual/intro.texinfo | 4 + doc/manual/package-locks-basic.texinfo | 4 + doc/manual/package-locks-extended.texinfo | 15 +- doc/manual/profiling.texinfo | 3 + doc/manual/sbcl.texinfo | 79 +-- doc/manual/streams.texinfo | 8 +- version.lisp-expr | 2 +- 14 files changed, 478 insertions(+), 451 deletions(-) diff --git a/contrib/sb-bsd-sockets/sb-bsd-sockets.texinfo b/contrib/sb-bsd-sockets/sb-bsd-sockets.texinfo index ab8fdd4..730f55a 100644 --- a/contrib/sb-bsd-sockets/sb-bsd-sockets.texinfo +++ b/contrib/sb-bsd-sockets/sb-bsd-sockets.texinfo @@ -1,6 +1,6 @@ -@c This currently appears in the manual as a chapter: if a -@c higher-level interface appear, it will make sense to lower this -@c into a section. +@node Networking +@comment node-name, next, previous, up +@chapter Networking @cindex Sockets, Networking The @code{sb-bsd-sockets} module provides a thinly disguised BSD diff --git a/doc/manual/beyond-ansi.texinfo b/doc/manual/beyond-ansi.texinfo index 848fb48..17d32e9 100644 --- a/doc/manual/beyond-ansi.texinfo +++ b/doc/manual/beyond-ansi.texinfo @@ -1,3 +1,7 @@ +@node Beyond the ANSI Standard +@comment node-name, next, previous, up +@chapter Beyond the ANSI Standard + SBCL is mostly an implementation of the ANSI standard for Common Lisp. However, there's some important behavior which extends or clarifies the standard, and various behavior which outright diff --git a/doc/manual/compiler.texinfo b/doc/manual/compiler.texinfo index b1062b5..ee242f4 100644 --- a/doc/manual/compiler.texinfo +++ b/doc/manual/compiler.texinfo @@ -1,27 +1,177 @@ -This chapter will discuss most compiler issues other than -efficiency, including compiler error messages, the SBCL compiler's -unusual approach to type safety in the presence of type declarations, -the effects of various compiler optimization policies, and the way -that inlining and open coding may cause optimized code to differ from -a naive translation. Efficiency issues are sufficiently varied and +@node Compiler +@comment node-name, next, previous, up +@chapter Compiler + +This chapter will discuss most compiler issues other than efficiency, +including compiler error messages, the SBCL compiler's unusual +approach to type safety in the presence of type declarations, the +effects of various compiler optimization policies, and the way that +inlining and open coding may cause optimized code to differ from a +naive translation. Efficiency issues are sufficiently varied and separate that they have their own chapter, @ref{Efficiency}. @menu -* Error Messages:: +* Diagnostic Messages:: * Handling of Types:: * Compiler Policy:: +* Compiler Errors:: * Open Coding and Inline Expansion:: @end menu -@node Error Messages +@node Diagnostic Messages +@comment node-name, next, previous, up +@section Diagnostic Messages +@cindex Messages, Compiler +@cindex Compiler messages + +@menu +* Controlling Verbosity:: +* Diagnostic Severity:: +* Understanding Compiler Diagnostics:: +@end menu + +@node Controlling Verbosity +@comment node-name, next, previous, up +@subsection Controlling Verbosity + +The compiler can be quite verbose in its diagnostic reporting, rather +more then some users would prefer -- the amount of noise emitted can +be controlled, however. + +To control emission of compiler diagnostics (of any severity other +than @code{error}: @pxref{Diagnostic Severity}) use the +@code{sb-ext:muffle-conditions} and @code{sb-ext:unmuffle-conditions} +declarations, specifying the type of condition that is to be muffled +(the muffling is done using an associated @code{muffle-warning} restart). + +Global control: +@lisp +;;; Muffle compiler-notes globally +(declaim (sb-ext:muffle-conditions sb-ext:compiler-note)) +@end lisp + +Local control: +@lisp +;;; Muffle compiler-notes based on lexical scope +(defun foo (x) + (declare (optimize speed) (fixnum x) + (sb-ext:muffle-conditions sb-ext:compiler-note)) + (values (* x 5) ; no compiler note from this + (locally + (declare (sb-ext:unmuffle-conditions sb-ext:compiler-note)) + ;; this one gives a compiler note + (* x -5)))) +@end lisp + +@deffn {Declaration} sb-ext:muffle-conditions +Syntax: type* + +Muffles the diagnostic messages that would be caused by compile-time +signals of given types. +@end deffn + +@deffn {Declaration} sb-ext:unmuffle-conditions +Syntax: type* + +Cancels the effect of a previous @code{sb-ext:muffle-condition} +declaration. +@end deffn + +@c + + +@node Diagnostic Severity +@comment node-name, next, previous, up +@subsection Diagnostic Severity +@cindex Severity of compiler messages +@cindex compiler diagnostic severity +@tindex error +@tindex warning +@tindex style-warning +@tindex compiler-note +@tindex code-deletion-note + +There are four levels of compiler diagnostic severity: + +@enumerate 1 +@item error +@item warning +@item style warning +@item note +@end enumerate + +The first three levels correspond to condition classes which are +defined in the ANSI standard for Common Lisp and which have special +significance to the @code{compile} and @code{compile-file} functions. +These levels of compiler error severity occur when the compiler +handles conditions of these classes. + +The fourth level of compiler error severity, @emph{note}, corresponds +to the @code{sb-ext:compiler-note}, and is used for problems which are +too mild for the standard condition classes, typically hints about how +efficiency might be improved. The @code{sb-ext:code-deletion-note}, a +subtype of @code{compiler-note}, is signalled when the compiler +deletes user-supplied code, usually after proving that the code in +question is unreachable. + +Future work for SBCL includes expanding this hierarchy of types to +allow more fine-grained control over emission of diagnostic messages. + +@include condition-sb-ext-compiler-note.texinfo +@include condition-sb-ext-code-deletion-note.texinfo + + +@node Understanding Compiler Diagnostics @comment node-name, next, previous, up -@section Error Messages -@cindex Error messages, Compiler -@cindex Compiler error messages +@subsection Understanding Compile Diagnostics -The compiler supplies a large amount of source location information in -error messages. The error messages contain a lot of detail in a terse -format, so they may be confusing at first. Error messages will be +The messages emitted by the compiler contain a lot of detail in a +terse format, so they may be confusing at first. The messages will be illustrated using this example program: @lisp @@ -37,18 +187,15 @@ The main problem with this program is that it is trying to add @code{3} to a symbol. Note also that the functions @code{roq} and @code{ploq} aren't defined anywhere. - @menu -* The Parts of the Error Message:: +* The Parts of a Compiler Diagnostic:: * The Original and Actual Source:: -* Error Severity:: -* Errors During Macroexpansion:: -* Read Errors:: +* The Processing Path:: @end menu -@node The Parts of the Error Message +@node The Parts of a Compiler Diagnostic @comment node-name, next, previous, up -@subsection The Parts of the Error Message +@subsubsection The Parts of a Compiler Diagnostic When processing this program, the compiler will produce this warning: @@ -65,7 +212,7 @@ When processing this program, the compiler will produce this warning: @end example In this example we see each of the six possible parts of a compiler -error message: +diagnostic: @enumerate @@ -79,43 +226,43 @@ during compilation of a large system, especially when @item @samp{in: DEFUN FOO} This is the definition top level form responsible -for the error. It is obtained by taking the first two elements of the -enclosing form whose first element is a symbol beginning with -``@samp{def}''. If there is no such enclosing ``@samp{def}'' form, -then the outermost form is used. If there are multiple @samp{def} +for the diagnostic. It is obtained by taking the first two elements of +the enclosing form whose first element is a symbol beginning with +``@samp{def}''. If there is no such enclosing ``@samp{def}'' form, +then the outermost form is used. If there are multiple @samp{def} forms, then they are all printed from the outside in, separated by -@samp{=>}'s. In this example, the problem was in the @code{defun} for +@samp{=>}'s. In this example, the problem was in the @code{defun} for @code{foo}. @item @cindex Original Source @samp{(ZOQ Y)} This is the @dfn{original source} form responsible for -the error. Original source means that the form directly appeared in -the original input to the compiler, i.e. in the lambda passed to +the diagnostic. Original source means that the form directly appeared +in the original input to the compiler, i.e. in the lambda passed to @code{compile} or in the top level form read from the source file. In this example, the expansion of the @code{zoq} macro was responsible -for the error. +for the message. @item @cindex Processing Path @samp{--> ROQ PLOQ} This is the @dfn{processing path} that the -compiler used to produce the errorful code. The processing path is a -representation of the evaluated forms enclosing the actual source that -the compiler encountered when processing the original source. The -path is the first element of each form, or the form itself if the form -is not a list. These forms result from the expansion of macros or -source-to-source transformation done by the compiler. In this -example, the enclosing evaluated forms are the calls to @code{roq} and -@code{ploq}. These calls resulted from the expansion of the -@code{zoq} macro. +compiler used to produce the code that caused the message to be +emitted. The processing path is a representation of the evaluated +forms enclosing the actual source that the compiler encountered when +processing the original source. The path is the first element of each +form, or the form itself if the form is not a list. These forms result +from the expansion of macros or source-to-source transformation done +by the compiler. In this example, the enclosing evaluated forms are +the calls to @code{roq} and @code{ploq}. These calls resulted from the +expansion of the @code{zoq} macro. @item @cindex Actual Source @samp{==> (+ Y 3)} This is the @dfn{actual source} responsible for the -error. If the actual source appears in the explanation, then we print -the next enclosing evaluated form, instead of printing the actual -source twice. (This is the form that would otherwise have been the -last form of the processing path.) In this example, the problem is +diagnostic. If the actual source appears in the explanation, then we +print the next enclosing evaluated form, instead of printing the +actual source twice. (This is the form that would otherwise have been +the last form of the processing path.) In this example, the problem is with the evaluation of the reference to the variable @code{y}. @item @@ -129,7 +276,7 @@ that @code{y} evaluates to precisely one value. @end enumerate -Note that each part of the error message is distinctively marked: +Note that each part of the message is distinctively marked: @itemize @@ -149,17 +296,16 @@ marked by a preceding @samp{==>} line. @comment no it isn't. @item -The explanation is prefixed with the error severity, which can be +The explanation is prefixed with the diagnostic severity, which can be @samp{caught ERROR:}, @samp{caught WARNING:}, @samp{caught STYLE-WARNING:}, or @samp{note:}. @end itemize -Each part of the error message is more specific than the preceding -one. If consecutive error messages are for nearby locations, then the -front part of the error messages would be the same. In this case, the -compiler omits as much of the second message as in common with the -first. For example: +Each part of the message is more specific than the preceding one. If +consecutive messages are for nearby locations, then the front part of +the messages would be the same. In this case, the compiler omits as +much of the second message as in common with the first. For example: @example ; file: /tmp/foo.lisp @@ -182,12 +328,12 @@ first. For example: In this example, the file, definition and original source are identical for the two messages, so the compiler omits them in the -second message. If consecutive messages are entirely identical, then +second message. If consecutive messages are entirely identical, then the compiler prints only the first message, followed by: @samp{[Last message occurs @var{repeats} times]} where @var{repeats} is the number of times the message was given. -If the source was not from a file, then no file line is printed. If +If the source was not from a file, then no file line is printed. If the actual source is the same as the original source, then the processing path and actual source will be omitted. If no forms intervene between the original source and the actual source, then the @@ -196,26 +342,26 @@ processing path will also be omitted. @node The Original and Actual Source @comment node-name, next, previous, up -@subsection The Original and Actual Source +@subsubsection The Original and Actual Source @cindex Original Source @cindex Actual Source The @emph{original source} displayed will almost always be a list. If -the actual source for an error message is a symbol, the original -source will be the immediately enclosing evaluated list form. So even -if the offending symbol does appear in the original source, the -compiler will print the enclosing list and then print the symbol as -the actual source (as though the symbol were introduced by a macro.) +the actual source for an message is a symbol, the original source will +be the immediately enclosing evaluated list form. So even if the +offending symbol does appear in the original source, the compiler will +print the enclosing list and then print the symbol as the actual +source (as though the symbol were introduced by a macro.) When the @emph{actual source} is displayed (and is not a symbol), it will always be code that resulted from the expansion of a macro or a -source-to-source compiler optimization. This is code that did not +source-to-source compiler optimization. This is code that did not appear in the original source program; it was introduced by the compiler. -Keep in mind that when the compiler displays a source form in an error -message, it always displays the most specific (innermost) responsible -form. For example, compiling this function +Keep in mind that when the compiler displays a source form in an +diagnostic message, it always displays the most specific (innermost) +responsible form. For example, compiling this function @lisp (defun bar (x) @@ -239,13 +385,14 @@ gives this error message ; Asserted type FIXNUM conflicts with derived type (VALUES NULL &OPTIONAL). @end example -This error message is not saying ``there is a problem somewhere in -this @code{let}'' -- it is saying that there is a problem with the +This message is not saying ``there is a problem somewhere in this +@code{let}'' -- it is saying that there is a problem with the @code{let} itself. In this example, the problem is that @code{a}'s @code{nil} initial value is not a @code{fixnum}. - -@subsection The Processing Path +@node The Processing Path +@comment node-name, next, previous, up +@subsubsection The Processing Path @cindex Processing path @cindex Macroexpansion @cindex Source-to-source transformation @@ -294,230 +441,99 @@ The rest of the processing path results from the expansion of @end lisp In this example, the compiler descended into the @code{block}, -@code{let}, @code{tagbody} and @code{return-from} to -reach the @code{progn} printed as the actual source. This is a -place where the ``actual source appears in explanation'' rule -was applied. The innermost actual source form was the symbol -@code{*undefined*} itself, but that also appeared in the -explanation, so the compiler backed out one level. - - -@node Error Severity -@comment node-name, next, previous, up -@subsection Error Severity -@cindex Severity of compiler errors -@cindex compiler error severity -@tindex error -@tindex warning -@tindex style-warning -@tindex compiler-note -@tindex code-deletion-note - -There are four levels of compiler error severity: @emph{error}, -@emph{warning}, @emph{style warning}, and @emph{note}. The first three -levels correspond to condition classes which are defined in the ANSI -standard for Common Lisp and which have special significance to the -@code{compile} and @code{compile-file} functions. These levels of -compiler error severity occur when the compiler handles conditions of -these classes. The fourth level of compiler error severity, -@emph{note}, corresponds to the @code{sb-ext:compiler-note}, and is -used for problems which are too mild for the standard condition -classes, typically hints about how efficiency might be improved. The -@code{sb-ext:code-deletion-note}, a subtype of @code{compiler-note}, -is signalled when the compiler deletes user-supplied code, usually -after proving that the code in question is unreachable. - -@include condition-sb-ext-compiler-note.texinfo -@include condition-sb-ext-code-deletion-note.texinfo - -@node Errors During Macroexpansion -@comment node-name, next, previous, up -@subsection Errors During Macroexpansion -@cindex Macroexpansion, errors during - -The compiler handles errors that happen during macroexpansion, turning -them into compiler errors. If you want to debug the error (to debug a -macro), you can set @code{*break-on-signals*} to @code{error}. For -example, this definition: - -@lisp -(defun foo (e l) - (do ((current l (cdr current)) - ((atom current) nil)) - (when (eq (car current) e) (return current)))) -@end lisp - -gives this error: - -@example -; in: DEFUN FOO -; (DO ((CURRENT L (CDR CURRENT)) -; ((ATOM CURRENT) NIL)) -; (WHEN (EQ (CAR CURRENT) E) (RETURN CURRENT))) -; -; caught ERROR: -; (in macroexpansion of (DO # #)) -; (hint: For more precise location, try *BREAK-ON-SIGNALS*.) -; DO step variable is not a symbol: (ATOM CURRENT) -@end example +@code{let}, @code{tagbody} and @code{return-from} to reach the +@code{progn} printed as the actual source. This is a place where the +``actual source appears in explanation'' rule was applied. The +innermost actual source form was the symbol @code{*undefined*} itself, +but that also appeared in the explanation, so the compiler backed out +one level. -@node Read Errors -@comment node-name, next, previous, up -@subsection Read Errors -@cindex Read errors, compiler -SBCL's compiler does not attempt to recover from read errors when -reading a source file, but instead just reports the offending -character position and gives up on the entire source file. - - -@c @node Handling of Types @comment node-name, next, previous, up -@section The Compiler's Handling of Types - -The most unusual features of the SBCL compiler (which is very similar -to the original CMUCL compiler, also known as @dfn{Python}) is its -unusually sophisticated understanding of the Common Lisp type system -and its unusually conservative approach to the implementation of type -declarations. These two features reward the use of type declarations -throughout development, even when high performance is not a -concern. Also, as discussed in the chapter on performance -(@pxref{Efficiency}), the use of appropriate type declarations can be -very important for performance as well. +@section Handling of Types -@findex safety -The SBCL compiler treats type declarations differently from most other -Lisp compilers. By default (@emph{i.e.}, at ordinary levels of the -@code{safety} compiler optimization parameter), the compiler doesn't -blindly believe most type declarations; it considers them assertions -about the program that should be checked. +The most unusual features of the SBCL compiler (which is very +similar to the original CMUCL compiler, also known as @dfn{Python}) +is its unusually sophisticated understanding of the Common Lisp type +system and its unusually conservative approach to the implementation +of type declarations. + +These two features reward the use of type declarations throughout +development, even when high performance is not a concern. Also, as +discussed in the chapter on performance (@pxref{Efficiency}), the use +of appropriate type declarations can be very important for performance +as well. @findex satisfies -The SBCL compiler also has a greater knowledge of the -Common Lisp type system than other compilers. Support is incomplete -only for types involving the @code{satisfies} type specifier. +The SBCL compiler also has a greater knowledge of the Common Lisp +type system than other compilers. Support is incomplete only for types +involving the @code{satisfies} type specifier. @c - +@c @c Also see my paper on improving Baker, when I get round to it. +@c +@c Whose paper? @menu -* Type Errors at Compile Time:: +* Declarations as Assertions:: * Precise Type Checking:: -* Weakened Type Checking:: * Getting Existing Programs to Run:: * Implementation Limitations:: @end menu - -@node Type Errors at Compile Time +@node Declarations as Assertions @comment node-name, next, previous, up -@subsection Type Errors at Compile Time -@cindex Compile time type errors -@cindex Type checking, at compile time +@subsection Declarations as Assertions +@findex safety -If the compiler can prove at compile time that some portion of the -program cannot be executed without a type error, then it will give a -warning at compile time. It is possible that the offending code would -never actually be executed at run-time due to some higher level -consistency constraint unknown to the compiler, so a type warning -doesn't always indicate an incorrect program. For example, consider -this code fragment: +The SBCL compiler treats type declarations differently from most +other Lisp compilers. Under default compilation policy the compiler +doesn't blindly believe type declarations, but considers them +assertions about the program that should be checked: all type +declarations that have not been proven to always hold are asserted at +runtime. +@quotation +@emph{Remaining bugs in the compiler's handling of types unfortunately +provide some exceptions to this rule, see @ref{Implementation +Limitations}).} +@end quotation -@lisp -(defun raz (foo) - (let ((x (case foo - (:this 13) - (:that 9) - (:the-other 42)))) - (declare (fixnum x)) - (foo x))) -@end lisp +There are three type checking policies available in SBCL, +selectable via @code{optimize} declarations. -Compilation produces this warning: +@table @strong -@example -; in: DEFUN RAZ -; (CASE FOO (:THIS 13) (:THAT 9) (:THE-OTHER 42)) -; --> LET COND IF COND IF COND IF -; ==> -; (COND) -; -; caught WARNING: -; This is not a FIXNUM: -; NIL -@end example +@c FIXME: This should be properly integrated with general policy +@c stuff, once that gets cleaned up. -In this case, the warning means that if @code{foo} isn't any of -@code{:this}, @code{:that} or @code{:the-other}, then @code{x} will be -initialized to @code{nil}, which the @code{fixnum} declaration makes -illegal. The warning will go away if @code{ecase} is used instead of -@code{case}, or if @code{:the-other} is changed to @code{t}. +@item Full Type Checks +All declarations are considered assertions to be checked at runtime, +and all type checks are precise. -This sort of spurious type warning happens moderately often in the -expansion of complex macros and in inline functions. In such cases, -there may be dead code that is impossible to correctly execute. The -compiler can't always prove this code is dead (could never be -executed), so it compiles the erroneous code (which will always signal -an error if it is executed) and gives a warning. +Used when @code{(>= safety (max speed space compilation-speed)}. The +default compilation policy provides full type checks. + +@item Weak Type Checks +Any or all type declarations may be believed without runtime +assertions, and assertions that are done may be imprecise. -Type warnings are inhibited when the @code{sb-ext:inhibit-warnings} -optimization quality is @code{3}. @xref{Compiler Policy}. This -can be used in a local declaration to inhibit type warnings in a code -fragment that has spurious warnings. +Used when @code{(> 0 safety (max speed space compilation-speed)}. +@item No Type Checks +All declarations are believed without assertions. Also disables +argument count and array bounds checking. + +Used when @code{(= safety 0)}. + +@end table @node Precise Type Checking @comment node-name, next, previous, up @@ -525,14 +541,9 @@ fragment that has spurious warnings. @cindex Precise type checking @cindex Type checking, precise -With the default compilation policy, all type declarations are -precisely checked, except in a few situations where they are simply -ignored instead. Precise checking means that the check is done as -though @code{typep} had been called with the exact type specifier that -appeared in the declaration. In SBCL, adding type declarations makes -code safer. (Except that remaining bugs in the compiler's handling of -types unfortunately provide some exceptions to this rule, see -@ref{Implementation Limitations}). +Precise checking means that the check is done as though @code{typep} +had been called with the exact type specifier that appeared in the +declaration. If a variable is declared to be @code{(integer 3 17)} then its value must always be an integer between @code{3} and @code{17}. If multiple @@ -540,50 +551,10 @@ type declarations apply to a single variable, then all the declarations must be correct; it is as though all the types were intersected producing a single @code{and} type specifier. -Argument and result type declarations are automatically enforced. If -you declare the type of a function argument, a type check will be done -when that function is called. In a function call, the called function -does the argument type checking. - -The types of structure slots are also checked. The value of a -structure slot must always be of the type indicated in any -@code{:type} slot option. - -In traditional Common Lisp compilers, not all type assertions are -checked, and type checks are not precise. Traditional compilers -blindly trust explicit type declarations, but may check the argument -type assertions for built-in functions. Type checking is not precise, -since the argument type checks will be for the most general type legal -for that argument. In many systems, type declarations suppress what -little type checking is being done, so adding type declarations makes -code unsafe. This is a problem since it discourages writing type -declarations during initial coding. In addition to being more error -prone, adding type declarations during tuning also loses all the -benefits of debugging with checked type assertions. - To gain maximum benefit from the compiler's type checking, you should always declare the types of function arguments and structure slots as precisely as possible. This often involves the use of @code{or}, -@code{member}, and other list-style type specifiers. - - -@node Weakened Type Checking -@comment node-name, next, previous, up -@subsection Weakened Type Checking -@cindex Weakened type checking -@cindex Type checking, weakened - -At one time, CMUCL supported another level of type checking, -``weakened type checking'', when the value for the @code{speed} -optimization quality is greater than @code{safety}, and @code{safety} -is not @code{0}. The CMUCL manual still has a description of it, but -even the CMU CL code no longer corresponds to the manual. Some of this -partial safety checking lingers on in SBCL, but it's not a supported -feature, and should not be relied on. If you ask the compiler to -optimize @code{speed} to a higher level than @code{safety}, your -program is performing without a safety net, because SBCL may at its -option believe any or all type declarations with either partial or -nonexistent runtime checking. +@code{member}, and other list-style type specifiers. @node Getting Existing Programs to Run @@ -735,17 +706,16 @@ variable in the loop body. @comment node-name, next, previous, up @subsection Implementation Limitations - Ideally, the compiler would consider @emph{all} type declarations to be assertions, so that adding type declarations to a program, no matter how incorrect they might be, would @emph{never} cause undefined -behavior. As of SBCL version 0.8.1, the compiler is known to fall -short of this goal in two areas: +behavior. However, the compiler is known to fall short of this goal in +two areas: - @itemize +@itemize @item -@code{Proclaim}ed constraints on argument and result types of a +@emph{Proclaimed} constraints on argument and result types of a function are supposed to be checked by the function. If the function type is proclaimed before function definition, type checks are inserted by the compiler, but the standard allows the reversed order, @@ -756,57 +726,66 @@ The compiler cannot check types of an unknown number of values; if the number of generated values is unknown, but the number of consumed is known, only consumed values are checked. -@item -There are a few poorly characterized but apparently very uncommon -situations where a type declaration in an unexpected location will be -trusted and never checked by the compiler. +For example, -@end itemize +@lisp +(defun foo (x) + (the integer (bar x))) +@end lisp + +causes the following compiler diagnostic to be emitted: + +@example +; note: type assertion too complex to check: +; (VALUES INTEGER &REST T). +@end example + +A partial workaround is instead write: + +@lisp +(defun foo (x) + (the (values integer &optional) (bar x))) +@end lisp -These are important bugs, but are not necessarily easy to fix, so they -may, alas, remain in the system for a while. +@end itemize +These are important issues, but are not necessarily easy to fix, so +they may, alas, remain in the system for a while. @node Compiler Policy @comment node-name, next, previous, up @section Compiler Policy -As of version 0.6.4, SBCL still uses most of the CMUCL code for -compiler policy. The CMUCL code has many features and high-quality -documentation, but the two unfortunately do not match. So this area of -the compiler and its interface needs to be cleaned up. Meanwhile, here -is some rudimentary documentation on the current behavior of the -system. +Compiler policy is controlled by the @code{optimize} declaration, +supporting all ANSI optimization qualities (@code{debug}, +@code{safety}, @code{space}, and @code{speed}).@footnote{A deprecated +extension @code{sb-ext:inhibit-warnings} is still supported, but +liable to go away at any time.} -Compiler policy is controlled by the @code{optimize} declaration. The -compiler supports the ANSI optimization qualities, and also a -deprecated extension @code{sb-ext:inhibit-warnings}. +For effects of various optimization qualities on type-safety and +debuggability see @ref{Declarations as Assertions} and @ref{Debugger +Policy Control}. Ordinarily, when the @code{speed} quality is high, the compiler emits notes to notify the programmer about its inability to apply various -optimizations. Setting @code{sb-ext:inhibit-warnings} to a value at -least as large as the @code{speed} quality inhibits this -notification. This can be useful to suppress notes about code which is -known to be unavoidably inefficient. (For example, the compiler issues -notes about having to use generic arithmetic instead of fixnum -arithmetic, which is not helpful for code which by design supports -arbitrary-sized integers instead of being limited to fixnums.) - -The recommended way to inhibit compiler diagnostics (of any severity -other than @code{error}: @pxref{Error Severity}) is to use the +optimizations. + +Compiler diagnostics (of any severity other than @code{error}: +@pxref{Diagnostic Severity}) can be silenced by using the @code{sb-ext:muffle-conditions} declaration, specifying the type of condition that is to be muffled (using an associated -@code{muffle-warning} restart). Thus, what was previously written -@lisp -(declaim (optimize (sb-ext:inhibit-warnings 2))) -@end lisp -becomes something like +@code{muffle-warning} restart). + +To muffle all compiler notes: + @lisp (declaim (sb-ext:muffle-conditions sb-ext:compiler-note)) @end lisp -to muffle all compiler notes. Compiler diagnostics can be muffled in -the lexical scope of a declaration, and also lexically unmuffled by -the use of the sb-ext:unmuffle-conditions, for instance + +Compiler diagnostics can also be muffled in the lexical scope of a +declaration, and also lexically unmuffled by the use of the +sb-ext:unmuffle-conditions, for instance: + @lisp (defun foo (x) (declare (optimize speed) (fixnum x)) @@ -818,20 +797,6 @@ the use of the sb-ext:unmuffle-conditions, for instance (* x -5)))) @end lisp -In early versions of SBCL, a @code{speed} value of zero was used to -enable byte compilation, but since version 0.7.0, SBCL only supports -native compilation. - -When @code{safety} is zero, almost all runtime checking of types, -array bounds, and so forth is suppressed. - -When @code{safety} is less than @code{speed}, any and all type checks -may be suppressed. At some point in the past, CMUCL had a more nuanced -interpretation of this (@pxref{Weakened Type Checking}). However, SBCL -doesn't support that interpretation, and setting @code{safety} less -than @code{speed} may have roughly the same effect as setting -@code{safety} to zero. - The value of @code{space} mostly influences the compiler's decision whether to inline operations, which tend to increase the size of programs. Use the value @code{0} with caution, since it can cause the @@ -971,6 +936,110 @@ is to slow the program by causing cache misses or even swapping. @c _(end of section on compiler policy) @c _--> +@node Compiler Errors +@comment node-name, next, previous, up +@section Compiler Errors + +@menu +* Type Errors at Compile Time:: +* Errors During Macroexpansion:: +* Read Errors:: +@end menu + +@node Type Errors at Compile Time +@comment node-name, next, previous, up +@subsection Type Errors at Compile Time +@cindex Compile time type errors +@cindex Type checking, at compile time + +If the compiler can prove at compile time that some portion of the +program cannot be executed without a type error, then it will give a +warning at compile time. + +It is possible that the offending code would never actually be +executed at run-time due to some higher level consistency constraint +unknown to the compiler, so a type warning doesn't always indicate an +incorrect program. + +For example, consider this code fragment: + +@lisp +(defun raz (foo) + (let ((x (case foo + (:this 13) + (:that 9) + (:the-other 42)))) + (declare (fixnum x)) + (foo x))) +@end lisp + +Compilation produces this warning: + +@example +; in: DEFUN RAZ +; (CASE FOO (:THIS 13) (:THAT 9) (:THE-OTHER 42)) +; --> LET COND IF COND IF COND IF +; ==> +; (COND) +; +; caught WARNING: +; This is not a FIXNUM: +; NIL +@end example + +In this case, the warning means that if @code{foo} isn't any of +@code{:this}, @code{:that} or @code{:the-other}, then @code{x} will be +initialized to @code{nil}, which the @code{fixnum} declaration makes +illegal. The warning will go away if @code{ecase} is used instead of +@code{case}, or if @code{:the-other} is changed to @code{t}. + +This sort of spurious type warning happens moderately often in the +expansion of complex macros and in inline functions. In such cases, +there may be dead code that is impossible to correctly execute. The +compiler can't always prove this code is dead (could never be +executed), so it compiles the erroneous code (which will always signal +an error if it is executed) and gives a warning. + +@node Errors During Macroexpansion +@comment node-name, next, previous, up +@subsection Errors During Macroexpansion +@cindex Macroexpansion, errors during + +The compiler handles errors that happen during macroexpansion, turning +them into compiler errors. If you want to debug the error (to debug a +macro), you can set @code{*break-on-signals*} to @code{error}. For +example, this definition: + +@lisp +(defun foo (e l) + (do ((current l (cdr current)) + ((atom current) nil)) + (when (eq (car current) e) (return current)))) +@end lisp + +gives this error: + +@example +; in: DEFUN FOO +; (DO ((CURRENT L (CDR CURRENT)) +; ((ATOM CURRENT) NIL)) +; (WHEN (EQ (CAR CURRENT) E) (RETURN CURRENT))) +; +; caught ERROR: +; (in macroexpansion of (DO # #)) +; (hint: For more precise location, try *BREAK-ON-SIGNALS*.) +; DO step variable is not a symbol: (ATOM CURRENT) +@end example + + +@node Read Errors +@comment node-name, next, previous, up +@subsection Read Errors +@cindex Read errors, compiler + +SBCL's compiler does not attempt to recover from read errors when +reading a source file, but instead just reports the offending +character position and gives up on the entire source file. @node Open Coding and Inline Expansion @comment node-name, next, previous, up @@ -1048,4 +1117,3 @@ open-coded. Even when not open-coded, a call to a standard function may be transformed into a different function call (as in the last example) or compiled as @emph{static call}. Static function call uses a more efficient calling convention that forbids redefinition. - diff --git a/doc/manual/contrib-modules.texinfo b/doc/manual/contrib-modules.texinfo index 35fba4b..a9460ed 100644 --- a/doc/manual/contrib-modules.texinfo +++ b/doc/manual/contrib-modules.texinfo @@ -1,3 +1,7 @@ +@node Contributed Modules +@comment node-name, next, previous, up +@chapter Contributed Modules + SBCL comes with a number of modules that are not part of the core system. These are loaded via @code{(require :@var{modulename})} (@pxref{Customization Hooks for Users}). This section contains diff --git a/doc/manual/debugger.texinfo b/doc/manual/debugger.texinfo index 86f6ad2..8f6cdf5 100644 --- a/doc/manual/debugger.texinfo +++ b/doc/manual/debugger.texinfo @@ -1,3 +1,6 @@ +@node Debugger +@comment node-name, next, previous, up +@chapter Debugger @cindex Debugger The SBCL debugger (as the CMUCL debugger it was derived from) has very diff --git a/doc/manual/efficiency.texinfo b/doc/manual/efficiency.texinfo index ebd4a36..4643f90 100644 --- a/doc/manual/efficiency.texinfo +++ b/doc/manual/efficiency.texinfo @@ -1,3 +1,6 @@ +@node Efficiency +@comment node-name, next, previous, up +@chapter Efficiency @cindex Efficiency FIXME: The material in the CMUCL manual about getting good diff --git a/doc/manual/ffi.texinfo b/doc/manual/ffi.texinfo index 5f365d9..5546ce6 100644 --- a/doc/manual/ffi.texinfo +++ b/doc/manual/ffi.texinfo @@ -1,3 +1,7 @@ +@node Foreign Function Interface +@comment node-name, next, previous, up +@chapter Foreign Function Interface + This chapter describes SBCL's interface to C programs and libraries (and, since C interfaces are a sort of @emph{ingua franca} of the Unix world, to other programs and libraries in diff --git a/doc/manual/intro.texinfo b/doc/manual/intro.texinfo index 2c1ed8b..6ad18eb 100644 --- a/doc/manual/intro.texinfo +++ b/doc/manual/intro.texinfo @@ -1,3 +1,7 @@ +@node Introduction +@comment node-name, next, previous, up +@chapter Introduction + SBCL is a mostly-conforming implementation of the ANSI Common Lisp standard. This manual focuses on behavior which is specific to SBCL, not on behavior which is common to all implementations of ANSI Common diff --git a/doc/manual/package-locks-basic.texinfo b/doc/manual/package-locks-basic.texinfo index 9470edc..a4740b6 100644 --- a/doc/manual/package-locks-basic.texinfo +++ b/doc/manual/package-locks-basic.texinfo @@ -1,3 +1,7 @@ +@node Package Locks +@comment node-name, next, previous, up +@chapter Package Locks + SBCL can be built with support for package locks to protect against unintentional modifications of packages. The full documentation for package locks is only built if package locks are enabled in the image diff --git a/doc/manual/package-locks-extended.texinfo b/doc/manual/package-locks-extended.texinfo index 18fdece..60f32fb 100644 --- a/doc/manual/package-locks-extended.texinfo +++ b/doc/manual/package-locks-extended.texinfo @@ -1,3 +1,6 @@ +@node Package Locks +@comment node-name, next, previous, up +@chapter Package Locks @cindex Packages, locked None of the following sections apply to SBCL built without package @@ -9,19 +12,19 @@ consept of implementation packages and the associated operators may be renamed. @menu -* Package Lock Concepts:: -* Package Lock Dictionary:: +* Package Lock Concepts:: +* Package Lock Dictionary:: @end menu @node Package Lock Concepts @section Package Lock Concepts @menu -* Package Lock Overview:: +* Package Lock Overview:: * Implementation Packages:: -* Package Lock Violations:: -* Package Locks in Compiled Code:: -* Operations Violating Package Locks:: +* Package Lock Violations:: +* Package Locks in Compiled Code:: +* Operations Violating Package Locks:: @end menu @node Package Lock Overview diff --git a/doc/manual/profiling.texinfo b/doc/manual/profiling.texinfo index d793d53..19c43de 100644 --- a/doc/manual/profiling.texinfo +++ b/doc/manual/profiling.texinfo @@ -1,3 +1,6 @@ +@node Profiling +@comment node-name, next, previous, up +@chapter Profiling @cindex Profiling SBCL includes both an accurate profiler, that can collect statistics diff --git a/doc/manual/sbcl.texinfo b/doc/manual/sbcl.texinfo index b144e8a..fecadc3 100644 --- a/doc/manual/sbcl.texinfo +++ b/doc/manual/sbcl.texinfo @@ -76,94 +76,17 @@ provided with absolutely no warranty. See the @file{COPYING} and @end ifnottex -@node Introduction -@comment node-name, next, previous, up -@chapter Introduction @include intro.texinfo - -@node Compiler -@comment node-name, next, previous, up -@chapter Compiler @include compiler.texinfo - -@node Debugger -@comment node-name, next, previous, up -@chapter Debugger @include debugger.texinfo - -@node Efficiency -@comment node-name, next, previous, up -@chapter Efficiency @include efficiency.texinfo - -@node Beyond the ANSI Standard -@comment node-name, next, previous, up -@chapter Beyond the ANSI Standard @include beyond-ansi.texinfo - -@node Foreign Function Interface -@comment node-name, next, previous, up -@chapter Foreign Function Interface @include ffi.texinfo - -@node Extensible Streams -@comment node-name, next, previous, up -@chapter Extensible Streams @include streams.texinfo - -@node Package Locks -@comment node-name, next, previous, up -@chapter Package Locks @include package-locks.texi-temp - -@node Networking -@comment node-name, next, previous, up -@chapter Networking @include sb-bsd-sockets/sb-bsd-sockets.texinfo - -@node Profiling -@comment node-name, next, previous, up -@chapter Profiling @include profiling.texinfo - -@node Contributed Modules -@comment node-name, next, previous, up -@chapter Contributed Modules @include contrib-modules.texinfo - -@node Concept Index -@comment node-name, next, previous, up -@appendix Concept Index -@printindex cp - -@node Function Index -@comment node-name, next, previous, up -@appendix Function Index -@printindex fn - -@node Variable Index -@comment node-name, next, previous, up -@appendix Variable Index -@printindex vr - -@node Type Index -@comment node-name, next, previous, up -@appendix Type Index -@printindex tp - -@node Colophon -@comment node-name, next, previous, up -@unnumbered Colophon - -This manual is maintained in Texinfo, and automatically translated -into other forms (e.g. HTML or pdf). If you're @emph{reading} this -manual in one of these non-Texinfo translated forms, that's fine, but -if you want to @emph{modify} this manual, you are strongly advised to -seek out a Texinfo version and modify that instead of modifying a -translated version. Even better might be to seek out @emph{the} -Texinfo version (maintained at the time of this writing as part of the -SBCL project at @uref{http://sbcl.sourceforge.net/}) and submit a -patch. - +@include backmatter.texinfo @bye diff --git a/doc/manual/streams.texinfo b/doc/manual/streams.texinfo index 1cd0595..8b16e90 100644 --- a/doc/manual/streams.texinfo +++ b/doc/manual/streams.texinfo @@ -1,3 +1,7 @@ +@node Extensible Streams +@comment node-name, next, previous, up +@chapter Extensible Streams + SBCL supports @dfn{Gray streams}, user-overloadable CLOS classes whose instances can be used as Lisp streams (e.g. passed as the first argument to @code{format}). Additionally, the bundled contrib module @@ -5,8 +9,8 @@ argument to @code{format}). Additionally, the bundled contrib module simple-streams proposal. @menu -* Gray Streams:: -* Simple Streams:: +* Gray Streams:: +* Simple Streams:: @end menu @node Gray Streams diff --git a/version.lisp-expr b/version.lisp-expr index 654d79c..12ccca0 100644 --- a/version.lisp-expr +++ b/version.lisp-expr @@ -17,4 +17,4 @@ ;;; checkins which aren't released. (And occasionally for internal ;;; versions, especially for internal versions off the main CVS ;;; branch, it gets hairier, e.g. "0.pre7.14.flaky4.13".) -"0.8.13.70" +"0.8.13.71" -- 1.7.10.4