1.0.36.11: Make slam.sh work on Win32.

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

diff --git a/doc/manual/beyond-ansi.texinfo b/doc/manual/beyond-ansi.texinfo
index 2fc20c8..e595663 100644 (file)
--- a/doc/manual/beyond-ansi.texinfo
+++ b/doc/manual/beyond-ansi.texinfo
@@ -7,32 +7,63 @@ 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

-* Garbage Collection::          
-* Metaobject Protocol::         
-* Support For Unix::            
-* Customization Hooks for Users::  
-* Tools To Help Developers::    
-* Resolution of Name Conflicts::  
-* Stale Extensions::            
-* Efficiency Hacks::            
+* 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
 
 @node  Garbage Collection
 @comment  node-name,  next,  previous,  up
 @section Garbage Collection
 @end menu
 
 @node  Garbage Collection
 @comment  node-name,  next,  previous,  up
 @section Garbage Collection

+@cindex Garbage collection

 
 SBCL provides additional garbage collection functionality not
 
 SBCL provides additional garbage collection functionality not

-specified by ANSI. Weak pointers allow references to objects to be
-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.
+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
 
 @include fun-sb-ext-finalize.texinfo
 @include fun-sb-ext-cancel-finalization.texinfo

+
+@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.
+
+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
 @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
+
+@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-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
+@include fun-sb-ext-get-bytes-consed.texinfo

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

@@ -43,7 +74,7 @@ with AMOP; present exceptions to this (as distinct from current bugs)
 are:
 
 @itemize
 are:
 
 @itemize

-  
+

 @item
 @findex compute-effective-method
 @findex sb-mop:compute-effective-method
 @item
 @findex compute-effective-method
 @findex sb-mop:compute-effective-method

@@ -67,7 +98,7 @@ 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.
 precedence list of @code{generic-function} and
 @code{standard-generic-function}, as required by section 1.4.4.5 of the
 ANSI specification.

-  
+

 @item
 @findex ensure-generic-function
 @findex generic-function-declarations
 @item
 @findex ensure-generic-function
 @findex generic-function-declarations

@@ -199,20 +230,100 @@ states that any class found by @code{find-class}, no matter what its
 
 @end itemize
 
 
 @end itemize
 

+In addition, SBCL supports extensions to the Metaobject protocol from
+AMOP; at present, they are:
+
+@itemize
+
+@item
+@findex defmethod
+@findex find-class
+@findex intern-eql-specializer
+@findex sb-mop:intern-eql-specializer
+@findex make-method-specializers-form
+@findex sb-pcl:make-method-specializers-form
+@findex make-method-lambda
+@findex sb-mop: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
+@findex find-method
+@findex parse-specializer-using-class
+@findex unparse-specializer-using-class
+@findex sb-pcl:parse-specializer-using-class
+@findex sb-pcl: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.
+
+@end itemize
+

 @node  Support For Unix
 @comment  node-name,  next,  previous,  up
 @section Support For Unix
 
 @node  Support For Unix
 @comment  node-name,  next,  previous,  up
 @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 sb-ext:*posix-argv*
+@vindex *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
 

+@node Running external programs
+@subsection Running external programs
+

 External programs can be run with @code{sb-ext:run-program}.
 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
 
 
 @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-process-p.texinfo
 
 @include fun-sb-ext-process-input.texinfo
 @include fun-sb-ext-process-p.texinfo
 
 @include fun-sb-ext-process-input.texinfo

@@ -257,9 +368,19 @@ 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
 

+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
 @section Tools To Help Developers
 @node Tools To Help Developers
 @comment  node-name,  next,  previous,  up
 @section Tools To Help Developers

+@findex trace
+@findex inspect

 
 SBCL provides a profiler and other extensions to the ANSI @code{trace}
 facility.  For more information, see @ref{Macro common-lisp:trace}.
 
 SBCL provides a profiler and other extensions to the ANSI @code{trace}
 facility.  For more information, see @ref{Macro common-lisp:trace}.

@@ -272,6 +393,10 @@ the @code{inspect} prompt.
 
 @node Resolution of Name Conflicts
 @section Resolution of Name Conflicts
 
 @node Resolution of Name Conflicts
 @section Resolution of Name Conflicts

+@tindex sb-ext:name-conflict
+@tindex name-conflict
+@findex sb-ext:name-conflict-symbols
+@findex 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 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

@@ -281,6 +406,30 @@ 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}.
 
 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
+@section Hash Table Extensions
+@cindex Hash tables
+
+Hash table extensions supported by SBCL are all controlled by keyword
+arguments to @code{make-hash-table}.
+
+@include fun-common-lisp-make-hash-table.texinfo
+
+@include macro-sb-ext-define-hash-table-test.texinfo
+
+@include macro-sb-ext-with-locked-hash-table.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
+

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

@@ -329,13 +478,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. -->