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