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.
313 @findex @sbmop{slot-definition-name}
314 @tindex @cl{structure-class}
315 @findex @cl{defstruct}
316 an error is not signaled in the case of the @code{:name} initialization
317 argument for @code{slot-definition} objects being a constant, when the
318 slot definition is of type @code{structure-slot-definition} (i.e. it is
319 associated with a class of type @code{structure-class}).
321 This allows code which uses constant names for structure slots to
322 continue working as specified in ANSI, while enforcing the constraint
323 for all other types of slot.
327 @subsection Metaobject Protocol Extensions
329 In addition, SBCL supports extensions to the Metaobject protocol from
330 AMOP; at present, they are:
335 @findex @cl{defmethod}
336 @findex @cl{find-class}
337 @findex @sbmop{intern-eql-specializer}
338 @findex @sbpcl{make-method-specializers-form}
339 @findex @sbmop{make-method-lambda}
340 compile-time support for generating specializer metaobjects from
341 specializer names in @code{defmethod} forms is provided by the
342 @code{make-method-specializers-form} function, which returns a form
343 which, when evaluated in the lexical environment of the
344 @code{defmethod}, returns a list of specializer metaobjects. This
345 operator suffers from similar restrictions to those affecting
346 @code{make-method-lambda}, namely that the generic function must be
347 defined when the @code{defmethod} form is expanded, so that the
348 correct method of @code{make-method-specializers-form} is invoked.
349 The system-provided method on @code{make-method-specializers-form}
350 generates a call to @code{find-class} for each symbol specializer
351 name, and a call to @code{intern-eql-specializer} for each @code{(eql
352 @var{x})} specializer name.
355 @findex @cl{find-method}
356 @findex @sbpcl{parse-specializer-using-class}
357 @findex @sbpcl{unparse-specializer-using-class}
358 run-time support for converting between specializer names and
359 specializer metaobjects, mostly for the purposes of
360 @code{find-method}, is provided by
361 @code{parse-specializer-using-class} and
362 @code{unparse-specializer-using-class}, which dispatch on their first
363 argument, the generic function associated with a method with the given
364 specializer. The system-provided methods on those methods convert
365 between classes and proper names and between lists of the form
366 @code{(eql @var{x})} and interned eql specializer objects.
369 @vindex @sbpcl{+slot-unbound+}
370 @findex @sbmop{standard-instance-access}
371 @findex @sbmop{funcallable-standard-instance-access}
372 distinguishing unbound instance allocated slots from bound ones when
373 using @code{standard-instance-access} and
374 @code{funcallable-standard-instance-access} is possible by comparison
375 to the constant @code{+slot-unbound+}.
379 @node Extensible Sequences
380 @comment node-name, next, previous, up
381 @section Extensible Sequences
384 * Iterator Protocol::
385 * Simple Iterator Protocol::
388 ANSI Common Lisp has a class @code{sequence} with subclasses @code{list} and
389 @code{vector} on which the ``sequence functions'' like @code{find},
390 @code{subseq}, etc. operate. As an extension to the ANSI specification,
391 SBCL allows additional subclasses of @code{sequence} to be defined
392 @footnote{A motivation, rationale and additional examples for the design
393 of this extension can be found in the paper @cite{Rhodes, Christophe
394 (2007): User-extensible sequences in Common Lisp} available for download
396 @url{http://www.doc.gold.ac.uk/~mas01cr/papers/ilc2007/sequences-20070301.pdf}.}.
397 @tindex @cl{sequence}
402 Users of this extension just make instances of @code{sequence} subclasses
403 and transparently operate on them using sequence functions:
405 (coerce (subseq (make-instance 'my-sequence) 5 10) 'list)
407 From this perspective, no distinction between builtin and user-defined
408 @code{sequence} subclasses should be necessary.
411 @findex @cl{make-instance}
414 Providers of the extension, that is of user-defined @code{sequence}
415 subclasses, have to adhere to a ``sequence protocol'' which consists of
416 a set of generic functions in the @code{sequence} package.
418 A minimal @code{sequence} subclass has to specify @code{standard-object} and
419 @code{sequence} as its superclasses and has to be the specializer of the
420 @code{sequence} parameter of methods on at least the following generic
422 @tindex @cl{sequence}
423 @tindex @cl{standard-object}
425 @include fun-sb-sequence-length.texinfo
426 @include fun-sb-sequence-elt.texinfo
427 @include fun-sb-sequence-setf-elt.texinfo
428 @include fun-sb-sequence-adjust-sequence.texinfo
429 @include fun-sb-sequence-make-sequence-like.texinfo
431 @code{make-sequence-like} is needed for functions returning
432 freshly-allocated sequences such as @code{subseq} or
433 @code{copy-seq}. @code{adjust-sequence} is needed for functions which
434 destructively modify their arguments such as @code{delete}. In fact, all
435 other sequence functions can be implemented in terms of the above
436 functions and actually are, if no additional methods are
437 defined. However, relying on these generic implementations, in
438 particular not implementing the iterator protocol can incur a high
439 performance penalty @xref{Iterator Protocol}.
440 @tindex @cl{sequence}
441 @findex @sequence{make-sequence-like}
443 @findex @cl{copy-seq}
444 @findex @sequence{adjust-sequence}
446 In addition to the mandatory functions above, methods on the following
447 sequence functions can be defined:
449 @include fun-sb-sequence-emptyp.texinfo
453 @code{sb-sequence:count}, @code{sb-sequence:count-if}, @code{sb-sequence:count-if-not}
456 @code{sb-sequence:find}, @code{sb-sequence:find-if}, @code{sb-sequence:find-if-not}
459 @code{sb-sequence:position}, @code{sb-sequence:position-if}, @code{sb-sequence:position-if-not}
462 @code{sb-sequence:subseq}
465 @code{sb-sequence:copy-seq}
468 @code{sb-sequence:fill}
471 @code{sb-sequence:nsubstitute}, @code{sb-sequence:nsubstitute-if},
472 @code{sb-sequence:nsubstitute-if-not}, @code{sb-sequence:substitute},
473 @code{sb-sequence:substitute-if}, @code{sb-sequence:substitute-if-not}
476 @code{sb-sequence:replace}
479 @code{sb-sequence:nreverse}, @code{sb-sequence:reverse}
482 @code{sb-sequence:reduce}
485 @code{sb-sequence:mismatch}
488 @code{sb-sequence:search}
491 @code{sb-sequence:delete}, @code{sb-sequence:delete-if}, @code{sb-sequence:delete-if-not},
492 @code{sb-sequence:remove}, @code{sb-sequence:remove-if}, @code{sb-sequence:remove-if-not},
495 @code{sb-sequence:delete-duplicates}, @code{sb-sequence:remove-duplicates}
498 @code{sb-sequence:sort}, @code{sb-sequence:stable-sort}
501 In the spirit of @code{dolist}, generic sequences can be traversed using
505 @include macro-sb-sequence-dosequence.texinfo
507 @node Iterator Protocol
508 @comment node-name, next, previous, up
509 @subsection Iterator Protocol
511 The iterator protocol allows subsequently accessing some or all elements
512 of a sequence in forward or reverse direction. Users first call
513 @code{make-sequence-iterator} to create an iteration state and
514 receive functions to query and mutate it. These functions allow, among
515 other things, moving to, retrieving or modifying elements of the
516 sequence. An iteration state consists of a state object, a limit object,
517 a from-end indicator and the following six functions to query or mutate
519 @findex @sequence{make-sequence-iterator}
520 @deffn {Function} @code{step function} sequence iterator from-end
521 Moves the iterator one position forward or backward in the associated
522 sequence depending on the iteration direction.
524 @deffn {Function} @code{endp function} sequence iterator limit from-end
525 Returns non-@code{nil} when the iterator has reached the end of the
526 associated sequence with respect to the iteration direction.
528 @deffn {Function} @code{element function} sequence iterator
529 Returns the sequence element associated to the current position of the
532 @deffn {Function} @code{setf element function} new-value sequence iterator
533 Destructively modifies the associates sequence by replacing the sequence
534 element associated to the current iteration position with a new value.
536 @deffn {Function} @code{index function} sequence iterator
537 Returns the position of the iteration in the associated sequence.
539 @deffn {Function} @code{copy function} sequence iterator
540 Returns a copy of the iteration state which can be mutated independently
541 of the copied iteration state.
544 An iterator is created by calling:
546 @include fun-sb-sequence-make-sequence-iterator.texinfo
548 Note that @code{make-sequence-iterator} calls
549 @code{make-simple-sequence-iterator} when there is no specialized
550 method for a particular @code{sequence} subclass. @xref{Simple Iterator
552 @findex @sequence{make-sequence-iterator}
553 @findex @sequence{make-simple-sequence-iterator}
554 @tindex @cl{sequence}
556 The following convenience macros simplify traversing sequences using
559 @include macro-sb-sequence-with-sequence-iterator.texinfo
560 @include macro-sb-sequence-with-sequence-iterator-functions.texinfo
562 @node Simple Iterator Protocol
563 @comment node-name, next, previous, up
564 @subsection Simple Iterator Protocol
566 For cases in which the full flexibility and performance of the general
567 sequence iterator protocol is not required, there is a simplified
568 sequence iterator protocol consisting of a few generic functions which
569 can be specialized for iterator classes:
571 @include fun-sb-sequence-iterator-step.texinfo
572 @include fun-sb-sequence-iterator-endp.texinfo
573 @include fun-sb-sequence-iterator-element.texinfo
574 @include fun-sb-sequence-setf-iterator-element.texinfo
575 @include fun-sb-sequence-iterator-index.texinfo
576 @include fun-sb-sequence-iterator-copy.texinfo
578 Iterator objects implementing the above simple iteration protocol are
579 created by calling the following generic function:
581 @include fun-sb-sequence-make-simple-sequence-iterator.texinfo
583 @node Support For Unix
584 @comment node-name, next, previous, up
585 @section Support For Unix
588 * Command-line arguments::
589 * Querying the process environment::
590 * Running external programs::
593 @node Command-line arguments
594 @subsection Command-line arguments
595 @vindex @sbext{@earmuffs{posix-argv}}
597 The UNIX command line can be read from the variable
598 @code{sb-ext:*posix-argv*}.
600 @node Querying the process environment
601 @subsection Querying the process environment
603 The UNIX environment can be queried with the
604 @code{sb-ext:posix-getenv} function.
606 @include fun-sb-ext-posix-getenv.texinfo
608 @node Running external programs
609 @subsection Running external programs
611 External programs can be run with @code{sb-ext:run-program}.
612 @footnote{In SBCL versions prior to 1.0.13, @code{sb-ext:run-program}
613 searched for executables in a manner somewhat incompatible with other
614 languages. As of this version, SBCL uses the system library routine
615 @code{execvp(3)}, and no longer contains the function,
616 @code{find-executable-in-search-path}, which implemented the old
617 search. Users who need this function may find it
618 in @file{run-program.lisp} versions 1.67 and earlier in SBCL's CVS
620 @url{http://sbcl.cvs.sourceforge.net/sbcl/sbcl/src/code/run-program.lisp?view=log}. However,
621 we caution such users that this search routine finds executables that
622 system library routines do not.}
624 @include fun-sb-ext-run-program.texinfo
626 When @code{sb-ext:run-program} is called with @code{wait} equal to
627 NIL, an instance of class @var{sb-ext:process} is returned. The
628 following functions are available for use with processes:
630 @include fun-sb-ext-process-p.texinfo
632 @include fun-sb-ext-process-input.texinfo
634 @include fun-sb-ext-process-output.texinfo
636 @include fun-sb-ext-process-error.texinfo
638 @include fun-sb-ext-process-alive-p.texinfo
640 @include fun-sb-ext-process-status.texinfo
642 @include fun-sb-ext-process-wait.texinfo
644 @include fun-sb-ext-process-exit-code.texinfo
646 @include fun-sb-ext-process-core-dumped.texinfo
648 @include fun-sb-ext-process-close.texinfo
650 @include fun-sb-ext-process-kill.texinfo
652 @node Customization Hooks for Users
653 @comment node-name, next, previous, up
654 @section Customization Hooks for Users
656 The toplevel repl prompt may be customized, and the function
657 that reads user input may be replaced completely.
658 @c <!-- FIXME but I don't currently remember how -->
660 The behaviour of @code{require} when called with only one argument is
661 implementation-defined. In SBCL, @code{require} behaves in the
664 @include fun-common-lisp-require.texinfo
665 @include var-sb-ext-star-module-provider-functions-star.texinfo
667 Although SBCL does not provide a resident editor, the @code{ed}
668 function can be customized to hook into user-provided editing
669 mechanisms as follows:
671 @include fun-common-lisp-ed.texinfo
672 @include var-sb-ext-star-ed-functions-star.texinfo
674 Conditions of type @code{warning} and @code{style-warning} are
675 sometimes signaled at runtime, especially during execution of Common
676 Lisp defining forms such as @code{defun}, @code{defmethod}, etc. To
677 muffle these warnings at runtime, SBCL provides a variable
678 @code{sb-ext:*muffled-warnings*}:
680 @include var-sb-ext-star-muffled-warnings-star.texinfo
682 @node Tools To Help Developers
683 @comment node-name, next, previous, up
684 @section Tools To Help Developers
688 SBCL provides a profiler and other extensions to the ANSI @code{trace}
689 facility. For more information, see @ref{Macro common-lisp:trace}.
691 The debugger supports a number of options. Its documentation is
692 accessed by typing @kbd{help} at the debugger prompt. @xref{Debugger}.
694 Documentation for @code{inspect} is accessed by typing @kbd{help} at
695 the @code{inspect} prompt.
697 @node Resolution of Name Conflicts
698 @section Resolution of Name Conflicts
699 @tindex @sbext{name-conflict}
700 @findex @sbext{name-conflict-symbols}
702 The ANSI standard (section 11.1.1.2.5) requires that name conflicts in
703 packages be resolvable in favour of any of the conflicting symbols. In
704 the interactive debugger, this is achieved by prompting for the symbol
705 in whose favour the conflict should be resolved; for programmatic use,
706 the @code{sb-ext:resolve-conflict} restart should be invoked with one
707 argument, which should be a member of the list returned by the condition
708 accessor @code{sb-ext:name-conflict-symbols}.
710 @node Hash Table Extensions
711 @comment node-name, next, previous, up
712 @section Hash Table Extensions
715 Hash table extensions supported by SBCL are all controlled by keyword
716 arguments to @code{make-hash-table}.
718 @include fun-common-lisp-make-hash-table.texinfo
720 @include macro-sb-ext-define-hash-table-test.texinfo
722 @include macro-sb-ext-with-locked-hash-table.texinfo
724 @include fun-sb-ext-hash-table-synchronized-p.texinfo
726 @include fun-sb-ext-hash-table-weakness.texinfo
728 @node Random Number Generation
729 @comment node-name, next, previous, up
730 @section Random Number Generation
731 @cindex Random Number Generation
733 The initial value of @code{*random-state*} is the same each time SBCL
734 is started. This makes it possible for user code to obtain repeatable
735 pseudo random numbers using only standard-provided functionality. See
736 @code{seed-random-state} below for an SBCL extension that allows to
737 seed the random number generator from given data for an additional
738 possibility to achieve this. Non-repeatable random numbers can always
739 be obtained using @code{(make-random-state t)}.
741 The sequence of numbers produced by repeated calls to @code{random}
742 starting with the same random state and using the same sequence of
743 @code{limit} arguments is guaranteed to be reproducible only in the
744 same version of SBCL on the same platform, using the same code under
745 the same evaluator mode and compiler optimization qualities. Just two
746 examples of differences that may occur otherwise: calls to
747 @code{random} can be compiled differently depending on how much is
748 known about the @code{limit} argument at compile time, yielding
749 different results even if called with the same argument at run time,
750 and the results can differ depending on the machine's word size, for
751 example for limits that are fixnums under 64-bit word size but bignums
752 under 32-bit word size.
754 @include fun-sb-ext-seed-random-state.texinfo
756 Some notes on random floats: The standard doesn't prescribe a specific
757 method of generating random floats. The following paragraph describes
758 SBCL's current implementation and should be taken purely informational,
759 that is, user code should not depend on any of its specific properties.
760 The method used has been chosen because it is common, conceptually
763 To generate random floats, SBCL evaluates code that has an equivalent
767 (float (/ (random (expt 2 23)) (expt 2 23)) 1.0f0))
769 (for single-floats) and correspondingly (with @code{52} and
770 @code{1.0d0} instead of @code{23} and @code{1.0f0}) for double-floats.
771 Note especially that this means that zero is a possible return value
772 occurring with probability @code{(expt 2 -23)} respectively
773 @code{(expt 2 -52)}. Also note that there exist twice as many
774 equidistant floats between 0 and 1 as are generated. For example, the
775 largest number that @code{(random 1.0f0)} ever returns is
776 @code{(float (/ (1- (expt 2 23)) (expt 2 23)) 1.0f0)} while
777 @code{(float (/ (1- (expt 2 24)) (expt 2 24)) 1.0f0)} is the
778 largest single-float less than 1. This is a side effect of the fact
779 that the implementation uses the fastest possible conversion from bits
782 SBCL currently uses the Mersenne Twister as its random number
783 generator, specifically the 32-bit version under both 32- and 64-bit
784 word size. The seeding algorithm has been improved several times by
785 the authors of the Mersenne Twister; SBCL uses the third version
786 (from 2002) which is still the most recent as of June 2012. The
787 implementation has been tested to provide output identical to the
788 recommended C implementation.
790 While the Mersenne Twister generates random numbers of much better
791 statistical quality than other widely used generators, it uses only
792 linear operations modulo 2 and thus fails some statistical
793 tests@footnote{See chapter 7 "Testing widely used RNGs" in
794 @cite{TestU01: A C Library for Empirical Testing of Random Number
795 Generators} by Pierre L'Ecuyer and Richard Simard, ACM Transactions on
796 Mathematical Software, Vol. 33, article 22, 2007.}.
797 For example, the distribution of ranks of (sufficiently large) random
798 binary matrices is much distorted compared to the theoretically
799 expected one when the matrices are generated by the Mersenne Twister.
800 Thus, applications that are sensitive to this aspect should use a
801 different type of generator.
803 @node Miscellaneous Extensions
804 @comment node-name, next, previous, up
805 @section Miscellaneous Extensions
807 @include fun-sb-ext-array-storage-vector.texinfo
808 @include fun-sb-ext-delete-directory.texinfo
809 @include fun-sb-ext-get-time-of-day.texinfo
810 @include macro-sb-ext-wait-for.texinfo
811 @include fun-sb-ext-assert-version-gt=.texinfo
813 @node Stale Extensions
814 @comment node-name, next, previous, up
815 @section Stale Extensions
817 SBCL has inherited from CMUCL various hooks to allow the user to
818 tweak and monitor the garbage collection process. These are somewhat
819 stale code, and their interface might need to be cleaned up. If you
820 have urgent need of them, look at the code in @file{src/code/gc.lisp}
821 and bring it up on the developers' mailing list.
823 SBCL has various hooks inherited from CMUCL, like
824 @code{sb-ext:float-denormalized-p}, to allow a program to take
825 advantage of IEEE floating point arithmetic properties which aren't
826 conveniently or efficiently expressible using the ANSI standard. These
827 look good, and their interface looks good, but IEEE support is
828 slightly broken due to a stupid decision to remove some support for
829 infinities (because it wasn't in the ANSI spec and it didn't occur to
830 me that it was in the IEEE spec). If you need this stuff, take a look
831 at the code and bring it up on the developers' mailing
835 @node Efficiency Hacks
836 @comment node-name, next, previous, up
837 @section Efficiency Hacks
839 The @code{sb-ext:purify} function causes SBCL first to collect all
840 garbage, then to mark all uncollected objects as permanent, never again
841 attempting to collect them as garbage. This can cause a large increase
842 in efficiency when using a primitive garbage collector, or a more
843 moderate increase in efficiency when using a more sophisticated garbage
844 collector which is well suited to the program's memory usage pattern. It
845 also allows permanent code to be frozen at fixed addresses, a
846 precondition for using copy-on-write to share code between multiple Lisp
847 processes. This is less important with modern generational garbage
848 collectors, but not all SBCL platforms use such a garbage collector.
850 @include fun-sb-ext-purify.texinfo
852 The @code{sb-ext:truly-the} special form declares the type of the
853 result of the operations, producing its argument; the declaration is
854 not checked. In short: don't use it.
856 @include special-operator-sb-ext-truly-the.texinfo
858 The @code{sb-ext:freeze-type} declaration declares that a
859 type will never change, which can make type testing
860 (@code{typep}, etc.) more efficient for structure types.