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 * Reader Extensions::
  11 * Package-Local Nicknames::
  12 * Package Variance::
  13 * Garbage Collection::
  14 * Metaobject Protocol::
  15 * Support For Unix::
  16 * Customization Hooks for Users::
  17 * Tools To Help Developers::
  18 * Resolution of Name Conflicts::
  19 * Hash Table Extensions::
  20 * Random Number Generation::
  21 * Miscellaneous Extensions::
  22 * Stale Extensions::
  23 * Efficiency Hacks::
  24 @end menu
  25
  26 @node Reader Extensions
  27 @comment  node-name,  next,  previous,  up
  28 @section Reader Extensions
  29 @cindex Reader Extensions
  30
  31 SBCL supports extended package prefix syntax, which allows specifying
  32 an alternate package instead of @code{*package*} for the reader to use
  33 as the default package for interning symbols:
  34
  35 @lisp
  36 <package-name>::<form-with-interning-into-package>
  37 @end lisp
  38
  39 Example:
  40
  41 @lisp
  42   'foo::(bar quux zot) == '(foo::bar foo::quux foo::zot)
  43 @end lisp
  44
  45 Doesn't alter @code{*package*}: if @code{foo::bar} would cause a
  46 read-time package lock violation, so does @code{foo::(bar)}.
  47
  48 @node  Package-Local Nicknames
  49 @comment  node-name,  next,  previous,  up
  50 @section Package-Local Nicknames
  51 @cindex Package-Local Nicknames
  52
  53 SBCL allows giving packages local nicknames: they allow short and
  54 easy-to-use names to be used without fear of name conflict associated
  55 with normal nicknames.
  56
  57 A local nickname is valid only when inside the package for which it
  58 has been specified. Different packages can use same local nickname for
  59 different global names, or different local nickname for same global
  60 name.
  61
  62 Symbol @code{:package-local-nicknames} in @code{*features*} denotes the
  63 support for this feature.
  64
  65 @findex @cl{defpackage}
  66 @defmac @cl{defpackage} name [[option]]* @result{} package
  67
  68 Options are extended to include
  69
  70 @itemize
  71 @item
  72 @code{:local-nicknames} @var{(local-nickname actual-package-name)}*
  73
  74 The package has the specified local nicknames for the corresponding
  75 actual packages.
  76 @end itemize
  77
  78 Example:
  79
  80 @lisp
  81 (defpackage :bar (:intern "X"))
  82 (defpackage :foo (:intern "X"))
  83 (defpackage :quux (:use :cl) (:local-nicknames (:bar :foo) (:foo :bar)))
  84 (find-symbol "X" :foo) ; => FOO::X
  85 (find-symbol "X" :bar) ; => BAR::X
  86 (let ((*package* (find-package :quux)))
  87   (find-symbol "X" :foo))               ; => BAR::X
  88 (let ((*package* (find-package :quux)))
  89   (find-symbol "X" :bar))               ; => FOO::X
  90 @end lisp
  91 @end defmac
  92
  93 @include fun-sb-ext-package-local-nicknames.texinfo
  94 @include fun-sb-ext-package-locally-nicknamed-by-list.texinfo
  95 @include fun-sb-ext-add-package-local-nickname.texinfo
  96 @include fun-sb-ext-remove-package-local-nickname.texinfo
  97
  98 @node  Package Variance
  99 @comment  node-name,  next,  previous,  up
 100 @section Package Variance
 101
 102 Common Lisp standard specifies that ``If the new definition is at
 103 variance with the current state of that package, the consequences are
 104 undefined;'' SBCL by default signals a full warning and retains as
 105 much of the package state as possible.
 106
 107 This can be adjusted using @code{sb-ext:*on-package-variance*}:
 108
 109 @include var-sb-ext-star-on-package-variance-star.texinfo
 110
 111 @node  Garbage Collection
 112 @comment  node-name,  next,  previous,  up
 113 @section Garbage Collection
 114 @cindex Garbage collection
 115
 116 SBCL provides additional garbage collection functionality not
 117 specified by ANSI.
 118
 119 @include var-sb-ext-star-after-gc-hooks-star.texinfo
 120 @include fun-sb-ext-gc.texinfo
 121
 122 @subsection Finalization
 123 @cindex Finalization
 124
 125 Finalization allows code to be executed after an object has been
 126 garbage collected. This is useful for example for releasing foreign
 127 memory associated with a Lisp object.
 128
 129 @include fun-sb-ext-finalize.texinfo
 130 @include fun-sb-ext-cancel-finalization.texinfo
 131
 132 @subsection Weak Pointers
 133 @cindex Weak pointers
 134
 135 Weak pointers allow references to objects to be maintained without
 136 keeping them from being garbage collected: useful for building caches
 137 among other things.
 138
 139 Hash tables can also have weak keys and values: @pxref{Hash Table
 140 Extensions}.
 141
 142 @include fun-sb-ext-make-weak-pointer.texinfo
 143 @include fun-sb-ext-weak-pointer-value.texinfo
 144
 145 @subsection Introspection and Tuning
 146
 147 @include var-sb-ext-star-gc-run-time-star.texinfo
 148 @include fun-sb-ext-bytes-consed-between-gcs.texinfo
 149 @include fun-sb-ext-dynamic-space-size.texinfo
 150 @include fun-sb-ext-get-bytes-consed.texinfo
 151 @include fun-sb-ext-gc-logfile.texinfo
 152 @include fun-sb-ext-generation-average-age.texinfo
 153 @include fun-sb-ext-generation-bytes-allocated.texinfo
 154 @include fun-sb-ext-generation-bytes-consed-between-gcs.texinfo
 155 @include fun-sb-ext-generation-minimum-age-before-gc.texinfo
 156 @include fun-sb-ext-generation-number-of-gcs-before-promotion.texinfo
 157 @include fun-sb-ext-generation-number-of-gcs.texinfo
 158
 159 @node Metaobject Protocol
 160 @comment  node-name,  next,  previous,  up
 161 @section Metaobject Protocol
 162
 163 @subsection AMOP Compatibility of Metaobject Protocol
 164
 165 SBCL supports a metaobject protocol which is intended to be compatible
 166 with AMOP; present exceptions to this (as distinct from current bugs)
 167 are:
 168
 169 @itemize
 170
 171 @item
 172 @findex @sbmop{compute-effective-method}
 173 @code{compute-effective-method} only returns one value, not two.
 174
 175 There is no record of what the second return value was meant to
 176 indicate, and apparently no clients for it.
 177
 178 @item
 179 @tindex @cl{generic-function}
 180 @tindex @cl{standard-generic-function}
 181 @tindex @sbmop{funcallable-standard-object}
 182 @tindex @cl{standard-object}
 183 @tindex @cl{function}
 184 The direct superclasses of @code{sb-mop:funcallable-standard-object} are
 185 @code{(function standard-object)}, not @code{(standard-object function)}.
 186
 187 This is to ensure that the @code{standard-object} class is the last of
 188 the standardized classes before @code{t} appearing in the class
 189 precedence list of @code{generic-function} and
 190 @code{standard-generic-function}, as required by section 1.4.4.5 of the
 191 ANSI specification.
 192
 193 @item
 194 @findex @cl{ensure-generic-function}
 195 @findex @sbmop{generic-function-declarations}
 196 the arguments @code{:declare} and @code{:declarations} to
 197 @code{ensure-generic-function} are both accepted, with the leftmost
 198 argument defining the declarations to be stored and returned by
 199 @code{generic-function-declarations}.
 200
 201 Where AMOP specifies @code{:declarations} as the keyword argument to
 202 @code{ensure-generic-function}, the Common Lisp standard specifies
 203 @code{:declare}.  Portable code should use @code{:declare}.
 204
 205 @item
 206 @findex @sbmop{validate-superclass}
 207 @findex @sbmop{finalize-inheritance}
 208 @tindex @cl{standard-class}
 209 @tindex @sbmop{funcallable-standard-class}
 210 @tindex @cl{function}
 211 @findex @sbmop{class-prototype}
 212 although SBCL obeys the requirement in AMOP that
 213 @code{validate-superclass} should treat @code{standard-class} and
 214 @code{funcallable-standard-class} as compatible metaclasses, we
 215 impose an additional requirement at class finalization time: a class
 216 of metaclass @code{funcallable-standard-class} must have
 217 @code{function} in its superclasses, and a class of metaclass
 218 @code{standard-class} must not.
 219
 220 @findex @cl{typep}
 221 @findex @cl{class-of}
 222 @findex @cl{subtypep}
 223 After a class has been finalized, it is associated with a class
 224 prototype which is accessible by a standard mop function
 225 @code{sb-mop:class-prototype}.  The user can then ask whether this
 226 object is a @code{function} or not in several different ways: whether it
 227 is a function according to @code{typep}; whether its @code{class-of} is
 228 @code{subtypep} @code{function}, or whether @code{function} appears in
 229 the superclasses of the class.  The additional consistency requirement
 230 comes from the desire to make all of these answers the same.
 231
 232 The following class definitions are bad, and will lead to errors
 233 either immediately or if an instance is created:
 234 @lisp
 235 (defclass bad-object (funcallable-standard-object)
 236   ()
 237   (:metaclass standard-class))
 238 @end lisp
 239 @lisp
 240 (defclass bad-funcallable-object (standard-object)
 241   ()
 242   (:metaclass funcallable-standard-class))
 243 @end lisp
 244 The following definition is acceptable:
 245 @lisp
 246 (defclass mixin ()
 247   ((slot :initarg slot)))
 248 (defclass funcallable-object (funcallable-standard-object mixin)
 249   ()
 250   (:metaclass funcallable-standard-class))
 251 @end lisp
 252 and leads to a class whose instances are funcallable and have one slot.
 253
 254 @tindex @sbmop{funcallable-standard-object}
 255 Note that this requirement also applies to the class
 256 @code{sb-mop:funcallable-standard-object}, which has metaclass
 257 @code{sb-mop:funcallable-standard-class} rather than
 258 @code{standard-class} as AMOP specifies.
 259
 260 @item
 261 the requirement that ``No portable class @math{C_p} may inherit, by
 262 virtue of being a direct or indirect subclass of a specified class, any
 263 slot for which the name is a symbol accessible in the
 264 @code{common-lisp-user} package or exported by any package defined in
 265 the ANSI Common Lisp standard.'' is interpreted to mean that the
 266 standardized classes themselves should not have slots named by external
 267 symbols of public packages.
 268
 269 The rationale behind the restriction is likely to be similar to the ANSI
 270 Common Lisp restriction on defining functions, variables and types named
 271 by symbols in the Common Lisp package: preventing two independent pieces
 272 of software from colliding with each other.
 273
 274 @item
 275 @findex @sbmop{slot-value-using-class}
 276 @findex @setf{@sbmop{slot-value-using-class}}
 277 @findex @sbmop{slot-boundp-using-class}
 278 specializations of the @code{new-value} argument to @code{(setf
 279 sb-mop:slot-value-using-class)} are not allowed: all user-defined
 280 methods must have a specializer of the class @code{t}.
 281
 282 This prohibition is motivated by a separation of layers: the
 283 @code{slot-value-using-class} family of functions is intended for use in
 284 implementing different and new slot allocation strategies, rather than
 285 in performing application-level dispatching.  Additionally, with this
 286 requirement, there is a one-to-one mapping between metaclass, class and
 287 slot-definition-class tuples and effective methods of @code{(setf
 288 slot-value-using-class)}, which permits optimization of @code{(setf
 289 slot-value-using-class)}'s discriminating function in the same manner as
 290 for @code{slot-value-using-class} and @code{slot-boundp-using-class}.
 291
 292 Note that application code may specialize on the @code{new-value}
 293 argument of slot accessors.
 294
 295 @item
 296 @findex @cl{defclass}
 297 @findex @sbmop{ensure-class}
 298 @findex @sbmop{ensure-class-using-class}
 299 @findex @cl{find-class}
 300 @findex @cl{class-name}
 301 the class named by the @code{name} argument to @code{ensure-class}, if
 302 any, is only redefined if it is the proper name of that class;
 303 otherwise, a new class is created.
 304
 305 This is consistent with the description of @code{ensure-class} in AMOP
 306 as the functional version of @code{defclass}, which has this behaviour;
 307 however, it is not consistent with the weaker requirement in AMOP, which
 308 states that any class found by @code{find-class}, no matter what its
 309 @code{class-name}, is redefined.
 310
 311 @end itemize
 312
 313 @subsection Metaobject Protocol Extensions
 314
 315 In addition, SBCL supports extensions to the Metaobject protocol from
 316 AMOP; at present, they are:
 317
 318 @itemize
 319
 320 @item
 321 @findex @cl{defmethod}
 322 @findex @cl{find-class}
 323 @findex @sbmop{intern-eql-specializer}
 324 @findex @sbpcl{make-method-specializers-form}
 325 @findex @sbmop{make-method-lambda}
 326 compile-time support for generating specializer metaobjects from
 327 specializer names in @code{defmethod} forms is provided by the
 328 @code{make-method-specializers-form} function, which returns a form
 329 which, when evaluated in the lexical environment of the
 330 @code{defmethod}, returns a list of specializer metaobjects.  This
 331 operator suffers from similar restrictions to those affecting
 332 @code{make-method-lambda}, namely that the generic function must be
 333 defined when the @code{defmethod} form is expanded, so that the
 334 correct method of @code{make-method-specializers-form} is invoked.
 335 The system-provided method on @code{make-method-specializers-form}
 336 generates a call to @code{find-class} for each symbol specializer
 337 name, and a call to @code{intern-eql-specializer} for each @code{(eql
 338 @var{x})} specializer name.
 339
 340 @item
 341 @findex @cl{find-method}
 342 @findex @sbpcl{parse-specializer-using-class}
 343 @findex @sbpcl{unparse-specializer-using-class}
 344 run-time support for converting between specializer names and
 345 specializer metaobjects, mostly for the purposes of
 346 @code{find-method}, is provided by
 347 @code{parse-specializer-using-class} and
 348 @code{unparse-specializer-using-class}, which dispatch on their first
 349 argument, the generic function associated with a method with the given
 350 specializer.  The system-provided methods on those methods convert
 351 between classes and proper names and between lists of the form
 352 @code{(eql @var{x})} and interned eql specializer objects.
 353
 354 @item
 355 @vindex @sbpcl{+slot-unbound+}
 356 @findex @sbmop{standard-instance-access}
 357 @findex @sbmop{funcallable-standard-instance-access}
 358 distinguishing unbound instance allocated slots from bound ones when
 359 using @code{standard-instance-access} and
 360 @code{funcallable-standard-instance-access} is possible by comparison
 361 to the constant @code{+slot-unbound+}.
 362
 363 @end itemize
 364
 365 @node  Support For Unix
 366 @comment  node-name,  next,  previous,  up
 367 @section Support For Unix
 368
 369 @menu
 370 * Command-line arguments::
 371 * Querying the process environment::
 372 * Running external programs::
 373 @end menu
 374
 375 @node Command-line arguments
 376 @subsection Command-line arguments
 377 @vindex @sbext{@earmuffs{posix-argv}}
 378
 379 The UNIX command line can be read from the variable
 380 @code{sb-ext:*posix-argv*}.
 381
 382 @node Querying the process environment
 383 @subsection Querying the process environment
 384
 385 The UNIX environment can be queried with the
 386 @code{sb-ext:posix-getenv} function.
 387
 388 @include fun-sb-ext-posix-getenv.texinfo
 389
 390 @node Running external programs
 391 @subsection Running external programs
 392
 393 External programs can be run with @code{sb-ext:run-program}.
 394 @footnote{In SBCL versions prior to 1.0.13, @code{sb-ext:run-program}
 395 searched for executables in a manner somewhat incompatible with other
 396 languages.  As of this version, SBCL uses the system library routine
 397 @code{execvp(3)}, and no longer contains the function,
 398 @code{find-executable-in-search-path}, which implemented the old
 399 search.  Users who need this function may find it
 400 in @file{run-program.lisp} versions 1.67 and earlier in SBCL's CVS
 401 repository here
 402 @url{http://sbcl.cvs.sourceforge.net/sbcl/sbcl/src/code/run-program.lisp?view=log}. However,
 403 we caution such users that this search routine finds executables that
 404 system library routines do not.}
 405
 406 @include fun-sb-ext-run-program.texinfo
 407
 408 When @code{sb-ext:run-program} is called with @code{wait} equal to
 409 NIL, an instance of class @var{sb-ext:process} is returned.  The
 410 following functions are available for use with processes:
 411
 412 @include fun-sb-ext-process-p.texinfo
 413
 414 @include fun-sb-ext-process-input.texinfo
 415
 416 @include fun-sb-ext-process-output.texinfo
 417
 418 @include fun-sb-ext-process-error.texinfo
 419
 420 @include fun-sb-ext-process-alive-p.texinfo
 421
 422 @include fun-sb-ext-process-status.texinfo
 423
 424 @include fun-sb-ext-process-wait.texinfo
 425
 426 @include fun-sb-ext-process-exit-code.texinfo
 427
 428 @include fun-sb-ext-process-core-dumped.texinfo
 429
 430 @include fun-sb-ext-process-close.texinfo
 431
 432 @include fun-sb-ext-process-kill.texinfo
 433
 434 @node  Customization Hooks for Users
 435 @comment  node-name,  next,  previous,  up
 436 @section Customization Hooks for Users
 437
 438 The toplevel repl prompt may be customized, and the function
 439 that reads user input may be replaced completely.
 440 @c <!-- FIXME but I don't currently remember how -->
 441
 442 The behaviour of @code{require} when called with only one argument is
 443 implementation-defined.  In SBCL, @code{require} behaves in the
 444 following way:
 445
 446 @include fun-common-lisp-require.texinfo
 447 @include var-sb-ext-star-module-provider-functions-star.texinfo
 448
 449 Although SBCL does not provide a resident editor, the @code{ed}
 450 function can be customized to hook into user-provided editing
 451 mechanisms as follows:
 452
 453 @include fun-common-lisp-ed.texinfo
 454 @include var-sb-ext-star-ed-functions-star.texinfo
 455
 456 Conditions of type @code{warning} and @code{style-warning} are
 457 sometimes signaled at runtime, especially during execution of Common
 458 Lisp defining forms such as @code{defun}, @code{defmethod}, etc.  To
 459 muffle these warnings at runtime, SBCL provides a variable
 460 @code{sb-ext:*muffled-warnings*}:
 461
 462 @include var-sb-ext-star-muffled-warnings-star.texinfo
 463
 464 @node Tools To Help Developers
 465 @comment  node-name,  next,  previous,  up
 466 @section Tools To Help Developers
 467 @findex @cl{trace}
 468 @findex @cl{inspect}
 469
 470 SBCL provides a profiler and other extensions to the ANSI @code{trace}
 471 facility.  For more information, see @ref{Macro common-lisp:trace}.
 472
 473 The debugger supports a number of options. Its documentation is
 474 accessed by typing @kbd{help} at the debugger prompt. @xref{Debugger}.
 475
 476 Documentation for @code{inspect} is accessed by typing @kbd{help} at
 477 the @code{inspect} prompt.
 478
 479 @node Resolution of Name Conflicts
 480 @section Resolution of Name Conflicts
 481 @tindex @sbext{name-conflict}
 482 @findex @sbext{name-conflict-symbols}
 483
 484 The ANSI standard (section 11.1.1.2.5) requires that name conflicts in
 485 packages be resolvable in favour of any of the conflicting symbols.  In
 486 the interactive debugger, this is achieved by prompting for the symbol
 487 in whose favour the conflict should be resolved; for programmatic use,
 488 the @code{sb-ext:resolve-conflict} restart should be invoked with one
 489 argument, which should be a member of the list returned by the condition
 490 accessor @code{sb-ext:name-conflict-symbols}.
 491
 492 @node    Hash Table Extensions
 493 @comment  node-name,  next,  previous,  up
 494 @section Hash Table Extensions
 495 @cindex Hash tables
 496
 497 Hash table extensions supported by SBCL are all controlled by keyword
 498 arguments to @code{make-hash-table}.
 499
 500 @include fun-common-lisp-make-hash-table.texinfo
 501
 502 @include macro-sb-ext-define-hash-table-test.texinfo
 503
 504 @include macro-sb-ext-with-locked-hash-table.texinfo
 505
 506 @include fun-sb-ext-hash-table-synchronized-p.texinfo
 507
 508 @include fun-sb-ext-hash-table-weakness.texinfo
 509
 510 @node    Random Number Generation
 511 @comment  node-name,  next,  previous,  up
 512 @section Random Number Generation
 513 @cindex Random Number Generation
 514
 515 The initial value of @code{*random-state*} is the same each time SBCL
 516 is started. This makes it possible for user code to obtain repeatable
 517 pseudo random numbers using only standard-provided functionality. See
 518 @code{seed-random-state} below for an SBCL extension that allows to
 519 seed the random number generator from given data for an additional
 520 possibility to achieve this. Non-repeatable random numbers can always
 521 be obtained using @code{(make-random-state t)}.
 522
 523 The sequence of numbers produced by repeated calls to @code{random}
 524 starting with the same random state and using the same sequence of
 525 @code{limit} arguments is guaranteed to be reproducible only in the
 526 same version of SBCL on the same platform, using the same code under
 527 the same evaluator mode and compiler optimization qualities. Just two
 528 examples of differences that may occur otherwise: calls to
 529 @code{random} can be compiled differently depending on how much is
 530 known about the @code{limit} argument at compile time, yielding
 531 different results even if called with the same argument at run time,
 532 and the results can differ depending on the machine's word size, for
 533 example for limits that are fixnums under 64-bit word size but bignums
 534 under 32-bit word size.
 535
 536 @include fun-sb-ext-seed-random-state.texinfo
 537
 538 Some notes on random floats: The standard doesn't prescribe a specific
 539 method of generating random floats. The following paragraph describes
 540 SBCL's current implementation and should be taken purely informational,
 541 that is, user code should not depend on any of its specific properties.
 542 The method used has been chosen because it is common, conceptually
 543 simple and fast.
 544
 545 To generate random floats, SBCL evaluates code that has an equivalent
 546 effect as
 547 @lisp
 548 (* limit
 549    (float (/ (random (expt 2 23)) (expt 2 23)) 1.0f0))
 550 @end lisp
 551 (for single-floats) and correspondingly (with @code{52} and
 552 @code{1.0d0} instead of @code{23} and @code{1.0f0}) for double-floats.
 553 Note especially that this means that zero is a possible return value
 554 occurring with probability @code{(expt 2 -23)} respectively
 555 @code{(expt 2 -52)}. Also note that there exist twice as many
 556 equidistant floats between 0 and 1 as are generated. For example, the
 557 largest number that @code{(random 1.0f0)} ever returns is
 558 @code{(float (/ (1- (expt 2 23)) (expt 2 23)) 1.0f0)} while
 559 @code{(float (/ (1- (expt 2 24)) (expt 2 24)) 1.0f0)} is the
 560 largest single-float less than 1. This is a side effect of the fact
 561 that the implementation uses the fastest possible conversion from bits
 562 to floats.
 563
 564 SBCL currently uses the Mersenne Twister as its random number
 565 generator, specifically the 32-bit version under both 32- and 64-bit
 566 word size. The seeding algorithm has been improved several times by
 567 the authors of the Mersenne Twister; SBCL uses the third version
 568 (from 2002) which is still the most recent as of June 2012. The
 569 implementation has been tested to provide output identical to the
 570 recommended C implementation.
 571
 572 While the Mersenne Twister generates random numbers of much better
 573 statistical quality than other widely used generators, it uses only
 574 linear operations modulo 2 and thus fails some statistical
 575 tests@footnote{See chapter 7 "Testing widely used RNGs" in
 576 @cite{TestU01: A C Library for Empirical Testing of Random Number
 577 Generators} by Pierre L'Ecuyer and Richard Simard, ACM Transactions on
 578 Mathematical Software, Vol. 33, article 22, 2007.}.
 579 For example, the distribution of ranks of (sufficiently large) random
 580 binary matrices is much distorted compared to the theoretically
 581 expected one when the matrices are generated by the Mersenne Twister.
 582 Thus, applications that are sensitive to this aspect should use a
 583 different type of generator.
 584
 585 @node    Miscellaneous Extensions
 586 @comment  node-name,  next,  previous,  up
 587 @section Miscellaneous Extensions
 588
 589 @include fun-sb-ext-array-storage-vector.texinfo
 590 @include fun-sb-ext-delete-directory.texinfo
 591 @include fun-sb-ext-get-time-of-day.texinfo
 592 @include macro-sb-ext-wait-for.texinfo
 593
 594 @node Stale Extensions
 595 @comment  node-name,  next,  previous,  up
 596 @section Stale Extensions
 597
 598 SBCL has inherited from CMUCL various hooks to allow the user to
 599 tweak and monitor the garbage collection process. These are somewhat
 600 stale code, and their interface might need to be cleaned up. If you
 601 have urgent need of them, look at the code in @file{src/code/gc.lisp}
 602 and bring it up on the developers' mailing list.
 603
 604 SBCL has various hooks inherited from CMUCL, like
 605 @code{sb-ext:float-denormalized-p}, to allow a program to take
 606 advantage of IEEE floating point arithmetic properties which aren't
 607 conveniently or efficiently expressible using the ANSI standard. These
 608 look good, and their interface looks good, but IEEE support is
 609 slightly broken due to a stupid decision to remove some support for
 610 infinities (because it wasn't in the ANSI spec and it didn't occur to
 611 me that it was in the IEEE spec). If you need this stuff, take a look
 612 at the code and bring it up on the developers' mailing
 613 list.
 614
 615
 616 @node  Efficiency Hacks
 617 @comment  node-name,  next,  previous,  up
 618 @section Efficiency Hacks
 619
 620 The @code{sb-ext:purify} function causes SBCL first to collect all
 621 garbage, then to mark all uncollected objects as permanent, never again
 622 attempting to collect them as garbage. This can cause a large increase
 623 in efficiency when using a primitive garbage collector, or a more
 624 moderate increase in efficiency when using a more sophisticated garbage
 625 collector which is well suited to the program's memory usage pattern. It
 626 also allows permanent code to be frozen at fixed addresses, a
 627 precondition for using copy-on-write to share code between multiple Lisp
 628 processes.  This is less important with modern generational garbage
 629 collectors, but not all SBCL platforms use such a garbage collector.
 630
 631 @include fun-sb-ext-purify.texinfo
 632
 633 The @code{sb-ext:truly-the} special form declares the type of the
 634 result of the operations, producing its argument; the declaration is
 635 not checked. In short: don't use it.
 636
 637 @include special-operator-sb-ext-truly-the.texinfo
 638
 639 The @code{sb-ext:freeze-type} declaration declares that a
 640 type will never change, which can make type testing
 641 (@code{typep}, etc.) more efficient for structure types.