X-Git-Url: http://repo.macrolet.net/gitweb/?a=blobdiff_plain;f=doc%2Fmanual%2Fcompiler.texinfo;h=f90f97251f86933d8d09f19bcd3b10c617a3e528;hb=26d0559df82a00acf85b8ec89541ee8e09bb3e55;hp=729865fb7eb7bf6c086cbdeb51947cfc49402370;hpb=58ef9d8996d4421610101b52e5a25fd2c70c4792;p=sbcl.git

diff --git a/doc/manual/compiler.texinfo b/doc/manual/compiler.texinfo
index 729865f..f90f972 100644
--- a/doc/manual/compiler.texinfo
+++ b/doc/manual/compiler.texinfo
@@ -16,6 +16,7 @@ separate that they have their own chapter, @ref{Efficiency}.
 * Compiler Policy::             
 * Compiler Errors::             
 * Open Coding and Inline Expansion::  
+* Interpreter::
 @end menu
 
 @node  Diagnostic Messages
@@ -63,17 +64,17 @@ Local control:
       (* x -5))))
 @end lisp
 
-@deffn {Declaration} sb-ext:muffle-conditions
+@deffn {Declaration} @sbext{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
+@deffn {Declaration} @sbext{unmuffle-conditions}
 Syntax: type*
 
-Cancels the effect of a previous @code{sb-ext:muffle-condition}
+Cancels the effect of a previous @code{sb-ext:muffle-conditions}
 declaration.
 @end deffn
 
@@ -83,6 +84,9 @@ controlled via the alist
 
 @include var-sb-ext-star-compiler-print-variable-alist-star.texinfo
 
+For information about muffling warnings signaled outside of the
+compiler, see @ref{Customization Hooks for Users}.
+
 @c <!-- FIXME: How much control over error messages is in SBCL?
 @c      _     How much should be? How much of this documentation should
 @c      _     we save or adapt? 
@@ -126,11 +130,11 @@ controlled via the alist
 @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
+@tindex @cl{error}
+@tindex @cl{warning}
+@tindex @cl{style-warning}
+@tindex @sbext{compiler-note}
+@tindex @sbext{code-deletion-note}
 
 There are four levels of compiler diagnostic severity: 
 
@@ -152,8 +156,8 @@ 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.
+deletes user-supplied code 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.
@@ -213,7 +217,7 @@ diagnostic:
 @enumerate
 
 @item
-@findex with-compilation-unit
+@findex @cl{with-compilation-unit}
 @samp{file: /tmp/foo.lisp} This is the name of the file that the
 compiler read the relevant code from.  The file name is displayed
 because it may not be immediately obvious when there is an error
@@ -452,11 +456,10 @@ one level.
 @comment  node-name,  next,  previous,  up
 @section 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.
+One of the most important features of the SBCL compiler (similar to
+the original CMUCL compiler, also known as @dfn{Python}) is its fairly
+sophisticated understanding of the Common Lisp type system and its
+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
@@ -464,7 +467,7 @@ discussed in the chapter on performance (@pxref{Efficiency}), the use
 of appropriate type declarations can be very important for performance
 as well.
 
-@findex satisfies
+@findex @cl{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.
@@ -487,23 +490,30 @@ involving the @code{satisfies} type specifier.
 @node Declarations as Assertions
 @comment  node-name,  next,  previous,  up
 @subsection Declarations as Assertions
-@findex safety
+@cindex Safety optimization quality
 
-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.
+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}).}
+Limitations}.}
 @end quotation
 
-There are three type checking policies available in SBCL,
-selectable via @code{optimize} declarations.
+CLOS slot types form a notable exception. Types declared using the
+@code{:type} slot option in @code{defclass} are asserted if and only
+if the class was defined in @emph{safe code} and the slot access
+location is in @emph{safe code} as well. This laxness does not pose
+any internal consistency issues, as the CLOS slot types are not
+available for the type inferencer, nor do CLOS slot types provide any
+efficiency benefits.
+
+There are three type checking policies available in SBCL, selectable
+via @code{optimize} declarations.
 
 @table @strong
 
@@ -512,21 +522,28 @@ selectable via @code{optimize} declarations.
 
 @item Full Type Checks
 All declarations are considered assertions to be checked at runtime,
-and all type checks are precise.
+and all type checks are precise. The default compilation policy
+provides full type checks.
 
-Used when @code{(>= safety (max speed space compilation-speed)}. The
-default compilation policy provides full type checks.
+Used when @code{(or (>= safety 2) (>= safety speed 1))}.
 
 @item Weak Type Checks
-Any or all type declarations may be believed without runtime
-assertions, and assertions that are done may be imprecise.
+Declared types may be simplified into faster to check supertypes: for
+example, @code{(or (integer -17 -7) (integer 7 17))} is simplified
+into @code{(integer -17 17)}.
 
-Used when @code{(< 0 safety (max speed space compilation-speed)}.
+@strong{Note}: it is relatively easy to corrupt the heap when weak
+type checks are used if the program contains type-errors.
+
+Used when @code{(and (< safety 2) (< safety speed))}
 
 @item No Type Checks
 All declarations are believed without assertions. Also disables
 argument count and array bounds checking.
 
+@strong{Note}: any type errors in code where type checks are not
+performed are liable to corrupt the heap.
+
 Used when @code{(= safety 0)}.
 
 @end table
@@ -907,6 +924,10 @@ is to slow the program by causing cache misses or even swapping.
 @c      _(end of section on compiler policy)
 @c      _-->
 
+@include fun-sb-ext-describe-compiler-policy.texinfo
+@include fun-sb-ext-restrict-compiler-policy.texinfo
+@include macro-common-lisp-with-compilation-unit.texinfo
+
 @node Compiler Errors
 @comment  node-name,  next,  previous,  up
 @section Compiler Errors
@@ -1088,3 +1109,20 @@ 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.
+
+@node  Interpreter
+@comment  node-name,  next,  previous,  up
+@section Interpreter
+@cindex Interpreter
+@vindex @sbext{@earmuffs{evaluator-mode}}
+
+By default SBCL implements @code{eval} by calling the native code
+compiler. SBCL also includes an interpreter for use in special cases
+where using the compiler is undesirable, for example due to compilation
+overhead. Unlike in some other Lisp implementations, in SBCL interpreted
+code is not safer or more debuggable than compiled code.
+
+Switching between the compiler and the interpreter is done using the
+special variable @code{sb-ext:*evaluator-mode*}. As of 0.9.17, valid
+values for @code{sb-ext:*evaluator-mode*} are @code{:compile} and
+@code{:interpret}.