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 There is no record of what the second return value was meant to
  53 indicate, and apparently no clients for it.
  54
  55 @item
  56 @findex ensure-generic-function
  57 @findex generic-function-declarations
  58 @findex sb-mop:generic-function-declarations
  59 the arguments @code{:declare} and @code{:declarations} to
  60 @code{ensure-generic-function} are both accepted, with the leftmost
  61 argument defining the declarations to be stored and returned by
  62 @code{generic-function-declarations}.
  63
  64 Where AMOP specifies @code{:declarations} as the keyword argument to
  65 @code{ensure-generic-function}, the Common Lisp standard specifies
  66 @code{:declare}.  Portable code should use @code{:declare}.
  67
  68 @item
  69 @findex validate-superclass
  70 @findex finalize-inheritance
  71 @findex sb-mop:validate-superclass
  72 @findex sb-mop:finalize-inheritance
  73 @tindex standard-class
  74 @tindex funcallable-standard-class
  75 @tindex sb-mop:funcallable-standard-class
  76 @tindex function
  77 @findex sb-mop:class-prototype
  78 @findex class-prototype
  79 although SBCL obeys the requirement in AMOP for
  80 @code{validate-superclass} for @code{standard-class} and
  81 @code{funcallable-standard-class} to be compatible metaclasses, we
  82 impose an additional requirement at class finalization time: a class
  83 of metaclass @code{funcallable-standard-class} must have
  84 @code{function} in its superclasses, and a class of metaclass
  85 @code{standard-class} must not.
  86
  87 @findex typep
  88 @findex class-of
  89 @findex subtypep
  90 At class finalization, a class prototype which is accessible by a
  91 standard mop function @code{sb-mop:class-prototype}.  The user can
  92 then ask whether this object is a @code{function} or not in several
  93 different ways: whether it is a function according to @code{typep};
  94 whether its @code{class-of} is @code{subtypep} @code{function}, or
  95 whether @code{function} appears in the superclasses of the class.  The
  96 additional consistency requirement comes from the desire to make all
  97 of these answers the same.
  98
  99 The following class definitions are bad, and will lead to errors
 100 either immediately or if an instance is created:
 101 @lisp
 102 (defclass bad-object (funcallable-standard-object)
 103   ()
 104   (:metaclass standard-class))
 105 @end lisp
 106 @lisp
 107 (defclass bad-funcallable-object (standard-object)
 108   ()
 109   (:metaclass funcallable-standard-class))
 110 @end lisp
 111 The following definition is acceptable:
 112 @lisp
 113 (defclass mixin ()
 114   ((slot :initarg slot)))
 115 (defclass funcallable-object (funcallable-standard-object mixin)
 116   ()
 117   (:metaclass funcallable-standard-class))
 118 @end lisp
 119 and leads to a class whose instances are funcallable and have one slot.
 120
 121 @item
 122 the requirement that ``No portable class @math{C_p} may inherit, by
 123 virtue of being a direct or indirect subclass of a specified class, any
 124 slot for which the name is a symbol accessible in the
 125 @code{common-lisp-user} package or exported by any package defined in
 126 the ANSI Common Lisp standard.'' is interpreted to mean that the
 127 standardized classes themselves should not have slots named by external
 128 symbols of public packages.
 129
 130 The rationale behind the restriction is likely to be similar to the ANSI
 131 Common Lisp restriction on defining functions, variables and types named
 132 by symbols in the Common Lisp package: preventing two independent pieces
 133 of software from colliding with each other.
 134
 135 @item
 136 @findex slot-value-using-class
 137 @findex sb-mop:slot-value-using-class
 138 @findex (setf slot-value-using-class)
 139 @findex (setf sb-mop:slot-value-using-class)
 140 @findex slot-boundp-using-class
 141 @findex sb-mop:slot-boundp-using-class
 142 specializations of the @code{new-value} argument to @code{(setf
 143 sb-mop:slot-value-using-class)} are not allowed: all user-defined
 144 methods must have a specializer of the class @code{t}.
 145
 146 This prohibition is motivated by a separation of layers: the
 147 @code{slot-value-using-class} family of functions is intended for use in
 148 implementing different and new slot allocation strategies, rather than
 149 in performing application-level dispatching.  Additionally, with this
 150 requirement, there is a one-to-one mapping between metaclass, class and
 151 slot-definition-class tuples and effective methods of @code{(setf
 152 slot-value-using-class)}, which permits optimization of @code{(setf
 153 slot-value-using-class)}'s discriminating function in the same manner as
 154 for @code{slot-value-using-class} and @code{slot-boundp-using-class}.
 155
 156 Note that application code may specialize on the @code{new-value}
 157 argument of slot accessors.
 158
 159 @end itemize
 160
 161 @node  Support For Unix
 162 @comment  node-name,  next,  previous,  up
 163 @section Support For Unix
 164
 165 The UNIX command line can be read from the variable
 166 @code{sb-ext:*posix-argv*}. The UNIX environment can be queried with
 167 the @code{sb-ext:posix-getenv} function.
 168
 169 @include fun-sb-ext-posix-getenv.texinfo
 170
 171 External programs can be run with @code{sb-ext:run-program}.
 172
 173 @include fun-sb-ext-run-program.texinfo
 174
 175 @include fun-sb-ext-process-p.texinfo
 176
 177 @include fun-sb-ext-process-input.texinfo
 178
 179 @include fun-sb-ext-process-output.texinfo
 180
 181 @include fun-sb-ext-process-error.texinfo
 182
 183 @include fun-sb-ext-process-alive-p.texinfo
 184
 185 @include fun-sb-ext-process-status.texinfo
 186
 187 @include fun-sb-ext-process-wait.texinfo
 188
 189 @include fun-sb-ext-process-exit-code.texinfo
 190
 191 @include fun-sb-ext-process-core-dumped.texinfo
 192
 193 @include fun-sb-ext-process-close.texinfo
 194
 195 @include fun-sb-ext-process-kill.texinfo
 196
 197 @node  Customization Hooks for Users
 198 @comment  node-name,  next,  previous,  up
 199 @section Customization Hooks for Users
 200
 201 The toplevel repl prompt may be customized, and the function
 202 that reads user input may be replaced completely.
 203 @c <!-- FIXME but I don't currently remember how -->
 204
 205 The behaviour of @code{require} when called with only one argument is
 206 implementation-defined.  In SBCL, @code{require} behaves in the
 207 following way:
 208
 209 @include fun-common-lisp-require.texinfo
 210 @include var-sb-ext-star-module-provider-functions-star.texinfo
 211
 212 Although SBCL does not provide a resident editor, the @code{ed}
 213 function can be customized to hook into user-provided editing
 214 mechanisms as follows:
 215
 216 @include fun-common-lisp-ed.texinfo
 217 @include var-sb-ext-star-ed-functions-star.texinfo
 218
 219 @node Tools To Help Developers
 220 @comment  node-name,  next,  previous,  up
 221 @section Tools To Help Developers
 222
 223 SBCL provides a profiler and other extensions to the ANSI @code{trace}
 224 facility.  For more information, see @ref{Macro common-lisp:trace}.
 225
 226 The debugger supports a number of options. Its documentation is
 227 accessed by typing @kbd{help} at the debugger prompt. @xref{Debugger}.
 228
 229 Documentation for @code{inspect} is accessed by typing @kbd{help} at
 230 the @code{inspect} prompt.
 231
 232 @node Resolution of Name Conflicts
 233 @section Resolution of Name Conflicts
 234
 235 The ANSI standard (section 11.1.1.2.5) requires that name conflicts in
 236 packages be resolvable in favour of any of the conflicting symbols.  In
 237 the interactive debugger, this is achieved by prompting for the symbol
 238 in whose favour the conflict should be resolved; for programmatic use,
 239 the @code{sb-ext:resolve-conflict} restart should be invoked with one
 240 argument, which should be a member of the list returned by the condition
 241 accessor @code{sb-ext:name-conflict-symbols}.
 242
 243 @node Stale Extensions
 244 @comment  node-name,  next,  previous,  up
 245 @section 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 @section 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 again
 271 attempting to collect them as garbage. This can cause a large increase
 272 in efficiency when using a primitive garbage collector, or a more
 273 moderate increase in efficiency when using a more sophisticated garbage
 274 collector which is well suited to the program's memory usage pattern. It
 275 also allows permanent code to be frozen at fixed addresses, a
 276 precondition for using copy-on-write to share code between multiple Lisp
 277 processes.  This is less important with modern generational garbage
 278 collectors, but not all SBCL platforms use such a garbage collector.
 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. -->