X-Git-Url: http://repo.macrolet.net/gitweb/?a=blobdiff_plain;f=doc%2Fmanual%2Fbeyond-ansi.texinfo;h=e595663533d4c2e428a6e2165b604dda69a81b96;hb=3fa2feb10ab827fc6cc2a85287e78b6e66b7bf4d;hp=2fc20c84bc2062484aaba9308fd8ee0cb502b41d;hpb=f19ae86fb2c16ebb4dce3d16cc1bb32e94f07110;p=sbcl.git diff --git a/doc/manual/beyond-ansi.texinfo b/doc/manual/beyond-ansi.texinfo index 2fc20c8..e595663 100644 --- 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 -* 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 +@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. +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-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 @@ -43,7 +74,7 @@ with AMOP; present exceptions to this (as distinct from current bugs) are: @itemize - + @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. - + @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 +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 +@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 -@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 +@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-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 +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 +@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}. @@ -272,6 +393,10 @@ 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 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}. +@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 @@ -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: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