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::
20 @node Garbage Collection
21 @comment node-name, next, previous, up
22 @section Garbage Collection
24 SBCL provides additional garbage collection functionality not
25 specified by ANSI. Weak pointers allow references to objects to be
26 maintained without keeping them from being garbage collected, and
27 ``finalization'' hooks are available to cause code to be executed when
28 an object has been garbage collected. Additionally users can specify
29 their own cleanup actions to be executed with garbage collection.
31 @include fun-sb-ext-finalize.texinfo
32 @include fun-sb-ext-cancel-finalization.texinfo
33 @include fun-sb-ext-make-weak-pointer.texinfo
34 @include fun-sb-ext-weak-pointer-value.texinfo
35 @include var-sb-ext-star-after-gc-hooks-star.texinfo
37 @node Metaobject Protocol
38 @comment node-name, next, previous, up
39 @section Metaobject Protocol
41 SBCL supports a metaobject protocol which is intended to be compatible
42 with AMOP; present exceptions to this (as distinct from current bugs)
48 @findex compute-effective-method
49 @findex sb-mop:compute-effective-method
50 @code{compute-effective-method} only returns one value, not two.
52 There is no record of what the second return value was meant to
53 indicate, and apparently no clients for it.
56 @tindex generic-function
57 @tindex standard-generic-function
58 @tindex funcallable-standard-object
59 @tindex sb-mop:funcallable-standard-object
60 @tindex standard-object
62 The direct superclasses of @code{sb-mop:funcallable-standard-object} are
63 @code{(function standard-object)}, not @code{(standard-object function)}.
65 This is to ensure that the @code{standard-object} class is the last of
66 the standardized classes before @code{t} appearing in the class
67 precedence list of @code{generic-function} and
68 @code{standard-generic-function}, as required by section 1.4.4.5 of the
72 @findex ensure-generic-function
73 @findex generic-function-declarations
74 @findex sb-mop:generic-function-declarations
75 the arguments @code{:declare} and @code{:declarations} to
76 @code{ensure-generic-function} are both accepted, with the leftmost
77 argument defining the declarations to be stored and returned by
78 @code{generic-function-declarations}.
80 Where AMOP specifies @code{:declarations} as the keyword argument to
81 @code{ensure-generic-function}, the Common Lisp standard specifies
82 @code{:declare}. Portable code should use @code{:declare}.
85 @findex validate-superclass
86 @findex finalize-inheritance
87 @findex sb-mop:validate-superclass
88 @findex sb-mop:finalize-inheritance
89 @tindex standard-class
90 @tindex funcallable-standard-class
91 @tindex sb-mop:funcallable-standard-class
93 @findex sb-mop:class-prototype
94 @findex class-prototype
95 although SBCL obeys the requirement in AMOP that
96 @code{validate-superclass} should treat @code{standard-class} and
97 @code{funcallable-standard-class} as compatible metaclasses, we
98 impose an additional requirement at class finalization time: a class
99 of metaclass @code{funcallable-standard-class} must have
100 @code{function} in its superclasses, and a class of metaclass
101 @code{standard-class} must not.
106 After a class has been finalized, it is associated with a class
107 prototype which is accessible by a standard mop function
108 @code{sb-mop:class-prototype}. The user can then ask whether this
109 object is a @code{function} or not in several different ways: whether it
110 is a function according to @code{typep}; whether its @code{class-of} is
111 @code{subtypep} @code{function}, or whether @code{function} appears in
112 the superclasses of the class. The additional consistency requirement
113 comes from the desire to make all of these answers the same.
115 The following class definitions are bad, and will lead to errors
116 either immediately or if an instance is created:
118 (defclass bad-object (funcallable-standard-object)
120 (:metaclass standard-class))
123 (defclass bad-funcallable-object (standard-object)
125 (:metaclass funcallable-standard-class))
127 The following definition is acceptable:
130 ((slot :initarg slot)))
131 (defclass funcallable-object (funcallable-standard-object mixin)
133 (:metaclass funcallable-standard-class))
135 and leads to a class whose instances are funcallable and have one slot.
137 @tindex funcallable-standard-object
138 @tindex sb-mop:funcallable-standard-object
139 Note that this requirement also applies to the class
140 @code{sb-mop:funcallable-standard-object}, which has metaclass
141 @code{sb-mop:funcallable-standard-class} rather than
142 @code{standard-class} as AMOP specifies.
145 the requirement that ``No portable class @math{C_p} may inherit, by
146 virtue of being a direct or indirect subclass of a specified class, any
147 slot for which the name is a symbol accessible in the
148 @code{common-lisp-user} package or exported by any package defined in
149 the ANSI Common Lisp standard.'' is interpreted to mean that the
150 standardized classes themselves should not have slots named by external
151 symbols of public packages.
153 The rationale behind the restriction is likely to be similar to the ANSI
154 Common Lisp restriction on defining functions, variables and types named
155 by symbols in the Common Lisp package: preventing two independent pieces
156 of software from colliding with each other.
159 @findex slot-value-using-class
160 @findex sb-mop:slot-value-using-class
161 @findex (setf slot-value-using-class)
162 @findex (setf sb-mop:slot-value-using-class)
163 @findex slot-boundp-using-class
164 @findex sb-mop:slot-boundp-using-class
165 specializations of the @code{new-value} argument to @code{(setf
166 sb-mop:slot-value-using-class)} are not allowed: all user-defined
167 methods must have a specializer of the class @code{t}.
169 This prohibition is motivated by a separation of layers: the
170 @code{slot-value-using-class} family of functions is intended for use in
171 implementing different and new slot allocation strategies, rather than
172 in performing application-level dispatching. Additionally, with this
173 requirement, there is a one-to-one mapping between metaclass, class and
174 slot-definition-class tuples and effective methods of @code{(setf
175 slot-value-using-class)}, which permits optimization of @code{(setf
176 slot-value-using-class)}'s discriminating function in the same manner as
177 for @code{slot-value-using-class} and @code{slot-boundp-using-class}.
179 Note that application code may specialize on the @code{new-value}
180 argument of slot accessors.
185 @findex ensure-class-using-class
186 @findex sb-mop:ensure-class
187 @findex sb-mop:ensure-class-using-class
190 the class named by the @code{name} argument to @code{ensure-class}, if
191 any, is only redefined if it is the proper name of that class;
192 otherwise, a new class is created.
194 This is consistent with the description of @code{ensure-class} in AMOP
195 as the functional version of @code{defclass}, which has this behaviour;
196 however, it is not consistent with the weaker requirement in AMOP, which
197 states that any class found by @code{find-class}, no matter what its
198 @code{class-name}, is redefined.
202 @node Support For Unix
203 @comment node-name, next, previous, up
204 @section Support For Unix
206 The UNIX command line can be read from the variable
207 @code{sb-ext:*posix-argv*}. The UNIX environment can be queried with
208 the @code{sb-ext:posix-getenv} function.
210 @include fun-sb-ext-posix-getenv.texinfo
212 External programs can be run with @code{sb-ext:run-program}.
214 @include fun-sb-ext-run-program.texinfo
216 @include fun-sb-ext-process-p.texinfo
218 @include fun-sb-ext-process-input.texinfo
220 @include fun-sb-ext-process-output.texinfo
222 @include fun-sb-ext-process-error.texinfo
224 @include fun-sb-ext-process-alive-p.texinfo
226 @include fun-sb-ext-process-status.texinfo
228 @include fun-sb-ext-process-wait.texinfo
230 @include fun-sb-ext-process-exit-code.texinfo
232 @include fun-sb-ext-process-core-dumped.texinfo
234 @include fun-sb-ext-process-close.texinfo
236 @include fun-sb-ext-process-kill.texinfo
238 @node Customization Hooks for Users
239 @comment node-name, next, previous, up
240 @section Customization Hooks for Users
242 The toplevel repl prompt may be customized, and the function
243 that reads user input may be replaced completely.
244 @c <!-- FIXME but I don't currently remember how -->
246 The behaviour of @code{require} when called with only one argument is
247 implementation-defined. In SBCL, @code{require} behaves in the
250 @include fun-common-lisp-require.texinfo
251 @include var-sb-ext-star-module-provider-functions-star.texinfo
253 Although SBCL does not provide a resident editor, the @code{ed}
254 function can be customized to hook into user-provided editing
255 mechanisms as follows:
257 @include fun-common-lisp-ed.texinfo
258 @include var-sb-ext-star-ed-functions-star.texinfo
260 @node Tools To Help Developers
261 @comment node-name, next, previous, up
262 @section Tools To Help Developers
264 SBCL provides a profiler and other extensions to the ANSI @code{trace}
265 facility. For more information, see @ref{Macro common-lisp:trace}.
267 The debugger supports a number of options. Its documentation is
268 accessed by typing @kbd{help} at the debugger prompt. @xref{Debugger}.
270 Documentation for @code{inspect} is accessed by typing @kbd{help} at
271 the @code{inspect} prompt.
273 @node Resolution of Name Conflicts
274 @section Resolution of Name Conflicts
276 The ANSI standard (section 11.1.1.2.5) requires that name conflicts in
277 packages be resolvable in favour of any of the conflicting symbols. In
278 the interactive debugger, this is achieved by prompting for the symbol
279 in whose favour the conflict should be resolved; for programmatic use,
280 the @code{sb-ext:resolve-conflict} restart should be invoked with one
281 argument, which should be a member of the list returned by the condition
282 accessor @code{sb-ext:name-conflict-symbols}.
284 @node Stale Extensions
285 @comment node-name, next, previous, up
286 @section Stale Extensions
288 SBCL has inherited from CMUCL various hooks to allow the user to
289 tweak and monitor the garbage collection process. These are somewhat
290 stale code, and their interface might need to be cleaned up. If you
291 have urgent need of them, look at the code in @file{src/code/gc.lisp}
292 and bring it up on the developers' mailing list.
294 SBCL has various hooks inherited from CMUCL, like
295 @code{sb-ext:float-denormalized-p}, to allow a program to take
296 advantage of IEEE floating point arithmetic properties which aren't
297 conveniently or efficiently expressible using the ANSI standard. These
298 look good, and their interface looks good, but IEEE support is
299 slightly broken due to a stupid decision to remove some support for
300 infinities (because it wasn't in the ANSI spec and it didn't occur to
301 me that it was in the IEEE spec). If you need this stuff, take a look
302 at the code and bring it up on the developers' mailing
306 @node Efficiency Hacks
307 @comment node-name, next, previous, up
308 @section Efficiency Hacks
310 The @code{sb-ext:purify} function causes SBCL first to collect all
311 garbage, then to mark all uncollected objects as permanent, never again
312 attempting to collect them as garbage. This can cause a large increase
313 in efficiency when using a primitive garbage collector, or a more
314 moderate increase in efficiency when using a more sophisticated garbage
315 collector which is well suited to the program's memory usage pattern. It
316 also allows permanent code to be frozen at fixed addresses, a
317 precondition for using copy-on-write to share code between multiple Lisp
318 processes. This is less important with modern generational garbage
319 collectors, but not all SBCL platforms use such a garbage collector.
321 @include fun-sb-ext-purify.texinfo
323 The @code{sb-ext:truly-the} special form declares the type of the
324 result of the operations, producing its argument; the declaration is
325 not checked. In short: don't use it.
327 @include special-operator-sb-ext-truly-the.texinfo
329 The @code{sb-ext:freeze-type} declaration declares that a
330 type will never change, which can make type testing
331 (@code{typep}, etc.) more efficient for structure types.
333 The @code{sb-ext:constant-function} declaration specifies
334 that a function will always return the same value for the same
335 arguments, which may allow the compiler to optimize calls
336 to it. This is appropriate for functions like @code{sqrt}, but
337 is @emph{not} appropriate for functions like @code{aref},
338 which can change their return values when the underlying data are
340 @c <!-- FIXME: This declaration does not seem to be supported in the
341 @c current compiler. -->