1.0.8.48: Update comment.
[sbcl.git] / doc / manual / beyond-ansi.texinfo
1 @node  Beyond the ANSI Standard
2 @comment  node-name,  next,  previous,  up
3 @chapter Beyond the ANSI Standard
4
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}.
8
9 @menu
10 * Garbage Collection::          
11 * Metaobject Protocol::         
12 * Support For Unix::            
13 * Customization Hooks for Users::  
14 * Tools To Help Developers::    
15 * Resolution of Name Conflicts::  
16 * Stale Extensions::            
17 * Efficiency Hacks::            
18 @end menu
19
20 @node  Garbage Collection
21 @comment  node-name,  next,  previous,  up
22 @section Garbage Collection
23
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.
30
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
36
37 @node Metaobject Protocol
38 @comment  node-name,  next,  previous,  up
39 @section Metaobject Protocol
40
41 SBCL supports a metaobject protocol which is intended to be compatible
42 with AMOP; present exceptions to this (as distinct from current bugs)
43 are:
44
45 @itemize
46   
47 @item
48 @findex compute-effective-method
49 @findex sb-mop:compute-effective-method
50 @code{compute-effective-method} only returns one value, not two.
51
52 There is no record of what the second return value was meant to
53 indicate, and apparently no clients for it.
54
55 @item
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
61 @tindex function
62 The direct superclasses of @code{sb-mop:funcallable-standard-object} are
63 @code{(function standard-object)}, not @code{(standard-object function)}.
64
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
69 ANSI specification.
70   
71 @item
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}.
79
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}.
83
84 @item
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
92 @tindex function
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.
102
103 @findex typep
104 @findex class-of
105 @findex subtypep
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.
114
115 The following class definitions are bad, and will lead to errors
116 either immediately or if an instance is created:
117 @lisp
118 (defclass bad-object (funcallable-standard-object)
119   ()
120   (:metaclass standard-class))
121 @end lisp
122 @lisp
123 (defclass bad-funcallable-object (standard-object)
124   ()
125   (:metaclass funcallable-standard-class))
126 @end lisp
127 The following definition is acceptable:
128 @lisp
129 (defclass mixin ()
130   ((slot :initarg slot)))
131 (defclass funcallable-object (funcallable-standard-object mixin)
132   ()
133   (:metaclass funcallable-standard-class))
134 @end lisp
135 and leads to a class whose instances are funcallable and have one slot.
136
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.
143
144 @item
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.
152
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.
157
158 @item
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}.
168
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}.
178
179 Note that application code may specialize on the @code{new-value}
180 argument of slot accessors.
181
182 @item
183 @findex defclass
184 @findex ensure-class
185 @findex ensure-class-using-class
186 @findex sb-mop:ensure-class
187 @findex sb-mop:ensure-class-using-class
188 @findex find-class
189 @findex class-name
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.
193
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.
199
200 @end itemize
201
202 In addition, SBCL supports extensions to the Metaobject protocol from
203 AMOP; at present, they are:
204
205 @itemize
206
207 @item
208 @findex defmethod
209 @findex find-class
210 @findex intern-eql-specializer
211 @findex sb-mop:intern-eql-specializer
212 @findex make-method-specializers-form
213 @findex sb-pcl:make-method-specializers-form
214 @findex make-method-lambda
215 @findex sb-mop:make-method-lambda
216 compile-time support for generating specializer metaobjects from
217 specializer names in @code{defmethod} forms is provided by the
218 @code{make-method-specializers-form} function, which returns a form
219 which, when evaluated in the lexical environment of the
220 @code{defmethod}, returns a list of specializer metaobjects.  This
221 operator suffers from similar restrictions to those affecting
222 @code{make-method-lambda}, namely that the generic function must be
223 defined when the @code{defmethod} form is expanded, so that the
224 correct method of @code{make-method-specializers-form} is invoked.
225 The system-provided method on @code{make-method-specializers-form}
226 generates a call to @code{find-class} for each symbol specializer
227 name, and a call to @code{intern-eql-specializer} for each @code{(eql
228 @var{x})} specializer name.
229
230 @item
231 @findex find-method
232 @findex parse-specializer-using-class
233 @findex unparse-specializer-using-class
234 @findex sb-pcl:parse-specializer-using-class
235 @findex sb-pcl:unparse-specializer-using-class
236 run-time support for converting between specializer names and
237 specializer metaobjects, mostly for the purposes of
238 @code{find-method}, is provided by
239 @code{parse-specializer-using-class} and
240 @code{unparse-specializer-using-class}, which dispatch on their first
241 argument, the generic function associated with a method with the given
242 specializer.  The system-provided methods on those methods convert
243 between classes and proper names and between lists of the form
244 @code{(eql @var{x})} and interned eql specializer objects.
245
246 @end itemize
247
248 @node  Support For Unix
249 @comment  node-name,  next,  previous,  up
250 @section Support For Unix
251
252 The UNIX command line can be read from the variable
253 @code{sb-ext:*posix-argv*}. The UNIX environment can be queried with
254 the @code{sb-ext:posix-getenv} function.
255
256 @include fun-sb-ext-posix-getenv.texinfo
257
258 External programs can be run with @code{sb-ext:run-program}.
259
260 @include fun-sb-ext-run-program.texinfo
261
262 @include fun-sb-ext-process-p.texinfo
263
264 @include fun-sb-ext-process-input.texinfo
265
266 @include fun-sb-ext-process-output.texinfo
267
268 @include fun-sb-ext-process-error.texinfo
269
270 @include fun-sb-ext-process-alive-p.texinfo
271
272 @include fun-sb-ext-process-status.texinfo
273
274 @include fun-sb-ext-process-wait.texinfo
275
276 @include fun-sb-ext-process-exit-code.texinfo
277
278 @include fun-sb-ext-process-core-dumped.texinfo
279
280 @include fun-sb-ext-process-close.texinfo
281
282 @include fun-sb-ext-process-kill.texinfo
283
284 @node  Customization Hooks for Users
285 @comment  node-name,  next,  previous,  up
286 @section Customization Hooks for Users
287
288 The toplevel repl prompt may be customized, and the function
289 that reads user input may be replaced completely.
290 @c <!-- FIXME but I don't currently remember how -->
291
292 The behaviour of @code{require} when called with only one argument is
293 implementation-defined.  In SBCL, @code{require} behaves in the
294 following way:
295
296 @include fun-common-lisp-require.texinfo
297 @include var-sb-ext-star-module-provider-functions-star.texinfo
298
299 Although SBCL does not provide a resident editor, the @code{ed}
300 function can be customized to hook into user-provided editing
301 mechanisms as follows:
302
303 @include fun-common-lisp-ed.texinfo
304 @include var-sb-ext-star-ed-functions-star.texinfo
305
306 @node Tools To Help Developers
307 @comment  node-name,  next,  previous,  up
308 @section Tools To Help Developers
309
310 SBCL provides a profiler and other extensions to the ANSI @code{trace}
311 facility.  For more information, see @ref{Macro common-lisp:trace}.
312
313 The debugger supports a number of options. Its documentation is
314 accessed by typing @kbd{help} at the debugger prompt. @xref{Debugger}.
315
316 Documentation for @code{inspect} is accessed by typing @kbd{help} at
317 the @code{inspect} prompt.
318
319 @node Resolution of Name Conflicts
320 @section Resolution of Name Conflicts
321
322 The ANSI standard (section 11.1.1.2.5) requires that name conflicts in
323 packages be resolvable in favour of any of the conflicting symbols.  In
324 the interactive debugger, this is achieved by prompting for the symbol
325 in whose favour the conflict should be resolved; for programmatic use,
326 the @code{sb-ext:resolve-conflict} restart should be invoked with one
327 argument, which should be a member of the list returned by the condition
328 accessor @code{sb-ext:name-conflict-symbols}.
329
330 @node Stale Extensions
331 @comment  node-name,  next,  previous,  up
332 @section Stale Extensions
333
334 SBCL has inherited from CMUCL various hooks to allow the user to
335 tweak and monitor the garbage collection process. These are somewhat
336 stale code, and their interface might need to be cleaned up. If you
337 have urgent need of them, look at the code in @file{src/code/gc.lisp}
338 and bring it up on the developers' mailing list.
339
340 SBCL has various hooks inherited from CMUCL, like
341 @code{sb-ext:float-denormalized-p}, to allow a program to take
342 advantage of IEEE floating point arithmetic properties which aren't
343 conveniently or efficiently expressible using the ANSI standard. These
344 look good, and their interface looks good, but IEEE support is
345 slightly broken due to a stupid decision to remove some support for
346 infinities (because it wasn't in the ANSI spec and it didn't occur to
347 me that it was in the IEEE spec). If you need this stuff, take a look
348 at the code and bring it up on the developers' mailing
349 list.
350
351
352 @node  Efficiency Hacks
353 @comment  node-name,  next,  previous,  up
354 @section Efficiency Hacks
355
356 The @code{sb-ext:purify} function causes SBCL first to collect all
357 garbage, then to mark all uncollected objects as permanent, never again
358 attempting to collect them as garbage. This can cause a large increase
359 in efficiency when using a primitive garbage collector, or a more
360 moderate increase in efficiency when using a more sophisticated garbage
361 collector which is well suited to the program's memory usage pattern. It
362 also allows permanent code to be frozen at fixed addresses, a
363 precondition for using copy-on-write to share code between multiple Lisp
364 processes.  This is less important with modern generational garbage
365 collectors, but not all SBCL platforms use such a garbage collector.
366
367 @include fun-sb-ext-purify.texinfo
368
369 The @code{sb-ext:truly-the} special form declares the type of the
370 result of the operations, producing its argument; the declaration is
371 not checked. In short: don't use it.
372
373 @include special-operator-sb-ext-truly-the.texinfo
374
375 The @code{sb-ext:freeze-type} declaration declares that a
376 type will never change, which can make type testing
377 (@code{typep}, etc.) more efficient for structure types.
378
379 The @code{sb-ext:constant-function} declaration specifies
380 that a function will always return the same value for the same
381 arguments, which may allow the compiler to optimize calls
382 to it. This is appropriate for functions like @code{sqrt}, but
383 is @emph{not} appropriate for functions like @code{aref},
384 which can change their return values when the underlying data are
385 changed.
386 @c <!-- FIXME: This declaration does not seem to be supported in the 
387 @c      current compiler. -->