From 8852534331f5505348d1217a3080ee25e09ec47e Mon Sep 17 00:00:00 2001 From: Nikodemus Siivola Date: Fri, 8 May 2009 09:32:28 +0000 Subject: [PATCH] 1.0.28.29: some manual love Updates, light reorganization and a touch of prettification. Also warn about the dangers of dynamic environment as it pertains to timers. --- doc/manual/compiler.texinfo | 4 +- doc/manual/intro.texinfo | 82 +++++++++++++++++----------- doc/manual/start-stop.texinfo | 120 ++++++++++++++--------------------------- doc/manual/timers.texinfo | 30 +++++++++-- src/code/cold-init.lisp | 2 +- version.lisp-expr | 2 +- 6 files changed, 122 insertions(+), 118 deletions(-) diff --git a/doc/manual/compiler.texinfo b/doc/manual/compiler.texinfo index 2e0be37..a3cb00c 100644 --- a/doc/manual/compiler.texinfo +++ b/doc/manual/compiler.texinfo @@ -156,8 +156,8 @@ to the @code{sb-ext:compiler-note}, and is used for problems which are 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. diff --git a/doc/manual/intro.texinfo b/doc/manual/intro.texinfo index 26b1307..60b76a5 100644 --- a/doc/manual/intro.texinfo +++ b/doc/manual/intro.texinfo @@ -83,7 +83,8 @@ both TCP and UDP sockets. @xref{Networking}. @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 @@ -104,8 +105,8 @@ streams} API proposed by Franz Inc. @xref{Simple Streams}. 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 @@ -121,11 +122,7 @@ access functionality described in @cite{Common Lisp The Language, 2nd 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 @@ -161,6 +158,7 @@ implementation. @menu * Declarations:: +* FASL Format:: * Compiler-only Implementation:: * Defining Constants:: * Style Warnings:: @@ -175,6 +173,35 @@ principle, and its implications, and the bugs which still keep the 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 @@ -446,17 +473,15 @@ learn about Common Lisp, some books stand out: @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 @@ -465,20 +490,15 @@ guard against non-standard usages, and since it doesn't really even 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 diff --git a/doc/manual/start-stop.texinfo b/doc/manual/start-stop.texinfo index 1ec355a..cd07851 100644 --- a/doc/manual/start-stop.texinfo +++ b/doc/manual/start-stop.texinfo @@ -3,11 +3,11 @@ @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 @@ -15,9 +15,9 @@ @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 @@ -97,10 +97,10 @@ Hello, World! @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 @@ -184,8 +184,8 @@ passed on to the user program even if they was intended for the runtime system or the Lisp system. @menu -* Runtime Options:: -* Toplevel Options:: +* Runtime Options:: +* Toplevel Options:: @end menu @node Runtime Options @@ -255,7 +255,7 @@ chance to see it. @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, @@ -263,7 +263,7 @@ the @code{--sysinit} option is ignored. @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, @@ -271,10 +271,9 @@ the @code{--userinit} option is ignored. @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 @@ -307,80 +306,41 @@ shebang line, it is ignored. @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 diff --git a/doc/manual/timers.texinfo b/doc/manual/timers.texinfo index f4687e5..68215b0 100644 --- a/doc/manual/timers.texinfo +++ b/doc/manual/timers.texinfo @@ -2,12 +2,12 @@ @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 () @@ -16,6 +16,30 @@ separate scheduler thread. 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 diff --git a/src/code/cold-init.lisp b/src/code/cold-init.lisp index 370681d..d8c1160 100644 --- a/src/code/cold-init.lisp +++ b/src/code/cold-init.lisp @@ -276,7 +276,7 @@ (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)) diff --git a/version.lisp-expr b/version.lisp-expr index 31346a0..93bfa6f 100644 --- a/version.lisp-expr +++ b/version.lisp-expr @@ -17,4 +17,4 @@ ;;; 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" -- 1.7.10.4