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}.
10 * Garbage Collection::
11 * Metaobject Protocol::
13 * Customization Hooks for Users::
14 * Tools To Help Developers::
15 * Resolution of Name Conflicts::
16 * Hash Table Extensions::
17 * Miscellaneous Extensions::
22 @node Garbage Collection
23 @comment node-name, next, previous, up
24 @section Garbage Collection
25 @cindex Garbage collection
27 SBCL provides additional garbage collection functionality not
30 @include var-sb-ext-star-after-gc-hooks-star.texinfo
31 @include fun-sb-ext-gc.texinfo
33 @subsection Finalization
36 Finalization allows code to be executed after an object has been
37 garbage collected. This is useful for example for releasing foreign
38 memory associated with a Lisp object.
40 @include fun-sb-ext-finalize.texinfo
41 @include fun-sb-ext-cancel-finalization.texinfo
43 @subsection Weak Pointers
46 Weak pointers allow references to objects to be maintained without
47 keeping them from being garbage collected: useful for building caches
50 Hash tables can also have weak keys and values: @pxref{Hash Table
53 @include fun-sb-ext-make-weak-pointer.texinfo
54 @include fun-sb-ext-weak-pointer-value.texinfo
56 @subsection Introspection and Tuning
58 @include var-sb-ext-star-gc-run-time-star.texinfo
59 @include fun-sb-ext-bytes-consed-between-gcs.texinfo
60 @include fun-sb-ext-dynamic-space-size.texinfo
61 @include fun-sb-ext-setf-gc-logfile.texinfo
62 @include fun-sb-ext-gc-logfile.texinfo
63 @include fun-sb-ext-generation-average-age.texinfo
64 @include fun-sb-ext-generation-bytes-allocated.texinfo
65 @include fun-sb-ext-generation-bytes-consed-between-gcs.texinfo
66 @include fun-sb-ext-generation-minimum-age-before-gc.texinfo
67 @include fun-sb-ext-generation-number-of-gcs-before-promotion.texinfo
68 @include fun-sb-ext-generation-number-of-gcs.texinfo
69 @include fun-sb-ext-get-bytes-consed.texinfo
71 @node Metaobject Protocol
72 @comment node-name, next, previous, up
73 @section Metaobject Protocol
75 @subsection AMOP Compatibility of Metaobject Protocol
77 SBCL supports a metaobject protocol which is intended to be compatible
78 with AMOP; present exceptions to this (as distinct from current bugs)
84 @findex @sbmop{compute-effective-method}
85 @code{compute-effective-method} only returns one value, not two.
87 There is no record of what the second return value was meant to
88 indicate, and apparently no clients for it.
91 @tindex @cl{generic-function}
92 @tindex @cl{standard-generic-function}
93 @tindex @sbmop{funcallable-standard-object}
94 @tindex @cl{standard-object}
96 The direct superclasses of @code{sb-mop:funcallable-standard-object} are
97 @code{(function standard-object)}, not @code{(standard-object function)}.
99 This is to ensure that the @code{standard-object} class is the last of
100 the standardized classes before @code{t} appearing in the class
101 precedence list of @code{generic-function} and
102 @code{standard-generic-function}, as required by section 1.4.4.5 of the
106 @findex @cl{ensure-generic-function}
107 @findex @sbmop{generic-function-declarations}
108 the arguments @code{:declare} and @code{:declarations} to
109 @code{ensure-generic-function} are both accepted, with the leftmost
110 argument defining the declarations to be stored and returned by
111 @code{generic-function-declarations}.
113 Where AMOP specifies @code{:declarations} as the keyword argument to
114 @code{ensure-generic-function}, the Common Lisp standard specifies
115 @code{:declare}. Portable code should use @code{:declare}.
118 @findex @sbmop{validate-superclass}
119 @findex @sbmop{finalize-inheritance}
120 @tindex @cl{standard-class}
121 @tindex @sbmop{funcallable-standard-class}
122 @tindex @cl{function}
123 @findex @sbmop{class-prototype}
124 although SBCL obeys the requirement in AMOP that
125 @code{validate-superclass} should treat @code{standard-class} and
126 @code{funcallable-standard-class} as compatible metaclasses, we
127 impose an additional requirement at class finalization time: a class
128 of metaclass @code{funcallable-standard-class} must have
129 @code{function} in its superclasses, and a class of metaclass
130 @code{standard-class} must not.
133 @findex @cl{class-of}
134 @findex @cl{subtypep}
135 After a class has been finalized, it is associated with a class
136 prototype which is accessible by a standard mop function
137 @code{sb-mop:class-prototype}. The user can then ask whether this
138 object is a @code{function} or not in several different ways: whether it
139 is a function according to @code{typep}; whether its @code{class-of} is
140 @code{subtypep} @code{function}, or whether @code{function} appears in
141 the superclasses of the class. The additional consistency requirement
142 comes from the desire to make all of these answers the same.
144 The following class definitions are bad, and will lead to errors
145 either immediately or if an instance is created:
147 (defclass bad-object (funcallable-standard-object)
149 (:metaclass standard-class))
152 (defclass bad-funcallable-object (standard-object)
154 (:metaclass funcallable-standard-class))
156 The following definition is acceptable:
159 ((slot :initarg slot)))
160 (defclass funcallable-object (funcallable-standard-object mixin)
162 (:metaclass funcallable-standard-class))
164 and leads to a class whose instances are funcallable and have one slot.
166 @tindex @sbmop{funcallable-standard-object}
167 Note that this requirement also applies to the class
168 @code{sb-mop:funcallable-standard-object}, which has metaclass
169 @code{sb-mop:funcallable-standard-class} rather than
170 @code{standard-class} as AMOP specifies.
173 the requirement that ``No portable class @math{C_p} may inherit, by
174 virtue of being a direct or indirect subclass of a specified class, any
175 slot for which the name is a symbol accessible in the
176 @code{common-lisp-user} package or exported by any package defined in
177 the ANSI Common Lisp standard.'' is interpreted to mean that the
178 standardized classes themselves should not have slots named by external
179 symbols of public packages.
181 The rationale behind the restriction is likely to be similar to the ANSI
182 Common Lisp restriction on defining functions, variables and types named
183 by symbols in the Common Lisp package: preventing two independent pieces
184 of software from colliding with each other.
187 @findex @sbmop{slot-value-using-class}
188 @findex @setf{@sbmop{slot-value-using-class}}
189 @findex @sbmop{slot-boundp-using-class}
190 specializations of the @code{new-value} argument to @code{(setf
191 sb-mop:slot-value-using-class)} are not allowed: all user-defined
192 methods must have a specializer of the class @code{t}.
194 This prohibition is motivated by a separation of layers: the
195 @code{slot-value-using-class} family of functions is intended for use in
196 implementing different and new slot allocation strategies, rather than
197 in performing application-level dispatching. Additionally, with this
198 requirement, there is a one-to-one mapping between metaclass, class and
199 slot-definition-class tuples and effective methods of @code{(setf
200 slot-value-using-class)}, which permits optimization of @code{(setf
201 slot-value-using-class)}'s discriminating function in the same manner as
202 for @code{slot-value-using-class} and @code{slot-boundp-using-class}.
204 Note that application code may specialize on the @code{new-value}
205 argument of slot accessors.
208 @findex @cl{defclass}
209 @findex @sbmop{ensure-class}
210 @findex @sbmop{ensure-class-using-class}
211 @findex @cl{find-class}
212 @findex @cl{class-name}
213 the class named by the @code{name} argument to @code{ensure-class}, if
214 any, is only redefined if it is the proper name of that class;
215 otherwise, a new class is created.
217 This is consistent with the description of @code{ensure-class} in AMOP
218 as the functional version of @code{defclass}, which has this behaviour;
219 however, it is not consistent with the weaker requirement in AMOP, which
220 states that any class found by @code{find-class}, no matter what its
221 @code{class-name}, is redefined.
225 @subsection Metaobject Protocol Extensions
227 In addition, SBCL supports extensions to the Metaobject protocol from
228 AMOP; at present, they are:
233 @findex @cl{defmethod}
234 @findex @cl{find-class}
235 @findex @sbmop{intern-eql-specializer}
236 @findex @sbpcl{make-method-specializers-form}
237 @findex @sbmop{make-method-lambda}
238 compile-time support for generating specializer metaobjects from
239 specializer names in @code{defmethod} forms is provided by the
240 @code{make-method-specializers-form} function, which returns a form
241 which, when evaluated in the lexical environment of the
242 @code{defmethod}, returns a list of specializer metaobjects. This
243 operator suffers from similar restrictions to those affecting
244 @code{make-method-lambda}, namely that the generic function must be
245 defined when the @code{defmethod} form is expanded, so that the
246 correct method of @code{make-method-specializers-form} is invoked.
247 The system-provided method on @code{make-method-specializers-form}
248 generates a call to @code{find-class} for each symbol specializer
249 name, and a call to @code{intern-eql-specializer} for each @code{(eql
250 @var{x})} specializer name.
253 @findex @cl{find-method}
254 @findex @sbpcl{parse-specializer-using-class}
255 @findex @sbpcl{unparse-specializer-using-class}
256 run-time support for converting between specializer names and
257 specializer metaobjects, mostly for the purposes of
258 @code{find-method}, is provided by
259 @code{parse-specializer-using-class} and
260 @code{unparse-specializer-using-class}, which dispatch on their first
261 argument, the generic function associated with a method with the given
262 specializer. The system-provided methods on those methods convert
263 between classes and proper names and between lists of the form
264 @code{(eql @var{x})} and interned eql specializer objects.
267 @vindex @sbpcl{+slot-unbound+}
268 @findex @sbmop{standard-instance-access}
269 @findex @sbmop{funcallable-standard-instance-access}
270 distinguising unbound instance allocated slots from bound ones when
271 using @code{standard-instance-access} and
272 @code{funcallable-standard-instance-access} is possible by comparison
273 to the constant @code{+slot-unbound+}.
277 @node Support For Unix
278 @comment node-name, next, previous, up
279 @section Support For Unix
282 * Command-line arguments::
283 * Querying the process environment::
284 * Running external programs::
287 @node Command-line arguments
288 @subsection Command-line arguments
289 @vindex @sbext{@earmuffs{posix-argv}}
291 The UNIX command line can be read from the variable
292 @code{sb-ext:*posix-argv*}.
294 @node Querying the process environment
295 @subsection Querying the process environment
297 The UNIX environment can be queried with the
298 @code{sb-ext:posix-getenv} function.
300 @include fun-sb-ext-posix-getenv.texinfo
302 @node Running external programs
303 @subsection Running external programs
305 External programs can be run with @code{sb-ext:run-program}.
306 @footnote{In SBCL versions prior to 1.0.13, @code{sb-ext:run-program}
307 searched for executables in a manner somewhat incompatible with other
308 languages. As of this version, SBCL uses the system library routine
309 @code{execvp(3)}, and no longer contains the function,
310 @code{find-executable-in-search-path}, which implemented the old
311 search. Users who need this function may find it
312 in @file{run-program.lisp} versions 1.67 and earlier in SBCL's CVS
314 @url{http://sbcl.cvs.sourceforge.net/sbcl/sbcl/src/code/run-program.lisp?view=log}. However,
315 we caution such users that this search routine finds executables that
316 system library routines do not.}
318 @include fun-sb-ext-run-program.texinfo
320 When @code{sb-ext:run-program} is called with @code{wait} equal to
321 NIL, an instance of class @var{sb-ext:process} is returned. The
322 following functions are available for use with processes:
324 @include fun-sb-ext-process-p.texinfo
326 @include fun-sb-ext-process-input.texinfo
328 @include fun-sb-ext-process-output.texinfo
330 @include fun-sb-ext-process-error.texinfo
332 @include fun-sb-ext-process-alive-p.texinfo
334 @include fun-sb-ext-process-status.texinfo
336 @include fun-sb-ext-process-wait.texinfo
338 @include fun-sb-ext-process-exit-code.texinfo
340 @include fun-sb-ext-process-core-dumped.texinfo
342 @include fun-sb-ext-process-close.texinfo
344 @include fun-sb-ext-process-kill.texinfo
346 @node Customization Hooks for Users
347 @comment node-name, next, previous, up
348 @section Customization Hooks for Users
350 The toplevel repl prompt may be customized, and the function
351 that reads user input may be replaced completely.
352 @c <!-- FIXME but I don't currently remember how -->
354 The behaviour of @code{require} when called with only one argument is
355 implementation-defined. In SBCL, @code{require} behaves in the
358 @include fun-common-lisp-require.texinfo
359 @include var-sb-ext-star-module-provider-functions-star.texinfo
361 Although SBCL does not provide a resident editor, the @code{ed}
362 function can be customized to hook into user-provided editing
363 mechanisms as follows:
365 @include fun-common-lisp-ed.texinfo
366 @include var-sb-ext-star-ed-functions-star.texinfo
368 Conditions of type @code{warning} and @code{style-warning} are
369 sometimes signaled at runtime, especially during execution of Common
370 Lisp defining forms such as @code{defun}, @code{defmethod}, etc. To
371 muffle these warnings at runtime, SBCL provides a variable
372 @code{sb-ext:*muffled-warnings*}:
374 @include var-sb-ext-star-muffled-warnings-star.texinfo
376 @node Tools To Help Developers
377 @comment node-name, next, previous, up
378 @section Tools To Help Developers
382 SBCL provides a profiler and other extensions to the ANSI @code{trace}
383 facility. For more information, see @ref{Macro common-lisp:trace}.
385 The debugger supports a number of options. Its documentation is
386 accessed by typing @kbd{help} at the debugger prompt. @xref{Debugger}.
388 Documentation for @code{inspect} is accessed by typing @kbd{help} at
389 the @code{inspect} prompt.
391 @node Resolution of Name Conflicts
392 @section Resolution of Name Conflicts
393 @tindex @sbext{name-conflict}
394 @findex @sbext{name-conflict-symbols}
396 The ANSI standard (section 11.1.1.2.5) requires that name conflicts in
397 packages be resolvable in favour of any of the conflicting symbols. In
398 the interactive debugger, this is achieved by prompting for the symbol
399 in whose favour the conflict should be resolved; for programmatic use,
400 the @code{sb-ext:resolve-conflict} restart should be invoked with one
401 argument, which should be a member of the list returned by the condition
402 accessor @code{sb-ext:name-conflict-symbols}.
404 @node Hash Table Extensions
405 @comment node-name, next, previous, up
406 @section Hash Table Extensions
409 Hash table extensions supported by SBCL are all controlled by keyword
410 arguments to @code{make-hash-table}.
412 @include fun-common-lisp-make-hash-table.texinfo
414 @include macro-sb-ext-define-hash-table-test.texinfo
416 @include macro-sb-ext-with-locked-hash-table.texinfo
418 @include fun-sb-ext-hash-table-synchronized-p.texinfo
420 @include fun-sb-ext-hash-table-weakness.texinfo
422 @node Miscellaneous Extensions
423 @comment node-name, next, previous, up
424 @section Miscellaneous Extensions
426 @include fun-sb-ext-array-storage-vector.texinfo
427 @include fun-sb-ext-delete-directory.texinfo
428 @include fun-sb-ext-get-time-of-day.texinfo
429 @include fun-sb-ext-seed-random-state.texinfo
430 @include macro-sb-ext-wait-for.texinfo
432 @node Stale Extensions
433 @comment node-name, next, previous, up
434 @section Stale Extensions
436 SBCL has inherited from CMUCL various hooks to allow the user to
437 tweak and monitor the garbage collection process. These are somewhat
438 stale code, and their interface might need to be cleaned up. If you
439 have urgent need of them, look at the code in @file{src/code/gc.lisp}
440 and bring it up on the developers' mailing list.
442 SBCL has various hooks inherited from CMUCL, like
443 @code{sb-ext:float-denormalized-p}, to allow a program to take
444 advantage of IEEE floating point arithmetic properties which aren't
445 conveniently or efficiently expressible using the ANSI standard. These
446 look good, and their interface looks good, but IEEE support is
447 slightly broken due to a stupid decision to remove some support for
448 infinities (because it wasn't in the ANSI spec and it didn't occur to
449 me that it was in the IEEE spec). If you need this stuff, take a look
450 at the code and bring it up on the developers' mailing
454 @node Efficiency Hacks
455 @comment node-name, next, previous, up
456 @section Efficiency Hacks
458 The @code{sb-ext:purify} function causes SBCL first to collect all
459 garbage, then to mark all uncollected objects as permanent, never again
460 attempting to collect them as garbage. This can cause a large increase
461 in efficiency when using a primitive garbage collector, or a more
462 moderate increase in efficiency when using a more sophisticated garbage
463 collector which is well suited to the program's memory usage pattern. It
464 also allows permanent code to be frozen at fixed addresses, a
465 precondition for using copy-on-write to share code between multiple Lisp
466 processes. This is less important with modern generational garbage
467 collectors, but not all SBCL platforms use such a garbage collector.
469 @include fun-sb-ext-purify.texinfo
471 The @code{sb-ext:truly-the} special form declares the type of the
472 result of the operations, producing its argument; the declaration is
473 not checked. In short: don't use it.
475 @include special-operator-sb-ext-truly-the.texinfo
477 The @code{sb-ext:freeze-type} declaration declares that a
478 type will never change, which can make type testing
479 (@code{typep}, etc.) more efficient for structure types.