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-setf-gc-logfile.texinfo
61 @include fun-sb-ext-gc-logfile.texinfo
62 @include fun-sb-ext-generation-average-age.texinfo
63 @include fun-sb-ext-generation-bytes-allocated.texinfo
64 @include fun-sb-ext-generation-bytes-consed-between-gcs.texinfo
65 @include fun-sb-ext-generation-minimum-age-before-gc.texinfo
66 @include fun-sb-ext-generation-number-of-gcs-before-promotion.texinfo
67 @include fun-sb-ext-generation-number-of-gcs.texinfo
68 @include fun-sb-ext-get-bytes-consed.texinfo
70 @node Metaobject Protocol
71 @comment node-name, next, previous, up
72 @section Metaobject Protocol
74 @subsection AMOP Compatibility of Metaobject Protocol
76 SBCL supports a metaobject protocol which is intended to be compatible
77 with AMOP; present exceptions to this (as distinct from current bugs)
83 @findex @sbmop{compute-effective-method}
84 @code{compute-effective-method} only returns one value, not two.
86 There is no record of what the second return value was meant to
87 indicate, and apparently no clients for it.
90 @tindex @cl{generic-function}
91 @tindex @cl{standard-generic-function}
92 @tindex @sbmop{funcallable-standard-object}
93 @tindex @cl{standard-object}
95 The direct superclasses of @code{sb-mop:funcallable-standard-object} are
96 @code{(function standard-object)}, not @code{(standard-object function)}.
98 This is to ensure that the @code{standard-object} class is the last of
99 the standardized classes before @code{t} appearing in the class
100 precedence list of @code{generic-function} and
101 @code{standard-generic-function}, as required by section 1.4.4.5 of the
105 @findex @cl{ensure-generic-function}
106 @findex @sbmop{generic-function-declarations}
107 the arguments @code{:declare} and @code{:declarations} to
108 @code{ensure-generic-function} are both accepted, with the leftmost
109 argument defining the declarations to be stored and returned by
110 @code{generic-function-declarations}.
112 Where AMOP specifies @code{:declarations} as the keyword argument to
113 @code{ensure-generic-function}, the Common Lisp standard specifies
114 @code{:declare}. Portable code should use @code{:declare}.
117 @findex @sbmop{validate-superclass}
118 @findex @sbmop{finalize-inheritance}
119 @tindex @cl{standard-class}
120 @tindex @sbmop{funcallable-standard-class}
121 @tindex @cl{function}
122 @findex @sbmop{class-prototype}
123 although SBCL obeys the requirement in AMOP that
124 @code{validate-superclass} should treat @code{standard-class} and
125 @code{funcallable-standard-class} as compatible metaclasses, we
126 impose an additional requirement at class finalization time: a class
127 of metaclass @code{funcallable-standard-class} must have
128 @code{function} in its superclasses, and a class of metaclass
129 @code{standard-class} must not.
132 @findex @cl{class-of}
133 @findex @cl{subtypep}
134 After a class has been finalized, it is associated with a class
135 prototype which is accessible by a standard mop function
136 @code{sb-mop:class-prototype}. The user can then ask whether this
137 object is a @code{function} or not in several different ways: whether it
138 is a function according to @code{typep}; whether its @code{class-of} is
139 @code{subtypep} @code{function}, or whether @code{function} appears in
140 the superclasses of the class. The additional consistency requirement
141 comes from the desire to make all of these answers the same.
143 The following class definitions are bad, and will lead to errors
144 either immediately or if an instance is created:
146 (defclass bad-object (funcallable-standard-object)
148 (:metaclass standard-class))
151 (defclass bad-funcallable-object (standard-object)
153 (:metaclass funcallable-standard-class))
155 The following definition is acceptable:
158 ((slot :initarg slot)))
159 (defclass funcallable-object (funcallable-standard-object mixin)
161 (:metaclass funcallable-standard-class))
163 and leads to a class whose instances are funcallable and have one slot.
165 @tindex @sbmop{funcallable-standard-object}
166 Note that this requirement also applies to the class
167 @code{sb-mop:funcallable-standard-object}, which has metaclass
168 @code{sb-mop:funcallable-standard-class} rather than
169 @code{standard-class} as AMOP specifies.
172 the requirement that ``No portable class @math{C_p} may inherit, by
173 virtue of being a direct or indirect subclass of a specified class, any
174 slot for which the name is a symbol accessible in the
175 @code{common-lisp-user} package or exported by any package defined in
176 the ANSI Common Lisp standard.'' is interpreted to mean that the
177 standardized classes themselves should not have slots named by external
178 symbols of public packages.
180 The rationale behind the restriction is likely to be similar to the ANSI
181 Common Lisp restriction on defining functions, variables and types named
182 by symbols in the Common Lisp package: preventing two independent pieces
183 of software from colliding with each other.
186 @findex @sbmop{slot-value-using-class}
187 @findex @setf{@sbmop{slot-value-using-class}}
188 @findex @sbmop{slot-boundp-using-class}
189 specializations of the @code{new-value} argument to @code{(setf
190 sb-mop:slot-value-using-class)} are not allowed: all user-defined
191 methods must have a specializer of the class @code{t}.
193 This prohibition is motivated by a separation of layers: the
194 @code{slot-value-using-class} family of functions is intended for use in
195 implementing different and new slot allocation strategies, rather than
196 in performing application-level dispatching. Additionally, with this
197 requirement, there is a one-to-one mapping between metaclass, class and
198 slot-definition-class tuples and effective methods of @code{(setf
199 slot-value-using-class)}, which permits optimization of @code{(setf
200 slot-value-using-class)}'s discriminating function in the same manner as
201 for @code{slot-value-using-class} and @code{slot-boundp-using-class}.
203 Note that application code may specialize on the @code{new-value}
204 argument of slot accessors.
207 @findex @cl{defclass}
208 @findex @sbmop{ensure-class}
209 @findex @sbmop{ensure-class-using-class}
210 @findex @cl{find-class}
211 @findex @cl{class-name}
212 the class named by the @code{name} argument to @code{ensure-class}, if
213 any, is only redefined if it is the proper name of that class;
214 otherwise, a new class is created.
216 This is consistent with the description of @code{ensure-class} in AMOP
217 as the functional version of @code{defclass}, which has this behaviour;
218 however, it is not consistent with the weaker requirement in AMOP, which
219 states that any class found by @code{find-class}, no matter what its
220 @code{class-name}, is redefined.
224 @subsection Metaobject Protocol Extensions
226 In addition, SBCL supports extensions to the Metaobject protocol from
227 AMOP; at present, they are:
232 @findex @cl{defmethod}
233 @findex @cl{find-class}
234 @findex @sbmop{intern-eql-specializer}
235 @findex @sbpcl{make-method-specializers-form}
236 @findex @sbmop{make-method-lambda}
237 compile-time support for generating specializer metaobjects from
238 specializer names in @code{defmethod} forms is provided by the
239 @code{make-method-specializers-form} function, which returns a form
240 which, when evaluated in the lexical environment of the
241 @code{defmethod}, returns a list of specializer metaobjects. This
242 operator suffers from similar restrictions to those affecting
243 @code{make-method-lambda}, namely that the generic function must be
244 defined when the @code{defmethod} form is expanded, so that the
245 correct method of @code{make-method-specializers-form} is invoked.
246 The system-provided method on @code{make-method-specializers-form}
247 generates a call to @code{find-class} for each symbol specializer
248 name, and a call to @code{intern-eql-specializer} for each @code{(eql
249 @var{x})} specializer name.
252 @findex @cl{find-method}
253 @findex @sbpcl{parse-specializer-using-class}
254 @findex @sbpcl{unparse-specializer-using-class}
255 run-time support for converting between specializer names and
256 specializer metaobjects, mostly for the purposes of
257 @code{find-method}, is provided by
258 @code{parse-specializer-using-class} and
259 @code{unparse-specializer-using-class}, which dispatch on their first
260 argument, the generic function associated with a method with the given
261 specializer. The system-provided methods on those methods convert
262 between classes and proper names and between lists of the form
263 @code{(eql @var{x})} and interned eql specializer objects.
266 @vindex @sbpcl{+slot-unbound+}
267 @findex @sbmop{standard-instance-access}
268 @findex @sbmop{funcallable-standard-instance-access}
269 distinguising unbound instance allocated slots from bound ones when
270 using @code{standard-instance-access} and
271 @code{funcallable-standard-instance-access} is possible by comparison
272 to the constant @code{+slot-unbound+}.
276 @node Support For Unix
277 @comment node-name, next, previous, up
278 @section Support For Unix
281 * Command-line arguments::
282 * Querying the process environment::
283 * Running external programs::
286 @node Command-line arguments
287 @subsection Command-line arguments
288 @vindex @sbext{@earmuffs{posix-argv}}
290 The UNIX command line can be read from the variable
291 @code{sb-ext:*posix-argv*}.
293 @node Querying the process environment
294 @subsection Querying the process environment
296 The UNIX environment can be queried with the
297 @code{sb-ext:posix-getenv} function.
299 @include fun-sb-ext-posix-getenv.texinfo
301 @node Running external programs
302 @subsection Running external programs
304 External programs can be run with @code{sb-ext:run-program}.
305 @footnote{In SBCL versions prior to 1.0.13, @code{sb-ext:run-program}
306 searched for executables in a manner somewhat incompatible with other
307 languages. As of this version, SBCL uses the system library routine
308 @code{execvp(3)}, and no longer contains the function,
309 @code{find-executable-in-search-path}, which implemented the old
310 search. Users who need this function may find it
311 in @file{run-program.lisp} versions 1.67 and earlier in SBCL's CVS
313 @url{http://sbcl.cvs.sourceforge.net/sbcl/sbcl/src/code/run-program.lisp?view=log}. However,
314 we caution such users that this search routine finds executables that
315 system library routines do not.}
317 @include fun-sb-ext-run-program.texinfo
319 When @code{sb-ext:run-program} is called with @code{wait} equal to
320 NIL, an instance of class @var{sb-ext:process} is returned. The
321 following functions are available for use with processes:
323 @include fun-sb-ext-process-p.texinfo
325 @include fun-sb-ext-process-input.texinfo
327 @include fun-sb-ext-process-output.texinfo
329 @include fun-sb-ext-process-error.texinfo
331 @include fun-sb-ext-process-alive-p.texinfo
333 @include fun-sb-ext-process-status.texinfo
335 @include fun-sb-ext-process-wait.texinfo
337 @include fun-sb-ext-process-exit-code.texinfo
339 @include fun-sb-ext-process-core-dumped.texinfo
341 @include fun-sb-ext-process-close.texinfo
343 @include fun-sb-ext-process-kill.texinfo
345 @node Customization Hooks for Users
346 @comment node-name, next, previous, up
347 @section Customization Hooks for Users
349 The toplevel repl prompt may be customized, and the function
350 that reads user input may be replaced completely.
351 @c <!-- FIXME but I don't currently remember how -->
353 The behaviour of @code{require} when called with only one argument is
354 implementation-defined. In SBCL, @code{require} behaves in the
357 @include fun-common-lisp-require.texinfo
358 @include var-sb-ext-star-module-provider-functions-star.texinfo
360 Although SBCL does not provide a resident editor, the @code{ed}
361 function can be customized to hook into user-provided editing
362 mechanisms as follows:
364 @include fun-common-lisp-ed.texinfo
365 @include var-sb-ext-star-ed-functions-star.texinfo
367 Conditions of type @code{warning} and @code{style-warning} are
368 sometimes signaled at runtime, especially during execution of Common
369 Lisp defining forms such as @code{defun}, @code{defmethod}, etc. To
370 muffle these warnings at runtime, SBCL provides a variable
371 @code{sb-ext:*muffled-warnings*}:
373 @include var-sb-ext-star-muffled-warnings-star.texinfo
375 @node Tools To Help Developers
376 @comment node-name, next, previous, up
377 @section Tools To Help Developers
381 SBCL provides a profiler and other extensions to the ANSI @code{trace}
382 facility. For more information, see @ref{Macro common-lisp:trace}.
384 The debugger supports a number of options. Its documentation is
385 accessed by typing @kbd{help} at the debugger prompt. @xref{Debugger}.
387 Documentation for @code{inspect} is accessed by typing @kbd{help} at
388 the @code{inspect} prompt.
390 @node Resolution of Name Conflicts
391 @section Resolution of Name Conflicts
392 @tindex @sbext{name-conflict}
393 @findex @sbext{name-conflict-symbols}
395 The ANSI standard (section 11.1.1.2.5) requires that name conflicts in
396 packages be resolvable in favour of any of the conflicting symbols. In
397 the interactive debugger, this is achieved by prompting for the symbol
398 in whose favour the conflict should be resolved; for programmatic use,
399 the @code{sb-ext:resolve-conflict} restart should be invoked with one
400 argument, which should be a member of the list returned by the condition
401 accessor @code{sb-ext:name-conflict-symbols}.
403 @node Hash Table Extensions
404 @comment node-name, next, previous, up
405 @section Hash Table Extensions
408 Hash table extensions supported by SBCL are all controlled by keyword
409 arguments to @code{make-hash-table}.
411 @include fun-common-lisp-make-hash-table.texinfo
413 @include macro-sb-ext-define-hash-table-test.texinfo
415 @include macro-sb-ext-with-locked-hash-table.texinfo
417 @include fun-sb-ext-hash-table-synchronized-p.texinfo
419 @include fun-sb-ext-hash-table-weakness.texinfo
421 @node Miscellaneous Extensions
422 @comment node-name, next, previous, up
423 @section Miscellaneous Extensions
425 @include fun-sb-ext-array-storage-vector.texinfo
426 @include fun-sb-ext-delete-directory.texinfo
427 @include fun-sb-ext-get-time-of-day.texinfo
428 @include fun-sb-ext-seed-random-state.texinfo
430 @node Stale Extensions
431 @comment node-name, next, previous, up
432 @section Stale Extensions
434 SBCL has inherited from CMUCL various hooks to allow the user to
435 tweak and monitor the garbage collection process. These are somewhat
436 stale code, and their interface might need to be cleaned up. If you
437 have urgent need of them, look at the code in @file{src/code/gc.lisp}
438 and bring it up on the developers' mailing list.
440 SBCL has various hooks inherited from CMUCL, like
441 @code{sb-ext:float-denormalized-p}, to allow a program to take
442 advantage of IEEE floating point arithmetic properties which aren't
443 conveniently or efficiently expressible using the ANSI standard. These
444 look good, and their interface looks good, but IEEE support is
445 slightly broken due to a stupid decision to remove some support for
446 infinities (because it wasn't in the ANSI spec and it didn't occur to
447 me that it was in the IEEE spec). If you need this stuff, take a look
448 at the code and bring it up on the developers' mailing
452 @node Efficiency Hacks
453 @comment node-name, next, previous, up
454 @section Efficiency Hacks
456 The @code{sb-ext:purify} function causes SBCL first to collect all
457 garbage, then to mark all uncollected objects as permanent, never again
458 attempting to collect them as garbage. This can cause a large increase
459 in efficiency when using a primitive garbage collector, or a more
460 moderate increase in efficiency when using a more sophisticated garbage
461 collector which is well suited to the program's memory usage pattern. It
462 also allows permanent code to be frozen at fixed addresses, a
463 precondition for using copy-on-write to share code between multiple Lisp
464 processes. This is less important with modern generational garbage
465 collectors, but not all SBCL platforms use such a garbage collector.
467 @include fun-sb-ext-purify.texinfo
469 The @code{sb-ext:truly-the} special form declares the type of the
470 result of the operations, producing its argument; the declaration is
471 not checked. In short: don't use it.
473 @include special-operator-sb-ext-truly-the.texinfo
475 The @code{sb-ext:freeze-type} declaration declares that a
476 type will never change, which can make type testing
477 (@code{typep}, etc.) more efficient for structure types.