X-Git-Url: http://repo.macrolet.net/gitweb/?a=blobdiff_plain;f=doc%2Fmanual%2Fbeyond-ansi.texinfo;h=c79ee95b79173a7caa617a6c2bb7fe4bc42cfea3;hb=4293ef0eaa26fc153dfae88de3d1dbe5043ac39e;hp=82d824fc5d54293df02c0e6d3f171dc9ed8fad49;hpb=b93f08e862504964f907b745e80cba816e77ac03;p=sbcl.git diff --git a/doc/manual/beyond-ansi.texinfo b/doc/manual/beyond-ansi.texinfo index 82d824f..c79ee95 100644 --- a/doc/manual/beyond-ansi.texinfo +++ b/doc/manual/beyond-ansi.texinfo @@ -1,295 +1,128 @@ -@node Beyond The ANSI Standard +@node Beyond the ANSI Standard @comment node-name, next, previous, up -@chapter Beyond The ANSI Standard - -SBCL is mostly an implementation of the ANSI standard for -Common Lisp. However, there's some important behavior which extends -or clarifies the standard, and various behavior which outright -violates the standard. - - -@menu -* Non-Conformance With The ANSI Standard:: -* Idiosyncrasies:: -* Extensions:: -@end menu - -@node Non-Conformance With The ANSI Standard -@comment node-name, next, previous, up -@section Non-Conformance With The ANSI Standard - -Essentially every type of non-conformance is considered a bug. (The -exceptions involve internal inconsistencies in the standard.) In SBCL -0.7.6, the master record of known bugs is in the @file{BUGS} file in -the distribution. Some highlight information about bugs may also be -found in the manual page. The recommended way to report bugs is -through the sbcl-help or sbcl-devel mailings lists. For mailing list -addresses, @ref{More SBCL Information}. - - -@node Idiosyncrasies -@comment node-name, next, previous, up -@section Idiosyncrasies - -The information in this section describes some of the ways that SBCL -deals with choices that the ANSI standard leaves to the -implementation. - -Declarations are generally treated as assertions. This general -principle, and its implications, and the bugs which still keep the -compiler from quite satisfying this principle, are discussed in the -chapter on the compiler, @ref{The Compiler}. - -SBCL is essentially a compiler-only implementation of Common -Lisp. That is, for all but a few special cases, @code{eval} creates a -lambda expression, calls @code{compile} on the lambda expression to -create a compiled function, and then calls @code{funcall} on the -resulting function object. This is explicitly allowed by the ANSI -standard, but leads to some oddities, e.g. collapsing @code{functionp} -and @code{compiled-function-p} into the same predicate. - -SBCL is quite strict about ANSI's definition of -@code{defconstant}. ANSI says that doing @code{defconstant} of the -same symbol more than once is undefined unless the new value is -@code{eql} to the old value. Conforming to this specification is a -nuisance when the ``constant'' value is only constant under some -weaker test like @code{string=} or @code{equal}. It's especially -annoying because, in SBCL, @code{defconstant} takes effect not only at -load time but also at compile time, so that just compiling and loading -reasonable code like - -@lisp -(defconstant +foobyte+ '(1 4)) -@end lisp - -runs into this undefined behavior. Many implementations of Common Lisp -try to help the programmer around this annoyance by silently accepting -the undefined code and trying to do what the programmer probably -meant. SBCL instead treats the undefined behavior as an error. Often -such code can be rewritten in portable ANSI Common Lisp which has the -desired behavior. E.g., the code above can be given an exactly -defined meaning by replacing @code{defconstant} either with -@code{defparameter} or with a customized macro which does the right -thing, possibly along the lines of the @code{defconstant-eqx} macro -used internally in the implementation of SBCL itself. In -circumstances where this is not appropriate, the programmer can handle -the condition type @code{sb-ext:defconstant-uneql}, and choose either -the @command{continue} or @command{abort} restart as appropriate. - -SBCL gives style warnings about various kinds of perfectly legal code, -e.g. - -@itemize - -@item -@code{defmethod} without @code{defgeneric} - -@item -multiple @code{defun}s of the same symbol - -@item -special variables not named in the conventional @code{*foo*} style, -and lexical variables unconventionally named in the @code{*foo*} style - -@end itemize - -This causes friction with people who point out that other ways of -organizing code (especially avoiding the use of @code{defgeneric}) are -just as aesthetically stylish. However, these warnings should be read -not as ``warning, bad aesthetics detected, you have no style'' but -``warning, this style keeps the compiler from understanding the code -as well as you might like.'' That is, unless the compiler warns about -such conditions, there's no way for the compiler to warn about some -programming errors which would otherwise be easy to overlook. (Related -bug: The warning about multiple @code{defun}s is pointlessly annoying -when you compile and then load a function containing @code{defun} -wrapped in @code{eval-when}, and ideally should be suppressed in that -case, but still isn't as of SBCL 0.7.6.) - - -@node Extensions -@comment node-name, next, previous, up -@section Extensions +@chapter Beyond the ANSI Standard SBCL is derived from CMUCL, which implements many extensions to the ANSI standard. SBCL doesn't support as many extensions as CMUCL, but -it still has quite a few. - +it still has quite a few. @xref{Contributed Modules}. @menu -* Things Which Might Be In The Next ANSI Standard:: -* Threading:: +* Garbage Collection:: +* Metaobject Protocol:: * Support For Unix:: * Customization Hooks for Users:: * Tools To Help Developers:: -* Interface To Low-Level SBCL Implementation:: +* Resolution of Name Conflicts:: * 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 -@subsection Things Which Might Be In The Next ANSI Standard - -SBCL provides extensive support for calling external C code, @ref{The -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 -the abstract @code{metaobject} class is not present in the class -hierarchy; - -@item -the @code{standard-object} and @code{funcallable-standard-object} -classes are disjoint; - -@item -@code{compute-effective-method} only returns one value, not two; - -@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. - -@end itemize - - -@node Threading -@comment node-name, next, previous, up -@subsection Threading (a.k.a Multiprocessing) - -SBCL (as of version 0.8.3, on Linux x86 only) supports a fairly -low-level threading interface that maps onto the host operating -system's concept of threads or lightweight processes. - -@subsubsection Lisp-level view +@findex compute-effective-method +@findex sb-mop:compute-effective-method +@code{compute-effective-method} only returns one value, not two. -A rudimentary interface to creating and managing multiple threads can -be found in the @dfn{sb-thread} package. This is intended for public -consumption, so look at the exported symbols and their documentation -strings. - -Dynamic bindings to symbols are per-thread. Signal handlers are -per-thread. - -Mutexes and condition variables are available for managing access to -shared data: see - -@itemize - -@item -@code{(apropos "mutex" :sb-thread)} +There is no record of what the second return value was meant to +indicate, and apparently no clients for it. @item -@code{(apropos "condition" :sb-thread)} - +@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 -and the @code{waitqueue} structure +@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 for +@code{validate-superclass} for @code{standard-class} and +@code{funcallable-standard-class} to be 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 +At class finalization, 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. @end itemize -and poke around in their documentation strings. - -@subsubsection Sessions - -If the user has multiple views onto the same Lisp image (for example, -using multiple terminals, or a windowing system, or network access) -they are typically set up as multiple @dfn{sessions} such that each -view has its own collection of foreground/background/stopped threads. -A thread which wishes to create a new session can use -@code{sb-thread:with-new-session} to remove itself from the current -session (which it shares with its parent and siblings) and create a -fresh one. See also @code{sb-thread:make-listener-thread}. - -Within a single session, threads arbitrate between themselves for the -user's attention. A thread may be in one of three notional states: -foreground, background, or stopped. When a background process -attempts to print a repl prompt or to enter the debugger, it will stop -and print a message saying that it has stopped. The user at his -leisure may switch to that thread to find out what it needs. If a -background thread enters the debugger, selecting any restart will put -it back into the background before it resumes. Arbitration for the -input stream is managed by calls to @code{sb-thread:get-foreground} -(which may block) and @code{sb-thread:release-foreground}. - -@code{sb-ext:quit} terminates all threads in the current session, but -leaves other sessions running. - - -@subsubsection Implementation (Linux x86) - -On Linux x86, threading is implemented using @code{clone()} and does -not involve pthreads. This is not because there is anything wrong -with pthreads @emph{per se}, but there is plenty wrong (from our -perspective) with LinuxThreads. SBCL threads are mapped 1:1 onto -Linux tasks which share a VM but nothing else - each has its own -process id and can be seen in e.g. @command{ps} output. - -Per-thread local bindings for special variables is achieved using the -%fs segment register to point to a per-thread storage area. This may -cause interesting results if you link to foreign code that expects -threading or creates new threads, and the thread library in question -uses %fs in an incompatible way. - -There are two implementation mechanisms for queueing. If SBCL was -built on an NPTL-capable Linux system (2.6 or some vendor 2.4 ports) -with the @code{:SB-FUTEX} feature, queuing will be done using the -@code{sys_futex()} system call if it's available at runtime. -Otherwise it will fall back to using @code{sigtimedwait()} to sleep -and a signal (@code{SIG_DEQUEUE}, one of the POSIX RT signals) to -wake. - -Garbage collection is done with the existing Conservative Generational -GC. Allocation is done in small (typically 8k) regions: each thread -has its own region so this involves no stopping. However, when a -region fills, a lock must be obtained while another is allocated, and -when a collection is required, all processes are stopped. This is -achieved by sending them signals, which may make for interesting -behaviour if they are interrupted in system calls. The streams -interface is believed to handle the required system call restarting -correctly, but this may be a consideration when making other blocking -calls e.g. from foreign library code. - -Large amounts of the SBCL library have not been inspected for -thread-safety. Some of the obviously unsafe areas have large locks -around them, so compilation and fasl loading, for example, cannot be -parallelized. Work is ongoing in this area. - -A new thread by default is created in the same POSIX process group and -session as the thread it was created by. This has an impact on -keyboard interrupt handling: pressing your terminal's intr key -(typically @kbd{Control-C}) will interrupt all processes in the -foreground process group, including Lisp threads that SBCL considers -to be notionally `background'. This is undesirable, so background -threads are set to ignore the SIGINT signal. - -@code{sb-thread:make-listener-thread} in addition to creating a new -Lisp session makes a new POSIX session, so that pressing -@kbd{Control-C} in one window will not interrupt another listener - -this has been found to be embarrassing. - - @node Support For Unix @comment node-name, next, previous, up -@subsection Support For Unix +@section Support For Unix The UNIX command line can be read from the variable @code{sb-ext:*posix-argv*}. The UNIX environment can be queried with @@ -297,17 +130,10 @@ the @code{sb-ext:posix-getenv} function. @include fun-sb-ext-posix-getenv.texinfo -The SBCL system can be terminated with @code{sb-ext:quit}, (but see -notes in @ref{Threading} about the interaction between this feature and -sessions) optionally returning a specified numeric value to the -calling Unix process. The normal Unix idiom of terminating on end of -file on input is also supported. - -@include fun-sb-ext-quit.texinfo @node Customization Hooks for Users @comment node-name, next, previous, up -@subsection Customization Hooks for Users +@section Customization Hooks for Users The toplevel repl prompt may be customized, and the function that reads user input may be replaced completely. @@ -318,45 +144,42 @@ implementation-defined. In SBCL, @code{require} behaves in the following way: @include fun-common-lisp-require.texinfo - @include var-sb-ext-star-module-provider-functions-star.texinfo +Although SBCL does not provide a resident editor, the @code{ed} +function can be customized to hook into user-provided editing +mechanisms as follows: + +@include fun-common-lisp-ed.texinfo +@include var-sb-ext-star-ed-functions-star.texinfo -@node Tools To Help Developers +@node Tools To Help Developers @comment node-name, next, previous, up -@subsection Tools To Help Developers +@section Tools To Help Developers SBCL provides a profiler and other extensions to the ANSI @code{trace} -facility. For more information, see @ref{macro-common-lisp-trace}. +facility. For more information, see @ref{Macro common-lisp:trace}. The debugger supports a number of options. Its documentation is -accessed by typing @kbd{help} at the debugger prompt. @xref{The -Debugger}. +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 -@node Interface To Low-Level SBCL Implementation -@comment node-name, next, previous, up -@subsection Interface To Low-Level SBCL Implementation - -SBCL has the ability to save its state as a file for later -execution. This functionality is important for its bootstrapping -process, and is also provided as an extension to the user. Note that -foreign libraries loaded via @code{load-1-foreign} don't survive this -process; a core should not be saved in this case. - -@emph{FIXME: what should be done for foreign libraries?} - -@emph{FIXME: document load-1-foreign somewhere} - -@include fun-sb-ext-save-lisp-and-die.texinfo - +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 Stale Extensions @comment node-name, next, previous, up -@subsection Stale Extensions +@section Stale Extensions SBCL has inherited from CMUCL various hooks to allow the user to tweak and monitor the garbage collection process. These are somewhat @@ -378,24 +201,24 @@ list. @node Efficiency Hacks @comment node-name, next, previous, up -@subsection Efficiency Hacks +@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 -@code{sb-ext:truly-the} special form declares the type of the result -of the operations, producing its argument; the declaration is not -checked. In short: don't use it. +The @code{sb-ext:truly-the} special form declares the type of the +result of the operations, producing its argument; the declaration is +not checked. In short: don't use it. @include special-operator-sb-ext-truly-the.texinfo