1 SBCL is mostly an implementation of the ANSI standard for
2 Common Lisp. However, there's some important behavior which extends
3 or clarifies the standard, and various behavior which outright
8 * Non-Conformance With The ANSI Standard::
13 @node Non-Conformance With The ANSI Standard
14 @comment node-name, next, previous, up
15 @section Non-Conformance With The ANSI Standard
17 Essentially every type of non-conformance is considered a bug. (The
18 exceptions involve internal inconsistencies in the standard.) In SBCL
19 0.7.6, the master record of known bugs is in the @file{BUGS} file in
20 the distribution. Some highlight information about bugs may also be
21 found in the manual page. The recommended way to report bugs is
22 through the sbcl-help or sbcl-devel mailing lists. For mailing list
23 addresses, @xref{More SBCL Information}.
27 @comment node-name, next, previous, up
28 @section Idiosyncrasies
30 The information in this section describes some of the ways that SBCL
31 deals with choices that the ANSI standard leaves to the
34 Declarations are generally treated as assertions. This general
35 principle, and its implications, and the bugs which still keep the
36 compiler from quite satisfying this principle, are discussed in
39 SBCL is essentially a compiler-only implementation of Common
40 Lisp. That is, for all but a few special cases, @code{eval} creates a
41 lambda expression, calls @code{compile} on the lambda expression to
42 create a compiled function, and then calls @code{funcall} on the
43 resulting function object. This is explicitly allowed by the ANSI
44 standard, but leads to some oddities, e.g. collapsing @code{functionp}
45 and @code{compiled-function-p} into the same predicate.
48 SBCL is quite strict about ANSI's definition of
49 @code{defconstant}. ANSI says that doing @code{defconstant} of the
50 same symbol more than once is undefined unless the new value is
51 @code{eql} to the old value. Conforming to this specification is a
52 nuisance when the ``constant'' value is only constant under some
53 weaker test like @code{string=} or @code{equal}. It's especially
54 annoying because, in SBCL, @code{defconstant} takes effect not only at
55 load time but also at compile time, so that just compiling and loading
58 (defconstant +foobyte+ '(1 4))
60 runs into this undefined behavior. Many implementations of Common Lisp
61 try to help the programmer around this annoyance by silently accepting
62 the undefined code and trying to do what the programmer probably
63 meant. SBCL instead treats the undefined behavior as an error. Often
64 such code can be rewritten in portable ANSI Common Lisp which has the
65 desired behavior. E.g., the code above can be given an exactly
66 defined meaning by replacing @code{defconstant} either with
67 @code{defparameter} or with a customized macro which does the right
68 thing, possibly along the lines of the @code{defconstant-eqx} macro
69 used internally in the implementation of SBCL itself. In
70 circumstances where this is not appropriate, the programmer can handle
71 the condition type @code{sb-ext:defconstant-uneql}, and choose either
72 the @command{continue} or @command{abort} restart as appropriate.
74 SBCL gives style warnings about various kinds of perfectly legal code,
80 @code{defmethod} without a preceding @code{defgeneric};
83 multiple @code{defun}s of the same symbol in different units;
86 special variables not named in the conventional @code{*foo*} style,
87 and lexical variables unconventionally named in the @code{*foo*} style
91 This causes friction with people who point out that other ways of
92 organizing code (especially avoiding the use of @code{defgeneric}) are
93 just as aesthetically stylish. However, these warnings should be read
94 not as ``warning, bad aesthetics detected, you have no style'' but
95 ``warning, this style keeps the compiler from understanding the code
96 as well as you might like.'' That is, unless the compiler warns about
97 such conditions, there's no way for the compiler to warn about some
98 programming errors which would otherwise be easy to overlook. (Related
99 bug: The warning about multiple @code{defun}s is pointlessly annoying
100 when you compile and then load a function containing @code{defun}
101 wrapped in @code{eval-when}, and ideally should be suppressed in that
102 case, but still isn't as of SBCL 0.7.6.)
106 @comment node-name, next, previous, up
109 SBCL is derived from CMUCL, which implements many extensions to the
110 ANSI standard. SBCL doesn't support as many extensions as CMUCL, but
111 it still has quite a few. @xref{Contributed Modules}.
115 * Things Which Might Be In The Next ANSI Standard::
118 * Customization Hooks for Users::
119 * Tools To Help Developers::
120 * Interface To Low-Level SBCL Implementation::
125 @node Things Which Might Be In The Next ANSI Standard
126 @comment node-name, next, previous, up
127 @subsection Things Which Might Be In The Next ANSI Standard
129 SBCL provides extensive support for calling external C code,
130 @ref{Foreign Function Interface}.
132 SBCL provides additional garbage collection functionality not
133 specified by ANSI. Weak pointers allow references to objects to be
134 maintained without keeping them from being GCed (garbage
135 collected). And ``finalization'' hooks are available to cause code to
136 be executed when an object has been GCed.
137 @c <!-- FIXME: Actually documenting these would be good.:-| -->
139 SBCL supports @dfn{Gray streams}, user-overloadable CLOS classes whose
140 instances can be used as Lisp streams (e.g. passed as the first
141 argument to @code{format}). Additionally, the bundled contrib module
142 @dfn{sb-simple-streams} implements a subset of the Franz Allegro
143 simple-streams proposal.
145 SBCL supports a MetaObject Protocol which is intended to be compatible
146 with AMOP; present exceptions to this (as distinct from current bugs)
152 the abstract @code{metaobject} class is not present in the class
156 the @code{standard-object} and @code{funcallable-standard-object}
157 classes are disjoint;
160 @code{compute-effective-method} only returns one value, not two;
163 the system-supplied @code{:around} method for @code{compute-slots}
164 specialized on @code{funcallable-standard-class} does not respect the
165 requested order from a user-supplied primary method.
171 @comment node-name, next, previous, up
172 @subsection Threading (a.k.a Multiprocessing)
174 SBCL supports a fairly low-level threading interface that maps onto
175 the host operating system's concept of threads or lightweight
176 processes. This means that threads may take advantage of hardware
177 multiprocessing on machines that have more than one CPU, but it does
178 not allow Lisp control of the scheduler. This is found in the
181 This requires x86 and Linux kernel 2.6 or systems with NPTL backports.
183 @subsubsection Special variables
185 The interaction of special variables with multiple threads is mostly
186 as one would expect, but users of other Lisps are warned that the
187 behaviour of locally bound specials differs in places from what they
192 global special values are visible across all threads;
194 bindings (e.g. using LET) are local to the thread;
196 initial values in a new thread are taken from the thread that created it.
199 @subsubsection Mutex support
201 Mutexes are used for controlling access to a shared resource. One
202 thread is allowed to hold the mutex, others which attempt to take it
203 will be made to wait until it's free. Threads are woken in the order
204 that they go to sleep.
206 There isn't a timeout on mutex acquisition, but the usual WITH-TIMEOUT
207 macro (which throws a TIMEOUT condition after n seconds) can be used
208 if you want a bounded wait.
211 (defpackage :demo (:use "CL" "SB-THREAD" "SB-EXT"))
215 (defvar *a-mutex* (make-mutex :name "my lock"))
218 (let ((id (current-thread-id)))
219 (format t "Thread ~A running ~%" id)
220 (with-mutex (*a-mutex*)
221 (format t "Thread ~A got the lock~%" id)
223 (format t "Thread ~A dropped lock, dying now~%" id)))
225 (make-thread #'thread-fn)
226 (make-thread #'thread-fn)
230 @subsubsection Waitqueue/condition variables
232 These are based on the POSIX condition variable design, hence the
233 annoyingly CL-conflicting name. For use when you want to check a
234 condition and sleep until it's true. For example: you have a shared
235 queue, a writer process checking ``queue is empty'' and one or more
236 readers that need to know when ``queue is not empty''. It sounds
237 simple, but is astonishingly easy to deadlock if another process runs
238 when you weren't expecting it to.
240 There are three components:
243 @item the condition itself (not represented in code)
244 @item the condition variable (a.k.a waitqueue) which proxies for it
245 @item a lock to hold while testing the condition
248 Important stuff to be aware of:
251 @item when calling condition-wait, you must hold the mutex. condition-wait will drop the mutex while it waits, and obtain it again before returning for whatever reason;
253 @item likewise, you must be holding the mutex around calls to condition-notify;
255 @item a process may return from condition-wait in several circumstances: it is not guaranteed that the underlying condition has become true. You must check that the resource is ready for whatever you want to do to it.
260 (defvar *buffer-queue* (make-waitqueue))
261 (defvar *buffer-lock* (make-mutex :name "buffer lock"))
263 (defvar *buffer* (list nil))
266 (with-mutex (*buffer-lock*)
268 (condition-wait *buffer-queue* *buffer-lock*)
270 (unless *buffer* (return))
271 (let ((head (car *buffer*)))
272 (setf *buffer* (cdr *buffer*))
273 (format t "reader ~A woke, read ~A~%"
274 (current-thread-id) head))))))
279 (with-mutex (*buffer-lock*)
282 (+ (char-code #\A) (random 26)))))))
283 (setf *buffer* (cons el *buffer*)))
284 (condition-notify *buffer-queue*))))
286 (make-thread #'writer)
287 (make-thread #'reader)
288 (make-thread #'reader)
292 @subsubsection Sessions/Debugging
294 If the user has multiple views onto the same Lisp image (for example,
295 using multiple terminals, or a windowing system, or network access)
296 they are typically set up as multiple @dfn{sessions} such that each
297 view has its own collection of foreground/background/stopped threads.
298 A thread which wishes to create a new session can use
299 @code{sb-thread:with-new-session} to remove itself from the current
300 session (which it shares with its parent and siblings) and create a
302 # See also @code{sb-thread:make-listener-thread}.
304 Within a single session, threads arbitrate between themselves for the
305 user's attention. A thread may be in one of three notional states:
306 foreground, background, or stopped. When a background process
307 attempts to print a repl prompt or to enter the debugger, it will stop
308 and print a message saying that it has stopped. The user at his
309 leisure may switch to that thread to find out what it needs. If a
310 background thread enters the debugger, selecting any restart will put
311 it back into the background before it resumes. Arbitration for the
312 input stream is managed by calls to @code{sb-thread:get-foreground}
313 (which may block) and @code{sb-thread:release-foreground}.
315 @code{sb-ext:quit} terminates all threads in the current session, but
316 leaves other sessions running.
319 @subsubsection Implementation (Linux x86)
321 On Linux x86, threading is implemented using @code{clone()} and does
322 not involve pthreads. This is not because there is anything wrong
323 with pthreads @emph{per se}, but there is plenty wrong (from our
324 perspective) with LinuxThreads. SBCL threads are mapped 1:1 onto
325 Linux tasks which share a VM but nothing else - each has its own
326 process id and can be seen in e.g. @command{ps} output.
328 Per-thread local bindings for special variables is achieved using the
329 %fs segment register to point to a per-thread storage area. This may
330 cause interesting results if you link to foreign code that expects
331 threading or creates new threads, and the thread library in question
332 uses %fs in an incompatible way.
334 Queues require the @code{sys_futex()} system call to be available:
335 this is the reason for the NPTL requirement. We test at runtime that
336 this system call exists.
338 Garbage collection is done with the existing Conservative Generational
339 GC. Allocation is done in small (typically 8k) regions: each thread
340 has its own region so this involves no stopping. However, when a
341 region fills, a lock must be obtained while another is allocated, and
342 when a collection is required, all processes are stopped. This is
343 achieved by sending them signals, which may make for interesting
344 behaviour if they are interrupted in system calls. The streams
345 interface is believed to handle the required system call restarting
346 correctly, but this may be a consideration when making other blocking
347 calls e.g. from foreign library code.
349 Large amounts of the SBCL library have not been inspected for
350 thread-safety. Some of the obviously unsafe areas have large locks
351 around them, so compilation and fasl loading, for example, cannot be
352 parallelized. Work is ongoing in this area.
354 A new thread by default is created in the same POSIX process group and
355 session as the thread it was created by. This has an impact on
356 keyboard interrupt handling: pressing your terminal's intr key
357 (typically @kbd{Control-C}) will interrupt all processes in the
358 foreground process group, including Lisp threads that SBCL considers
359 to be notionally `background'. This is undesirable, so background
360 threads are set to ignore the SIGINT signal.
362 @code{sb-thread:make-listener-thread} in addition to creating a new
363 Lisp session makes a new POSIX session, so that pressing
364 @kbd{Control-C} in one window will not interrupt another listener -
365 this has been found to be embarrassing.
368 @node Support For Unix
369 @comment node-name, next, previous, up
370 @subsection Support For Unix
372 The UNIX command line can be read from the variable
373 @code{sb-ext:*posix-argv*}. The UNIX environment can be queried with
374 the @code{sb-ext:posix-getenv} function.
376 @include fun-sb-ext-posix-getenv.texinfo
378 The SBCL system can be terminated with @code{sb-ext:quit}, (but see
379 notes in @ref{Threading} about the interaction between this feature and
380 sessions) optionally returning a specified numeric value to the
381 calling Unix process. The normal Unix idiom of terminating on end of
382 file on input is also supported.
384 @include fun-sb-ext-quit.texinfo
386 @node Customization Hooks for Users
387 @comment node-name, next, previous, up
388 @subsection Customization Hooks for Users
390 The toplevel repl prompt may be customized, and the function
391 that reads user input may be replaced completely.
392 @c <!-- FIXME but I don't currently remember how -->
394 The behaviour of @code{require} when called with only one argument is
395 implementation-defined. In SBCL, @code{require} behaves in the
398 @include fun-common-lisp-require.texinfo
399 @include var-sb-ext-star-module-provider-functions-star.texinfo
401 Although SBCL does not provide a resident editor, the @code{ed}
402 function can be customized to hook into user-provided editing
403 mechanisms as follows:
405 @include fun-common-lisp-ed.texinfo
406 @include var-sb-ext-star-ed-functions-star.texinfo
408 @node Tools To Help Developers
409 @comment node-name, next, previous, up
410 @subsection Tools To Help Developers
412 SBCL provides a profiler and other extensions to the ANSI @code{trace}
413 facility. For more information, see @ref{macro-common-lisp-trace}.
415 The debugger supports a number of options. Its documentation is
416 accessed by typing @kbd{help} at the debugger prompt. @xref{Debugger}.
418 Documentation for @code{inspect} is accessed by typing @kbd{help} at
419 the @code{inspect} prompt.
421 @node Interface To Low-Level SBCL Implementation
422 @comment node-name, next, previous, up
423 @subsection Interface To Low-Level SBCL Implementation
425 SBCL has the ability to save its state as a file for later
426 execution. This functionality is important for its bootstrapping
427 process, and is also provided as an extension to the user. Note that
428 foreign libraries loaded via @code{load-shared-object} don't survive
429 this process; a core should not be saved in this case.
431 @emph{FIXME: what should be done for foreign libraries?}
433 @emph{FIXME: document load-shared-object somewhere - it's in
436 @include fun-sb-ext-save-lisp-and-die.texinfo
439 @node Stale Extensions
440 @comment node-name, next, previous, up
441 @subsection Stale Extensions
443 SBCL has inherited from CMUCL various hooks to allow the user to
444 tweak and monitor the garbage collection process. These are somewhat
445 stale code, and their interface might need to be cleaned up. If you
446 have urgent need of them, look at the code in @file{src/code/gc.lisp}
447 and bring it up on the developers' mailing list.
449 SBCL has various hooks inherited from CMUCL, like
450 @code{sb-ext:float-denormalized-p}, to allow a program to take
451 advantage of IEEE floating point arithmetic properties which aren't
452 conveniently or efficiently expressible using the ANSI standard. These
453 look good, and their interface looks good, but IEEE support is
454 slightly broken due to a stupid decision to remove some support for
455 infinities (because it wasn't in the ANSI spec and it didn't occur to
456 me that it was in the IEEE spec). If you need this stuff, take a look
457 at the code and bring it up on the developers' mailing
461 @node Efficiency Hacks
462 @comment node-name, next, previous, up
463 @subsection Efficiency Hacks
465 The @code{sb-ext:purify} function causes SBCL first to collect all
466 garbage, then to mark all uncollected objects as permanent, never
467 again attempting to collect them as garbage. This can cause a large
468 increase in efficiency when using a primitive garbage collector, or a
469 more moderate increase in efficiency when using a more sophisticated
470 garbage collector which is well suited to the program's memory usage
471 pattern. It also allows permanent code to be frozen at fixed
472 addresses, a precondition for using copy-on-write to share code
473 between multiple Lisp processes. it is less important with modern
474 generational garbage collectors.
476 @include fun-sb-ext-purify.texinfo
478 The @code{sb-ext:truly-the} special form declares the type of the
479 result of the operations, producing its argument; the declaration is
480 not checked. In short: don't use it.
482 @include special-operator-sb-ext-truly-the.texinfo
484 The @code{sb-ext:freeze-type} declaration declares that a
485 type will never change, which can make type testing
486 (@code{typep}, etc.) more efficient for structure types.
488 The @code{sb-ext:constant-function} declaration specifies
489 that a function will always return the same value for the same
490 arguments, which may allow the compiler to optimize calls
491 to it. This is appropriate for functions like @code{sqrt}, but
492 is @emph{not} appropriate for functions like @code{aref},
493 which can change their return values when the underlying data are
495 @c <!-- FIXME: This declaration does not seem to be supported in the
496 @c current compiler. -->