Updates, light reorganization and a touch of prettification.
Also warn about the dangers of dynamic environment as it pertains to
timers.
too mild for the standard condition classes, typically hints about how
efficiency might be improved. The @code{sb-ext:code-deletion-note}, a
subtype of @code{compiler-note}, is signalled when the compiler
-deletes user-supplied code, usually after proving that the code in
-question is unreachable.
+deletes user-supplied code after proving that the code in question is
+unreachable.
Future work for SBCL includes expanding this hierarchy of types to
allow more fine-grained control over emission of diagnostic messages.
@item Introspective Facilities
@code{sb-introspect} module offers numerous introspective extensions,
-including access to function lambda-lists.
+including access to function lambda-lists and a cross referencing
+facility.
@item Operating System Interface
@code{sb-ext} contains a number of functions for running external
Profiler}.
@code{sb-sprof} is a statistical profiler, capable of call-graph
-generation and instruction level profiling. @xref{Statistical
-Profiler}.
+generation and instruction level profiling, which also supports
+allocation profiling. @xref{Statistical Profiler}.
@item Customization Hooks
SBCL contains a number of extra-standard customization hooks that
Edition} which were removed from the language during the ANSI
standardization process.
-@item Executable Fasl Packaging
-@code{sb-executable} can be used to concatenate multiple fasls into a
-single executable (though the presence of an SBCL runtime and core image
-is still required to run it).
-
+@item Executable Delivery
The @code{:executable} argument to @ref{Function
sb-ext:save-lisp-and-die} can produce a `standalone' executable
containing both an image of the current Lisp session and an SBCL
@menu
* Declarations::
+* FASL Format::
* Compiler-only Implementation::
* Defining Constants::
* Style Warnings::
compiler from quite satisfying this principle, are discussed in
@ref{Declarations as Assertions}.
+
+@node FASL Format
+@comment node-name, next, previous, up
+@subsection FASL Format
+
+SBCL fasl-format is binary compatible only with the exact SBCL version
+it was generated with. While this is obviously suboptimal, it has
+proven more robust than trying to maintain fasl compatibility across
+versions: accidentally breaking things is far too easy, and can lead
+to hard to diagnose bugs.
+
+The following snippet handles fasl recompilation automatically for
+ASDF-based systems, and makes a good candidate for inclusion in
+the user or system initialization file (@pxref{Initialization Files}.)
+
+@lisp
+(require :asdf)
+
+;;; If a fasl was stale, try to recompile and load (once).
+(defmethod asdf:perform :around ((o asdf:load-op)
+ (c asdf:cl-source-file))
+ (handler-case (call-next-method o c)
+ ;; If a fasl was stale, try to recompile and load (once).
+ (sb-ext:invalid-fasl ()
+ (asdf:perform (make-instance 'asdf:compile-op) c)
+ (call-next-method))))
+@end lisp
+
+
@node Compiler-only Implementation
@comment node-name, next, previous, up
@subsection Compiler-only Implementation
@table @cite
-@c FIXME: Ask Seibel if he minds us referring to the preview
-@c
-@c @item Practical Common Lisp, by Peter Seibel
-@c A forthcoming book from APress with a web free preview at
-@c @uref{http://www.gigamonkeys.com/book/}. An excellent introduction to
-@c the language, covering both the basics and ``advanced topics'' like
-@c macros, CLOS, and packages.
+@item Practical Common Lisp, by Peter Seibel
+An excellent introduction to the language, covering both the basics
+and ``advanced topics'' like macros, CLOS, and packages. Available
+both in print format and on the web: @uref{http://www.gigamonkeys.com/book/}.
-@item ANSI Common Lisp, by Paul Graham
-Introduces most of the language, though some parts (eg. CLOS) are
-covered only lightly.
+@item Paradigms Of Artificial Intelligence Programming, by Peter Norvig
+Good information on general Common Lisp programming, and many
+nontrivial examples. Whether or not your work is AI, it's a very good
+book to look at.
@item On Lisp, by Paul Graham
An in-depth treatment of macros, but not recommended as a first Common
try to cover the language as a whole, focusing solely on macros.
Downloadable from @uref{http://www.paulgraham.com/onlisp.html}.
-@item Paradigms Of Artificial Intelligence Programming, by Peter Norvig
-Good information on general Common Lisp programming, and many
-nontrivial examples. Whether or not your work is AI, it's a very good
-book to look at.
-
@item Object-Oriented Programming In Common Lisp, by Sonya Keene
-@c With the exception of @cite{Practical Common Lisp}
-None the books above emphasize CLOS, but this one does. Even if you're
-very knowledgeable about object oriented programming in the abstract,
-it's worth looking at this book if you want to do any OO in Common
-Lisp. Some abstractions in CLOS (especially multiple dispatch) go
-beyond anything you'll see in most OO systems, and there are a number
-of lesser differences as well. This book tends to help with the
-culture shock.
+With the exception of @cite{Practical Common Lisp} most introductory
+books don't emphasize CLOS. This one does. Even if you're very
+knowledgeable about object oriented programming in the abstract, it's
+worth looking at this book if you want to do any OO in Common Lisp.
+Some abstractions in CLOS (especially multiple dispatch) go beyond
+anything you'll see in most OO systems, and there are a number of
+lesser differences as well. This book tends to help with the culture
+shock.
@item Art Of Metaobject Programming, by Gregor Kiczales et al.
Currently to prime source of information on the Common Lisp Metaobject
@chapter Starting and Stopping
@menu
-* Starting SBCL::
-* Stopping SBCL::
-* Command Line Options::
-* Initialization Files::
-* Initialization and Exit Hooks::
+* Starting SBCL::
+* Stopping SBCL::
+* Command Line Options::
+* Initialization Files::
+* Initialization and Exit Hooks::
@end menu
@node Starting SBCL
@section Starting SBCL
@menu
-* Running from Shell::
-* Running from Emacs::
-* Shebang Scripts::
+* Running from Shell::
+* Running from Emacs::
+* Shebang Scripts::
@end menu
@node Running from Shell
@section Stopping SBCL
@menu
-* Quit::
-* End of File::
-* Saving a Core Image::
-* Exit on Errors::
+* Quit::
+* End of File::
+* Saving a Core Image::
+* Exit on Errors::
@end menu
@node Quit
runtime system or the Lisp system.
@menu
-* Runtime Options::
-* Toplevel Options::
+* Runtime Options::
+* Toplevel Options::
@end menu
@node Runtime Options
@item --sysinit @var{filename}
Load filename instead of the default system initialization file
-(@pxref{System Initialization File}.)
+(@pxref{Initialization Files}.)
@item --no-sysinit
Don't load a system-wide initialization file. If this option is given,
@item --userinit @var{filename}
Load filename instead of the default user initialization file
-(@pxref{User Initialization File}.)
+(@pxref{Initialization Files}.)
@item --no-userinit
Don't load a user initialization file. If this option is given,
@item --eval @var{command}
After executing any initialization file, but before starting the
-read-eval-print loop on standard input, read and evaluate the com-
-mand given. More than one @code{--eval} option can be used, and all
-will be read and executed, in the order they appear on the command
-line.
+read-eval-print loop on standard input, read and evaluate the command
+given. More than one @code{--eval} option can be used, and all will be
+read and executed, in the order they appear on the command line.
@item --load @var{filename}
This is equivalent to @code{--eval '(load "@var{filename}")'}. The
@end table
-
@node Initialization Files
@comment node-name, next, previous, up
@section Initialization Files
-This section covers initialization files processed at startup, which
-can be used to customize the lisp environment.
-
-@menu
-* System Initialization File::
-* User Initialization File::
-* Initialization File Semantics::
-* Initialization Examples::
-@end menu
-
-@node System Initialization File
-@comment node-name, next, previous, up
-@subsection System Initialization File
-
-Site-wide startup script. Unless overridden with the command line
-option @code{--sysinit} defaults to @file{@env{SBCL_HOME}/sbclrc}, or
-if that doesn't exist to @file{/etc/sbclrc}.
-
-No system initialization file is required.
-
-@node User Initialization File
-@comment node-name, next, previous, up
-@subsection User Initialization File
-
-Per-user startup script. Unless overridden with the command line
-option @code{--userinit} defaults to @file{@env{HOME}/.sbclrc}.
-
-No user initialization file is required.
-
-@node Initialization File Semantics
-@comment node-name, next, previous, up
-@subsection Initialization File Semantics
-
SBCL processes initialization files with @code{read} and @code{eval},
not @code{load}; hence initialization files can be used to set startup
@code{*package*} and @code{*readtable*}, and for proclaiming a global
optimization policy.
-@node Initialization Examples
-@comment node-name, next, previous, up
-@subsection Initialization Examples
+@itemize @w{}
+@item
+@strong{System Initialization File}
-Some examples of what you may consider doing in the initialization
-files follow.
+Defaults to @file{@env{$SBCL_HOME}/sbclrc}, or if that doesn't exist to
+@file{/etc/sbclrc}. Can be overridden with the command line option
+@code{--sysinit} or @code{--no-sysinit}.
-@menu
-* Automatic Recompilation of Stale Fasls::
-@end menu
+The system initialization file is intended for system administrators
+and software packagers to configure locations of installed third party
+modules, etc.
-@node Automatic Recompilation of Stale Fasls
-@comment node-name, next, previous, up
-@subsubsection Automatic Recompilation of Stale Fasls
+@item
+@strong{User Initialization File}
-SBCL fasl-format is at current stage of development undergoing
-non-backwards compatible changes fairly often. The following snippet
-handles recompilation automatically for ASDF-based systems.
+Defaults to @file{@env{$HOME}/.sbclrc}. Can be overridden with the
+command line option @code{--userinit} or @code{--no-userinit}.
-@lisp
-(require :asdf)
-
-;;; If a fasl was stale, try to recompile and load (once).
-(defmethod asdf:perform :around ((o asdf:load-op)
- (c asdf:cl-source-file))
- (handler-case (call-next-method o c)
- ;; If a fasl was stale, try to recompile and load (once).
- (sb-ext:invalid-fasl ()
- (asdf:perform (make-instance 'asdf:compile-op) c)
- (call-next-method))))
-@end lisp
+The user initialization file is intended for personal customizations,
+such as loading certain modules at startup, defining convenience
+functions to use in the REPL, handling automatic recompilation
+of FASLs (@pxref{FASL Format}), etc.
+
+@end itemize
+
+Neither initialization file is required.
@node Initialization and Exit Hooks
@comment node-name, next, previous, up
@comment node-name, next, previous, up
@chapter Timers
-SBCL supports a system-wide scheduler implemented on top of
+SBCL supports a system-wide event scheduler implemented on top of
@code{setitimer} that also works with threads but does not require a
separate scheduler thread.
-@menu
-@end menu
+The following example schedules a timer that writes ``Hello, word'' after
+two seconds.
@lisp
(schedule-timer (make-timer (lambda ()
2)
@end lisp
+It should be noted that writing timer functions requires special care,
+as the dynamic environment in which they run is unpredictable: dynamic
+variable bindings, locks held, etc, all depend on whatever code was
+running when the timer fired. The following example should serve as
+a cautionary tale:
+
+@lisp
+(defvar *foo* nil)
+
+(defun show-foo ()
+ (format t "~&foo=~S~%" *foo*)
+ (force-output t))
+
+(defun demo ()
+ (schedule-timer (make-timer #'show-foo) 0.5)
+ (schedule-timer (make-timer #'show-foo) 1.5)
+ (let ((*foo* t))
+ (sleep 1.0))
+ (let ((*foo* :surprise!))
+ (sleep 2.0)))
+@end lisp
+
+@section Timer Dictionary
+
@include struct-sb-ext-timer.texinfo
@include fun-sb-ext-make-timer.texinfo
@include fun-sb-ext-timer-name.texinfo
(defun quit (&key recklessly-p (unix-status 0))
#!+sb-doc
- "Terminate the current Lisp. *EXIT-HOOKS* are pending unwind-protect
+ "Terminate the current Lisp. *EXIT-HOOKS* and pending unwind-protect
cleanup forms are run unless RECKLESSLY-P is true. On UNIX-like
systems, UNIX-STATUS is used as the status code."
(declare (type (signed-byte 32) unix-status))
;;; checkins which aren't released. (And occasionally for internal
;;; versions, especially for internal versions off the main CVS
;;; branch, it gets hairier, e.g. "0.pre7.14.flaky4.13".)
-"1.0.28.28"
+"1.0.28.29"
projects / sbcl.git / commitdiff