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 @findex compute-effective-method
  49 @findex sb-mop:compute-effective-method
  50 @code{compute-effective-method} only returns one value, not two;
  51
  52 @item
  53 @findex compute-slots
  54 @findex sb-mop:compute-slots
  55 @tindex funcallable-standard-class
  56 @tindex sb-mop:funcallable-standard-class
  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 @item
  62 @findex ensure-generic-function
  63 @findex generic-function-declarations
  64 @findex sb-mop:generic-function-declarations
  65 the arguments @code{:declare} and @code{:declarations} to
  66 @code{ensure-generic-function} are both accepted, with the leftmost
  67 argument defining the declarations to be stored and returned by
  68 @code{generic-function-declarations}.
  69
  70 @item
  71 @findex validate-superclass
  72 @findex finalize-inheritance
  73 @findex sb-mop:validate-superclass
  74 @findex sb-mop:finalize-inheritance
  75 @tindex standard-class
  76 @tindex funcallable-standard-class
  77 @tindex sb-mop:funcallable-standard-class
  78 although we obey the requirement in AMOP for @code{validate-superclass}
  79 for @code{standard-class} and @code{funcallable-standard-class} to be
  80 compatible metaclasses, we impose an additional requirement at class
  81 finalization time: a class of metaclass
  82 @code{funcallable-standard-class} must have @code{function} in its
  83 superclasses, and a class of metaclass @code{standard-class} must not.
  84
  85 @end itemize
  86
  87 @node  Support For Unix
  88 @comment  node-name,  next,  previous,  up
  89 @section Support For Unix
  90
  91 The UNIX command line can be read from the variable
  92 @code{sb-ext:*posix-argv*}. The UNIX environment can be queried with
  93 the @code{sb-ext:posix-getenv} function.
  94
  95 @include fun-sb-ext-posix-getenv.texinfo
  96
  97
  98 @node  Customization Hooks for Users
  99 @comment  node-name,  next,  previous,  up
 100 @section Customization Hooks for Users
 101
 102 The toplevel repl prompt may be customized, and the function
 103 that reads user input may be replaced completely.
 104 @c <!-- FIXME but I don't currently remember how -->
 105
 106 The behaviour of @code{require} when called with only one argument is
 107 implementation-defined.  In SBCL, @code{require} behaves in the
 108 following way:
 109
 110 @include fun-common-lisp-require.texinfo
 111 @include var-sb-ext-star-module-provider-functions-star.texinfo
 112
 113 Although SBCL does not provide a resident editor, the @code{ed}
 114 function can be customized to hook into user-provided editing
 115 mechanisms as follows:
 116
 117 @include fun-common-lisp-ed.texinfo
 118 @include var-sb-ext-star-ed-functions-star.texinfo
 119
 120 @node Tools To Help Developers
 121 @comment  node-name,  next,  previous,  up
 122 @section Tools To Help Developers
 123
 124 SBCL provides a profiler and other extensions to the ANSI @code{trace}
 125 facility.  For more information, see @ref{Macro common-lisp:trace}.
 126
 127 The debugger supports a number of options. Its documentation is
 128 accessed by typing @kbd{help} at the debugger prompt. @xref{Debugger}.
 129
 130 Documentation for @code{inspect} is accessed by typing @kbd{help} at
 131 the @code{inspect} prompt.
 132
 133 @node Resolution of Name Conflicts
 134 @section Resolution of Name Conflicts
 135
 136 The ANSI standard (section 11.1.1.2.5) requires that name conflicts in
 137 packages be resolvable in favour of any of the conflicting symbols.  In
 138 the interactive debugger, this is achieved by prompting for the symbol
 139 in whose favour the conflict should be resolved; for programmatic use,
 140 the @code{sb-ext:resolve-conflict} restart should be invoked with one
 141 argument, which should be a member of the list returned by the condition
 142 accessor @code{sb-ext:name-conflict-symbols}.
 143
 144 @node Stale Extensions
 145 @comment  node-name,  next,  previous,  up
 146 @section Stale Extensions
 147
 148 SBCL has inherited from CMUCL various hooks to allow the user to
 149 tweak and monitor the garbage collection process. These are somewhat
 150 stale code, and their interface might need to be cleaned up. If you
 151 have urgent need of them, look at the code in @file{src/code/gc.lisp}
 152 and bring it up on the developers' mailing list.
 153
 154 SBCL has various hooks inherited from CMUCL, like
 155 @code{sb-ext:float-denormalized-p}, to allow a program to take
 156 advantage of IEEE floating point arithmetic properties which aren't
 157 conveniently or efficiently expressible using the ANSI standard. These
 158 look good, and their interface looks good, but IEEE support is
 159 slightly broken due to a stupid decision to remove some support for
 160 infinities (because it wasn't in the ANSI spec and it didn't occur to
 161 me that it was in the IEEE spec). If you need this stuff, take a look
 162 at the code and bring it up on the developers' mailing
 163 list.
 164
 165
 166 @node  Efficiency Hacks
 167 @comment  node-name,  next,  previous,  up
 168 @section Efficiency Hacks
 169
 170 The @code{sb-ext:purify} function causes SBCL first to collect all
 171 garbage, then to mark all uncollected objects as permanent, never again
 172 attempting to collect them as garbage. This can cause a large increase
 173 in efficiency when using a primitive garbage collector, or a more
 174 moderate increase in efficiency when using a more sophisticated garbage
 175 collector which is well suited to the program's memory usage pattern. It
 176 also allows permanent code to be frozen at fixed addresses, a
 177 precondition for using copy-on-write to share code between multiple Lisp
 178 processes.  This is less important with modern generational garbage
 179 collectors, but not all SBCL platforms use such a garbage collector.
 180
 181 @include fun-sb-ext-purify.texinfo
 182
 183 The @code{sb-ext:truly-the} special form declares the type of the
 184 result of the operations, producing its argument; the declaration is
 185 not checked. In short: don't use it.
 186
 187 @include special-operator-sb-ext-truly-the.texinfo
 188
 189 The @code{sb-ext:freeze-type} declaration declares that a
 190 type will never change, which can make type testing
 191 (@code{typep}, etc.) more efficient for structure types.
 192
 193 The @code{sb-ext:constant-function} declaration specifies
 194 that a function will always return the same value for the same
 195 arguments, which may allow the compiler to optimize calls
 196 to it. This is appropriate for functions like @code{sqrt}, but
 197 is @emph{not} appropriate for functions like @code{aref},
 198 which can change their return values when the underlying data are
 199 changed.
 200 @c <!-- FIXME: This declaration does not seem to be supported in the
 201 @c      current compiler. -->