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
26 SBCL provides additional garbage collection functionality not
27 specified by ANSI. Weak pointers allow references to objects to be
28 maintained without keeping them from being garbage collected, and
29 ``finalization'' hooks are available to cause code to be executed when
30 an object has been garbage collected. Additionally users can specify
31 their own cleanup actions to be executed with garbage collection. See
32 also @code{make-hash-table} for information on weak hash tables.
34 @include fun-sb-ext-finalize.texinfo
35 @include fun-sb-ext-cancel-finalization.texinfo
36 @include fun-sb-ext-make-weak-pointer.texinfo
37 @include fun-sb-ext-weak-pointer-value.texinfo
38 @include var-sb-ext-star-after-gc-hooks-star.texinfo
40 @node Metaobject Protocol
41 @comment node-name, next, previous, up
42 @section Metaobject Protocol
44 SBCL supports a metaobject protocol which is intended to be compatible
45 with AMOP; present exceptions to this (as distinct from current bugs)
51 @findex compute-effective-method
52 @findex sb-mop:compute-effective-method
53 @code{compute-effective-method} only returns one value, not two.
55 There is no record of what the second return value was meant to
56 indicate, and apparently no clients for it.
59 @tindex generic-function
60 @tindex standard-generic-function
61 @tindex funcallable-standard-object
62 @tindex sb-mop:funcallable-standard-object
63 @tindex standard-object
65 The direct superclasses of @code{sb-mop:funcallable-standard-object} are
66 @code{(function standard-object)}, not @code{(standard-object function)}.
68 This is to ensure that the @code{standard-object} class is the last of
69 the standardized classes before @code{t} appearing in the class
70 precedence list of @code{generic-function} and
71 @code{standard-generic-function}, as required by section 1.4.4.5 of the
75 @findex ensure-generic-function
76 @findex generic-function-declarations
77 @findex sb-mop:generic-function-declarations
78 the arguments @code{:declare} and @code{:declarations} to
79 @code{ensure-generic-function} are both accepted, with the leftmost
80 argument defining the declarations to be stored and returned by
81 @code{generic-function-declarations}.
83 Where AMOP specifies @code{:declarations} as the keyword argument to
84 @code{ensure-generic-function}, the Common Lisp standard specifies
85 @code{:declare}. Portable code should use @code{:declare}.
88 @findex validate-superclass
89 @findex finalize-inheritance
90 @findex sb-mop:validate-superclass
91 @findex sb-mop:finalize-inheritance
92 @tindex standard-class
93 @tindex funcallable-standard-class
94 @tindex sb-mop:funcallable-standard-class
96 @findex sb-mop:class-prototype
97 @findex class-prototype
98 although SBCL obeys the requirement in AMOP that
99 @code{validate-superclass} should treat @code{standard-class} and
100 @code{funcallable-standard-class} as compatible metaclasses, we
101 impose an additional requirement at class finalization time: a class
102 of metaclass @code{funcallable-standard-class} must have
103 @code{function} in its superclasses, and a class of metaclass
104 @code{standard-class} must not.
109 After a class has been finalized, it is associated with a class
110 prototype which is accessible by a standard mop function
111 @code{sb-mop:class-prototype}. The user can then ask whether this
112 object is a @code{function} or not in several different ways: whether it
113 is a function according to @code{typep}; whether its @code{class-of} is
114 @code{subtypep} @code{function}, or whether @code{function} appears in
115 the superclasses of the class. The additional consistency requirement
116 comes from the desire to make all of these answers the same.
118 The following class definitions are bad, and will lead to errors
119 either immediately or if an instance is created:
121 (defclass bad-object (funcallable-standard-object)
123 (:metaclass standard-class))
126 (defclass bad-funcallable-object (standard-object)
128 (:metaclass funcallable-standard-class))
130 The following definition is acceptable:
133 ((slot :initarg slot)))
134 (defclass funcallable-object (funcallable-standard-object mixin)
136 (:metaclass funcallable-standard-class))
138 and leads to a class whose instances are funcallable and have one slot.
140 @tindex funcallable-standard-object
141 @tindex sb-mop:funcallable-standard-object
142 Note that this requirement also applies to the class
143 @code{sb-mop:funcallable-standard-object}, which has metaclass
144 @code{sb-mop:funcallable-standard-class} rather than
145 @code{standard-class} as AMOP specifies.
148 the requirement that ``No portable class @math{C_p} may inherit, by
149 virtue of being a direct or indirect subclass of a specified class, any
150 slot for which the name is a symbol accessible in the
151 @code{common-lisp-user} package or exported by any package defined in
152 the ANSI Common Lisp standard.'' is interpreted to mean that the
153 standardized classes themselves should not have slots named by external
154 symbols of public packages.
156 The rationale behind the restriction is likely to be similar to the ANSI
157 Common Lisp restriction on defining functions, variables and types named
158 by symbols in the Common Lisp package: preventing two independent pieces
159 of software from colliding with each other.
162 @findex slot-value-using-class
163 @findex sb-mop:slot-value-using-class
164 @findex (setf slot-value-using-class)
165 @findex (setf sb-mop:slot-value-using-class)
166 @findex slot-boundp-using-class
167 @findex sb-mop:slot-boundp-using-class
168 specializations of the @code{new-value} argument to @code{(setf
169 sb-mop:slot-value-using-class)} are not allowed: all user-defined
170 methods must have a specializer of the class @code{t}.
172 This prohibition is motivated by a separation of layers: the
173 @code{slot-value-using-class} family of functions is intended for use in
174 implementing different and new slot allocation strategies, rather than
175 in performing application-level dispatching. Additionally, with this
176 requirement, there is a one-to-one mapping between metaclass, class and
177 slot-definition-class tuples and effective methods of @code{(setf
178 slot-value-using-class)}, which permits optimization of @code{(setf
179 slot-value-using-class)}'s discriminating function in the same manner as
180 for @code{slot-value-using-class} and @code{slot-boundp-using-class}.
182 Note that application code may specialize on the @code{new-value}
183 argument of slot accessors.
188 @findex ensure-class-using-class
189 @findex sb-mop:ensure-class
190 @findex sb-mop:ensure-class-using-class
193 the class named by the @code{name} argument to @code{ensure-class}, if
194 any, is only redefined if it is the proper name of that class;
195 otherwise, a new class is created.
197 This is consistent with the description of @code{ensure-class} in AMOP
198 as the functional version of @code{defclass}, which has this behaviour;
199 however, it is not consistent with the weaker requirement in AMOP, which
200 states that any class found by @code{find-class}, no matter what its
201 @code{class-name}, is redefined.
205 In addition, SBCL supports extensions to the Metaobject protocol from
206 AMOP; at present, they are:
213 @findex intern-eql-specializer
214 @findex sb-mop:intern-eql-specializer
215 @findex make-method-specializers-form
216 @findex sb-pcl:make-method-specializers-form
217 @findex make-method-lambda
218 @findex sb-mop:make-method-lambda
219 compile-time support for generating specializer metaobjects from
220 specializer names in @code{defmethod} forms is provided by the
221 @code{make-method-specializers-form} function, which returns a form
222 which, when evaluated in the lexical environment of the
223 @code{defmethod}, returns a list of specializer metaobjects. This
224 operator suffers from similar restrictions to those affecting
225 @code{make-method-lambda}, namely that the generic function must be
226 defined when the @code{defmethod} form is expanded, so that the
227 correct method of @code{make-method-specializers-form} is invoked.
228 The system-provided method on @code{make-method-specializers-form}
229 generates a call to @code{find-class} for each symbol specializer
230 name, and a call to @code{intern-eql-specializer} for each @code{(eql
231 @var{x})} specializer name.
235 @findex parse-specializer-using-class
236 @findex unparse-specializer-using-class
237 @findex sb-pcl:parse-specializer-using-class
238 @findex sb-pcl:unparse-specializer-using-class
239 run-time support for converting between specializer names and
240 specializer metaobjects, mostly for the purposes of
241 @code{find-method}, is provided by
242 @code{parse-specializer-using-class} and
243 @code{unparse-specializer-using-class}, which dispatch on their first
244 argument, the generic function associated with a method with the given
245 specializer. The system-provided methods on those methods convert
246 between classes and proper names and between lists of the form
247 @code{(eql @var{x})} and interned eql specializer objects.
251 @node Support For Unix
252 @comment node-name, next, previous, up
253 @section Support For Unix
256 * Command-line arguments::
257 * Querying the process environment::
258 * Running external programs::
261 @node Command-line arguments
262 @subsection Command-line arguments
263 @vindex sb-ext:*posix-argv*
266 The UNIX command line can be read from the variable
267 @code{sb-ext:*posix-argv*}.
269 @node Querying the process environment
270 @subsection Querying the process environment
272 The UNIX environment can be queried with the
273 @code{sb-ext:posix-getenv} function.
275 @include fun-sb-ext-posix-getenv.texinfo
277 @node Running external programs
278 @subsection Running external programs
280 External programs can be run with @code{sb-ext:run-program}.
281 @footnote{In SBCL versions prior to 1.0.13, @code{sb-ext:run-program}
282 searched for executables in a manner somewhat incompatible with other
283 languages. As of this version, SBCL uses the system library routine
284 @code{execvp(3)}, and no longer contains the function,
285 @code{find-executable-in-search-path}, which implemented the old
286 search. Users who need this function may find it
287 in @file{run-program.lisp} versions 1.67 and earlier in SBCL's CVS
289 @url{http://sbcl.cvs.sourceforge.net/sbcl/sbcl/src/code/run-program.lisp?view=log}. However,
290 we caution such users that this search routine finds executables that
291 system library routines do not.}
293 @include fun-sb-ext-run-program.texinfo
295 When @code{sb-ext:run-program} is called with @code{wait} equal to
296 NIL, an instance of class @var{sb-ext:process} is returned. The
297 following functions are available for use with processes:
299 @include fun-sb-ext-process-p.texinfo
301 @include fun-sb-ext-process-input.texinfo
303 @include fun-sb-ext-process-output.texinfo
305 @include fun-sb-ext-process-error.texinfo
307 @include fun-sb-ext-process-alive-p.texinfo
309 @include fun-sb-ext-process-status.texinfo
311 @include fun-sb-ext-process-wait.texinfo
313 @include fun-sb-ext-process-exit-code.texinfo
315 @include fun-sb-ext-process-core-dumped.texinfo
317 @include fun-sb-ext-process-close.texinfo
319 @include fun-sb-ext-process-kill.texinfo
321 @node Customization Hooks for Users
322 @comment node-name, next, previous, up
323 @section Customization Hooks for Users
325 The toplevel repl prompt may be customized, and the function
326 that reads user input may be replaced completely.
327 @c <!-- FIXME but I don't currently remember how -->
329 The behaviour of @code{require} when called with only one argument is
330 implementation-defined. In SBCL, @code{require} behaves in the
333 @include fun-common-lisp-require.texinfo
334 @include var-sb-ext-star-module-provider-functions-star.texinfo
336 Although SBCL does not provide a resident editor, the @code{ed}
337 function can be customized to hook into user-provided editing
338 mechanisms as follows:
340 @include fun-common-lisp-ed.texinfo
341 @include var-sb-ext-star-ed-functions-star.texinfo
343 Conditions of type @code{warning} and @code{style-warning} are
344 sometimes signaled at runtime, especially during execution of Common
345 Lisp defining forms such as @code{defun}, @code{defmethod}, etc. To
346 muffle these warnings at runtime, SBCL provides a variable
347 @code{sb-ext:*muffled-warnings*}:
349 @include var-sb-ext-star-muffled-warnings-star.texinfo
351 @node Tools To Help Developers
352 @comment node-name, next, previous, up
353 @section Tools To Help Developers
357 SBCL provides a profiler and other extensions to the ANSI @code{trace}
358 facility. For more information, see @ref{Macro common-lisp:trace}.
360 The debugger supports a number of options. Its documentation is
361 accessed by typing @kbd{help} at the debugger prompt. @xref{Debugger}.
363 Documentation for @code{inspect} is accessed by typing @kbd{help} at
364 the @code{inspect} prompt.
366 @node Resolution of Name Conflicts
367 @section Resolution of Name Conflicts
368 @tindex sb-ext:name-conflict
369 @tindex name-conflict
370 @findex sb-ext:name-conflict-symbols
371 @findex name-conflict-symbols
373 The ANSI standard (section 11.1.1.2.5) requires that name conflicts in
374 packages be resolvable in favour of any of the conflicting symbols. In
375 the interactive debugger, this is achieved by prompting for the symbol
376 in whose favour the conflict should be resolved; for programmatic use,
377 the @code{sb-ext:resolve-conflict} restart should be invoked with one
378 argument, which should be a member of the list returned by the condition
379 accessor @code{sb-ext:name-conflict-symbols}.
381 @node Hash Table Extensions
382 @comment node-name, next, previous, up
383 @section Hash Table Extensions
385 Hash table extensions supported by SBCL are all controlled by keyword
386 arguments to @code{make-hash-table}.
388 @include fun-common-lisp-make-hash-table.texinfo
390 @include macro-sb-ext-define-hash-table-test.texinfo
392 @include macro-sb-ext-with-locked-hash-table.texinfo
394 @include fun-sb-ext-hash-table-synchronized-p.texinfo
396 @include fun-sb-ext-hash-table-weakness.texinfo
398 @node Miscellaneous Extensions
399 @comment node-name, next, previous, up
400 @section Miscellaneous Extensions
402 @include fun-sb-ext-array-storage-vector.texinfo
404 @node Stale Extensions
405 @comment node-name, next, previous, up
406 @section Stale Extensions
408 SBCL has inherited from CMUCL various hooks to allow the user to
409 tweak and monitor the garbage collection process. These are somewhat
410 stale code, and their interface might need to be cleaned up. If you
411 have urgent need of them, look at the code in @file{src/code/gc.lisp}
412 and bring it up on the developers' mailing list.
414 SBCL has various hooks inherited from CMUCL, like
415 @code{sb-ext:float-denormalized-p}, to allow a program to take
416 advantage of IEEE floating point arithmetic properties which aren't
417 conveniently or efficiently expressible using the ANSI standard. These
418 look good, and their interface looks good, but IEEE support is
419 slightly broken due to a stupid decision to remove some support for
420 infinities (because it wasn't in the ANSI spec and it didn't occur to
421 me that it was in the IEEE spec). If you need this stuff, take a look
422 at the code and bring it up on the developers' mailing
426 @node Efficiency Hacks
427 @comment node-name, next, previous, up
428 @section Efficiency Hacks
430 The @code{sb-ext:purify} function causes SBCL first to collect all
431 garbage, then to mark all uncollected objects as permanent, never again
432 attempting to collect them as garbage. This can cause a large increase
433 in efficiency when using a primitive garbage collector, or a more
434 moderate increase in efficiency when using a more sophisticated garbage
435 collector which is well suited to the program's memory usage pattern. It
436 also allows permanent code to be frozen at fixed addresses, a
437 precondition for using copy-on-write to share code between multiple Lisp
438 processes. This is less important with modern generational garbage
439 collectors, but not all SBCL platforms use such a garbage collector.
441 @include fun-sb-ext-purify.texinfo
443 The @code{sb-ext:truly-the} special form declares the type of the
444 result of the operations, producing its argument; the declaration is
445 not checked. In short: don't use it.
447 @include special-operator-sb-ext-truly-the.texinfo
449 The @code{sb-ext:freeze-type} declaration declares that a
450 type will never change, which can make type testing
451 (@code{typep}, etc.) more efficient for structure types.
453 The @code{sb-ext:constant-function} declaration specifies
454 that a function will always return the same value for the same
455 arguments, which may allow the compiler to optimize calls
456 to it. This is appropriate for functions like @code{sqrt}, but
457 is @emph{not} appropriate for functions like @code{aref},
458 which can change their return values when the underlying data are
460 @c <!-- FIXME: This declaration does not seem to be supported in the
461 @c current compiler. -->