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 @findex ensure-generic-function
57 @findex generic-function-declarations
58 @findex sb-mop:generic-function-declarations
59 the arguments @code{:declare} and @code{:declarations} to
60 @code{ensure-generic-function} are both accepted, with the leftmost
61 argument defining the declarations to be stored and returned by
62 @code{generic-function-declarations}.
64 Where AMOP specifies @code{:declarations} as the keyword argument to
65 @code{ensure-generic-function}, the Common Lisp standard specifies
66 @code{:declare}. Portable code should use @code{:declare}.
69 @findex validate-superclass
70 @findex finalize-inheritance
71 @findex sb-mop:validate-superclass
72 @findex sb-mop:finalize-inheritance
73 @tindex standard-class
74 @tindex funcallable-standard-class
75 @tindex sb-mop:funcallable-standard-class
77 @findex sb-mop:class-prototype
78 @findex class-prototype
79 although SBCL obeys the requirement in AMOP for
80 @code{validate-superclass} for @code{standard-class} and
81 @code{funcallable-standard-class} to be compatible metaclasses, we
82 impose an additional requirement at class finalization time: a class
83 of metaclass @code{funcallable-standard-class} must have
84 @code{function} in its superclasses, and a class of metaclass
85 @code{standard-class} must not.
90 At class finalization, a class prototype which is accessible by a
91 standard mop function @code{sb-mop:class-prototype}. The user can
92 then ask whether this object is a @code{function} or not in several
93 different ways: whether it is a function according to @code{typep};
94 whether its @code{class-of} is @code{subtypep} @code{function}, or
95 whether @code{function} appears in the superclasses of the class. The
96 additional consistency requirement comes from the desire to make all
97 of these answers the same.
99 The following class definitions are bad, and will lead to errors
100 either immediately or if an instance is created:
102 (defclass bad-object (funcallable-standard-object)
104 (:metaclass standard-class))
107 (defclass bad-funcallable-object (standard-object)
109 (:metaclass funcallable-standard-class))
111 The following definition is acceptable:
114 ((slot :initarg slot)))
115 (defclass funcallable-object (funcallable-standard-object mixin)
117 (:metaclass funcallable-standard-class))
119 and leads to a class whose instances are funcallable and have one slot.
121 @tindex funcallable-standard-object
122 @tindex sb-mop:funcallable-standard-object
123 Note that this requirement also applies to the class
124 @code{sb-mop:funcallable-standard-object}, which has metaclass
125 @code{sb-mop:funcallable-standard-class} rather than
126 @code{standard-class} as AMOP specifies.
129 the requirement that ``No portable class @math{C_p} may inherit, by
130 virtue of being a direct or indirect subclass of a specified class, any
131 slot for which the name is a symbol accessible in the
132 @code{common-lisp-user} package or exported by any package defined in
133 the ANSI Common Lisp standard.'' is interpreted to mean that the
134 standardized classes themselves should not have slots named by external
135 symbols of public packages.
137 The rationale behind the restriction is likely to be similar to the ANSI
138 Common Lisp restriction on defining functions, variables and types named
139 by symbols in the Common Lisp package: preventing two independent pieces
140 of software from colliding with each other.
143 @findex slot-value-using-class
144 @findex sb-mop:slot-value-using-class
145 @findex (setf slot-value-using-class)
146 @findex (setf sb-mop:slot-value-using-class)
147 @findex slot-boundp-using-class
148 @findex sb-mop:slot-boundp-using-class
149 specializations of the @code{new-value} argument to @code{(setf
150 sb-mop:slot-value-using-class)} are not allowed: all user-defined
151 methods must have a specializer of the class @code{t}.
153 This prohibition is motivated by a separation of layers: the
154 @code{slot-value-using-class} family of functions is intended for use in
155 implementing different and new slot allocation strategies, rather than
156 in performing application-level dispatching. Additionally, with this
157 requirement, there is a one-to-one mapping between metaclass, class and
158 slot-definition-class tuples and effective methods of @code{(setf
159 slot-value-using-class)}, which permits optimization of @code{(setf
160 slot-value-using-class)}'s discriminating function in the same manner as
161 for @code{slot-value-using-class} and @code{slot-boundp-using-class}.
163 Note that application code may specialize on the @code{new-value}
164 argument of slot accessors.
169 @findex ensure-class-using-class
170 @findex sb-mop:ensure-class
171 @findex sb-mop:ensure-class-using-class
174 the class named by the @code{name} argument to @code{ensure-class}, if
175 any, is only redefined if it is the proper name of that class;
176 otherwise, a new class is created.
178 This is consistent with the description of @code{ensure-class} in AMOP
179 as the functional version of @code{defclass}, which has this behaviour;
180 however, it is not consistent with the weaker requirement in AMOP, which
181 states that any class found by @code{find-class}, no matter what its
182 @code{class-name}, is redefined.
186 @node Support For Unix
187 @comment node-name, next, previous, up
188 @section Support For Unix
190 The UNIX command line can be read from the variable
191 @code{sb-ext:*posix-argv*}. The UNIX environment can be queried with
192 the @code{sb-ext:posix-getenv} function.
194 @include fun-sb-ext-posix-getenv.texinfo
196 External programs can be run with @code{sb-ext:run-program}.
198 @include fun-sb-ext-run-program.texinfo
200 @include fun-sb-ext-process-p.texinfo
202 @include fun-sb-ext-process-input.texinfo
204 @include fun-sb-ext-process-output.texinfo
206 @include fun-sb-ext-process-error.texinfo
208 @include fun-sb-ext-process-alive-p.texinfo
210 @include fun-sb-ext-process-status.texinfo
212 @include fun-sb-ext-process-wait.texinfo
214 @include fun-sb-ext-process-exit-code.texinfo
216 @include fun-sb-ext-process-core-dumped.texinfo
218 @include fun-sb-ext-process-close.texinfo
220 @include fun-sb-ext-process-kill.texinfo
222 @node Customization Hooks for Users
223 @comment node-name, next, previous, up
224 @section Customization Hooks for Users
226 The toplevel repl prompt may be customized, and the function
227 that reads user input may be replaced completely.
228 @c <!-- FIXME but I don't currently remember how -->
230 The behaviour of @code{require} when called with only one argument is
231 implementation-defined. In SBCL, @code{require} behaves in the
234 @include fun-common-lisp-require.texinfo
235 @include var-sb-ext-star-module-provider-functions-star.texinfo
237 Although SBCL does not provide a resident editor, the @code{ed}
238 function can be customized to hook into user-provided editing
239 mechanisms as follows:
241 @include fun-common-lisp-ed.texinfo
242 @include var-sb-ext-star-ed-functions-star.texinfo
244 @node Tools To Help Developers
245 @comment node-name, next, previous, up
246 @section Tools To Help Developers
248 SBCL provides a profiler and other extensions to the ANSI @code{trace}
249 facility. For more information, see @ref{Macro common-lisp:trace}.
251 The debugger supports a number of options. Its documentation is
252 accessed by typing @kbd{help} at the debugger prompt. @xref{Debugger}.
254 Documentation for @code{inspect} is accessed by typing @kbd{help} at
255 the @code{inspect} prompt.
257 @node Resolution of Name Conflicts
258 @section Resolution of Name Conflicts
260 The ANSI standard (section 11.1.1.2.5) requires that name conflicts in
261 packages be resolvable in favour of any of the conflicting symbols. In
262 the interactive debugger, this is achieved by prompting for the symbol
263 in whose favour the conflict should be resolved; for programmatic use,
264 the @code{sb-ext:resolve-conflict} restart should be invoked with one
265 argument, which should be a member of the list returned by the condition
266 accessor @code{sb-ext:name-conflict-symbols}.
268 @node Stale Extensions
269 @comment node-name, next, previous, up
270 @section Stale Extensions
272 SBCL has inherited from CMUCL various hooks to allow the user to
273 tweak and monitor the garbage collection process. These are somewhat
274 stale code, and their interface might need to be cleaned up. If you
275 have urgent need of them, look at the code in @file{src/code/gc.lisp}
276 and bring it up on the developers' mailing list.
278 SBCL has various hooks inherited from CMUCL, like
279 @code{sb-ext:float-denormalized-p}, to allow a program to take
280 advantage of IEEE floating point arithmetic properties which aren't
281 conveniently or efficiently expressible using the ANSI standard. These
282 look good, and their interface looks good, but IEEE support is
283 slightly broken due to a stupid decision to remove some support for
284 infinities (because it wasn't in the ANSI spec and it didn't occur to
285 me that it was in the IEEE spec). If you need this stuff, take a look
286 at the code and bring it up on the developers' mailing
290 @node Efficiency Hacks
291 @comment node-name, next, previous, up
292 @section Efficiency Hacks
294 The @code{sb-ext:purify} function causes SBCL first to collect all
295 garbage, then to mark all uncollected objects as permanent, never again
296 attempting to collect them as garbage. This can cause a large increase
297 in efficiency when using a primitive garbage collector, or a more
298 moderate increase in efficiency when using a more sophisticated garbage
299 collector which is well suited to the program's memory usage pattern. It
300 also allows permanent code to be frozen at fixed addresses, a
301 precondition for using copy-on-write to share code between multiple Lisp
302 processes. This is less important with modern generational garbage
303 collectors, but not all SBCL platforms use such a garbage collector.
305 @include fun-sb-ext-purify.texinfo
307 The @code{sb-ext:truly-the} special form declares the type of the
308 result of the operations, producing its argument; the declaration is
309 not checked. In short: don't use it.
311 @include special-operator-sb-ext-truly-the.texinfo
313 The @code{sb-ext:freeze-type} declaration declares that a
314 type will never change, which can make type testing
315 (@code{typep}, etc.) more efficient for structure types.
317 The @code{sb-ext:constant-function} declaration specifies
318 that a function will always return the same value for the same
319 arguments, which may allow the compiler to optimize calls
320 to it. This is appropriate for functions like @code{sqrt}, but
321 is @emph{not} appropriate for functions like @code{aref},
322 which can change their return values when the underlying data are
324 @c <!-- FIXME: This declaration does not seem to be supported in the
325 @c current compiler. -->