1 @node Beyond the ANSI Standard
2 @comment node-name, next, previous, up
3 @chapter Beyond the ANSI Standard
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}.
11 * Package-Local Nicknames::
13 * Garbage Collection::
14 * Metaobject Protocol::
15 * Extensible Sequences::
17 * Customization Hooks for Users::
18 * Tools To Help Developers::
19 * Resolution of Name Conflicts::
20 * Hash Table Extensions::
21 * Random Number Generation::
22 * Miscellaneous Extensions::
27 @node Reader Extensions
28 @comment node-name, next, previous, up
29 @section Reader Extensions
30 @cindex Reader Extensions
32 SBCL supports extended package prefix syntax, which allows specifying
33 an alternate package instead of @code{*package*} for the reader to use
34 as the default package for interning symbols:
37 <package-name>::<form-with-interning-into-package>
43 'foo::(bar quux zot) == '(foo::bar foo::quux foo::zot)
46 Doesn't alter @code{*package*}: if @code{foo::bar} would cause a
47 read-time package lock violation, so does @code{foo::(bar)}.
49 @node Package-Local Nicknames
50 @comment node-name, next, previous, up
51 @section Package-Local Nicknames
52 @cindex Package-Local Nicknames
54 SBCL allows giving packages local nicknames: they allow short and
55 easy-to-use names to be used without fear of name conflict associated
56 with normal nicknames.
58 A local nickname is valid only when inside the package for which it
59 has been specified. Different packages can use same local nickname for
60 different global names, or different local nickname for same global
63 Symbol @code{:package-local-nicknames} in @code{*features*} denotes the
64 support for this feature.
66 @findex @cl{defpackage}
67 @defmac @cl{defpackage} name [[option]]* @result{} package
69 Options are extended to include
73 @code{:local-nicknames (@var{local-nickname} @var{actual-package-name})*}
75 The package has the specified local nicknames for the corresponding
82 (defpackage :bar (:intern "X"))
83 (defpackage :foo (:intern "X"))
84 (defpackage :quux (:use :cl) (:local-nicknames (:bar :foo) (:foo :bar)))
85 (find-symbol "X" :foo) ; => FOO::X
86 (find-symbol "X" :bar) ; => BAR::X
87 (let ((*package* (find-package :quux)))
88 (find-symbol "X" :foo)) ; => BAR::X
89 (let ((*package* (find-package :quux)))
90 (find-symbol "X" :bar)) ; => FOO::X
94 @include fun-sb-ext-package-local-nicknames.texinfo
95 @include fun-sb-ext-package-locally-nicknamed-by-list.texinfo
96 @include fun-sb-ext-add-package-local-nickname.texinfo
97 @include fun-sb-ext-remove-package-local-nickname.texinfo
99 @node Package Variance
100 @comment node-name, next, previous, up
101 @section Package Variance
103 Common Lisp standard specifies that ``If the new definition is at
104 variance with the current state of that package, the consequences are
105 undefined;'' SBCL by default signals a full warning and retains as
106 much of the package state as possible.
108 This can be adjusted using @code{sb-ext:*on-package-variance*}:
110 @include var-sb-ext-star-on-package-variance-star.texinfo
112 @node Garbage Collection
113 @comment node-name, next, previous, up
114 @section Garbage Collection
115 @cindex Garbage collection
117 SBCL provides additional garbage collection functionality not
120 @include var-sb-ext-star-after-gc-hooks-star.texinfo
121 @include fun-sb-ext-gc.texinfo
123 @subsection Finalization
126 Finalization allows code to be executed after an object has been
127 garbage collected. This is useful for example for releasing foreign
128 memory associated with a Lisp object.
130 @include fun-sb-ext-finalize.texinfo
131 @include fun-sb-ext-cancel-finalization.texinfo
133 @subsection Weak Pointers
134 @cindex Weak pointers
136 Weak pointers allow references to objects to be maintained without
137 keeping them from being garbage collected: useful for building caches
140 Hash tables can also have weak keys and values: @pxref{Hash Table
143 @include fun-sb-ext-make-weak-pointer.texinfo
144 @include fun-sb-ext-weak-pointer-value.texinfo
146 @subsection Introspection and Tuning
148 @include var-sb-ext-star-gc-run-time-star.texinfo
149 @include fun-sb-ext-bytes-consed-between-gcs.texinfo
150 @include fun-sb-ext-dynamic-space-size.texinfo
151 @include fun-sb-ext-get-bytes-consed.texinfo
152 @include fun-sb-ext-gc-logfile.texinfo
153 @include fun-sb-ext-generation-average-age.texinfo
154 @include fun-sb-ext-generation-bytes-allocated.texinfo
155 @include fun-sb-ext-generation-bytes-consed-between-gcs.texinfo
156 @include fun-sb-ext-generation-minimum-age-before-gc.texinfo
157 @include fun-sb-ext-generation-number-of-gcs-before-promotion.texinfo
158 @include fun-sb-ext-generation-number-of-gcs.texinfo
160 @node Metaobject Protocol
161 @comment node-name, next, previous, up
162 @section Metaobject Protocol
164 @subsection AMOP Compatibility of Metaobject Protocol
166 SBCL supports a metaobject protocol which is intended to be compatible
167 with AMOP; present exceptions to this (as distinct from current bugs)
173 @findex @sbmop{compute-effective-method}
174 @code{compute-effective-method} only returns one value, not two.
176 There is no record of what the second return value was meant to
177 indicate, and apparently no clients for it.
180 @tindex @cl{generic-function}
181 @tindex @cl{standard-generic-function}
182 @tindex @sbmop{funcallable-standard-object}
183 @tindex @cl{standard-object}
184 @tindex @cl{function}
185 The direct superclasses of @code{sb-mop:funcallable-standard-object} are
186 @code{(function standard-object)}, not @code{(standard-object function)}.
188 This is to ensure that the @code{standard-object} class is the last of
189 the standardized classes before @code{t} appearing in the class
190 precedence list of @code{generic-function} and
191 @code{standard-generic-function}, as required by section 1.4.4.5 of the
195 @findex @cl{ensure-generic-function}
196 @findex @sbmop{generic-function-declarations}
197 the arguments @code{:declare} and @code{:declarations} to
198 @code{ensure-generic-function} are both accepted, with the leftmost
199 argument defining the declarations to be stored and returned by
200 @code{generic-function-declarations}.
202 Where AMOP specifies @code{:declarations} as the keyword argument to
203 @code{ensure-generic-function}, the Common Lisp standard specifies
204 @code{:declare}. Portable code should use @code{:declare}.
207 @findex @sbmop{validate-superclass}
208 @findex @sbmop{finalize-inheritance}
209 @tindex @cl{standard-class}
210 @tindex @sbmop{funcallable-standard-class}
211 @tindex @cl{function}
212 @findex @sbmop{class-prototype}
213 although SBCL obeys the requirement in AMOP that
214 @code{validate-superclass} should treat @code{standard-class} and
215 @code{funcallable-standard-class} as compatible metaclasses, we
216 impose an additional requirement at class finalization time: a class
217 of metaclass @code{funcallable-standard-class} must have
218 @code{function} in its superclasses, and a class of metaclass
219 @code{standard-class} must not.
222 @findex @cl{class-of}
223 @findex @cl{subtypep}
224 After a class has been finalized, it is associated with a class
225 prototype which is accessible by a standard mop function
226 @code{sb-mop:class-prototype}. The user can then ask whether this
227 object is a @code{function} or not in several different ways: whether it
228 is a function according to @code{typep}; whether its @code{class-of} is
229 @code{subtypep} @code{function}, or whether @code{function} appears in
230 the superclasses of the class. The additional consistency requirement
231 comes from the desire to make all of these answers the same.
233 The following class definitions are bad, and will lead to errors
234 either immediately or if an instance is created:
236 (defclass bad-object (funcallable-standard-object)
238 (:metaclass standard-class))
241 (defclass bad-funcallable-object (standard-object)
243 (:metaclass funcallable-standard-class))
245 The following definition is acceptable:
248 ((slot :initarg slot)))
249 (defclass funcallable-object (funcallable-standard-object mixin)
251 (:metaclass funcallable-standard-class))
253 and leads to a class whose instances are funcallable and have one slot.
255 @tindex @sbmop{funcallable-standard-object}
256 Note that this requirement also applies to the class
257 @code{sb-mop:funcallable-standard-object}, which has metaclass
258 @code{sb-mop:funcallable-standard-class} rather than
259 @code{standard-class} as AMOP specifies.
262 the requirement that ``No portable class @math{C_p} may inherit, by
263 virtue of being a direct or indirect subclass of a specified class, any
264 slot for which the name is a symbol accessible in the
265 @code{common-lisp-user} package or exported by any package defined in
266 the ANSI Common Lisp standard.'' is interpreted to mean that the
267 standardized classes themselves should not have slots named by external
268 symbols of public packages.
270 The rationale behind the restriction is likely to be similar to the ANSI
271 Common Lisp restriction on defining functions, variables and types named
272 by symbols in the Common Lisp package: preventing two independent pieces
273 of software from colliding with each other.
276 @findex @sbmop{slot-value-using-class}
277 @findex @setf{@sbmop{slot-value-using-class}}
278 @findex @sbmop{slot-boundp-using-class}
279 specializations of the @code{new-value} argument to @code{(setf
280 sb-mop:slot-value-using-class)} are not allowed: all user-defined
281 methods must have a specializer of the class @code{t}.
283 This prohibition is motivated by a separation of layers: the
284 @code{slot-value-using-class} family of functions is intended for use in
285 implementing different and new slot allocation strategies, rather than
286 in performing application-level dispatching. Additionally, with this
287 requirement, there is a one-to-one mapping between metaclass, class and
288 slot-definition-class tuples and effective methods of @code{(setf
289 slot-value-using-class)}, which permits optimization of @code{(setf
290 slot-value-using-class)}'s discriminating function in the same manner as
291 for @code{slot-value-using-class} and @code{slot-boundp-using-class}.
293 Note that application code may specialize on the @code{new-value}
294 argument of slot accessors.
297 @findex @cl{defclass}
298 @findex @sbmop{ensure-class}
299 @findex @sbmop{ensure-class-using-class}
300 @findex @cl{find-class}
301 @findex @cl{class-name}
302 the class named by the @code{name} argument to @code{ensure-class}, if
303 any, is only redefined if it is the proper name of that class;
304 otherwise, a new class is created.
306 This is consistent with the description of @code{ensure-class} in AMOP
307 as the functional version of @code{defclass}, which has this behaviour;
308 however, it is not consistent with the weaker requirement in AMOP, which
309 states that any class found by @code{find-class}, no matter what its
310 @code{class-name}, is redefined.
314 @subsection Metaobject Protocol Extensions
316 In addition, SBCL supports extensions to the Metaobject protocol from
317 AMOP; at present, they are:
322 @findex @cl{defmethod}
323 @findex @cl{find-class}
324 @findex @sbmop{intern-eql-specializer}
325 @findex @sbpcl{make-method-specializers-form}
326 @findex @sbmop{make-method-lambda}
327 compile-time support for generating specializer metaobjects from
328 specializer names in @code{defmethod} forms is provided by the
329 @code{make-method-specializers-form} function, which returns a form
330 which, when evaluated in the lexical environment of the
331 @code{defmethod}, returns a list of specializer metaobjects. This
332 operator suffers from similar restrictions to those affecting
333 @code{make-method-lambda}, namely that the generic function must be
334 defined when the @code{defmethod} form is expanded, so that the
335 correct method of @code{make-method-specializers-form} is invoked.
336 The system-provided method on @code{make-method-specializers-form}
337 generates a call to @code{find-class} for each symbol specializer
338 name, and a call to @code{intern-eql-specializer} for each @code{(eql
339 @var{x})} specializer name.
342 @findex @cl{find-method}
343 @findex @sbpcl{parse-specializer-using-class}
344 @findex @sbpcl{unparse-specializer-using-class}
345 run-time support for converting between specializer names and
346 specializer metaobjects, mostly for the purposes of
347 @code{find-method}, is provided by
348 @code{parse-specializer-using-class} and
349 @code{unparse-specializer-using-class}, which dispatch on their first
350 argument, the generic function associated with a method with the given
351 specializer. The system-provided methods on those methods convert
352 between classes and proper names and between lists of the form
353 @code{(eql @var{x})} and interned eql specializer objects.
356 @vindex @sbpcl{+slot-unbound+}
357 @findex @sbmop{standard-instance-access}
358 @findex @sbmop{funcallable-standard-instance-access}
359 distinguishing unbound instance allocated slots from bound ones when
360 using @code{standard-instance-access} and
361 @code{funcallable-standard-instance-access} is possible by comparison
362 to the constant @code{+slot-unbound+}.
366 @node Extensible Sequences
367 @comment node-name, next, previous, up
368 @section Extensible Sequences
371 * Iterator Protocol::
372 * Simple Iterator Protocol::
375 ANSI Common Lisp has a class @code{sequence} with subclasses @code{list} and
376 @code{vector} on which the ``sequence functions'' like @code{find},
377 @code{subseq}, etc. operate. As an extension to the ANSI specification,
378 SBCL allows additional subclasses of @code{sequence} to be defined
379 @footnote{A motivation, rationale and additional examples for the design
380 of this extension can be found in the paper @cite{Rhodes, Christophe
381 (2007): User-extensible sequences in Common Lisp} available for download
383 @url{http://www.doc.gold.ac.uk/~mas01cr/papers/ilc2007/sequences-20070301.pdf}.}.
384 @tindex @cl{sequence}
389 Users of this extension just make instances of @cl{sequence} subclasses
390 and transparently operate on them using sequence functions:
392 (coerce (subseq (make-instance 'my-sequence) 5 10) 'list)
394 From this perspective, no distinction between builtin and user-defined
395 @code{sequence} subclasses should be necessary.
398 @findex @cl{make-instance}
401 Providers of the extension, that is of user-defined @code{sequence}
402 subclasses, have to adhere to a ``sequence protocol'' which consists of
403 a set of generic functions in the @code{sequence} package.
405 A minimal @code{sequence} subclass has to specify @code{standard-object} and
406 @code{sequence} as its superclasses and has to be the specializer of the
407 @code{sequence} parameter of methods on at least the following generic
409 @tindex @cl{sequence}
410 @tindex @cl{standard-object}
412 @include fun-sb-sequence-length.texinfo
413 @include fun-sb-sequence-elt.texinfo
414 @include fun-sb-sequence-setf-elt.texinfo
415 @include fun-sb-sequence-adjust-sequence.texinfo
416 @include fun-sb-sequence-make-sequence-like.texinfo
418 @code{make-sequence-like} is needed for functions returning
419 freshly-allocated sequences such as @code{subseq} or
420 @code{copy-seq}. @code{adjust-sequence} is needed for functions which
421 destructively modify their arguments such as @code{delete}. In fact, all
422 other sequence functions can be implemented in terms of the above
423 functions and actually are, if no additional methods are
424 defined. However, relying on these generic implementations, in
425 particular not implementing the iterator protocol can incur a high
426 performance penalty @xref{Iterator Protocol}.
427 @tindex @cl{sequence}
428 @findex @sequence{make-sequence-like}
430 @findex @cl{copy-seq}
431 @findex @sequence{adjust-sequence}
433 In addition to the mandatory functions above, methods on the following
434 sequence functions can be defined:
436 @include fun-sb-sequence-emptyp.texinfo
440 @code{sb-sequence:count}, @code{sb-sequence:count-if}, @code{sb-sequence:count-if-not}
443 @code{sb-sequence:find}, @code{sb-sequence:find-if}, @code{sb-sequence:find-if-not}
446 @code{sb-sequence:position}, @code{sb-sequence:position-if}, @code{sb-sequence:position-if-not}
449 @code{sb-sequence:subseq}
452 @code{sb-sequence:copy-seq}
455 @code{sb-sequence:fill}
458 @code{sb-sequence:nsubstitute}, @code{sb-sequence:nsubstitute-if},
459 @code{sb-sequence:nsubstitute-if-not}, @code{sb-sequence:substitute},
460 @code{sb-sequence:substitute-if}, @code{sb-sequence:substitute-if-not}
463 @code{sb-sequence:replace}
466 @code{sb-sequence:nreverse}, @code{sb-sequence:reverse}
469 @code{sb-sequence:reduce}
472 @code{sb-sequence:mismatch}
475 @code{sb-sequence:search}
478 @code{sb-sequence:delete}, @code{sb-sequence:delete-if}, @code{sb-sequence:delete-if-not},
479 @code{sb-sequence:remove}, @code{sb-sequence:remove-if}, @code{sb-sequence:remove-if-not},
482 @code{sb-sequence:delete-duplicates}, @code{sb-sequence:remove-duplicates}
485 @code{sb-sequence:sort}, @code{sb-sequence:stable-sort}
488 In the spirit of @code{dolist}, generic sequences can be traversed using
492 @include macro-sb-sequence-dosequence.texinfo
494 @node Iterator Protocol
495 @comment node-name, next, previous, up
496 @subsection Iterator Protocol
498 The iterator protocol allows subsequently accessing some or all elements
499 of a sequence in forward or reverse direction. Users first call
500 @code{make-sequence-iterator} to create an iteration state and
501 receive functions to query and mutate it. These functions allow, among
502 other things, moving to, retrieving or modifying elements of the
503 sequence. An iteration state consists of a state object, a limit object,
504 a from-end indicator and the following six functions to query or mutate
506 @findex @sequence{make-sequence-iterator}
507 @deffn {Function} @code{step function} sequence iterator from-end
508 Moves the iterator one position forward or backward in the associated
509 sequence depending on the iteration direction.
511 @deffn {Function} @code{endp function} sequence iterator limit from-end
512 Returns non-@code{nil} when the iterator has reached the end of the
513 associated sequence with respect to the iteration direction.
515 @deffn {Function} @code{element function} sequence iterator
516 Returns the sequence element associated to the current position of the
519 @deffn {Function} @code{setf element function} new-value sequence iterator
520 Destructively modifies the associates sequence by replacing the sequence
521 element associated to the current iteration position with a new value.
523 @deffn {Function} @code{index function} sequence iterator
524 Returns the position of the iteration in the associated sequence.
526 @deffn {Function} @code{copy function} sequence iterator
527 Returns a copy of the iteration state which can be mutated independently
528 of the copied iteration state.
531 An iterator is created by calling:
533 @include fun-sb-sequence-make-sequence-iterator.texinfo
535 Note that @code{make-sequence-iterator} calls
536 @code{make-simple-sequence-iterator} when there is no specialized
537 method for a particular @code{sequence} subclass. @xref{Simple Iterator
539 @findex @sequence{make-sequence-iterator}
540 @findex @sequence{make-simple-sequence-iterator}
541 @tindex @cl{sequence}
543 The following convenience macros simplify traversing sequences using
546 @include macro-sb-sequence-with-sequence-iterator.texinfo
547 @include macro-sb-sequence-with-sequence-iterator-functions.texinfo
549 @node Simple Iterator Protocol
550 @comment node-name, next, previous, up
551 @subsection Simple Iterator Protocol
553 For cases in which the full flexibility and performance of the general
554 sequence iterator protocol is not required, there is a simplified
555 sequence iterator protocol consisting of a few generic functions which
556 can be specialized for iterator classes:
558 @include fun-sb-sequence-iterator-step.texinfo
559 @include fun-sb-sequence-iterator-endp.texinfo
560 @include fun-sb-sequence-iterator-element.texinfo
561 @include fun-sb-sequence-setf-iterator-element.texinfo
562 @include fun-sb-sequence-iterator-index.texinfo
563 @include fun-sb-sequence-iterator-copy.texinfo
565 Iterator objects implementing the above simple iteration protocol are
566 created by calling the following generic function:
568 @include fun-sb-sequence-make-simple-sequence-iterator.texinfo
570 @node Support For Unix
571 @comment node-name, next, previous, up
572 @section Support For Unix
575 * Command-line arguments::
576 * Querying the process environment::
577 * Running external programs::
580 @node Command-line arguments
581 @subsection Command-line arguments
582 @vindex @sbext{@earmuffs{posix-argv}}
584 The UNIX command line can be read from the variable
585 @code{sb-ext:*posix-argv*}.
587 @node Querying the process environment
588 @subsection Querying the process environment
590 The UNIX environment can be queried with the
591 @code{sb-ext:posix-getenv} function.
593 @include fun-sb-ext-posix-getenv.texinfo
595 @node Running external programs
596 @subsection Running external programs
598 External programs can be run with @code{sb-ext:run-program}.
599 @footnote{In SBCL versions prior to 1.0.13, @code{sb-ext:run-program}
600 searched for executables in a manner somewhat incompatible with other
601 languages. As of this version, SBCL uses the system library routine
602 @code{execvp(3)}, and no longer contains the function,
603 @code{find-executable-in-search-path}, which implemented the old
604 search. Users who need this function may find it
605 in @file{run-program.lisp} versions 1.67 and earlier in SBCL's CVS
607 @url{http://sbcl.cvs.sourceforge.net/sbcl/sbcl/src/code/run-program.lisp?view=log}. However,
608 we caution such users that this search routine finds executables that
609 system library routines do not.}
611 @include fun-sb-ext-run-program.texinfo
613 When @code{sb-ext:run-program} is called with @code{wait} equal to
614 NIL, an instance of class @var{sb-ext:process} is returned. The
615 following functions are available for use with processes:
617 @include fun-sb-ext-process-p.texinfo
619 @include fun-sb-ext-process-input.texinfo
621 @include fun-sb-ext-process-output.texinfo
623 @include fun-sb-ext-process-error.texinfo
625 @include fun-sb-ext-process-alive-p.texinfo
627 @include fun-sb-ext-process-status.texinfo
629 @include fun-sb-ext-process-wait.texinfo
631 @include fun-sb-ext-process-exit-code.texinfo
633 @include fun-sb-ext-process-core-dumped.texinfo
635 @include fun-sb-ext-process-close.texinfo
637 @include fun-sb-ext-process-kill.texinfo
639 @node Customization Hooks for Users
640 @comment node-name, next, previous, up
641 @section Customization Hooks for Users
643 The toplevel repl prompt may be customized, and the function
644 that reads user input may be replaced completely.
645 @c <!-- FIXME but I don't currently remember how -->
647 The behaviour of @code{require} when called with only one argument is
648 implementation-defined. In SBCL, @code{require} behaves in the
651 @include fun-common-lisp-require.texinfo
652 @include var-sb-ext-star-module-provider-functions-star.texinfo
654 Although SBCL does not provide a resident editor, the @code{ed}
655 function can be customized to hook into user-provided editing
656 mechanisms as follows:
658 @include fun-common-lisp-ed.texinfo
659 @include var-sb-ext-star-ed-functions-star.texinfo
661 Conditions of type @code{warning} and @code{style-warning} are
662 sometimes signaled at runtime, especially during execution of Common
663 Lisp defining forms such as @code{defun}, @code{defmethod}, etc. To
664 muffle these warnings at runtime, SBCL provides a variable
665 @code{sb-ext:*muffled-warnings*}:
667 @include var-sb-ext-star-muffled-warnings-star.texinfo
669 @node Tools To Help Developers
670 @comment node-name, next, previous, up
671 @section Tools To Help Developers
675 SBCL provides a profiler and other extensions to the ANSI @code{trace}
676 facility. For more information, see @ref{Macro common-lisp:trace}.
678 The debugger supports a number of options. Its documentation is
679 accessed by typing @kbd{help} at the debugger prompt. @xref{Debugger}.
681 Documentation for @code{inspect} is accessed by typing @kbd{help} at
682 the @code{inspect} prompt.
684 @node Resolution of Name Conflicts
685 @section Resolution of Name Conflicts
686 @tindex @sbext{name-conflict}
687 @findex @sbext{name-conflict-symbols}
689 The ANSI standard (section 11.1.1.2.5) requires that name conflicts in
690 packages be resolvable in favour of any of the conflicting symbols. In
691 the interactive debugger, this is achieved by prompting for the symbol
692 in whose favour the conflict should be resolved; for programmatic use,
693 the @code{sb-ext:resolve-conflict} restart should be invoked with one
694 argument, which should be a member of the list returned by the condition
695 accessor @code{sb-ext:name-conflict-symbols}.
697 @node Hash Table Extensions
698 @comment node-name, next, previous, up
699 @section Hash Table Extensions
702 Hash table extensions supported by SBCL are all controlled by keyword
703 arguments to @code{make-hash-table}.
705 @include fun-common-lisp-make-hash-table.texinfo
707 @include macro-sb-ext-define-hash-table-test.texinfo
709 @include macro-sb-ext-with-locked-hash-table.texinfo
711 @include fun-sb-ext-hash-table-synchronized-p.texinfo
713 @include fun-sb-ext-hash-table-weakness.texinfo
715 @node Random Number Generation
716 @comment node-name, next, previous, up
717 @section Random Number Generation
718 @cindex Random Number Generation
720 The initial value of @code{*random-state*} is the same each time SBCL
721 is started. This makes it possible for user code to obtain repeatable
722 pseudo random numbers using only standard-provided functionality. See
723 @code{seed-random-state} below for an SBCL extension that allows to
724 seed the random number generator from given data for an additional
725 possibility to achieve this. Non-repeatable random numbers can always
726 be obtained using @code{(make-random-state t)}.
728 The sequence of numbers produced by repeated calls to @code{random}
729 starting with the same random state and using the same sequence of
730 @code{limit} arguments is guaranteed to be reproducible only in the
731 same version of SBCL on the same platform, using the same code under
732 the same evaluator mode and compiler optimization qualities. Just two
733 examples of differences that may occur otherwise: calls to
734 @code{random} can be compiled differently depending on how much is
735 known about the @code{limit} argument at compile time, yielding
736 different results even if called with the same argument at run time,
737 and the results can differ depending on the machine's word size, for
738 example for limits that are fixnums under 64-bit word size but bignums
739 under 32-bit word size.
741 @include fun-sb-ext-seed-random-state.texinfo
743 Some notes on random floats: The standard doesn't prescribe a specific
744 method of generating random floats. The following paragraph describes
745 SBCL's current implementation and should be taken purely informational,
746 that is, user code should not depend on any of its specific properties.
747 The method used has been chosen because it is common, conceptually
750 To generate random floats, SBCL evaluates code that has an equivalent
754 (float (/ (random (expt 2 23)) (expt 2 23)) 1.0f0))
756 (for single-floats) and correspondingly (with @code{52} and
757 @code{1.0d0} instead of @code{23} and @code{1.0f0}) for double-floats.
758 Note especially that this means that zero is a possible return value
759 occurring with probability @code{(expt 2 -23)} respectively
760 @code{(expt 2 -52)}. Also note that there exist twice as many
761 equidistant floats between 0 and 1 as are generated. For example, the
762 largest number that @code{(random 1.0f0)} ever returns is
763 @code{(float (/ (1- (expt 2 23)) (expt 2 23)) 1.0f0)} while
764 @code{(float (/ (1- (expt 2 24)) (expt 2 24)) 1.0f0)} is the
765 largest single-float less than 1. This is a side effect of the fact
766 that the implementation uses the fastest possible conversion from bits
769 SBCL currently uses the Mersenne Twister as its random number
770 generator, specifically the 32-bit version under both 32- and 64-bit
771 word size. The seeding algorithm has been improved several times by
772 the authors of the Mersenne Twister; SBCL uses the third version
773 (from 2002) which is still the most recent as of June 2012. The
774 implementation has been tested to provide output identical to the
775 recommended C implementation.
777 While the Mersenne Twister generates random numbers of much better
778 statistical quality than other widely used generators, it uses only
779 linear operations modulo 2 and thus fails some statistical
780 tests@footnote{See chapter 7 "Testing widely used RNGs" in
781 @cite{TestU01: A C Library for Empirical Testing of Random Number
782 Generators} by Pierre L'Ecuyer and Richard Simard, ACM Transactions on
783 Mathematical Software, Vol. 33, article 22, 2007.}.
784 For example, the distribution of ranks of (sufficiently large) random
785 binary matrices is much distorted compared to the theoretically
786 expected one when the matrices are generated by the Mersenne Twister.
787 Thus, applications that are sensitive to this aspect should use a
788 different type of generator.
790 @node Miscellaneous Extensions
791 @comment node-name, next, previous, up
792 @section Miscellaneous Extensions
794 @include fun-sb-ext-array-storage-vector.texinfo
795 @include fun-sb-ext-delete-directory.texinfo
796 @include fun-sb-ext-get-time-of-day.texinfo
797 @include macro-sb-ext-wait-for.texinfo
799 @node Stale Extensions
800 @comment node-name, next, previous, up
801 @section Stale Extensions
803 SBCL has inherited from CMUCL various hooks to allow the user to
804 tweak and monitor the garbage collection process. These are somewhat
805 stale code, and their interface might need to be cleaned up. If you
806 have urgent need of them, look at the code in @file{src/code/gc.lisp}
807 and bring it up on the developers' mailing list.
809 SBCL has various hooks inherited from CMUCL, like
810 @code{sb-ext:float-denormalized-p}, to allow a program to take
811 advantage of IEEE floating point arithmetic properties which aren't
812 conveniently or efficiently expressible using the ANSI standard. These
813 look good, and their interface looks good, but IEEE support is
814 slightly broken due to a stupid decision to remove some support for
815 infinities (because it wasn't in the ANSI spec and it didn't occur to
816 me that it was in the IEEE spec). If you need this stuff, take a look
817 at the code and bring it up on the developers' mailing
821 @node Efficiency Hacks
822 @comment node-name, next, previous, up
823 @section Efficiency Hacks
825 The @code{sb-ext:purify} function causes SBCL first to collect all
826 garbage, then to mark all uncollected objects as permanent, never again
827 attempting to collect them as garbage. This can cause a large increase
828 in efficiency when using a primitive garbage collector, or a more
829 moderate increase in efficiency when using a more sophisticated garbage
830 collector which is well suited to the program's memory usage pattern. It
831 also allows permanent code to be frozen at fixed addresses, a
832 precondition for using copy-on-write to share code between multiple Lisp
833 processes. This is less important with modern generational garbage
834 collectors, but not all SBCL platforms use such a garbage collector.
836 @include fun-sb-ext-purify.texinfo
838 The @code{sb-ext:truly-the} special form declares the type of the
839 result of the operations, producing its argument; the declaration is
840 not checked. In short: don't use it.
842 @include special-operator-sb-ext-truly-the.texinfo
844 The @code{sb-ext:freeze-type} declaration declares that a
845 type will never change, which can make type testing
846 (@code{typep}, etc.) more efficient for structure types.