X-Git-Url: http://repo.macrolet.net/gitweb/?a=blobdiff_plain;f=doc%2Fmanual%2Fbeyond-ansi.texinfo;h=a00ae6a402c95407ed5c08e7c524728bc2430fe5;hb=fb2656c40ff25482dcf3519c3d0fab510216f983;hp=fdf8b6981883ee73404df98fef7386c96f2480d0;hpb=53f4147704fbe48c03dd73d7b6a9f92c0a066ed8;p=sbcl.git diff --git a/doc/manual/beyond-ansi.texinfo b/doc/manual/beyond-ansi.texinfo index fdf8b69..a00ae6a 100644 --- a/doc/manual/beyond-ansi.texinfo +++ b/doc/manual/beyond-ansi.texinfo @@ -7,55 +7,242 @@ ANSI standard. SBCL doesn't support as many extensions as CMUCL, but it still has quite a few. @xref{Contributed Modules}. @menu -* Things Which Might Be In The Next ANSI Standard:: -* Support For Unix:: -* Customization Hooks for Users:: -* Tools To Help Developers:: -* Stale Extensions:: -* Efficiency Hacks:: +* Garbage Collection:: +* Metaobject Protocol:: +* Support For Unix:: +* Customization Hooks for Users:: +* Tools To Help Developers:: +* Resolution of Name Conflicts:: +* Miscellaneous Extensions:: +* 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 -@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 -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 - -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 +@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 +@tindex generic-function +@tindex standard-generic-function +@tindex funcallable-standard-object +@tindex sb-mop:funcallable-standard-object +@tindex standard-object +@tindex function +The direct superclasses of @code{sb-mop:funcallable-standard-object} are +@code{(function standard-object)}, not @code{(standard-object function)}. + +This is to ensure that the @code{standard-object} class is the last of +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 +@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 +@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 that +@code{validate-superclass} should treat @code{standard-class} and +@code{funcallable-standard-class} as 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 +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 +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. + +@tindex funcallable-standard-object +@tindex sb-mop: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 +@code{standard-class} as AMOP specifies. + +@item +the requirement that ``No portable class @math{C_p} may inherit, by +virtue of being a direct or indirect subclass of a specified class, any +slot for which the name is a symbol accessible in the +@code{common-lisp-user} package or exported by any package defined in +the ANSI Common Lisp standard.'' is interpreted to mean that the +standardized classes themselves should not have slots named by external +symbols of public packages. + +The rationale behind the restriction is likely to be similar to the ANSI +Common Lisp restriction on defining functions, variables and types named +by symbols in the Common Lisp package: preventing two independent pieces +of software from colliding with each other. + @item -the abstract @code{metaobject} class is not present in the class -hierarchy; - +@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 +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}. + +This prohibition is motivated by a separation of layers: the +@code{slot-value-using-class} family of functions is intended for use in +implementing different and new slot allocation strategies, rather than +in performing application-level dispatching. Additionally, with this +requirement, there is a one-to-one mapping between metaclass, class and +slot-definition-class tuples and effective methods of @code{(setf +slot-value-using-class)}, which permits optimization of @code{(setf +slot-value-using-class)}'s discriminating function in the same manner as +for @code{slot-value-using-class} and @code{slot-boundp-using-class}. + +Note that application code may specialize on the @code{new-value} +argument of slot accessors. + @item -the @code{standard-object} and @code{funcallable-standard-object} -classes are disjoint; - +@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 +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. + +This is consistent with the description of @code{ensure-class} in AMOP +as the functional version of @code{defclass}, which has this behaviour; +however, it is not consistent with the weaker requirement in AMOP, which +states that any class found by @code{find-class}, no matter what its +@code{class-name}, is redefined. + +@end itemize + +In addition, SBCL supports extensions to the Metaobject protocol from +AMOP; at present, they are: + +@itemize + @item -@code{compute-effective-method} only returns one value, not two; - +@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 -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 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 @@ -63,12 +250,71 @@ requested order from a user-supplied primary method. @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 + +@include fun-sb-ext-process-output.texinfo + +@include fun-sb-ext-process-error.texinfo + +@include fun-sb-ext-process-alive-p.texinfo + +@include fun-sb-ext-process-status.texinfo + +@include fun-sb-ext-process-wait.texinfo + +@include fun-sb-ext-process-exit-code.texinfo + +@include fun-sb-ext-process-core-dumped.texinfo + +@include fun-sb-ext-process-close.texinfo + +@include fun-sb-ext-process-kill.texinfo @node Customization Hooks for Users @comment node-name, next, previous, up @@ -92,9 +338,19 @@ mechanisms as follows: @include fun-common-lisp-ed.texinfo @include var-sb-ext-star-ed-functions-star.texinfo -@node Tools To Help Developers +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}. @@ -105,6 +361,27 @@ 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. +@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 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 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 @@ -132,15 +409,15 @@ list. @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 @@ -161,5 +438,5 @@ 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