doc/manual/beyond-ansi.texinfo

   1 @node  Beyond the ANSI Standard
   2 @comment  node-name,  next,  previous,  up
   3 @chapter Beyond the ANSI Standard
   4
   5 SBCL is mostly an implementation of the ANSI standard for
   6 Common Lisp. However, there's some important behavior which extends
   7 or clarifies the standard, and various behavior which outright
   8 violates the standard.
   9
  10
  11 @menu
  12 * Non-Conformance With The ANSI Standard::
  13 * Idiosyncrasies::
  14 * Extensions::
  15 @end menu
  16
  17 @node Non-Conformance With The ANSI Standard
  18 @comment  node-name,  next,  previous,  up
  19 @section Non-Conformance With The ANSI Standard
  20
  21 Essentially every type of non-conformance is considered a bug.  (The
  22 exceptions involve internal inconsistencies in the standard.)  In SBCL
  23 0.7.6, the master record of known bugs is in the @file{BUGS} file in
  24 the distribution.  Some highlight information about bugs may also be
  25 found in the manual page. The recommended way to report bugs is
  26 through the sbcl-help or sbcl-devel mailing lists.  For mailing list
  27 addresses, @xref{More SBCL Information}.
  28
  29
  30 @node Idiosyncrasies
  31 @comment  node-name,  next,  previous,  up
  32 @section Idiosyncrasies
  33
  34 The information in this section describes some of the ways that SBCL
  35 deals with choices that the ANSI standard leaves to the
  36 implementation.
  37
  38 Declarations are generally treated as assertions. This general
  39 principle, and its implications, and the bugs which still keep the
  40 compiler from quite satisfying this principle, are discussed in
  41 @ref{Compiler}.
  42
  43 SBCL is essentially a compiler-only implementation of Common
  44 Lisp. That is, for all but a few special cases, @code{eval} creates a
  45 lambda expression, calls @code{compile} on the lambda expression to
  46 create a compiled function, and then calls @code{funcall} on the
  47 resulting function object. This is explicitly allowed by the ANSI
  48 standard, but leads to some oddities, e.g. collapsing @code{functionp}
  49 and @code{compiled-function-p} into the same predicate.
  50
  51 @findex defconstant
  52 SBCL is quite strict about ANSI's definition of
  53 @code{defconstant}. ANSI says that doing @code{defconstant} of the
  54 same symbol more than once is undefined unless the new value is
  55 @code{eql} to the old value. Conforming to this specification is a
  56 nuisance when the ``constant'' value is only constant under some
  57 weaker test like @code{string=} or @code{equal}. It's especially
  58 annoying because, in SBCL, @code{defconstant} takes effect not only at
  59 load time but also at compile time, so that just compiling and loading
  60 reasonable code like
  61 @lisp
  62 (defconstant +foobyte+ '(1 4))
  63 @end lisp
  64 runs into this undefined behavior. Many implementations of Common Lisp
  65 try to help the programmer around this annoyance by silently accepting
  66 the undefined code and trying to do what the programmer probably
  67 meant. SBCL instead treats the undefined behavior as an error. Often
  68 such code can be rewritten in portable ANSI Common Lisp which has the
  69 desired behavior.  E.g., the code above can be given an exactly
  70 defined meaning by replacing @code{defconstant} either with
  71 @code{defparameter} or with a customized macro which does the right
  72 thing, possibly along the lines of the @code{defconstant-eqx} macro
  73 used internally in the implementation of SBCL itself.  In
  74 circumstances where this is not appropriate, the programmer can handle
  75 the condition type @code{sb-ext:defconstant-uneql}, and choose either
  76 the @command{continue} or @command{abort} restart as appropriate.
  77
  78 SBCL gives style warnings about various kinds of perfectly legal code,
  79 e.g.
  80
  81 @itemize
  82
  83 @item
  84 @code{defmethod} without a preceding @code{defgeneric};
  85
  86 @item
  87 multiple @code{defun}s of the same symbol in different units;
  88
  89 @item
  90 special variables not named in the conventional @code{*foo*} style,
  91 and lexical variables unconventionally named in the @code{*foo*} style
  92
  93 @end itemize
  94
  95 This causes friction with people who point out that other ways of
  96 organizing code (especially avoiding the use of @code{defgeneric}) are
  97 just as aesthetically stylish.  However, these warnings should be read
  98 not as ``warning, bad aesthetics detected, you have no style'' but
  99 ``warning, this style keeps the compiler from understanding the code
 100 as well as you might like.'' That is, unless the compiler warns about
 101 such conditions, there's no way for the compiler to warn about some
 102 programming errors which would otherwise be easy to overlook. (Related
 103 bug: The warning about multiple @code{defun}s is pointlessly annoying
 104 when you compile and then load a function containing @code{defun}
 105 wrapped in @code{eval-when}, and ideally should be suppressed in that
 106 case, but still isn't as of SBCL 0.7.6.)
 107
 108
 109 @node  Extensions
 110 @comment  node-name,  next,  previous,  up
 111 @section Extensions
 112
 113 SBCL is derived from CMUCL, which implements many extensions to the
 114 ANSI standard. SBCL doesn't support as many extensions as CMUCL, but
 115 it still has quite a few.  @xref{Contributed Modules}.
 116
 117
 118 @menu
 119 * Things Which Might Be In The Next ANSI Standard::
 120 * Support For Unix::
 121 * Customization Hooks for Users::
 122 * Tools To Help Developers::
 123 * Interface To Low-Level SBCL Implementation::
 124 * Stale Extensions::
 125 * Efficiency Hacks::
 126 @end menu
 127
 128 @node  Things Which Might Be In The Next ANSI Standard
 129 @comment  node-name,  next,  previous,  up
 130 @subsection Things Which Might Be In The Next ANSI Standard
 131
 132 SBCL provides extensive support for calling external C code,
 133 @ref{Foreign Function Interface}.
 134
 135 SBCL provides additional garbage collection functionality not
 136 specified by ANSI. Weak pointers allow references to objects to be
 137 maintained without keeping them from being GCed (garbage
 138 collected). And ``finalization'' hooks are available to cause code to
 139 be executed when an object has been GCed.
 140 @c <!-- FIXME: Actually documenting these would be good.:-| -->
 141
 142 SBCL supports @dfn{Gray streams}, user-overloadable CLOS classes whose
 143 instances can be used as Lisp streams (e.g. passed as the first
 144 argument to @code{format}).  Additionally, the bundled contrib module
 145 @dfn{sb-simple-streams} implements a subset of the Franz Allegro
 146 simple-streams proposal.
 147
 148 SBCL supports a MetaObject Protocol which is intended to be compatible
 149 with AMOP; present exceptions to this (as distinct from current bugs)
 150 are:
 151
 152 @itemize
 153
 154 @item
 155 the abstract @code{metaobject} class is not present in the class
 156 hierarchy;
 157
 158 @item
 159 the @code{standard-object} and @code{funcallable-standard-object}
 160 classes are disjoint;
 161
 162 @item
 163 @code{compute-effective-method} only returns one value, not two;
 164
 165 @item
 166 the system-supplied @code{:around} method for @code{compute-slots}
 167 specialized on @code{funcallable-standard-class} does not respect the
 168 requested order from a user-supplied primary method.
 169
 170 @end itemize
 171
 172 @node  Support For Unix
 173 @comment  node-name,  next,  previous,  up
 174 @subsection Support For Unix
 175
 176 The UNIX command line can be read from the variable
 177 @code{sb-ext:*posix-argv*}. The UNIX environment can be queried with
 178 the @code{sb-ext:posix-getenv} function.
 179
 180 @include fun-sb-ext-posix-getenv.texinfo
 181
 182 The SBCL system can be terminated with @code{sb-ext:quit}, (but see
 183 notes in @ref{Threading} about the interaction between this feature and
 184 sessions) optionally returning a specified numeric value to the
 185 calling Unix process. The normal Unix idiom of terminating on end of
 186 file on input is also supported.
 187
 188 @include fun-sb-ext-quit.texinfo
 189
 190 @node  Customization Hooks for Users
 191 @comment  node-name,  next,  previous,  up
 192 @subsection Customization Hooks for Users
 193
 194 The toplevel repl prompt may be customized, and the function
 195 that reads user input may be replaced completely.
 196 @c <!-- FIXME but I don't currently remember how -->
 197
 198 The behaviour of @code{require} when called with only one argument is
 199 implementation-defined.  In SBCL, @code{require} behaves in the
 200 following way:
 201
 202 @include fun-common-lisp-require.texinfo
 203 @include var-sb-ext-star-module-provider-functions-star.texinfo
 204
 205 Although SBCL does not provide a resident editor, the @code{ed}
 206 function can be customized to hook into user-provided editing
 207 mechanisms as follows:
 208
 209 @include fun-common-lisp-ed.texinfo
 210 @include var-sb-ext-star-ed-functions-star.texinfo
 211
 212 @node  Tools To Help Developers
 213 @comment  node-name,  next,  previous,  up
 214 @subsection Tools To Help Developers
 215
 216 SBCL provides a profiler and other extensions to the ANSI @code{trace}
 217 facility.  For more information, see @ref{macro-common-lisp-trace}.
 218
 219 The debugger supports a number of options. Its documentation is
 220 accessed by typing @kbd{help} at the debugger prompt. @xref{Debugger}.
 221
 222 Documentation for @code{inspect} is accessed by typing @kbd{help} at
 223 the @code{inspect} prompt.
 224
 225 @node  Interface To Low-Level SBCL Implementation
 226 @comment  node-name,  next,  previous,  up
 227 @subsection Interface To Low-Level SBCL Implementation
 228
 229 SBCL has the ability to save its state as a file for later
 230 execution. This functionality is important for its bootstrapping
 231 process, and is also provided as an extension to the user.  Note that
 232 foreign libraries loaded via @code{load-shared-object} don't survive
 233 this process; a core should not be saved in this case.
 234
 235 @emph{FIXME: what should be done for foreign libraries?}
 236
 237 @emph{FIXME: document load-shared-object somewhere - it's in
 238 ffi.texinfo?}
 239
 240 @include fun-sb-ext-save-lisp-and-die.texinfo
 241
 242
 243 @node Stale Extensions
 244 @comment  node-name,  next,  previous,  up
 245 @subsection Stale Extensions
 246
 247 SBCL has inherited from CMUCL various hooks to allow the user to
 248 tweak and monitor the garbage collection process. These are somewhat
 249 stale code, and their interface might need to be cleaned up. If you
 250 have urgent need of them, look at the code in @file{src/code/gc.lisp}
 251 and bring it up on the developers' mailing list.
 252
 253 SBCL has various hooks inherited from CMUCL, like
 254 @code{sb-ext:float-denormalized-p}, to allow a program to take
 255 advantage of IEEE floating point arithmetic properties which aren't
 256 conveniently or efficiently expressible using the ANSI standard. These
 257 look good, and their interface looks good, but IEEE support is
 258 slightly broken due to a stupid decision to remove some support for
 259 infinities (because it wasn't in the ANSI spec and it didn't occur to
 260 me that it was in the IEEE spec). If you need this stuff, take a look
 261 at the code and bring it up on the developers' mailing
 262 list.
 263
 264
 265 @node  Efficiency Hacks
 266 @comment  node-name,  next,  previous,  up
 267 @subsection Efficiency Hacks
 268
 269 The @code{sb-ext:purify} function causes SBCL first to collect all
 270 garbage, then to mark all uncollected objects as permanent, never
 271 again attempting to collect them as garbage. This can cause a large
 272 increase in efficiency when using a primitive garbage collector, or a
 273 more moderate increase in efficiency when using a more sophisticated
 274 garbage collector which is well suited to the program's memory usage
 275 pattern. It also allows permanent code to be frozen at fixed
 276 addresses, a precondition for using copy-on-write to share code
 277 between multiple Lisp processes. it is less important with modern
 278 generational garbage collectors.
 279
 280 @include fun-sb-ext-purify.texinfo
 281
 282 The @code{sb-ext:truly-the} special form declares the type of the
 283 result of the operations, producing its argument; the declaration is
 284 not checked. In short: don't use it.
 285
 286 @include special-operator-sb-ext-truly-the.texinfo
 287
 288 The @code{sb-ext:freeze-type} declaration declares that a
 289 type will never change, which can make type testing
 290 (@code{typep}, etc.) more efficient for structure types.
 291
 292 The @code{sb-ext:constant-function} declaration specifies
 293 that a function will always return the same value for the same
 294 arguments, which may allow the compiler to optimize calls
 295 to it. This is appropriate for functions like @code{sqrt}, but
 296 is @emph{not} appropriate for functions like @code{aref},
 297 which can change their return values when the underlying data are
 298 changed.
 299 @c <!-- FIXME: This declaration does not seem to be supported in the
 300 @c      current compiler. -->