0.9.11.4
[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 @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}.
63
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}.
67
68 @item
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
76 @tindex function
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.
86
87 @findex typep
88 @findex class-of
89 @findex subtypep
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.
98
99 The following class definitions are bad, and will lead to errors
100 either immediately or if an instance is created:
101 @lisp
102 (defclass bad-object (funcallable-standard-object)
103   ()
104   (:metaclass standard-class))
105 @end lisp
106 @lisp
107 (defclass bad-funcallable-object (standard-object)
108   ()
109   (:metaclass funcallable-standard-class))
110 @end lisp
111 The following definition is acceptable:
112 @lisp
113 (defclass mixin ()
114   ((slot :initarg slot)))
115 (defclass funcallable-object (funcallable-standard-object mixin)
116   ()
117   (:metaclass funcallable-standard-class))
118 @end lisp
119 and leads to a class whose instances are funcallable and have one slot.
120
121 @item
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.
129
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.
134
135 @end itemize
136
137 @node  Support For Unix
138 @comment  node-name,  next,  previous,  up
139 @section Support For Unix
140
141 The UNIX command line can be read from the variable
142 @code{sb-ext:*posix-argv*}. The UNIX environment can be queried with
143 the @code{sb-ext:posix-getenv} function.
144
145 @include fun-sb-ext-posix-getenv.texinfo
146
147 External programs can be run with @code{sb-ext:run-program}.
148
149 @include fun-sb-ext-run-program.texinfo
150
151 @include fun-sb-ext-process-p.texinfo
152
153 @include fun-sb-ext-process-input.texinfo
154
155 @include fun-sb-ext-process-output.texinfo
156
157 @include fun-sb-ext-process-error.texinfo
158
159 @include fun-sb-ext-process-alive-p.texinfo
160
161 @include fun-sb-ext-process-status.texinfo
162
163 @include fun-sb-ext-process-wait.texinfo
164
165 @include fun-sb-ext-process-exit-code.texinfo
166
167 @include fun-sb-ext-process-core-dumped.texinfo
168
169 @include fun-sb-ext-process-close.texinfo
170
171 @include fun-sb-ext-process-kill.texinfo
172
173 @node  Customization Hooks for Users
174 @comment  node-name,  next,  previous,  up
175 @section Customization Hooks for Users
176
177 The toplevel repl prompt may be customized, and the function
178 that reads user input may be replaced completely.
179 @c <!-- FIXME but I don't currently remember how -->
180
181 The behaviour of @code{require} when called with only one argument is
182 implementation-defined.  In SBCL, @code{require} behaves in the
183 following way:
184
185 @include fun-common-lisp-require.texinfo
186 @include var-sb-ext-star-module-provider-functions-star.texinfo
187
188 Although SBCL does not provide a resident editor, the @code{ed}
189 function can be customized to hook into user-provided editing
190 mechanisms as follows:
191
192 @include fun-common-lisp-ed.texinfo
193 @include var-sb-ext-star-ed-functions-star.texinfo
194
195 @node Tools To Help Developers
196 @comment  node-name,  next,  previous,  up
197 @section Tools To Help Developers
198
199 SBCL provides a profiler and other extensions to the ANSI @code{trace}
200 facility.  For more information, see @ref{Macro common-lisp:trace}.
201
202 The debugger supports a number of options. Its documentation is
203 accessed by typing @kbd{help} at the debugger prompt. @xref{Debugger}.
204
205 Documentation for @code{inspect} is accessed by typing @kbd{help} at
206 the @code{inspect} prompt.
207
208 @node Resolution of Name Conflicts
209 @section Resolution of Name Conflicts
210
211 The ANSI standard (section 11.1.1.2.5) requires that name conflicts in
212 packages be resolvable in favour of any of the conflicting symbols.  In
213 the interactive debugger, this is achieved by prompting for the symbol
214 in whose favour the conflict should be resolved; for programmatic use,
215 the @code{sb-ext:resolve-conflict} restart should be invoked with one
216 argument, which should be a member of the list returned by the condition
217 accessor @code{sb-ext:name-conflict-symbols}.
218
219 @node Stale Extensions
220 @comment  node-name,  next,  previous,  up
221 @section Stale Extensions
222
223 SBCL has inherited from CMUCL various hooks to allow the user to
224 tweak and monitor the garbage collection process. These are somewhat
225 stale code, and their interface might need to be cleaned up. If you
226 have urgent need of them, look at the code in @file{src/code/gc.lisp}
227 and bring it up on the developers' mailing list.
228
229 SBCL has various hooks inherited from CMUCL, like
230 @code{sb-ext:float-denormalized-p}, to allow a program to take
231 advantage of IEEE floating point arithmetic properties which aren't
232 conveniently or efficiently expressible using the ANSI standard. These
233 look good, and their interface looks good, but IEEE support is
234 slightly broken due to a stupid decision to remove some support for
235 infinities (because it wasn't in the ANSI spec and it didn't occur to
236 me that it was in the IEEE spec). If you need this stuff, take a look
237 at the code and bring it up on the developers' mailing
238 list.
239
240
241 @node  Efficiency Hacks
242 @comment  node-name,  next,  previous,  up
243 @section Efficiency Hacks
244
245 The @code{sb-ext:purify} function causes SBCL first to collect all
246 garbage, then to mark all uncollected objects as permanent, never again
247 attempting to collect them as garbage. This can cause a large increase
248 in efficiency when using a primitive garbage collector, or a more
249 moderate increase in efficiency when using a more sophisticated garbage
250 collector which is well suited to the program's memory usage pattern. It
251 also allows permanent code to be frozen at fixed addresses, a
252 precondition for using copy-on-write to share code between multiple Lisp
253 processes.  This is less important with modern generational garbage
254 collectors, but not all SBCL platforms use such a garbage collector.
255
256 @include fun-sb-ext-purify.texinfo
257
258 The @code{sb-ext:truly-the} special form declares the type of the
259 result of the operations, producing its argument; the declaration is
260 not checked. In short: don't use it.
261
262 @include special-operator-sb-ext-truly-the.texinfo
263
264 The @code{sb-ext:freeze-type} declaration declares that a
265 type will never change, which can make type testing
266 (@code{typep}, etc.) more efficient for structure types.
267
268 The @code{sb-ext:constant-function} declaration specifies
269 that a function will always return the same value for the same
270 arguments, which may allow the compiler to optimize calls
271 to it. This is appropriate for functions like @code{sqrt}, but
272 is @emph{not} appropriate for functions like @code{aref},
273 which can change their return values when the underlying data are
274 changed.
275 @c <!-- FIXME: This declaration does not seem to be supported in the 
276 @c      current compiler. -->