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