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 derived from CMUCL, which implements many extensions to the
   6 ANSI standard. SBCL doesn't support as many extensions as CMUCL, but
   7 it still has quite a few.  @xref{Contributed Modules}.
   8
   9 @menu
  10 * Things Which Might Be In The Next ANSI Standard::
  11 * Support For Unix::
  12 * Customization Hooks for Users::
  13 * Tools To Help Developers::
  14 * Interface To Low-Level SBCL Implementation::
  15 * Stale Extensions::
  16 * Efficiency Hacks::
  17 @end menu
  18
  19 @node  Things Which Might Be In The Next ANSI Standard
  20 @comment  node-name,  next,  previous,  up
  21 @section Things Which Might Be In The Next ANSI Standard
  22
  23 SBCL provides extensive support for calling external C code,
  24 @ref{Foreign Function Interface}.
  25
  26 SBCL provides additional garbage collection functionality not
  27 specified by ANSI. Weak pointers allow references to objects to be
  28 maintained without keeping them from being GCed (garbage
  29 collected). And ``finalization'' hooks are available to cause code to
  30 be executed when an object has been GCed.
  31 @c <!-- FIXME: Actually documenting these would be good.:-| -->
  32
  33 SBCL supports @dfn{Gray streams}, user-overloadable CLOS classes whose
  34 instances can be used as Lisp streams (e.g. passed as the first
  35 argument to @code{format}).  Additionally, the bundled contrib module
  36 @dfn{sb-simple-streams} implements a subset of the Franz Allegro
  37 simple-streams proposal.
  38
  39 SBCL supports a MetaObject Protocol which is intended to be compatible
  40 with AMOP; present exceptions to this (as distinct from current bugs)
  41 are:
  42
  43 @itemize
  44
  45 @item
  46 the abstract @code{metaobject} class is not present in the class
  47 hierarchy;
  48
  49 @item
  50 the @code{standard-object} and @code{funcallable-standard-object}
  51 classes are disjoint;
  52
  53 @item
  54 @code{compute-effective-method} only returns one value, not two;
  55
  56 @item
  57 the system-supplied @code{:around} method for @code{compute-slots}
  58 specialized on @code{funcallable-standard-class} does not respect the
  59 requested order from a user-supplied primary method.
  60
  61 @end itemize
  62
  63 @node  Support For Unix
  64 @comment  node-name,  next,  previous,  up
  65 @section Support For Unix
  66
  67 The UNIX command line can be read from the variable
  68 @code{sb-ext:*posix-argv*}. The UNIX environment can be queried with
  69 the @code{sb-ext:posix-getenv} function.
  70
  71 @include fun-sb-ext-posix-getenv.texinfo
  72
  73
  74 @node  Customization Hooks for Users
  75 @comment  node-name,  next,  previous,  up
  76 @section Customization Hooks for Users
  77
  78 The toplevel repl prompt may be customized, and the function
  79 that reads user input may be replaced completely.
  80 @c <!-- FIXME but I don't currently remember how -->
  81
  82 The behaviour of @code{require} when called with only one argument is
  83 implementation-defined.  In SBCL, @code{require} behaves in the
  84 following way:
  85
  86 @include fun-common-lisp-require.texinfo
  87 @include var-sb-ext-star-module-provider-functions-star.texinfo
  88
  89 Although SBCL does not provide a resident editor, the @code{ed}
  90 function can be customized to hook into user-provided editing
  91 mechanisms as follows:
  92
  93 @include fun-common-lisp-ed.texinfo
  94 @include var-sb-ext-star-ed-functions-star.texinfo
  95
  96 @node  Tools To Help Developers
  97 @comment  node-name,  next,  previous,  up
  98 @section Tools To Help Developers
  99
 100 SBCL provides a profiler and other extensions to the ANSI @code{trace}
 101 facility.  For more information, see @ref{macro-common-lisp-trace}.
 102
 103 The debugger supports a number of options. Its documentation is
 104 accessed by typing @kbd{help} at the debugger prompt. @xref{Debugger}.
 105
 106 Documentation for @code{inspect} is accessed by typing @kbd{help} at
 107 the @code{inspect} prompt.
 108
 109 @node  Interface To Low-Level SBCL Implementation
 110 @comment  node-name,  next,  previous,  up
 111 @section Interface To Low-Level SBCL Implementation
 112
 113 SBCL has the ability to save its state as a file for later
 114 execution. This functionality is important for its bootstrapping
 115 process, and is also provided as an extension to the user.
 116
 117 Note that foreign libraries loaded via @code{load-shared-object} don't
 118 survive this process on all platforms; a core should not be saved in
 119 this case. Platforms where this is supported as of SBCL 0.8.14.5 are
 120 x86/Linux, x86/FreeBSD and sparc/SunOS.
 121
 122 @emph{FIXME: what should be done for foreign libraries?}
 123
 124 @emph{FIXME: document load-shared-object somewhere - it's in
 125 ffi.texinfo?}
 126
 127 @include fun-sb-ext-save-lisp-and-die.texinfo
 128
 129
 130 @node Stale Extensions
 131 @comment  node-name,  next,  previous,  up
 132 @section Stale Extensions
 133
 134 SBCL has inherited from CMUCL various hooks to allow the user to
 135 tweak and monitor the garbage collection process. These are somewhat
 136 stale code, and their interface might need to be cleaned up. If you
 137 have urgent need of them, look at the code in @file{src/code/gc.lisp}
 138 and bring it up on the developers' mailing list.
 139
 140 SBCL has various hooks inherited from CMUCL, like
 141 @code{sb-ext:float-denormalized-p}, to allow a program to take
 142 advantage of IEEE floating point arithmetic properties which aren't
 143 conveniently or efficiently expressible using the ANSI standard. These
 144 look good, and their interface looks good, but IEEE support is
 145 slightly broken due to a stupid decision to remove some support for
 146 infinities (because it wasn't in the ANSI spec and it didn't occur to
 147 me that it was in the IEEE spec). If you need this stuff, take a look
 148 at the code and bring it up on the developers' mailing
 149 list.
 150
 151
 152 @node  Efficiency Hacks
 153 @comment  node-name,  next,  previous,  up
 154 @section Efficiency Hacks
 155
 156 The @code{sb-ext:purify} function causes SBCL first to collect all
 157 garbage, then to mark all uncollected objects as permanent, never
 158 again attempting to collect them as garbage. This can cause a large
 159 increase in efficiency when using a primitive garbage collector, or a
 160 more moderate increase in efficiency when using a more sophisticated
 161 garbage collector which is well suited to the program's memory usage
 162 pattern. It also allows permanent code to be frozen at fixed
 163 addresses, a precondition for using copy-on-write to share code
 164 between multiple Lisp processes. it is less important with modern
 165 generational garbage collectors.
 166
 167 @include fun-sb-ext-purify.texinfo
 168
 169 The @code{sb-ext:truly-the} special form declares the type of the
 170 result of the operations, producing its argument; the declaration is
 171 not checked. In short: don't use it.
 172
 173 @include special-operator-sb-ext-truly-the.texinfo
 174
 175 The @code{sb-ext:freeze-type} declaration declares that a
 176 type will never change, which can make type testing
 177 (@code{typep}, etc.) more efficient for structure types.
 178
 179 The @code{sb-ext:constant-function} declaration specifies
 180 that a function will always return the same value for the same
 181 arguments, which may allow the compiler to optimize calls
 182 to it. This is appropriate for functions like @code{sqrt}, but
 183 is @emph{not} appropriate for functions like @code{aref},
 184 which can change their return values when the underlying data are
 185 changed.
 186 @c <!-- FIXME: This declaration does not seem to be supported in the
 187 @c      current compiler. -->