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 c492969..08b942b 100644 (file)
--- a/doc/manual/beyond-ansi.texinfo
+++ b/doc/manual/beyond-ansi.texinfo
@@ -22,25 +22,57 @@ it still has quite a few.  @xref{Contributed Modules}.
 @node  Garbage Collection
 @comment  node-name,  next,  previous,  up
 @section Garbage Collection
 @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. See
-also @code{make-hash-table} for information on weak hash tables.
+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-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
 @section Metaobject Protocol
 
 
 @node Metaobject Protocol
 @comment  node-name,  next,  previous,  up
 @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:
 SBCL supports a metaobject protocol which is intended to be compatible
 with AMOP; present exceptions to this (as distinct from current bugs)
 are:

@@ -48,20 +80,18 @@ are:
 @itemize
 
 @item
 @itemize
 
 @item

-@findex compute-effective-method
-@findex sb-mop:compute-effective-method
+@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
 @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

-@tindex generic-function
-@tindex standard-generic-function
-@tindex funcallable-standard-object
-@tindex sb-mop:funcallable-standard-object
-@tindex standard-object
-@tindex function
+@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)}.
 
 The direct superclasses of @code{sb-mop:funcallable-standard-object} are
 @code{(function standard-object)}, not @code{(standard-object function)}.
 

@@ -72,9 +102,8 @@ precedence list of @code{generic-function} and
 ANSI specification.
 
 @item
 ANSI specification.
 
 @item

-@findex ensure-generic-function
-@findex generic-function-declarations
-@findex sb-mop:generic-function-declarations
+@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
 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

@@ -85,16 +114,12 @@ Where AMOP specifies @code{:declarations} as the keyword argument to
 @code{:declare}.  Portable code should use @code{:declare}.
 
 @item
 @code{:declare}.  Portable code should use @code{:declare}.
 
 @item

-@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
+@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
 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

@@ -103,9 +128,9 @@ of metaclass @code{funcallable-standard-class} must have
 @code{function} in its superclasses, and a class of metaclass
 @code{standard-class} must not.
 
 @code{function} in its superclasses, and a class of metaclass
 @code{standard-class} must not.
 

-@findex typep
-@findex class-of
-@findex subtypep
+@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
 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

@@ -137,8 +162,7 @@ The following definition is acceptable:
 @end lisp
 and leads to a class whose instances are funcallable and have one slot.
 
 @end lisp
 and leads to a class whose instances are funcallable and have one slot.
 

-@tindex funcallable-standard-object
-@tindex sb-mop:funcallable-standard-object
+@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
 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

@@ -159,12 +183,9 @@ by symbols in the Common Lisp package: preventing two independent pieces
 of software from colliding with each other.
 
 @item
 of software from colliding with each other.
 
 @item

-@findex slot-value-using-class
-@findex sb-mop:slot-value-using-class
-@findex (setf slot-value-using-class)
-@findex (setf sb-mop:slot-value-using-class)
-@findex slot-boundp-using-class
-@findex sb-mop:slot-boundp-using-class
+@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}.
 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}.

@@ -183,13 +204,11 @@ Note that application code may specialize on the @code{new-value}
 argument of slot accessors.
 
 @item
 argument of slot accessors.
 
 @item

-@findex defclass
-@findex ensure-class
-@findex ensure-class-using-class
-@findex sb-mop:ensure-class
-@findex sb-mop:ensure-class-using-class
-@findex find-class
-@findex class-name
+@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.
 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.

@@ -202,20 +221,19 @@ states that any class found by @code{find-class}, no matter what its
 
 @end itemize
 
 
 @end itemize
 

+@subsection Metaobject Protocol Extensions
+

 In addition, SBCL supports extensions to the Metaobject protocol from
 AMOP; at present, they are:
 
 @itemize
 
 @item
 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
+@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
 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

@@ -231,11 +249,9 @@ name, and a call to @code{intern-eql-specializer} for each @code{(eql
 @var{x})} specializer name.
 
 @item
 @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
+@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
 run-time support for converting between specializer names and
 specializer metaobjects, mostly for the purposes of
 @code{find-method}, is provided by

@@ -246,6 +262,15 @@ 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.
 
 between classes and proper names and between lists of the form
 @code{(eql @var{x})} and interned eql specializer objects.
 

+@item
+@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
 @end itemize
 
 @node  Support For Unix

@@ -260,8 +285,7 @@ between classes and proper names and between lists of the form
 
 @node Command-line arguments
 @subsection Command-line arguments
 
 @node Command-line arguments
 @subsection Command-line arguments

-@vindex sb-ext:*posix-argv*
-@vindex *posix-argv*
+@vindex @sbext{@earmuffs{posix-argv}}

 
 The UNIX command line can be read from the variable
 @code{sb-ext:*posix-argv*}.
 
 The UNIX command line can be read from the variable
 @code{sb-ext:*posix-argv*}.

@@ -351,8 +375,8 @@ muffle these warnings at runtime, SBCL provides a variable
 @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
+@findex @cl{trace}
+@findex @cl{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}.

@@ -365,10 +389,8 @@ 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
+@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 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

@@ -381,6 +403,7 @@ accessor @code{sb-ext:name-conflict-symbols}.
 @node    Hash Table Extensions
 @comment  node-name,  next,  previous,  up
 @section Hash Table Extensions
 @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}.
 
 Hash table extensions supported by SBCL are all controlled by keyword
 arguments to @code{make-hash-table}.

@@ -400,6 +423,10 @@ arguments to @code{make-hash-table}.
 @section Miscellaneous Extensions
 
 @include fun-sb-ext-array-storage-vector.texinfo
 @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

@@ -449,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. -->