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