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