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