fix Darwin/PPC build

[sbcl.git] / doc / manual / beyond-ansi.texinfo

diff --git a/doc/manual/beyond-ansi.texinfo b/doc/manual/beyond-ansi.texinfo
index 0f1b27a..08b942b 100644 (file)
--- a/doc/manual/beyond-ansi.texinfo
+++ b/doc/manual/beyond-ansi.texinfo
@@ -2,194 +2,349 @@
 @comment  node-name,  next,  previous,  up
 @chapter 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
-violates the standard.
-
+SBCL is derived from CMUCL, which implements many extensions to the
+ANSI standard. SBCL doesn't support as many extensions as CMUCL, but
+it still has quite a few.  @xref{Contributed Modules}.

 
 @menu
 
 @menu

-* Non-Conformance With The ANSI Standard::  
-* Idiosyncrasies::              
-* Extensions::                  
+* Garbage Collection::
+* Metaobject Protocol::
+* Support For Unix::
+* Customization Hooks for Users::
+* Tools To Help Developers::
+* Resolution of Name Conflicts::
+* Hash Table Extensions::
+* Miscellaneous Extensions::
+* Stale Extensions::
+* Efficiency Hacks::

 @end menu
 
 @end menu
 

-@node Non-Conformance With The ANSI Standard
+@node  Garbage Collection

 @comment  node-name,  next,  previous,  up
 @comment  node-name,  next,  previous,  up

-@section Non-Conformance With The ANSI Standard
+@section Garbage Collection
+@cindex Garbage collection
+
+SBCL provides additional garbage collection functionality not
+specified by ANSI.
+
+@include var-sb-ext-star-after-gc-hooks-star.texinfo
+@include fun-sb-ext-gc.texinfo
+
+@subsection Finalization
+@cindex Finalization
+
+Finalization allows code to be executed after an object has been
+garbage collected. This is useful for example for releasing foreign
+memory associated with a Lisp object.
+
+@include fun-sb-ext-finalize.texinfo
+@include fun-sb-ext-cancel-finalization.texinfo

 
 

-Essentially every type of non-conformance is considered a bug.  (The
-exceptions involve internal inconsistencies in the standard.)  In SBCL
-0.7.6, the master record of known bugs is in the @file{BUGS} file in
-the distribution.  Some highlight information about bugs may also be
-found in the manual page. The recommended way to report bugs is
-through the sbcl-help or sbcl-devel mailing lists.  For mailing list
-addresses, @xref{More SBCL Information}.
+@subsection Weak Pointers
+@cindex Weak pointers

 
 

+Weak pointers allow references to objects to be maintained without
+keeping them from being garbage collected: useful for building caches
+among other things.

 
 

-@node Idiosyncrasies
+Hash tables can also have weak keys and values: @pxref{Hash Table
+Extensions}.
+
+@include fun-sb-ext-make-weak-pointer.texinfo
+@include fun-sb-ext-weak-pointer-value.texinfo
+
+@subsection Introspection and Tuning
+
+@include var-sb-ext-star-gc-run-time-star.texinfo
+@include fun-sb-ext-bytes-consed-between-gcs.texinfo
+@include fun-sb-ext-dynamic-space-size.texinfo
+@include fun-sb-ext-get-bytes-consed.texinfo
+@include fun-sb-ext-gc-logfile.texinfo
+@include fun-sb-ext-generation-average-age.texinfo
+@include fun-sb-ext-generation-bytes-allocated.texinfo
+@include fun-sb-ext-generation-bytes-consed-between-gcs.texinfo
+@include fun-sb-ext-generation-minimum-age-before-gc.texinfo
+@include fun-sb-ext-generation-number-of-gcs-before-promotion.texinfo
+@include fun-sb-ext-generation-number-of-gcs.texinfo
+
+@node Metaobject Protocol

 @comment  node-name,  next,  previous,  up
 @comment  node-name,  next,  previous,  up

