0.8.6:
[sbcl.git] / doc / beyond-ansi.sgml
1 <!-- -*- mode: SGML; sgml-parent-document: ("user-manual.sgml" "BOOK") -*- -->
2 <chapter id="beyond-ansi"><title>Beyond The &ANSI; Standard</>
3
4 <para>&SBCL; is mostly an implementation of the &ANSI; standard for
5 Common Lisp. However, there's some important behavior which extends
6 or clarifies the standard, and various behavior which outright
7 violates the standard.
8 </para>
9
10 <sect1 id="non-conformance"><title>Non-Conformance With The &ANSI; Standard</>
11
12 <para>
13 Essentially every type of non-conformance is considered a bug.
14 (The exceptions involve internal inconsistencies in the standard.)
15 In &SBCL; 0.7.6, the master record of known bugs is in
16 the <filename>BUGS</> file in the distribution.
17 Some highlight information about bugs may also be found in the
18 manual page. The recommended way to report bugs is through the sbcl-help or
19 sbcl-devel mailings lists.
20 </para>
21
22 </sect1>
23
24 <sect1 id="idiosyncrasies"><title>Idiosyncrasies</>
25
26 <para>The information in this section describes some of the ways
27 that &SBCL; deals with choices that the &ANSI; standard 
28 leaves to the implementation.</para>
29
30 <para>Declarations are generally treated as assertions. This general
31 principle, and its implications, and the bugs which still keep the
32 compiler from quite satisfying this principle, are discussed in the
33 <link linkend="compiler">chapter on the compiler</link>.</para>
34
35 <para>&SBCL; is essentially a compiler-only implementation of
36 &CommonLisp;. That is, for all but a few special cases,
37 <function>eval</> creates a
38 lambda expression, calls <function>compile</> on the lambda
39 expression to create a compiled function, and then calls
40 <function>funcall</> on the resulting function object. This 
41 is explicitly allowed by the &ANSI; standard, but leads to some
42 oddities, e.g. collapsing <function>functionp</> and 
43 <function>compiled-function-p</> into the same predicate.</para>
44
45 <para>&SBCL; is quite strict about ANSI's definition of
46 <function>defconstant</>. ANSI says that doing <function>defconstant</>
47 of the same symbol more than once is undefined unless the new value
48 is <function>eql</> to the old value. Conforming to this specification
49 is a nuisance when the "constant" value is only constant under some
50 weaker test like <function>string=</> or <function>equal</>. It's
51 especially annoying because, in &SBCL;, <function>defconstant</> takes effect
52 not only at load time but also at compile time, so that just 
53 compiling and loading reasonable code like 
54 <programlisting>(defconstant +foobyte+ '(1 4))</>
55 runs into this undefined behavior. Many
56 implementations of Common Lisp try to help the programmer around
57 this annoyance by silently accepting the undefined code and 
58 trying to do what the programmer probably meant. &SBCL; instead
59 treats the undefined behavior as an error. Often
60 such code can be rewritten
61 in portable &ANSI; Common Lisp which has the desired behavior.
62 E.g., the code above can be given an exactly defined meaning by replacing
63 <function>defconstant</> either with <function>defparameter</> or 
64 with a customized macro which does the right thing, possibly along the
65 lines of the <function>defconstant-eqx</> macro used internally in the
66 implementation of &SBCL; itself.  In circumstances where this is not 
67 appropriate, the programmer can handle the condition type 
68 <errortype>sb-ext:defconstant-uneql</errortype>, and choose either the 
69 <action>continue</action> or <action>abort</action> restart as 
70 appropriate.</para>
71
72 <para>&SBCL; gives style warnings about various kinds of perfectly
73 legal code, e.g.
74 <itemizedlist>
75   <listitem><para><function>defmethod</> without
76     <function>defgeneric</></para></listitem>
77   <listitem><para>multiple <function>defun</>s of the same
78     symbol</para></listitem>
79   <listitem><para>special variables not named in the conventional
80     <varname>*foo*</> style, and lexical variables unconventionally named
81     in the <varname>*foo*</> style</para></listitem>
82 </itemizedlist>
83 This causes friction with people
84 who point out that other ways of organizing code (especially
85 avoiding the use of <function>defgeneric</>)
86 are just as aesthetically stylish.
87 However, these warnings should be read not
88 as "warning, bad aesthetics detected, you have no style" but
89 "warning, this style keeps the compiler from understanding
90 the code as well as you might like." That is, 
91 unless the compiler warns about such conditions, there's no
92 way for the compiler to warn 
93 about some programming errors which would otherwise be
94 easy to overlook. (related bug: The warning about
95 multiple <function>defun</>s is pointlessly annoying when you compile
96 and then load a function containing <function>defun</> wrapped
97 in <function>eval-when</>, and ideally should be suppressed in 
98 that case, but still isn't as of &SBCL; 0.7.6.)</para>
99
100 </sect1>
101
102 <sect1 id="extensions"><title>Extensions</>
103
104 <para>&SBCL; is derived from &CMUCL;, which implements many extensions
105 to the &ANSI; standard. &SBCL; doesn't support as many extensions as
106 &CMUCL;, but it still has quite a few.</para>
107
108 <sect2><title>Things Which Might Be In The Next &ANSI; Standard</>
109
110 <para>&SBCL; provides extensive support for 
111 calling external C code, described 
112 <link linkend="ffi">in its own chapter</link>.</para>
113
114 <para>&SBCL; provides additional garbage collection functionality not
115 specified by &ANSI;. Weak pointers allow references to objects to be
116 maintained without keeping them from being GCed. And "finalization"
117 hooks are available to cause code to be executed when an object has been
118 GCed.</para> <!-- FIXME: Actually documenting these would be good.:-| -->
119
120 <para>&SBCL; supports Gray streams, user-overloadable CLOS classes
121 whose instances can be used as Lisp streams (e.g. passed as the
122 first argument to <function>format</>).  Additionally, the 
123 bundled contrib module <interface>sb-simple-streams</interface>
124 implements a subset of the Franz Allegro simple-streams proposal.</para>  
125
126 <para>&SBCL; supports a MetaObject Protocol which is intended to be
127 compatible with &AMOP;; present exceptions to this (as distinct from
128 current bugs) are:</para>
129 <itemizedlist>
130   <listitem><para>the abstract <classname>metaobject</> class is not
131     present in the class hierarchy;</para></listitem>
132   <listitem><para>the <classname>standard-object</> and
133     <classname>funcallable-standard-object</> classes are
134     disjoint;</para></listitem>
135   <listitem><para><function>compute-effective-method</> only returns
136     one value, not two;</para></listitem>
137   <listitem><para>the system-supplied <property>:around</> method for
138     <function>compute-slots</> specialized on
139     <classname>funcallable-standard-class</> does not respect the
140     requested order from a user-supplied primary method.</para>
141 </listitem>
142 </itemizedlist>
143
144 </sect2>
145
146 <sect2><title>Threading (a.k.a Multiprocessing)</>
147
148 <para>&SBCL; (as of version 0.8.3, on Linux x86 only) supports a
149 fairly low-level threading interface that maps onto the host operating
150 system's concept of threads or lightweight processes.  </para>
151
152 <sect3><title>Lisp-level view</title>
153
154 <para>A rudimentary interface to creating and managing multiple threads
155 can be found in the <literal>sb-thread</literal> package.  This is
156 intended for public consumption, so look at the exported symbols and
157 their documentation strings.  
158 </para>
159
160 <para>Dynamic bindings to symbols are per-thread.   Signal handlers
161 are per-thread.
162 </para>
163
164 <para><function>sb-ext:quit</function> exits the current thread, not
165 necessarily the whole environment.  The environment will be shut down
166 when the last thread exits.  
167 </para>
168
169 <para>Threads arbitrate between themselves for the user's attention.
170 A thread may be in one of three notional states: foreground,
171 background, or stopped.  When a background process attempts to print a
172 repl prompt or to enter the debugger, it will stop and print a message
173 saying that it has stopped.  The user at his leisure may switch to
174 that thread to find out what it needs.  If a background thread enters
175 the debugger, selecting any restart will put it back into the
176 background before it resumes.
177 </para>
178
179 <para>If the user has multiple views onto the same Lisp image (for
180 example, using multiple terminals, or a windowing system, or network
181 access) they are typically set up as multiple `sessions' such that each 
182 view has its own collection of foreground/background/stopped threads.
183 <function>sb-thread:make-listener-thread</function> can be used to
184 start a new thread in its own `session'.
185 </para>
186
187 <para>Mutexes and condition variables are available for 
188 managing access to shared data: see 
189 <itemizedlist>
190 <listitem>
191 <programlisting>(apropos "mutex" :sb-thread)</programlisting> 
192 </listitem>
193 <listitem>
194 <programlisting>(apropos "condition" :sb-thread)</programlisting> 
195 </listitem>
196 <listitem> <para>and the <structname>waitqueue</structname> structure
197 </para>
198 </listitem>
199 </itemizedlist>
200 and poke around in their documentation strings.</para>
201 </sect3>
202
203 <sect3><title>Implementation (Linux x86)</title>
204
205 <para>On Linux x86, this is implemented using
206 <function>clone()</function> and does not involve pthreads.  This is
207 not because there is anything wrong with pthreads <emphasis>per
208 se</emphasis>, but there is plenty wrong (from our perspective) with
209 LinuxThreads.  &SBCL; threads are mapped 1:1 onto Linux tasks which
210 share a VM but nothing else - each has its own process id and can be
211 seen in e.g. <command>ps</command> output.
212 </para>
213
214 <para>Per-thread local bindings for special variables is achieved
215 using the %fs segment register to point to a per-thread storage area.
216 This may cause interesting results if you link to foreign code that
217 expects threading or creates new threads, and the thread library in
218 question uses %fs in an incompatible way.
219 </para>
220
221 <para>Threads waiting on queues (e.g. for locks or condition
222 variables) are put to sleep using <function>sigtimedwait()</function>
223 and woken with SIGCONT.
224 </para>
225
226 <para>&SBCL; at present will alway have at least two tasks running as
227 seen from Linux: when the first process has done startup
228 initialization (mapping files in place, installing signal handlers
229 etc) it creates a new thread to run the Lisp startup and initial
230 listener.  The original thread stays around to reap dead subthreads
231 and deallocate their resources (e.g. stacks) when they exit.
232 </para>
233
234 <para>Garbage collection is done with the existing Conservative
235 Generational GC.  Allocation is done in small (typically 8k) regions :
236 each thread has its own region so this involves no stopping. However,
237 when a region fills, a lock must be obtained while another is
238 allocated, and when a collection is required, all processes are
239 stopped.  This is achieved by sending them signals, which may make for 
240 interesting behaviour if they are interrupted in system calls.  The
241 streams interface is believed to handle the required system call
242 restarting correctly, but this may be a consideration when making
243 other blocking calls e.g. from foreign library code.
244 </para>
245
246 <para>Large amounts of the &SBCL; library have not been inspected for
247 thread-safety.  Some of the obviously unsafe areas have large locks
248 around them, so compilation and fasl loading, for example, cannot be
249 parallelized.  Work is ongoing in this area.
250 </para>
251
252 <para>A new thread by default is created in the same POSIX process
253 group and session as the thread it was created by.  This has an impact
254 on keyboard interrupt handling: pressing your terminal's intr key
255 (typically Control-C) will interrupt all processes in the foreground
256 process group, including Lisp threads that &SBCL; considers to be
257 notionally `background'.  This is undesirable, so background threads
258 are set to ignore the SIGINT signal.  Arbitration for the input stream
259 is managed by locking on <varname>sb-thread::*session-lock*</varname>
260 </para>
261
262 <para>A thread can be created in a new Lisp 'session' (new terminal or
263 window) using <function>sb-thread:make-listener-thread</function>.
264 These sessions map directly onto POSIX sessions, so that pressing
265 Control-C in the wrong window will not interrupt them - this has been
266 found to be embarrassing.
267 </para>
268
269 </sect3>
270
271 </sect2>
272
273 <sect2><title>Support For Unix</>
274
275 <para>The UNIX command line can be read from the variable
276 <varname>sb-ext:*posix-argv*</>. The UNIX environment can be queried with the
277 <function>sb-ext:posix-getenv</> function.</para>
278
279 <para>The &SBCL; system can be terminated with <function>sb-ext:quit</>,
280 optionally returning a specified numeric value to the calling Unix
281 process. The normal Unix idiom of terminating on end of file on input
282 is also supported.</para>
283
284 </sect2>
285
286 <sect2><title>Customization Hooks for Users</title>
287
288 <para>The behaviour of <function>require</function> when called with only
289 one argument is implementation-defined.  In &SBCL; it calls functions
290 on the user-settable list <varname>sb-ext:*module-provider-functions*</varname>
291 - see the <function>require</function> documentation string for details.
292 </para>
293
294 <para>The toplevel repl prompt may be customized, and the function
295 that reads user input may be replaced completely.  <!-- FIXME but I 
296 don't currently remember how -->
297 </para>
298
299 </sect2>
300
301 <sect2><title>Tools To Help Developers</title>
302
303 <para>&SBCL; provides a profiler and other extensions to the &ANSI;
304 <function>trace</> facility. See the online function documentation for
305 <function>trace</> for more information.</para>
306
307 <para>The debugger supports a number of options. Its documentation is
308 accessed by typing <userinput>help</> at the debugger prompt.</para>
309 <!-- FIXME:
310      A true debugger section in the manual would be good. Start
311      with CMU CL's debugger section, but remember:
312        * no QUIT command (TOPLEVEL restart instead)
313        * no GO command (CONTINUE restart instead)
314        * Limitations of the x86 port of the debugger should be 
315          documented or fixed where possible.
316        * Discuss TRACE and its unification with PROFILE. -->
317
318 <para>Documentation for <function>inspect</> is accessed by typing
319 <userinput>help</> at the <function>inspect</> prompt.</para>
320
321 </sect2>
322
323 <sect2><title>Interface To Low-Level &SBCL; Implementation</title>
324
325 <para>&SBCL; has the ability to save its state as a file for later
326 execution. This functionality is important for its bootstrapping
327 process, and is also provided as an extension to the user See the
328 documentation for <function>sb-ext:save-lisp-and-die</> for more
329 information.</para>
330
331 <note><para>&SBCL; has inherited from &CMUCL; various hooks to allow
332 the user to tweak and monitor the garbage collection process. These
333 are somewhat stale code, and their interface might need to be cleaned
334 up. If you have urgent need of them, look at the code in
335 <filename>src/code/gc.lisp</filename> and bring it up on the
336 developers' mailing list.</para></note>
337
338 <note><para>&SBCL; has various hooks inherited from &CMUCL;, like
339 <function>sb-ext:float-denormalized-p</>, to allow a program to take
340 advantage of &IEEE; floating point arithmetic properties which aren't
341 conveniently or efficiently expressible using the &ANSI; standard. These
342 look good, and their interface looks good, but &IEEE; support is
343 slightly broken due to a stupid decision to remove some support for
344 infinities (because it wasn't in the &ANSI; spec and it didn't occur to
345 me that it was in the &IEEE; spec). If you need this stuff, take a look
346 at the code and bring it up on the developers' mailing
347 list.</para></note>
348
349 </sect2>
350
351 <sect2><title>Efficiency Hacks</title>
352
353 <para>The <function>sb-ext:purify</function> function causes &SBCL;
354 first to collect all garbage, then to mark all uncollected objects as
355 permanent, never again attempting to collect them as garbage. This can
356 cause a large increase in efficiency when using a primitive garbage
357 collector, or a more moderate increase in efficiency when using a more
358 sophisticated garbage collector which is well suited to the program's
359 memory usage pattern. It also allows permanent code to be frozen at
360 fixed addresses, a precondition for using copy-on-write to share code
361 between multiple Lisp processes. is less important with modern
362 generational garbage collectors. </para>
363
364 <para>The <function>sb-ext:truly-the</> declares the type of the
365 result of the operations, producing its argument; the declaration is
366 not checked. In short: don't use it.</para>
367
368 <para>The <function>sb-ext:freeze-type</> declaration declares that a
369 type will never change, which can make type testing
370 (<function>typep</>, etc.) more efficient for structure types.</para>
371
372 <para>The <function>sb-ext:constant-function</> declaration specifies
373 that a function will always return the same value for the same
374 arguments, which may allow the compiler to optimize calls
375 to it. This is appropriate for functions like <function>sqrt</>, but
376 is <emphasis>not</> appropriate for functions like <function>aref</>,
377 which can change their return values when the underlying data are
378 changed.</para>
379 <!-- FIXME: This declaration does not seem to be supported in the --
380   -- current compiler. -->
381
382 </sect2>
383
384 </sect1>
385
386 </chapter>