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 * Garbage Collection::
  11 * Metaobject Protocol::
  12 * Support For Unix::
  13 * Customization Hooks for Users::
  14 * Tools To Help Developers::
  15 * Resolution of Name Conflicts::
  16 * Stale Extensions::
  17 * Efficiency Hacks::
  18 @end menu
  19
  20 @node  Garbage Collection
  21 @comment  node-name,  next,  previous,  up
  22 @section Garbage Collection
  23
  24 SBCL provides additional garbage collection functionality not
  25 specified by ANSI. Weak pointers allow references to objects to be
  26 maintained without keeping them from being garbage collected, and
  27 ``finalization'' hooks are available to cause code to be executed when
  28 an object has been garbage collected. Additionally users can specify
  29 their own cleanup actions to be executed with garbage collection.
  30
  31 @include fun-sb-ext-finalize.texinfo
  32 @include fun-sb-ext-cancel-finalization.texinfo
  33 @include fun-sb-ext-make-weak-pointer.texinfo
  34 @include fun-sb-ext-weak-pointer-value.texinfo
  35 @include var-sb-ext-star-after-gc-hooks-star.texinfo
  36
  37 @node Metaobject Protocol
  38 @comment  node-name,  next,  previous,  up
  39 @section Metaobject Protocol
  40
  41 SBCL supports a metaobject protocol which is intended to be compatible
  42 with AMOP; present exceptions to this (as distinct from current bugs)
  43 are:
  44
  45 @itemize
  46
  47 @item
  48 the abstract @code{metaobject} class is not present in the class
  49 hierarchy;
  50
  51 @item
  52 the @code{standard-object} and @code{funcallable-standard-object}
  53 classes are disjoint;
  54
  55 @item
  56 @code{compute-effective-method} only returns one value, not two;
  57
  58 @item
  59 the system-supplied @code{:around} method for @code{compute-slots}
  60 specialized on @code{funcallable-standard-class} does not respect the
  61 requested order from a user-supplied primary method.
  62
  63 @end itemize
  64
  65 @node  Support For Unix
  66 @comment  node-name,  next,  previous,  up
  67 @section Support For Unix
  68
  69 The UNIX command line can be read from the variable
  70 @code{sb-ext:*posix-argv*}. The UNIX environment can be queried with
  71 the @code{sb-ext:posix-getenv} function.
  72
  73 @include fun-sb-ext-posix-getenv.texinfo
  74
  75
  76 @node  Customization Hooks for Users
  77 @comment  node-name,  next,  previous,  up
  78 @section Customization Hooks for Users
  79
  80 The toplevel repl prompt may be customized, and the function
  81 that reads user input may be replaced completely.
  82 @c <!-- FIXME but I don't currently remember how -->
  83
  84 The behaviour of @code{require} when called with only one argument is
  85 implementation-defined.  In SBCL, @code{require} behaves in the
  86 following way:
  87
  88 @include fun-common-lisp-require.texinfo
  89 @include var-sb-ext-star-module-provider-functions-star.texinfo
  90
  91 Although SBCL does not provide a resident editor, the @code{ed}
  92 function can be customized to hook into user-provided editing
  93 mechanisms as follows:
  94
  95 @include fun-common-lisp-ed.texinfo
  96 @include var-sb-ext-star-ed-functions-star.texinfo
  97
  98 @node Tools To Help Developers
  99 @comment  node-name,  next,  previous,  up
 100 @section Tools To Help Developers
 101
 102 SBCL provides a profiler and other extensions to the ANSI @code{trace}
 103 facility.  For more information, see @ref{Macro common-lisp:trace}.
 104
 105 The debugger supports a number of options. Its documentation is
 106 accessed by typing @kbd{help} at the debugger prompt. @xref{Debugger}.
 107
 108 Documentation for @code{inspect} is accessed by typing @kbd{help} at
 109 the @code{inspect} prompt.
 110
 111 @node Resolution of Name Conflicts
 112 @section Resolution of Name Conflicts
 113
 114 The ANSI standard (section 11.1.1.2.5) requires that name conflicts in
 115 packages be resolvable in favour of any of the conflicting symbols.  In
 116 the interactive debugger, this is achieved by prompting for the symbol
 117 in whose favour the conflict should be resolved; for programmatic use,
 118 the @code{sb-ext:resolve-conflict} restart should be invoked with one
 119 argument, which should be a member of the list returned by the condition
 120 accessor @code{sb-ext:name-conflict-symbols}.
 121
 122 @node Stale Extensions
 123 @comment  node-name,  next,  previous,  up
 124 @section Stale Extensions
 125
 126 SBCL has inherited from CMUCL various hooks to allow the user to
 127 tweak and monitor the garbage collection process. These are somewhat
 128 stale code, and their interface might need to be cleaned up. If you
 129 have urgent need of them, look at the code in @file{src/code/gc.lisp}
 130 and bring it up on the developers' mailing list.
 131
 132 SBCL has various hooks inherited from CMUCL, like
 133 @code{sb-ext:float-denormalized-p}, to allow a program to take
 134 advantage of IEEE floating point arithmetic properties which aren't
 135 conveniently or efficiently expressible using the ANSI standard. These
 136 look good, and their interface looks good, but IEEE support is
 137 slightly broken due to a stupid decision to remove some support for
 138 infinities (because it wasn't in the ANSI spec and it didn't occur to
 139 me that it was in the IEEE spec). If you need this stuff, take a look
 140 at the code and bring it up on the developers' mailing
 141 list.
 142
 143
 144 @node  Efficiency Hacks
 145 @comment  node-name,  next,  previous,  up
 146 @section Efficiency Hacks
 147
 148 The @code{sb-ext:purify} function causes SBCL first to collect all
 149 garbage, then to mark all uncollected objects as permanent, never again
 150 attempting to collect them as garbage. This can cause a large increase
 151 in efficiency when using a primitive garbage collector, or a more
 152 moderate increase in efficiency when using a more sophisticated garbage
 153 collector which is well suited to the program's memory usage pattern. It
 154 also allows permanent code to be frozen at fixed addresses, a
 155 precondition for using copy-on-write to share code between multiple Lisp
 156 processes.  This is less important with modern generational garbage
 157 collectors, but not all SBCL platforms use such a garbage collector.
 158
 159 @include fun-sb-ext-purify.texinfo
 160
 161 The @code{sb-ext:truly-the} special form declares the type of the
 162 result of the operations, producing its argument; the declaration is
 163 not checked. In short: don't use it.
 164
 165 @include special-operator-sb-ext-truly-the.texinfo
 166
 167 The @code{sb-ext:freeze-type} declaration declares that a
 168 type will never change, which can make type testing
 169 (@code{typep}, etc.) more efficient for structure types.
 170
 171 The @code{sb-ext:constant-function} declaration specifies
 172 that a function will always return the same value for the same
 173 arguments, which may allow the compiler to optimize calls
 174 to it. This is appropriate for functions like @code{sqrt}, but
 175 is @emph{not} appropriate for functions like @code{aref},
 176 which can change their return values when the underlying data are
 177 changed.
 178 @c <!-- FIXME: This declaration does not seem to be supported in the
 179 @c      current compiler. -->