0.9.4.77:
[sbcl.git] / doc / manual / beyond-ansi.texinfo
index b4606f5..c79ee95 100644 (file)
@@ -7,56 +7,116 @@ ANSI standard. SBCL doesn't support as many extensions as CMUCL, but
 it still has quite a few.  @xref{Contributed Modules}.
 
 @menu
 it still has quite a few.  @xref{Contributed Modules}.
 
 @menu
-* Things Which Might Be In The Next ANSI Standard::  
+* Garbage Collection::          
+* Metaobject Protocol::         
 * Support For Unix::            
 * Customization Hooks for Users::  
 * Tools To Help Developers::    
 * Support For Unix::            
 * Customization Hooks for Users::  
 * Tools To Help Developers::    
-* Interface To Low-Level SBCL Implementation::  
+* Resolution of Name Conflicts::  
 * Stale Extensions::            
 * Efficiency Hacks::            
 @end menu
 
 * Stale Extensions::            
 * Efficiency Hacks::            
 @end menu
 
-@node  Things Which Might Be In The Next ANSI Standard
+@node  Garbage Collection
 @comment  node-name,  next,  previous,  up
 @comment  node-name,  next,  previous,  up
-@section Things Which Might Be In The Next ANSI Standard
-
-SBCL provides extensive support for calling external C code,
-@ref{Foreign Function Interface}.
+@section Garbage Collection
 
 SBCL provides additional garbage collection functionality not
 specified by ANSI. Weak pointers allow references to objects to be
 
 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
+maintained without keeping them from being garbage collected, and
+``finalization'' hooks are available to cause code to be executed when
+an object has been garbage collected. Additionally users can specify
+their own cleanup actions to be executed with garbage collection.
+
+@include fun-sb-ext-finalize.texinfo
+@include fun-sb-ext-cancel-finalization.texinfo
+@include fun-sb-ext-make-weak-pointer.texinfo
+@include fun-sb-ext-weak-pointer-value.texinfo
+@include var-sb-ext-star-after-gc-hooks-star.texinfo
+
+@node Metaobject Protocol
+@comment  node-name,  next,  previous,  up
+@section 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
   
 @item
 with AMOP; present exceptions to this (as distinct from current bugs)
 are:
 
 @itemize
   
 @item
-the abstract @code{metaobject} class is not present in the class
-hierarchy;
-  
-@item
-the @code{standard-object} and @code{funcallable-standard-object}
-classes are disjoint;
+@findex compute-effective-method
+@findex sb-mop: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
-@code{compute-effective-method} only returns one value, not two;
-  
+@findex ensure-generic-function
+@findex generic-function-declarations
+@findex sb-mop: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}.
+
+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}.
+
 @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.
+@findex validate-superclass
+@findex finalize-inheritance
+@findex sb-mop:validate-superclass
+@findex sb-mop:finalize-inheritance
+@tindex standard-class
+@tindex funcallable-standard-class
+@tindex sb-mop:funcallable-standard-class
+@tindex function
+@findex sb-mop:class-prototype
+@findex class-prototype
+although SBCL obeys the requirement in AMOP for
+@code{validate-superclass} for @code{standard-class} and
+@code{funcallable-standard-class} to be 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 typep
+@findex class-of
+@findex subtypep
+At class finalization, 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.
 
 @end itemize
 
 
 @end itemize
 
@@ -93,12 +153,12 @@ 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
+@node Tools To Help Developers
 @comment  node-name,  next,  previous,  up
 @section Tools To Help Developers
 
 SBCL provides a profiler and other extensions to the ANSI @code{trace}
 @comment  node-name,  next,  previous,  up
 @section Tools To Help Developers
 
 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}.
@@ -106,26 +166,16 @@ 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
-@comment  node-name,  next,  previous,  up
-@section Interface To Low-Level SBCL Implementation
-
-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 on all platforms; a core should not be saved in
-this case. Platforms where this is supported as of SBCL 0.8.14.5 are
-x86/Linux, x86/FreeBSD and sparc/SunOS.
-
-@emph{FIXME: what should be done for foreign libraries?}
-
-@emph{FIXME: document load-shared-object somewhere - it's in
-ffi.texinfo?}
-
-@include fun-sb-ext-save-lisp-and-die.texinfo
+@node Resolution of Name Conflicts
+@section Resolution of Name Conflicts
 
 
+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 Stale Extensions
 @comment  node-name,  next,  previous,  up
 
 @node Stale Extensions
 @comment  node-name,  next,  previous,  up
@@ -154,15 +204,15 @@ list.
 @section Efficiency Hacks
 
 The @code{sb-ext:purify} function causes SBCL first to collect all
 @section Efficiency Hacks
 
 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