X-Git-Url: http://repo.macrolet.net/gitweb/?a=blobdiff_plain;f=doc%2Fcompiler.sgml;h=131508b9ff3b892e482018641cd70f3a32ad11d0;hb=14d8510d30b5ee723ad9c2d89ff907ec38923e51;hp=9fc61a226a9777fe9f0a27cabccd72cf47a8266d;hpb=5ec8d0c1c8b7939818b75118b472fac1af554f9a;p=sbcl.git
diff --git a/doc/compiler.sgml b/doc/compiler.sgml
index 9fc61a2..131508b 100644
--- a/doc/compiler.sgml
+++ b/doc/compiler.sgml
@@ -274,10 +274,10 @@ gives this error:
in: DEFUN FOO
(DO ((CURRENT L #) (# NIL)) (WHEN (EQ # E) (RETURN CURRENT)) )
-caught ERROR: (during macroexpansion)
-
-error in function LISP::DO-DO-BODY:
- DO step variable is not a symbol: (ATOM 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)
@@ -323,7 +323,7 @@ _ \code{3}. If null, the global values of \code{*print-level*} and
_ \code{*print-length*} are used.
_ \end{defvar}
_
-_ \begin{defmac}{extensions:}{def-source-context}{%
+_ \begin{defmac}{extensions:}{define-source-context}{%
_ \args{\var{name} \var{lambda-list} \mstar{form}}}
_
_ This macro defines how to extract an abbreviated source context from
@@ -376,11 +376,19 @@ types.
Ideally, the compiler would consider all> type declarations to
be assertions, so that adding type declarations to a program, no
matter how incorrect they might be, would never> cause
-undefined behavior. As of &SBCL; version 0.6.4, the compiler is known to
+undefined behavior. As of &SBCL; version 0.8.1, the compiler is known to
fall short of this goal in two areas:
- The compiler trusts function return values which
- have been established with proclaim>.
+ Proclaim>ed 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, in which case the compiler
+ will trust the declaration.
+ 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.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
@@ -439,44 +447,39 @@ an error if it is executed) and gives a warning.
Type warnings are inhibited when the
-extensions:inhibit-warnings> optimization quality is
-3>. (See the section
+sb-ext:inhibit-warnings> optimization quality is
+3>. (See the section
on compiler policy>.) This can be used in a local declaration
to inhibit type warnings in a code fragment that has spurious
warnings.
-Precise Type Checking>
+Precise Type Checking>
With the default compilation policy, all type declarations are
-precisely checked, except in a few situations (such as using
-the> to constrain the argument type passed to a function)
-where they are simply ignored instead. Precise checking means that the
-check is done as though typep> had been called with the
-exact type specifier that appeared in the declaration. In &SBCL;,
-adding type declarations makes code safer. (Except that as noted elsewhere, remaining bugs in
-the compiler's handling of types unfortunately provide some exceptions to
-this rule.)
+precisely checked, except in a few situations where they are simply
+ignored instead. Precise checking means that the check is done as
+though typep> had been called with the exact type
+specifier that appeared in the declaration. In &SBCL;, adding type
+declarations makes code safer. (Except that as noted elsewhere, remaining bugs
+in the compiler's handling of types unfortunately provide some
+exceptions to this rule.)
If a variable is declared to be
-(integer 3 17)>
-then its
-value must always always be an integer between 3>
-and 17>.
-If multiple 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 and> type specifier.
-
-Argument 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, which means that a more restrictive type
-assertion in the calling function (e.g., from the>) may be
-lost.
+(integer 3 17)> then its value must always be an integer
+between 3> and 17>. If multiple 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 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
@@ -509,84 +512,14 @@ slots as precisely as possible. This often involves the use of
weakened type checking>, when the value for the
speed> optimization quality is greater than
safety>, and safety> is not 0>.
-The &CMUCL; manual still has a description of it, but the code no
-longer corresponds to the manual. It sounds like a good thing to have,
-and we might someday be able to restore it in &SBCL; but in the
-meantime, if you ask the compiler to optimize speed> to a
-higher level than safety>, your program is performing
-without a safety net, because &SBCL; may believe any or all type
-declarations without any runtime checking at all.
-
-
+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
+speed> to a higher level than 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.
@@ -596,20 +529,21 @@ _ features it would be nice for SBCL to restore someday) -->
-Since &SBCL;'s compiler does much more comprehensive type
-checking than other Lisp compilers, &SBCL; will detect type errors in
-many programs that have been debugged using other compilers. These
-errors are mostly incorrect declarations, although compile-time type
-errors can find actual bugs if parts of the program have never been
-tested.
+Since &SBCL;'s compiler, like &CMUCL;'s compiler, does much more
+comprehensive type checking than most Lisp compilers, &SBCL; may
+detect type errors in programs that have been debugged using other
+compilers. These errors are mostly incorrect declarations, although
+compile-time type errors can find actual bugs if parts of the program
+have never been tested.Some incorrect declarations can only be detected by run-time
-type checking. It is very important to initially compile programs with
-full type checks and then test this version. After the checking
-version has been tested, then you can consider weakening or
-eliminating type checks. This applies even to previously
-debugged programs, because the &SBCL; compiler does much
-more type inference than other &CommonLisp; compilers, so an incorrect
+type checking. It is very important to initially compile a program
+with full type checks (high safety> optimization) and
+then test this safe version. After the checking version has been
+tested, then you can consider weakening or eliminating type checks.
+This applies even to previously debugged
+programs, because the &SBCL; compiler does much more type
+inference than other &CommonLisp; compilers, so an incorrect
declaration can do more damage.The most common problem is with variables whose constant initial
@@ -670,9 +604,7 @@ type of the result of evaluating a macro argument, then put a
`(the fixnum (1+ (the fixnum ,x))))
In this case, it would be stylistically preferable to change this
-macro back to a function and declare it inline. Macros have no
-efficiency advantage over inline functions when using the
-&SBCL; compiler.
+macro back to a function and declare it inline.
@@ -704,15 +636,15 @@ compiled using other compilers.
In this case, the fix is to weaken the type declaration to
(or fixnum null)>.
-Actually, this declaration is unnecessary
- unnecessary in &SBCL;, since it already knows position>
+Actually, this declaration is
+ unnecessary in &SBCL;, since it already knows that position>
returns a non-negative fixnum> or nil>.
Note that there is usually little performance penalty for weakening a
-declaration in this way. Any numeric operations in the body can still
-assume the variable is a fixnum>, since nil> is not a legal
-numeric argument. Another possible fix would be to say:
+declaration in this way. Any numeric operations in the body can still
+assume that the variable is a fixnum>, since nil>
+is not a legal numeric argument. Another possible fix would be to say:
(do ((pos 0 (position #\a string :start (1+ pos))))
((null pos))
@@ -727,10 +659,6 @@ variable in the loop body.
CMU CL manual. -->
-In summary, remember that all> values that a variable
-ever> has must be of the declared type, and that you
-should test using safe compilation options initially.
-
@@ -738,7 +666,7 @@ should test using safe compilation options initially.
Compiler Policy>
As of version 0.6.4, &SBCL; still uses most of the &CMUCL; code
-for compiler policy. Thi &CMUCL; code has many features and high-quality
+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
@@ -756,8 +684,8 @@ the 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 useful for code which truly can't guarantee that its arguments
-will always be fixnums.)
+is not helpful for code which by design supports arbitrary-sized
+integers instead of being limited to fixnums.)
The basic functionality of the optimize
inhibit-warnings> extension will probably be supported in all future
@@ -766,8 +694,8 @@ compiler and its interface are cleaned up. The current name is
misleading, because it mostly inhibits optimization notes, not
warnings. And making it an optimization quality is misleading, because
it shouldn't affect the resulting code at all. It may become a
-declaration identifier with a name like SB-EXT:INHIBIT-NOTES, so that
-what's currently written
+declaration identifier with a name like
+sb-ext:inhibit-notes>, so that what's currently written
(declaim (optimize (sb-ext:inhibit-warnings 2)))>
@@ -787,16 +715,16 @@ of types, array bounds, and so forth is suppressed.When safety> is less than speed>, any
and all type checks may be suppressed. At some point in the past,
&CMUCL; had a more nuanced
-interpretation of this. At some point in the future, &SBCL; may
-restore that interpretation, or something like it. Until then, setting
-safety> less than speed> may have roughly
-the same effect as setting safety> to zero.
+interpretation of this. However, &SBCL; doesn't support that
+interpretation, and setting safety> less than
+speed> may have roughly the same effect as setting
+safety> to zero.
The value of space> mostly influences the
compiler's decision whether to inline operations, which tend to
increase the size of programs. Use the value 0> with
caution, since it can cause the compiler to inline operations so
-promiscuously that the net effect is to slow the program by causing
+indiscriminately that the net effect is to slow the program by causing
cache misses or swapping.