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.
122 the requirement that ``No portable class @math{C_p} may inherit, by
123 virtue of being a direct or indirect subclass of a specified class, any
124 slot for which the name is a symbol accessible in the
125 @code{common-lisp-user} package or exported by any package defined in
126 the ANSI Common Lisp standard.'' is interpreted to mean that the
127 standardized classes themselves should not have slots named by external
128 symbols of public packages.
130 The rationale behind the restriction is likely to be similar to the ANSI
131 Common Lisp restriction on defining functions, variables and types named
132 by symbols in the Common Lisp package: preventing two independent pieces
133 of software from colliding with each other.
136 @findex slot-value-using-class
137 @findex sb-mop:slot-value-using-class
138 @findex (setf slot-value-using-class)
139 @findex (setf sb-mop:slot-value-using-class)
140 @findex slot-boundp-using-class
141 @findex sb-mop:slot-boundp-using-class
142 specializations of the @code{new-value} argument to @code{(setf
143 sb-mop:slot-value-using-class)} are not allowed: all user-defined
144 methods must have a specializer of the class @code{t}.
146 This prohibition is motivated by a separation of layers: the
147 @code{slot-value-using-class} family of functions is intended for use in
148 implementing different and new slot allocation strategies, rather than
149 in performing application-level dispatching. Additionally, with this
150 requirement, there is a one-to-one mapping between metaclass, class and
151 slot-definition-class tuples and effective methods of @code{(setf
152 slot-value-using-class)}, which permits optimization of @code{(setf
153 slot-value-using-class)}'s discriminating function in the same manner as
154 for @code{slot-value-using-class} and @code{slot-boundp-using-class}.
156 Note that application code may specialize on the @code{new-value}
157 argument of slot accessors.
161 @node Support For Unix
162 @comment node-name, next, previous, up
163 @section Support For Unix
165 The UNIX command line can be read from the variable
166 @code{sb-ext:*posix-argv*}. The UNIX environment can be queried with
167 the @code{sb-ext:posix-getenv} function.
169 @include fun-sb-ext-posix-getenv.texinfo
171 External programs can be run with @code{sb-ext:run-program}.
173 @include fun-sb-ext-run-program.texinfo
175 @include fun-sb-ext-process-p.texinfo
177 @include fun-sb-ext-process-input.texinfo
179 @include fun-sb-ext-process-output.texinfo
181 @include fun-sb-ext-process-error.texinfo
183 @include fun-sb-ext-process-alive-p.texinfo
185 @include fun-sb-ext-process-status.texinfo
187 @include fun-sb-ext-process-wait.texinfo
189 @include fun-sb-ext-process-exit-code.texinfo
191 @include fun-sb-ext-process-core-dumped.texinfo
193 @include fun-sb-ext-process-close.texinfo
195 @include fun-sb-ext-process-kill.texinfo
197 @node Customization Hooks for Users
198 @comment node-name, next, previous, up
199 @section Customization Hooks for Users
201 The toplevel repl prompt may be customized, and the function
202 that reads user input may be replaced completely.
203 @c <!-- FIXME but I don't currently remember how -->
205 The behaviour of @code{require} when called with only one argument is
206 implementation-defined. In SBCL, @code{require} behaves in the
209 @include fun-common-lisp-require.texinfo
210 @include var-sb-ext-star-module-provider-functions-star.texinfo
212 Although SBCL does not provide a resident editor, the @code{ed}
213 function can be customized to hook into user-provided editing
214 mechanisms as follows:
216 @include fun-common-lisp-ed.texinfo
217 @include var-sb-ext-star-ed-functions-star.texinfo
219 @node Tools To Help Developers
220 @comment node-name, next, previous, up
221 @section Tools To Help Developers
223 SBCL provides a profiler and other extensions to the ANSI @code{trace}
224 facility. For more information, see @ref{Macro common-lisp:trace}.
226 The debugger supports a number of options. Its documentation is
227 accessed by typing @kbd{help} at the debugger prompt. @xref{Debugger}.
229 Documentation for @code{inspect} is accessed by typing @kbd{help} at
230 the @code{inspect} prompt.
232 @node Resolution of Name Conflicts
233 @section Resolution of Name Conflicts
235 The ANSI standard (section 11.1.1.2.5) requires that name conflicts in
236 packages be resolvable in favour of any of the conflicting symbols. In
237 the interactive debugger, this is achieved by prompting for the symbol
238 in whose favour the conflict should be resolved; for programmatic use,
239 the @code{sb-ext:resolve-conflict} restart should be invoked with one
240 argument, which should be a member of the list returned by the condition
241 accessor @code{sb-ext:name-conflict-symbols}.
243 @node Stale Extensions
244 @comment node-name, next, previous, up
245 @section Stale Extensions
247 SBCL has inherited from CMUCL various hooks to allow the user to
248 tweak and monitor the garbage collection process. These are somewhat
249 stale code, and their interface might need to be cleaned up. If you
250 have urgent need of them, look at the code in @file{src/code/gc.lisp}
251 and bring it up on the developers' mailing list.
253 SBCL has various hooks inherited from CMUCL, like
254 @code{sb-ext:float-denormalized-p}, to allow a program to take
255 advantage of IEEE floating point arithmetic properties which aren't
256 conveniently or efficiently expressible using the ANSI standard. These
257 look good, and their interface looks good, but IEEE support is
258 slightly broken due to a stupid decision to remove some support for
259 infinities (because it wasn't in the ANSI spec and it didn't occur to
260 me that it was in the IEEE spec). If you need this stuff, take a look
261 at the code and bring it up on the developers' mailing
265 @node Efficiency Hacks
266 @comment node-name, next, previous, up
267 @section Efficiency Hacks
269 The @code{sb-ext:purify} function causes SBCL first to collect all
270 garbage, then to mark all uncollected objects as permanent, never again
271 attempting to collect them as garbage. This can cause a large increase
272 in efficiency when using a primitive garbage collector, or a more
273 moderate increase in efficiency when using a more sophisticated garbage
274 collector which is well suited to the program's memory usage pattern. It
275 also allows permanent code to be frozen at fixed addresses, a
276 precondition for using copy-on-write to share code between multiple Lisp
277 processes. This is less important with modern generational garbage
278 collectors, but not all SBCL platforms use such a garbage collector.
280 @include fun-sb-ext-purify.texinfo
282 The @code{sb-ext:truly-the} special form declares the type of the
283 result of the operations, producing its argument; the declaration is
284 not checked. In short: don't use it.
286 @include special-operator-sb-ext-truly-the.texinfo
288 The @code{sb-ext:freeze-type} declaration declares that a
289 type will never change, which can make type testing
290 (@code{typep}, etc.) more efficient for structure types.
292 The @code{sb-ext:constant-function} declaration specifies
293 that a function will always return the same value for the same
294 arguments, which may allow the compiler to optimize calls
295 to it. This is appropriate for functions like @code{sqrt}, but
296 is @emph{not} appropriate for functions like @code{aref},
297 which can change their return values when the underlying data are
299 @c <!-- FIXME: This declaration does not seem to be supported in the
300 @c current compiler. -->