X-Git-Url: http://repo.macrolet.net/gitweb/?a=blobdiff_plain;f=doc%2Fmanual%2Fbeyond-ansi.texinfo;h=9e9f5dbf16696e362aa18471f9561f16a82cea21;hb=4783db4884a231e8d217ce85feaa2c32a53ef6b9;hp=c49296955e93ded53766c0a9d821f33da41e3225;hpb=146ca8325e1d9e206a6c14e76442543267dbbc51;p=sbcl.git diff --git a/doc/manual/beyond-ansi.texinfo b/doc/manual/beyond-ansi.texinfo index c492969..9e9f5db 100644 --- 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 +@cindex Garbage collection 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 + +@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 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-setf-gc-logfile.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 +@include fun-sb-ext-get-bytes-consed.texinfo @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: @@ -48,20 +80,18 @@ are: @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 -@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)}. @@ -72,9 +102,8 @@ precedence list of @code{generic-function} and 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 @@ -85,16 +114,12 @@ Where AMOP specifies @code{:declarations} as the keyword argument to @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 @@ -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. -@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 @@ -137,8 +162,7 @@ The following definition is acceptable: @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 @@ -159,12 +183,9 @@ by symbols in the Common Lisp package: preventing two independent pieces 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}. @@ -183,13 +204,11 @@ Note that application code may specialize on the @code{new-value} 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. @@ -202,20 +221,19 @@ states that any class found by @code{find-class}, no matter what its @end itemize +@subsection Metaobject Protocol Extensions + 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 @@ -231,11 +249,9 @@ 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 +@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 @@ -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. +@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 @@ -260,8 +285,7 @@ between classes and proper names and between lists of the form @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*}. @@ -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 -@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}. @@ -365,10 +389,8 @@ the @code{inspect} prompt. @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 @@ -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 +@cindex Hash tables Hash table extensions supported by SBCL are all controlled by keyword arguments to @code{make-hash-table}. @@ -400,6 +423,9 @@ arguments to @code{make-hash-table}. @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 @node Stale Extensions @comment node-name, next, previous, up @@ -449,13 +475,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: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