-@section Idiosyncrasies
-
-The information in this section describes some of the ways that SBCL
-deals with choices that the ANSI standard leaves to the
-implementation.
-
-Declarations are generally treated as assertions. This general
-principle, and its implications, and the bugs which still keep the
-compiler from quite satisfying this principle, are discussed in
-@ref{Compiler}.
-
-SBCL is essentially a compiler-only implementation of Common
-Lisp. That is, for all but a few special cases, @code{eval} creates a
-lambda expression, calls @code{compile} on the lambda expression to
-create a compiled function, and then calls @code{funcall} on the
-resulting function object. This is explicitly allowed by the ANSI
-standard, but leads to some oddities, e.g. collapsing @code{functionp}
-and @code{compiled-function-p} into the same predicate.
-
-@findex defconstant
-SBCL is quite strict about ANSI's definition of
-@code{defconstant}. ANSI says that doing @code{defconstant} of the
-same symbol more than once is undefined unless the new value is
-@code{eql} to the old value. Conforming to this specification is a
-nuisance when the ``constant'' value is only constant under some
-weaker test like @code{string=} or @code{equal}. It's especially
-annoying because, in SBCL, @code{defconstant} takes effect not only at
-load time but also at compile time, so that just compiling and loading
-reasonable code like
-@lisp
-(defconstant +foobyte+ '(1 4))
-@end lisp
-runs into this undefined behavior. Many implementations of Common Lisp
-try to help the programmer around this annoyance by silently accepting
-the undefined code and trying to do what the programmer probably
-meant. SBCL instead treats the undefined behavior as an error. Often
-such code can be rewritten in portable ANSI Common Lisp which has the
-desired behavior.  E.g., the code above can be given an exactly
-defined meaning by replacing @code{defconstant} either with
-@code{defparameter} or with a customized macro which does the right
-thing, possibly along the lines of the @code{defconstant-eqx} macro
-used internally in the implementation of SBCL itself.  In
-circumstances where this is not appropriate, the programmer can handle
-the condition type @code{sb-ext:defconstant-uneql}, and choose either
-the @command{continue} or @command{abort} restart as appropriate.
-
-SBCL gives style warnings about various kinds of perfectly legal code,
-e.g.
+@section Metaobject Protocol
+
+@subsection AMOP Compatibility of Metaobject Protocol
+
+SBCL supports a metaobject protocol which is intended to be compatible
+with AMOP; present exceptions to this (as distinct from current bugs)
+are:

 
 @itemize
 
 @itemize

-  
+

 @item
 @item

-@code{defmethod} without a preceding @code{defgeneric};
-  
+@findex @sbmop{compute-effective-method}
+@code{compute-effective-method} only returns one value, not two.
+
+There is no record of what the second return value was meant to
+indicate, and apparently no clients for it.
+

 @item
 @item

-multiple @code{defun}s of the same symbol in different units;
-  
+@tindex @cl{generic-function}
+@tindex @cl{standard-generic-function}
+@tindex @sbmop{funcallable-standard-object}
+@tindex @cl{standard-object}
+@tindex @cl{function}
+The direct superclasses of @code{sb-mop:funcallable-standard-object} are
+@code{(function standard-object)}, not @code{(standard-object function)}.
+
+This is to ensure that the @code{standard-object} class is the last of
+the standardized classes before @code{t} appearing in the class
+precedence list of @code{generic-function} and
+@code{standard-generic-function}, as required by section 1.4.4.5 of the
+ANSI specification.
+

 @item
 @item

-special variables not named in the conventional @code{*foo*} style,
-and lexical variables unconventionally named in the @code{*foo*} style
+@findex @cl{ensure-generic-function}
+@findex @sbmop{generic-function-declarations}
+the arguments @code{:declare} and @code{:declarations} to
+@code{ensure-generic-function} are both accepted, with the leftmost
+argument defining the declarations to be stored and returned by
+@code{generic-function-declarations}.

 
 

-@end itemize
+Where AMOP specifies @code{:declarations} as the keyword argument to
+@code{ensure-generic-function}, the Common Lisp standard specifies
+@code{:declare}.  Portable code should use @code{:declare}.

 
 

-This causes friction with people who point out that other ways of
-organizing code (especially avoiding the use of @code{defgeneric}) are
-just as aesthetically stylish.  However, these warnings should be read
-not as ``warning, bad aesthetics detected, you have no style'' but
-``warning, this style keeps the compiler from understanding the code
-as well as you might like.'' That is, unless the compiler warns about
-such conditions, there's no way for the compiler to warn about some
-programming errors which would otherwise be easy to overlook. (Related
-bug: The warning about multiple @code{defun}s is pointlessly annoying
-when you compile and then load a function containing @code{defun}
-wrapped in @code{eval-when}, and ideally should be suppressed in that
-case, but still isn't as of SBCL 0.7.6.)
-
-
-@node  Extensions
-@comment  node-name,  next,  previous,  up
-@section Extensions
+@item
+@findex @sbmop{validate-superclass}
+@findex @sbmop{finalize-inheritance}
+@tindex @cl{standard-class}
+@tindex @sbmop{funcallable-standard-class}
+@tindex @cl{function}
+@findex @sbmop{class-prototype}
+although SBCL obeys the requirement in AMOP that
+@code{validate-superclass} should treat @code{standard-class} and
+@code{funcallable-standard-class} as compatible metaclasses, we
+impose an additional requirement at class finalization time: a class
+of metaclass @code{funcallable-standard-class} must have
+@code{function} in its superclasses, and a class of metaclass
+@code{standard-class} must not.
+
+@findex @cl{typep}
+@findex @cl{class-of}
+@findex @cl{subtypep}
+After a class has been finalized, it is associated with a class
+prototype which is accessible by a standard mop function
+@code{sb-mop:class-prototype}.  The user can then ask whether this
+object is a @code{function} or not in several different ways: whether it
+is a function according to @code{typep}; whether its @code{class-of} is
+@code{subtypep} @code{function}, or whether @code{function} appears in
+the superclasses of the class.  The additional consistency requirement
+comes from the desire to make all of these answers the same.
+
+The following class definitions are bad, and will lead to errors
+either immediately or if an instance is created:
+@lisp
+(defclass bad-object (funcallable-standard-object)
+  ()
+  (:metaclass standard-class))
+@end lisp
+@lisp
+(defclass bad-funcallable-object (standard-object)
+  ()
+  (:metaclass funcallable-standard-class))
+@end lisp
+The following definition is acceptable:
+@lisp
+(defclass mixin ()
+  ((slot :initarg slot)))
+(defclass funcallable-object (funcallable-standard-object mixin)
+  ()
+  (:metaclass funcallable-standard-class))
+@end lisp
+and leads to a class whose instances are funcallable and have one slot.

 
 

-SBCL is derived from CMUCL, which implements many extensions to the
-ANSI standard. SBCL doesn't support as many extensions as CMUCL, but
-it still has quite a few.  @xref{Contributed Modules}.
+@tindex @sbmop{funcallable-standard-object}
+Note that this requirement also applies to the class
+@code{sb-mop:funcallable-standard-object}, which has metaclass
+@code{sb-mop:funcallable-standard-class} rather than
+@code{standard-class} as AMOP specifies.

 
 

+@item
+the requirement that ``No portable class @math{C_p} may inherit, by
+virtue of being a direct or indirect subclass of a specified class, any
+slot for which the name is a symbol accessible in the
+@code{common-lisp-user} package or exported by any package defined in
+the ANSI Common Lisp standard.'' is interpreted to mean that the
+standardized classes themselves should not have slots named by external
+symbols of public packages.
+
+The rationale behind the restriction is likely to be similar to the ANSI
+Common Lisp restriction on defining functions, variables and types named
+by symbols in the Common Lisp package: preventing two independent pieces
+of software from colliding with each other.

 
 

-@menu
-* Things Which Might Be In The Next ANSI Standard::  
-* Support For Unix::            
-* Customization Hooks for Users::  
-* Tools To Help Developers::    
-* Interface To Low-Level SBCL Implementation::  
-* Stale Extensions::            
-* Efficiency Hacks::            
-@end menu
+@item
+@findex @sbmop{slot-value-using-class}
+@findex @setf{@sbmop{slot-value-using-class}}
+@findex @sbmop{slot-boundp-using-class}
+specializations of the @code{new-value} argument to @code{(setf
+sb-mop:slot-value-using-class)} are not allowed: all user-defined
+methods must have a specializer of the class @code{t}.
+
+This prohibition is motivated by a separation of layers: the
+@code{slot-value-using-class} family of functions is intended for use in
+implementing different and new slot allocation strategies, rather than
+in performing application-level dispatching.  Additionally, with this
+requirement, there is a one-to-one mapping between metaclass, class and
+slot-definition-class tuples and effective methods of @code{(setf
+slot-value-using-class)}, which permits optimization of @code{(setf
+slot-value-using-class)}'s discriminating function in the same manner as
+for @code{slot-value-using-class} and @code{slot-boundp-using-class}.
+
+Note that application code may specialize on the @code{new-value}
+argument of slot accessors.

 
 

-@node  Things Which Might Be In The Next ANSI Standard
-@comment  node-name,  next,  previous,  up
-@subsection Things Which Might Be In The Next ANSI Standard
+@item
+@findex @cl{defclass}
+@findex @sbmop{ensure-class}
+@findex @sbmop{ensure-class-using-class}
+@findex @cl{find-class}
+@findex @cl{class-name}
+the class named by the @code{name} argument to @code{ensure-class}, if
+any, is only redefined if it is the proper name of that class;
+otherwise, a new class is created.
+
+This is consistent with the description of @code{ensure-class} in AMOP
+as the functional version of @code{defclass}, which has this behaviour;
+however, it is not consistent with the weaker requirement in AMOP, which
+states that any class found by @code{find-class}, no matter what its
+@code{class-name}, is redefined.

 
 

-SBCL provides extensive support for calling external C code,
-@ref{Foreign Function Interface}.
+@end itemize

 
 

-SBCL provides additional garbage collection functionality not
-specified by ANSI. Weak pointers allow references to objects to be
-maintained without keeping them from being GCed (garbage
-collected). And ``finalization'' hooks are available to cause code to
-be executed when an object has been GCed.
-@c <!-- FIXME: Actually documenting these would be good.:-| -->
-
-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
-@dfn{sb-simple-streams} implements a subset of the Franz Allegro
-simple-streams proposal.
-
-SBCL supports a MetaObject Protocol which is intended to be compatible
-with AMOP; present exceptions to this (as distinct from current bugs)
-are:
+@subsection Metaobject Protocol Extensions
+
+In addition, SBCL supports extensions to the Metaobject protocol from
+AMOP; at present, they are:

 
 @itemize
 
 @itemize

-  
-@item
-the abstract @code{metaobject} class is not present in the class
-hierarchy;
-  
+

 @item
 @item

-the @code{standard-object} and @code{funcallable-standard-object}
-classes are disjoint;
-  
+@findex @cl{defmethod}
+@findex @cl{find-class}
+@findex @sbmop{intern-eql-specializer}
+@findex @sbpcl{make-method-specializers-form}
+@findex @sbmop{make-method-lambda}
+compile-time support for generating specializer metaobjects from
+specializer names in @code{defmethod} forms is provided by the
+@code{make-method-specializers-form} function, which returns a form
+which, when evaluated in the lexical environment of the
+@code{defmethod}, returns a list of specializer metaobjects.  This
+operator suffers from similar restrictions to those affecting
+@code{make-method-lambda}, namely that the generic function must be
+defined when the @code{defmethod} form is expanded, so that the
+correct method of @code{make-method-specializers-form} is invoked.
+The system-provided method on @code{make-method-specializers-form}
+generates a call to @code{find-class} for each symbol specializer
+name, and a call to @code{intern-eql-specializer} for each @code{(eql
+@var{x})} specializer name.
+

 @item
 @item

-@code{compute-effective-method} only returns one value, not two;
-  
+@findex @cl{find-method}
+@findex @sbpcl{parse-specializer-using-class}
+@findex @sbpcl{unparse-specializer-using-class}
+run-time support for converting between specializer names and
+specializer metaobjects, mostly for the purposes of
+@code{find-method}, is provided by
+@code{parse-specializer-using-class} and
+@code{unparse-specializer-using-class}, which dispatch on their first
+argument, the generic function associated with a method with the given
+specializer.  The system-provided methods on those methods convert
+between classes and proper names and between lists of the form
+@code{(eql @var{x})} and interned eql specializer objects.
+

 @item
 @item

-the system-supplied @code{:around} method for @code{compute-slots}
-specialized on @code{funcallable-standard-class} does not respect the
-requested order from a user-supplied primary method.
+@vindex @sbpcl{+slot-unbound+}
+@findex @sbmop{standard-instance-access}
+@findex @sbmop{funcallable-standard-instance-access}
+distinguising unbound instance allocated slots from bound ones when
+using @code{standard-instance-access} and
+@code{funcallable-standard-instance-access} is possible by comparison
+to the constant @code{+slot-unbound+}.

 
 @end itemize
 
 @node  Support For Unix
 @comment  node-name,  next,  previous,  up
 
 @end itemize
 
 @node  Support For Unix
 @comment  node-name,  next,  previous,  up

-@subsection Support For Unix
+@section Support For Unix
+
+@menu
+* Command-line arguments::
+* Querying the process environment::
+* Running external programs::
+@end menu
+
+@node Command-line arguments
+@subsection Command-line arguments
+@vindex @sbext{@earmuffs{posix-argv}}

 
 The UNIX command line can be read from the variable
 
 The UNIX command line can be read from the variable

-@code{sb-ext:*posix-argv*}. The UNIX environment can be queried with
-the @code{sb-ext:posix-getenv} function.
+@code{sb-ext:*posix-argv*}.
+
+@node Querying the process environment
+@subsection Querying the process environment
+
+The UNIX environment can be queried with the
+@code{sb-ext:posix-getenv} function.

 
 @include fun-sb-ext-posix-getenv.texinfo
 
 
 @include fun-sb-ext-posix-getenv.texinfo
 

-The SBCL system can be terminated with @code{sb-ext:quit}, (but see
-notes in @ref{Threading} about the interaction between this feature and
-sessions) optionally returning a specified numeric value to the
-calling Unix process. The normal Unix idiom of terminating on end of
-file on input is also supported.
+@node Running external programs
+@subsection Running external programs
+
+External programs can be run with @code{sb-ext:run-program}.
+@footnote{In SBCL versions prior to 1.0.13, @code{sb-ext:run-program}
+searched for executables in a manner somewhat incompatible with other
+languages.  As of this version, SBCL uses the system library routine
+@code{execvp(3)}, and no longer contains the function,
+@code{find-executable-in-search-path}, which implemented the old
+search.  Users who need this function may find it
+in @file{run-program.lisp} versions 1.67 and earlier in SBCL's CVS
+repository here
+@url{http://sbcl.cvs.sourceforge.net/sbcl/sbcl/src/code/run-program.lisp?view=log}. However,
+we caution such users that this search routine finds executables that
+system library routines do not.}
+
+@include fun-sb-ext-run-program.texinfo
+
+When @code{sb-ext:run-program} is called with @code{wait} equal to
+NIL, an instance of class @var{sb-ext:process} is returned.  The
+following functions are available for use with processes:

 
 

-@include fun-sb-ext-quit.texinfo
+@include fun-sb-ext-process-p.texinfo
+
+@include fun-sb-ext-process-input.texinfo
+
+@include fun-sb-ext-process-output.texinfo
+
+@include fun-sb-ext-process-error.texinfo
+
+@include fun-sb-ext-process-alive-p.texinfo
+
+@include fun-sb-ext-process-status.texinfo
+
+@include fun-sb-ext-process-wait.texinfo
+
+@include fun-sb-ext-process-exit-code.texinfo
+
+@include fun-sb-ext-process-core-dumped.texinfo
+
+@include fun-sb-ext-process-close.texinfo
+
+@include fun-sb-ext-process-kill.texinfo

 
 @node  Customization Hooks for Users
 @comment  node-name,  next,  previous,  up
 
 @node  Customization Hooks for Users
 @comment  node-name,  next,  previous,  up

-@subsection Customization Hooks for Users
+@section Customization Hooks for Users

 
 The toplevel repl prompt may be customized, and the function
 that reads user input may be replaced completely.
 
 The toplevel repl prompt may be customized, and the function
 that reads user input may be replaced completely.

@@ -209,12 +364,22 @@ mechanisms as follows:
 @include fun-common-lisp-ed.texinfo
 @include var-sb-ext-star-ed-functions-star.texinfo
 
 @include fun-common-lisp-ed.texinfo
 @include var-sb-ext-star-ed-functions-star.texinfo
 

-@node  Tools To Help Developers
+Conditions of type @code{warning} and @code{style-warning} are
+sometimes signaled at runtime, especially during execution of Common
+Lisp defining forms such as @code{defun}, @code{defmethod}, etc.  To
+muffle these warnings at runtime, SBCL provides a variable
+@code{sb-ext:*muffled-warnings*}:
+
+@include var-sb-ext-star-muffled-warnings-star.texinfo
+
+@node Tools To Help Developers

 @comment  node-name,  next,  previous,  up
 @comment  node-name,  next,  previous,  up

-@subsection Tools To Help Developers
+@section Tools To Help Developers
+@findex @cl{trace}
+@findex @cl{inspect}

 
 SBCL provides a profiler and other extensions to the ANSI @code{trace}
 
 SBCL provides a profiler and other extensions to the ANSI @code{trace}

-facility.  For more information, see @ref{macro-common-lisp-trace}.
+facility.  For more information, see @ref{Macro common-lisp:trace}.

 
 The debugger supports a number of options. Its documentation is
 accessed by typing @kbd{help} at the debugger prompt. @xref{Debugger}.
 
 The debugger supports a number of options. Its documentation is
 accessed by typing @kbd{help} at the debugger prompt. @xref{Debugger}.

@@ -222,27 +387,50 @@ accessed by typing @kbd{help} at the debugger prompt. @xref{Debugger}.
 Documentation for @code{inspect} is accessed by typing @kbd{help} at
 the @code{inspect} prompt.
 
 Documentation for @code{inspect} is accessed by typing @kbd{help} at
 the @code{inspect} prompt.
 

-@node  Interface To Low-Level SBCL Implementation
+@node Resolution of Name Conflicts
+@section Resolution of Name Conflicts
+@tindex @sbext{name-conflict}
+@findex @sbext{name-conflict-symbols}
+
+The ANSI standard (section 11.1.1.2.5) requires that name conflicts in
+packages be resolvable in favour of any of the conflicting symbols.  In
+the interactive debugger, this is achieved by prompting for the symbol
+in whose favour the conflict should be resolved; for programmatic use,
+the @code{sb-ext:resolve-conflict} restart should be invoked with one
+argument, which should be a member of the list returned by the condition
+accessor @code{sb-ext:name-conflict-symbols}.
+
+@node    Hash Table Extensions

 @comment  node-name,  next,  previous,  up
 @comment  node-name,  next,  previous,  up

-@subsection Interface To Low-Level SBCL Implementation
+@section Hash Table Extensions
+@cindex Hash tables
+
+Hash table extensions supported by SBCL are all controlled by keyword
+arguments to @code{make-hash-table}.

 
 

-SBCL has the ability to save its state as a file for later
-execution. This functionality is important for its bootstrapping
-process, and is also provided as an extension to the user.  Note that
-foreign libraries loaded via @code{load-shared-object} don't survive
-this process; a core should not be saved in this case.
+@include fun-common-lisp-make-hash-table.texinfo

 
 

-@emph{FIXME: what should be done for foreign libraries?}
+@include macro-sb-ext-define-hash-table-test.texinfo

 
 

-@emph{FIXME: document load-shared-object somewhere - it's in
-ffi.texinfo?}
+@include macro-sb-ext-with-locked-hash-table.texinfo

 
 

-@include fun-sb-ext-save-lisp-and-die.texinfo
+@include fun-sb-ext-hash-table-synchronized-p.texinfo

 
 

+@include fun-sb-ext-hash-table-weakness.texinfo
+
+@node    Miscellaneous Extensions
+@comment  node-name,  next,  previous,  up
+@section Miscellaneous Extensions
+
+@include fun-sb-ext-array-storage-vector.texinfo
+@include fun-sb-ext-delete-directory.texinfo
+@include fun-sb-ext-get-time-of-day.texinfo
+@include fun-sb-ext-seed-random-state.texinfo
+@include macro-sb-ext-wait-for.texinfo

 
 @node Stale Extensions
 @comment  node-name,  next,  previous,  up
 
 @node Stale Extensions
 @comment  node-name,  next,  previous,  up

-@subsection Stale Extensions
+@section Stale Extensions

 
 SBCL has inherited from CMUCL various hooks to allow the user to
 tweak and monitor the garbage collection process. These are somewhat
 
 SBCL has inherited from CMUCL various hooks to allow the user to
 tweak and monitor the garbage collection process. These are somewhat

@@ -264,18 +452,18 @@ list.
 
 @node  Efficiency Hacks
 @comment  node-name,  next,  previous,  up
 
 @node  Efficiency Hacks
 @comment  node-name,  next,  previous,  up

-@subsection Efficiency Hacks
+@section Efficiency Hacks

 
 The @code{sb-ext:purify} function causes SBCL first to collect all
 
 The @code{sb-ext:purify} function causes SBCL first to collect all

-garbage, then to mark all uncollected objects as permanent, never
-again attempting to collect them as garbage. This can cause a large
-increase in efficiency when using a primitive garbage collector, or a
-more moderate increase in efficiency when using a more sophisticated
-garbage collector which is well suited to the program's memory usage
-pattern. It also allows permanent code to be frozen at fixed
-addresses, a precondition for using copy-on-write to share code
-between multiple Lisp processes. it is less important with modern
-generational garbage collectors.
+garbage, then to mark all uncollected objects as permanent, never again
+attempting to collect them as garbage. This can cause a large increase
+in efficiency when using a primitive garbage collector, or a more
+moderate increase in efficiency when using a more sophisticated garbage
+collector which is well suited to the program's memory usage pattern. It
+also allows permanent code to be frozen at fixed addresses, a
+precondition for using copy-on-write to share code between multiple Lisp
+processes.  This is less important with modern generational garbage
+collectors, but not all SBCL platforms use such a garbage collector.

 
 @include fun-sb-ext-purify.texinfo
 
 
 @include fun-sb-ext-purify.texinfo
 

@@ -288,13 +476,3 @@ not checked. In short: don't use it.
 The @code{sb-ext:freeze-type} declaration declares that a
 type will never change, which can make type testing
 (@code{typep}, etc.) more efficient for structure types.
 The @code{sb-ext:freeze-type} declaration declares that a
 type will never change, which can make type testing
 (@code{typep}, etc.) more efficient for structure types.

-
-The @code{sb-ext:constant-function} declaration specifies
-that a function will always return the same value for the same
-arguments, which may allow the compiler to optimize calls
-to it. This is appropriate for functions like @code{sqrt}, but
-is @emph{not} appropriate for functions like @code{aref},
-which can change their return values when the underlying data are
-changed.
-@c <!-- FIXME: This declaration does not seem to be supported in the 
-@c      current compiler. -->