master: doc: update generated texinfo files
melisgl via Sbcl-commits <[email protected]> Mon, 29 Jun 2026 12:19:38 +0000
| Newsgroups | gmane.lisp.steel-bank.cvs |
|---|---|
| Message-ID | <[email protected]> |
The branch "master" has been updated in SBCL:
via b3bfe0287674ebfa89203e94c52cd235f5c35839 (commit)
from 316291e3718890758a58882417d292dbd1c00942 (commit)
- Log -----------------------------------------------------------------
commit b3bfe0287674ebfa89203e94c52cd235f5c35839
Author: Gabor Melis <[email protected]>
Date: Sun Jun 7 19:21:11 2026 +0200
doc: update generated texinfo files
---
contrib/sb-aclrepl/sb-aclrepl.texinfo | 72 +-
contrib/sb-bsd-sockets/sb-bsd-sockets.texinfo | 444 ++-
contrib/sb-concurrency/sb-concurrency.texinfo | 373 ++-
contrib/sb-cover/sb-cover.texinfo | 108 +-
contrib/sb-grovel/sb-grovel.texinfo | 303 +-
contrib/sb-introspect/sb-introspect.texinfo | 388 ++-
contrib/sb-md5/sb-md5.texinfo | 61 +-
contrib/sb-posix/sb-posix.texinfo | 411 ++-
contrib/sb-queue/sb-queue.texinfo | 8 +-
contrib/sb-rotate-byte/sb-rotate-byte.texinfo | 28 +-
.../sb-simple-streams/sb-simple-streams.texinfo | 22 +-
contrib/sb-sprof/sb-sprof.texinfo | 296 +-
doc/manual/.gitignore | 1 +
doc/manual/README | 5 +-
doc/manual/beyond-ansi.texinfo | 3318 +++++++++++++-------
doc/manual/compiler.texinfo | 1143 +++----
doc/manual/contrib-modules.texinfo | 313 +-
doc/manual/debugger.texinfo | 1435 ++++-----
doc/manual/deprecation.texinfo | 574 ++--
doc/manual/efficiency.texinfo | 517 ++-
doc/manual/external-formats.texinfo | 314 +-
doc/manual/ffi.texinfo | 1520 +++++----
doc/manual/gray-streams-examples.texinfo | 223 --
doc/manual/intro.texinfo | 755 ++---
doc/manual/package-locks.texinfo | 443 +--
doc/manual/pathnames.texinfo | 230 +-
doc/manual/profiling.texinfo | 78 +-
doc/manual/start-stop.texinfo | 688 ++--
doc/manual/streams.texinfo | 646 +++-
doc/manual/support-and-bugs.texinfo | 127 +-
doc/manual/threading.texinfo | 1172 +++++--
doc/manual/timers.texinfo | 95 +-
32 files changed, 9802 insertions(+), 6309 deletions(-)
diff --git a/contrib/sb-aclrepl/sb-aclrepl.texinfo b/contrib/sb-aclrepl/sb-aclrepl.texinfo
index 9dc4204f5..81f4a343f 100644
--- a/contrib/sb-aclrepl/sb-aclrepl.texinfo
+++ b/contrib/sb-aclrepl/sb-aclrepl.texinfo
@@ -1,39 +1,68 @@
-@node sb-aclrepl
+@c Generated by the sb-manual contrib. Do not edit.
+
+@node sb aclrepl
@section sb-aclrepl
-@cindex Read-Eval-Print Loop
-@cindex REPL
-@c FIXME: I wanted to use @registeredsymbol{}, but that's
-@c only available in Texinfo 4.7. sigh.
+@menu
+* Usage: sb aclrepl usage.
+* Customization: sb aclrepl customization.
+* Example Initialization: sb aclrepl example initialization.
+@end menu
+
The @code{sb-aclrepl} module offers an Allegro CL-style
-Read-Eval-Print Loop for SBCL, with integrated inspector. Adding a
+Read-Eval-Print Loop for SBCL, with integrated inspector. Adding a
debugger interface is planned.
+Allegro CL is a registered trademark of Franz Inc.
+
+@node sb aclrepl usage
@subsection Usage
To start @code{sb-aclrepl} as your read-eval-print loop, put the form
-@lisp
+
+@example
(require 'sb-aclrepl)
-@end lisp
+@end example
-in your @file{~/.sbclrc} initialization file.
+in your @code{~/.sbclrc}, one of your @ref{initialization files}.
+@node sb aclrepl customization
@subsection Customization
The following customization variables are available:
-@include var-sb-aclrepl-star-command-char-star.texinfo
-@include var-sb-aclrepl-star-prompt-star.texinfo
-@include var-sb-aclrepl-star-exit-on-eof-star.texinfo
-@include var-sb-aclrepl-star-use-short-package-name-star.texinfo
-@include var-sb-aclrepl-star-max-history-star.texinfo
-
+@anchor{Variable sb-aclrepl *command-char*}
+@vvindex @sortas{command-char* sb-aclrepl} *command-char* [sb-aclrepl]
+@deffn{Variable} sb-aclrepl:*command-char*
+Prefix character for a top-level command
+@end deffn
+@anchor{Variable sb-aclrepl *prompt*}
+@vvindex @sortas{prompt* sb-aclrepl} *prompt* [sb-aclrepl]
+@deffn{Variable} sb-aclrepl:*prompt*
+The current prompt string or formatter function.
+@end deffn
+@anchor{Variable sb-aclrepl *exit-on-eof*}
+@vvindex @sortas{exit-on-eof* sb-aclrepl} *exit-on-eof* [sb-aclrepl]
+@deffn{Variable} sb-aclrepl:*exit-on-eof*
+If @code{t}, then exit when the EOF character is entered.
+@end deffn
+@anchor{Variable sb-aclrepl *use-short-package-name*}
+@vvindex @sortas{use-short-package-name* sb-aclrepl} *use-short-package-name* [sb-aclrepl]
+@deffn{Variable} sb-aclrepl:*use-short-package-name*
+When @code{t}, use the shortnest package nickname in a prompt
+@end deffn
+@anchor{Variable sb-aclrepl *max-history*}
+@vvindex @sortas{max-history* sb-aclrepl} *max-history* [sb-aclrepl]
+@deffn{Variable} sb-aclrepl:*max-history*
+Maximum number of history commands to remember
+@end deffn
+@node sb aclrepl example initialization
@subsection Example Initialization
-Here's a longer example of a @file{~/.sbclrc} file that shows off
-some of the features of @code{sb-aclrepl}:
+Here's a longer example of a @code{~/.sbclrc} file that shows off
+some of the features of sb-aclrepl:
-@lisp
+@example
(ignore-errors (require 'sb-aclrepl))
(when (find-package 'sb-aclrepl)
@@ -51,11 +80,8 @@ some of the features of @code{sb-aclrepl}:
;; such as ":r base64"
(sb-aclrepl:alias ("require" 0 "Require module") (sys) (require sys))
(setq cl:*features* (delete :aclrepl cl:*features*)))
-@end lisp
+@end example
Questions, comments, or bug reports should be sent to Kevin Rosenberg
-(@email{kevin@@rosenberg.net}).
+(kevin@@rosenberg.net).
-@subsection Credits
-
-Allegro CL is a registered trademark of Franz Inc.
diff --git a/contrib/sb-bsd-sockets/sb-bsd-sockets.texinfo b/contrib/sb-bsd-sockets/sb-bsd-sockets.texinfo
index dcbd61012..be0d46176 100644
--- a/contrib/sb-bsd-sockets/sb-bsd-sockets.texinfo
+++ b/contrib/sb-bsd-sockets/sb-bsd-sockets.texinfo
@@ -1,192 +1,368 @@
-@node Networking
-@comment node-name, next, previous, up
+@c Generated by the sb-manual contrib. Do not edit.
+
+@node networking
@chapter Networking
-@cindex Sockets, Networking
+
+@menu
+* Sockets Overview: sockets overview.
+* General Sockets: general sockets.
+* Socket Options: socket options.
+* INET Domain Sockets: inet domain sockets.
+* Local Domain Sockets: local domain sockets.
+* Name Service: name service.
+@end menu
The @code{sb-bsd-sockets} module provides a thinly disguised BSD
socket API for SBCL. Ideas have been stolen from the BSD socket API
-for C and Graham Barr's IO::Socket classes for Perl.
+for C and Graham Barr's @code{IO::Socket} classes for Perl.
Sockets are represented as CLOS objects, and the API naming
-conventions attempt to balance between the BSD names and good lisp style.
+conventions attempt to balance between the BSD names and good lisp
+style.
-@menu
-* Sockets Overview::
-* General Sockets:: Methods applicable to all sockets
-* Socket Options::
-* INET Domain Sockets::
-* Local (Unix) Domain Sockets::
-* Name Service::
-@end menu
-
-@node Sockets Overview
+@node sockets overview
@section Sockets Overview
-Most of the functions are modelled on the BSD socket API. BSD sockets
-are widely supported, portably @emph{(``portable'' by Unix standards, at least)}
-available on a variety of systems, and documented. There are some
+Most of the functions are modelled on the BSD socket API. BSD sockets
+are widely supported, portably (by Unix standards, at least)
+available on a variety of systems, and documented. There are some
differences in approach where we have taken advantage of some of the
-more useful features of Common Lisp - briefly:
+more useful features of Common Lisp -- briefly:
@itemize
+@item Where the C API would typically return -1 and set @code{errno},
+ @code{sb-bsd-sockets} signals an error. All the errors are subclasses
+ of @code{sb-bsd-sockets:socket-error} and generally correspond one for
+ one with possible @code{errno} values.
-@item
-Where the C API would typically return -1 and set @code{errno},
-@code{sb-bsd-sockets} signals an error. All the errors are subclasses
-of @code{sb-bsd-sockets:socket-condition} and generally correspond one
-for one with possible @code{errno} values.
+@item We use multiple return values in many places where the C API would
+ use pass-by-reference values.
-@item
-We use multiple return values in many places where the C API would use
-pass-by-reference values.
-
-@item
-We can often avoid supplying an explicit @emph{length} argument to
-functions because we already know how long the argument is.
-
-@item
-IP addresses and ports are represented in slightly friendlier fashion
-than "network-endian integers".
+@item We can often avoid supplying an explicit length argument to
+ functions because we already know how long the argument is.
+@item IP addresses and ports are represented in slightly friendlier
+ fashion than "network-endian integers".
@end itemize
-@node General Sockets
+@node general sockets
@section General Sockets
-@include class-sb-bsd-sockets-socket.texinfo
+@anchor{Class sb-bsd-sockets socket}
+@ttindex @sortas{socket sb-bsd-sockets} socket [sb-bsd-sockets]
+@deffn{Class} sb-bsd-sockets:socket
+Common superclass of all sockets, not meant to be
+directly instantiated.
+@end deffn
+@anchor{Function sb-bsd-sockets socket-bind}
+@ffindex @sortas{socket-bind sb-bsd-sockets} socket-bind [sb-bsd-sockets]
+@deffn{Function} sb-bsd-sockets:socket-bind socket &rest address
+Bind @code{socket} to @code{address}, which may vary according to socket family.
+For the INET family, pass @code{address} and @code{port} as two arguments; for local
+address family sockets, pass the filename string. See also @code{bind(2)}.
+@end deffn
+@anchor{Function sb-bsd-sockets socket-accept}
+@ffindex @sortas{socket-accept sb-bsd-sockets} socket-accept [sb-bsd-sockets]
+@deffn{Function} sb-bsd-sockets:socket-accept socket
+Perform the @code{accept(2)} call, returning a newly-created connected
+socket and the peer address as multiple values
+@end deffn
+@anchor{Function sb-bsd-sockets socket-connect}
+@ffindex @sortas{socket-connect sb-bsd-sockets} socket-connect [sb-bsd-sockets]
+@deffn{Function} sb-bsd-sockets:socket-connect socket &rest address
+Perform the @code{connect(2)} call to connect @code{socket} to a remote @code{peer}.
+No useful return value.
+@end deffn
+@anchor{Function sb-bsd-sockets socket-peername}
+@ffindex @sortas{socket-peername sb-bsd-sockets} socket-peername [sb-bsd-sockets]
+@deffn{Function} sb-bsd-sockets:socket-peername socket
+Return @code{socket}'s peer; depending on the address family this may
+return multiple values
+@end deffn
+@anchor{Function sb-bsd-sockets socket-name}
+@ffindex @sortas{socket-name sb-bsd-sockets} socket-name [sb-bsd-sockets]
+@deffn{Function} sb-bsd-sockets:socket-name socket
+Return the address (as vector of bytes) and port that @code{socket} is
+bound to, as multiple values.
+@end deffn
+@anchor{Function sb-bsd-sockets socket-receive}
+@ffindex @sortas{socket-receive sb-bsd-sockets} socket-receive [sb-bsd-sockets]
+@deffn{Function} sb-bsd-sockets:socket-receive socket buffer length &key oob peek waitall dontwait element-type
+Read @code{length} octets from @code{socket} into @code{buffer} (or a freshly-consed
+buffer if @code{nil}), using @code{recvfrom(2)}. If @code{length} is @code{nil}, the length of
+@code{buffer} is used, so at least one of these two arguments must be
+non-@code{nil}. If @code{buffer} is supplied, it had better be of an element type
+one octet wide. Returns the buffer, its length, and the address of the
+peer that sent it, as multiple values. On datagram sockets, sets
+@code{MSG_TRUNC} so that the actual packet length is returned even if
+the buffer was too small.
+@end deffn
+@anchor{Function sb-bsd-sockets socket-send}
+@ffindex @sortas{socket-send sb-bsd-sockets} socket-send [sb-bsd-sockets]
+@deffn{Function} sb-bsd-sockets:socket-send socket buffer length &key address external-format oob eor dontroute dontwait nosignal confirm more
+Send @code{length} octets from @code{buffer} into @code{socket}, using @code{sendto(2)}. If
+@code{buffer} is a string, it will converted to octets according to
+@code{external-format}. If @code{length} is @code{nil}, the length of the octet buffer is
+used. The format of @code{address} depends on the socket type (for example
+for INET domain sockets it would be a list of an IP address and a
+port). If no socket address is provided, @code{send(2)} will be called
+instead. Returns the number of octets written.
+@end deffn
+@anchor{Function sb-bsd-sockets socket-listen}
+@ffindex @sortas{socket-listen sb-bsd-sockets} socket-listen [sb-bsd-sockets]
+@deffn{Function} sb-bsd-sockets:socket-listen socket backlog
+Mark @code{socket} as willing to accept incoming connections. The
+integer @code{backlog} defines the maximum length that the queue of pending
+connections may grow to before new connection attempts are refused.
+See also @code{listen(2)}.
+@end deffn
+@anchor{Function sb-bsd-sockets socket-open-p}
+@ffindex @sortas{socket-open-p sb-bsd-sockets} socket-open-p [sb-bsd-sockets]
+@deffn{Function} sb-bsd-sockets:socket-open-p socket
+Return true if @code{socket} is open; otherwise, return false.
+@end deffn
+@anchor{Function sb-bsd-sockets socket-close}
+@ffindex @sortas{socket-close sb-bsd-sockets} socket-close [sb-bsd-sockets]
+@deffn{Function} sb-bsd-sockets:socket-close socket &key abort
+Close @code{socket}, unless it was already closed.
-@include fun-sb-bsd-sockets-socket-bind.texinfo
+If @code{socket-make-stream} has been called, calls @code{close} using @code{abort} on that
+stream. Otherwise closes the socket file descriptor using @code{close(2)}.
+@end deffn
+@anchor{Function sb-bsd-sockets socket-shutdown}
+@ffindex @sortas{socket-shutdown sb-bsd-sockets} socket-shutdown [sb-bsd-sockets]
+@deffn{Function} sb-bsd-sockets:socket-shutdown socket &key direction
+Indicate that no communication in @code{direction} will be performed on
+@code{socket}.
-@include fun-sb-bsd-sockets-socket-accept.texinfo
+@code{direction} has to be one of @code{:input}, @code{:output} or @code{:io}.
-@include fun-sb-bsd-sockets-socket-connect.texinfo
+After a shutdown, no input and/or output of the indicated @code{direction}
+can be performed on @code{socket}.
+@end deffn
+@anchor{Function sb-bsd-sockets socket-make-stream}
+@ffindex @sortas{socket-make-stream sb-bsd-sockets} socket-make-stream [sb-bsd-sockets]
+@deffn{Function} sb-bsd-sockets:socket-make-stream socket &key input output element-type external-format buffering timeout auto-close serve-events
+Find or create a @code{stream} that can be used for IO on @code{socket} (which
+must be connected). Specify whether the stream is for @code{input}, @code{output},
+or both (it is an error to specify neither).
-@include fun-sb-bsd-sockets-socket-peername.texinfo
+@code{element-type} and @code{external-format} are as per @code{open}.
-@include fun-sb-bsd-sockets-socket-name.texinfo
+@code{timeout} specifies a read timeout for the stream.
+@end deffn
+@anchor{Function sb-bsd-sockets socket-error}
+@ffindex @sortas{socket-error sb-bsd-sockets} socket-error [sb-bsd-sockets]
+@deffn{Function} sb-bsd-sockets:socket-error where &optional errno
+Signal an appropriate error for syscall @code{where} and @code{errno}.
-@include fun-sb-bsd-sockets-socket-receive.texinfo
+@code{where} should be a string naming the failed function.
-@include fun-sb-bsd-sockets-socket-send.texinfo
-
-@include fun-sb-bsd-sockets-socket-listen.texinfo
-
-@include fun-sb-bsd-sockets-socket-open-p.texinfo
-
-@include fun-sb-bsd-sockets-socket-close.texinfo
-
-@include fun-sb-bsd-sockets-socket-shutdown.texinfo
-
-@include fun-sb-bsd-sockets-socket-make-stream.texinfo
-
-@include fun-sb-bsd-sockets-socket-error.texinfo
-
-@include fun-sb-bsd-sockets-non-blocking-mode.texinfo
-
-@node Socket Options
+When supplied, @code{errno} should be the UNIX error number associated to the
+failed call. The default behavior is to use the current value of the
+errno variable.
+@end deffn
+@anchor{Function sb-bsd-sockets non-blocking-mode}
+@ffindex @sortas{non-blocking-mode sb-bsd-sockets} non-blocking-mode [sb-bsd-sockets]
+@deffn{Function} sb-bsd-sockets:non-blocking-mode socket
+Is @code{socket} in non-blocking mode?
+@end deffn
+@node socket options
@section Socket Options
A subset of socket options are supported, using a fairly general
-framework which should make it simple to add more as required - see
-@file{SYS:CONTRIB;SB-BSD-SOCKETS:SOCKOPT.LISP} for details. The name
+framework which should make it simple to add more as required -- see
+@code{SYS:CONTRIB;SB-BSD-SOCKETS:SOCKOPT.LISP} for details. The name
mapping from C is fairly straightforward: @code{SO_RCVLOWAT} becomes
-@code{sockopt-receive-low-water} and @code{(setf
-sockopt-receive-low-water)}.
-
-@include fun-sb-bsd-sockets-sockopt-reuse-address.texinfo
-
-@include fun-sb-bsd-sockets-sockopt-keep-alive.texinfo
-
-@include fun-sb-bsd-sockets-sockopt-oob-inline.texinfo
-
-@include fun-sb-bsd-sockets-sockopt-bsd-compatible.texinfo
-
-@include fun-sb-bsd-sockets-sockopt-pass-credentials.texinfo
-
-@include fun-sb-bsd-sockets-sockopt-debug.texinfo
-
-@include fun-sb-bsd-sockets-sockopt-dont-route.texinfo
-
-@include fun-sb-bsd-sockets-sockopt-broadcast.texinfo
-
-@include fun-sb-bsd-sockets-sockopt-tcp-nodelay.texinfo
-
-@node INET Domain Sockets
+@code{sb-bsd-sockets:sockopt-receive-low-water} and @code{(setf
+sb-bsd-sockets:sockopt-receive-low-water)}.
+
+@anchor{Function sb-bsd-sockets sockopt-reuse-address}
+@ffindex @sortas{sockopt-reuse-address sb-bsd-sockets} sockopt-reuse-address [sb-bsd-sockets]
+@deffn{Function} sb-bsd-sockets:sockopt-reuse-address socket
+Return the value of the SO-REUSEADDR socket option for @code{socket}. This can also be
+updated with @code{setf}.
+@end deffn
+@anchor{Function sb-bsd-sockets sockopt-keep-alive}
+@ffindex @sortas{sockopt-keep-alive sb-bsd-sockets} sockopt-keep-alive [sb-bsd-sockets]
+@deffn{Function} sb-bsd-sockets:sockopt-keep-alive socket
+Return the value of the SO-KEEPALIVE socket option for @code{socket}. This can also be
+updated with @code{setf}.
+@end deffn
+@anchor{Function sb-bsd-sockets sockopt-oob-inline}
+@ffindex @sortas{sockopt-oob-inline sb-bsd-sockets} sockopt-oob-inline [sb-bsd-sockets]
+@deffn{Function} sb-bsd-sockets:sockopt-oob-inline socket
+Return the value of the SO-OOBINLINE socket option for @code{socket}. This can also be
+updated with @code{setf}.
+@end deffn
+@anchor{Function sb-bsd-sockets sockopt-bsd-compatible}
+@ffindex @sortas{sockopt-bsd-compatible sb-bsd-sockets} sockopt-bsd-compatible [sb-bsd-sockets]
+@deffn{Function} sb-bsd-sockets:sockopt-bsd-compatible socket
+Return the value of the SO-BSDCOMPAT socket option for @code{socket}. This can also be
+updated with @code{setf}. Available only on Linux.
+@end deffn
+@anchor{Function sb-bsd-sockets sockopt-pass-credentials}
+@ffindex @sortas{sockopt-pass-credentials sb-bsd-sockets} sockopt-pass-credentials [sb-bsd-sockets]
+@deffn{Function} sb-bsd-sockets:sockopt-pass-credentials socket
+Return the value of the SO-PASSCRED socket option for @code{socket}. This can also be
+updated with @code{setf}. Available only on Linux.
+@end deffn
+@anchor{Function sb-bsd-sockets sockopt-debug}
+@ffindex @sortas{sockopt-debug sb-bsd-sockets} sockopt-debug [sb-bsd-sockets]
+@deffn{Function} sb-bsd-sockets:sockopt-debug socket
+Return the value of the SO-DEBUG socket option for @code{socket}. This can also be
+updated with @code{setf}.
+@end deffn
+@anchor{Function sb-bsd-sockets sockopt-dont-route}
+@ffindex @sortas{sockopt-dont-route sb-bsd-sockets} sockopt-dont-route [sb-bsd-sockets]
+@deffn{Function} sb-bsd-sockets:sockopt-dont-route socket
+Return the value of the SO-DONTROUTE socket option for @code{socket}. This can also be
+updated with @code{setf}.
+@end deffn
+@anchor{Function sb-bsd-sockets sockopt-broadcast}
+@ffindex @sortas{sockopt-broadcast sb-bsd-sockets} sockopt-broadcast [sb-bsd-sockets]
+@deffn{Function} sb-bsd-sockets:sockopt-broadcast socket
+Return the value of the SO-BROADCAST socket option for @code{socket}. This can also be
+updated with @code{setf}.
+@end deffn
+@anchor{Function sb-bsd-sockets sockopt-tcp-nodelay}
+@ffindex @sortas{sockopt-tcp-nodelay sb-bsd-sockets} sockopt-tcp-nodelay [sb-bsd-sockets]
+@deffn{Function} sb-bsd-sockets:sockopt-tcp-nodelay socket
+Return the value of the TCP-NODELAY socket option for @code{socket}. This can also be
+updated with @code{setf}.
+@end deffn
+@node inet domain sockets
@section INET Domain Sockets
The TCP and UDP sockets that you know and love. Some representation
issues:
@itemize
-
-@item
-IPv4 Internet addresses are represented by vectors of
-@code{(unsigned-byte 8)} - viz. @code{#(127 0 0 1)}. Ports are just
-integers: 6010. No conversion between network- and host-order data is
-needed from the user of this package.
-
-@item
-IPv6 Internet addresses are represented by vectors of 16
-@code{(unsigned-byte 8)} - viz. @code{#(0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
-1)}. Ports are just integers. As for IPv4 addresses, no conversion
-between network- and host-order data is needed from the user of this
-package.
-
-@item
-Socket addresses are represented by the two values for address and port,
-so for example, @code{(socket-connect socket #(192 168 1 1) 80)} for
-IPv4 and @code{(socket-connect socket #(0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1)
-80)} for IPv6.
-
+@item IPv4 Internet addresses are represented by vectors of
+ @code{(unsigned-byte 8)} (e.g. @code{#(127 0 0 1)}). Ports are just
+ integers. No conversion between network- and host-order data is
+ needed from the user of this package.
+
+@item IPv6 Internet addresses are represented by length 16 vectors of
+ @code{(unsigned-byte 8)} (e.g. @code{#(0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1)}.
+ Ports are just integers. As for IPv4 addresses, no conversion
+ between network- and host-order data is needed from the user of
+ this package.
+
+@item Socket addresses are represented by the two values for address and
+ port, so for example, @code{(sb-bsd-sockets:socket-connect socket #(192
+ 168 1 1) 80)} for IPv4 and @code{(sb-bsd-sockets:socket-connect socket
+ #(0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1) 80)} for IPv6.
@end itemize
-@include class-sb-bsd-sockets-inet-socket.texinfo
+@anchor{Class sb-bsd-sockets inet-socket}
+@ttindex @sortas{inet-socket sb-bsd-sockets} inet-socket [sb-bsd-sockets]
+@deffn{Class} sb-bsd-sockets:inet-socket
+Class representing TCP and UDP over IPv4 sockets.
-@include class-sb-bsd-sockets-inet6-socket.texinfo
+Examples:
-@include fun-sb-bsd-sockets-make-inet-address.texinfo
+@example
+(make-instance 'sb-bsd-sockets:inet-socket :type :stream :protocol :tcp)
-@include fun-sb-bsd-sockets-make-inet6-address.texinfo
+(make-instance 'sb-bsd-sockets:inet-socket :type :datagram :protocol :udp)
+@end example
+@end deffn
+@anchor{Class sb-bsd-sockets inet6-socket}
+@ttindex @sortas{inet6-socket sb-bsd-sockets} inet6-socket [sb-bsd-sockets]
+@deffn{Class} sb-bsd-sockets:inet6-socket
+Class representing TCP and UDP over IPv6 sockets.
-@include fun-sb-bsd-sockets-get-protocol-by-name.texinfo
+Examples:
-@node Local (Unix) Domain Sockets
-@section Local (Unix) Domain Sockets
+@example
+(make-instance 'sb-bsd-sockets:inet6-socket :type :stream :protocol :tcp)
+
+(make-instance 'sb-bsd-sockets:inet6-socket :type :datagram :protocol :udp)
+@end example
+@end deffn
+@anchor{Function sb-bsd-sockets make-inet-address}
+@ffindex @sortas{make-inet-address sb-bsd-sockets} make-inet-address [sb-bsd-sockets]
+@deffn{Function} sb-bsd-sockets:make-inet-address dotted-quads
+Return a vector of octets given a string @code{dotted-quads} in the format
+"127.0.0.1". Signals an error if the string is malformed.
+@end deffn
+@anchor{Function sb-bsd-sockets make-inet6-address}
+@ffindex @sortas{make-inet6-address sb-bsd-sockets} make-inet6-address [sb-bsd-sockets]
+@deffn{Function} sb-bsd-sockets:make-inet6-address colon-separated-integers
+Return a vector of octets given a string representation of an IPv6
+address @code{colon-separated-integers}. Signal an error if the string is
+malformed.
+@end deffn
+@anchor{Function sb-bsd-sockets get-protocol-by-name}
+@ffindex @sortas{get-protocol-by-name sb-bsd-sockets} get-protocol-by-name [sb-bsd-sockets]
+@deffn{Function} sb-bsd-sockets:get-protocol-by-name name
+Given a protocol name, return the protocol number, the protocol name, and
+a list of protocol aliases.
+@end deffn
+@node local domain sockets
+@section Local Domain Sockets
Local domain (@code{AF_LOCAL}) sockets are also known as Unix-domain
-sockets, but were renamed by POSIX presumably on the basis that they
+sockets but were renamed by POSIX presumably on the basis that they
may be available on other systems too.
-A local socket address is a string, which is used to create a node in
-the local filesystem. This means of course that they cannot be used
-across a network.
-
-@include class-sb-bsd-sockets-local-socket.texinfo
+A local socket address is a string, which is used to create a node
+in the local filesystem. This means of course that they cannot be
+used across a network.
+@anchor{Class sb-bsd-sockets local-socket}
+@ttindex @sortas{local-socket sb-bsd-sockets} local-socket [sb-bsd-sockets]
+@deffn{Class} sb-bsd-sockets:local-socket
+Class representing local domain (@code{AF_LOCAL}) sockets,
+also known as Unix-domain sockets.
+@end deffn
A local abstract socket address is also a string the scope of which is
the local machine. However, in contrast to a local socket address, there
is no corresponding filesystem node.
-@include class-sb-bsd-sockets-local-abstract-socket.texinfo
-
-@node Name Service
+@anchor{Class sb-bsd-sockets local-abstract-socket}
+@ttindex @sortas{local-abstract-socket sb-bsd-sockets} local-abstract-socket [sb-bsd-sockets]
+@deffn{Class} sb-bsd-sockets:local-abstract-socket
+Class representing local domain (@code{AF_LOCAL}) sockets with
+addresses in the abstract namespace.
+@end deffn
+@node name service
@section Name Service
Presently name service is implemented by calling out to the
-@code{getaddrinfo(3)} and @code{gethostinfo(3)}, or to
-@code{gethostbyname(3)} @code{gethostbyaddr(3)} on platforms where
-the preferred functions are not available. The exact details of
-the name resolving process (for example the choice of whether
-DNS or a hosts file is used for lookup) are platform dependent.
+@code{getaddrinfo(3)} and @code{gethostinfo(3)}, or to @code{gethostbyname(3)} and
+@code{gethostbyaddr(3)} on platforms where the preferred functions are
+not available. The exact details of the name resolving process (for
+example the choice of whether DNS or a hosts file is used for
+lookup) are platform dependent.
-@c Direct links to the asynchronous @code{resolver(3)} routines would be
-@c nice to have eventually, so that we can do DNS lookups in parallel
-@c with other things.
+@anchor{Class sb-bsd-sockets host-ent}
+@ttindex @sortas{host-ent sb-bsd-sockets} host-ent [sb-bsd-sockets]
+@deffn{Class} sb-bsd-sockets:host-ent
+This class represents the results of an address lookup.
+@end deffn
+@anchor{Function sb-bsd-sockets get-host-by-name}
+@ffindex @sortas{get-host-by-name sb-bsd-sockets} get-host-by-name [sb-bsd-sockets]
+@deffn{Function} sb-bsd-sockets:get-host-by-name host-name
+Returns a @code{host-ent} instance for @code{host-name} or signals a @code{name-service-error}.
-@include class-sb-bsd-sockets-host-ent.texinfo
+Another @code{host-ent} instance containing zero, one or more IPv6 addresses
+may be returned as a second return value.
-@include fun-sb-bsd-sockets-get-host-by-name.texinfo
-
-@include fun-sb-bsd-sockets-get-host-by-address.texinfo
-
-@include fun-sb-bsd-sockets-host-ent-address.texinfo
+@code{host-name} may also be an IP address in dotted quad notation or some other
+weird stuff - see getaddrinfo(3) for the details.
+@end deffn
+@anchor{Function sb-bsd-sockets get-host-by-address}
+@ffindex @sortas{get-host-by-address sb-bsd-sockets} get-host-by-address [sb-bsd-sockets]
+@deffn{Function} sb-bsd-sockets:get-host-by-address address
+Returns a @code{host-ent} instance for @code{address}, which should be a vector of
+(integer 0 255) with 4 elements in case of an IPv4 address and 16
+elements in case of an IPv6 address, or signals a @code{name-service-error}.
+See gethostbyaddr(3) for details.
+@end deffn
+@anchor{Function sb-bsd-sockets host-ent-address}
+@ffindex @sortas{host-ent-address sb-bsd-sockets} host-ent-address [sb-bsd-sockets]
+@deffn{Function} sb-bsd-sockets:host-ent-address host-ent
+Return some valid address for @code{host-ent}.
+@end deffn
diff --git a/contrib/sb-concurrency/sb-concurrency.texinfo b/contrib/sb-concurrency/sb-concurrency.texinfo
index 8aee59a51..7eab1f503 100644
--- a/contrib/sb-concurrency/sb-concurrency.texinfo
+++ b/contrib/sb-concurrency/sb-concurrency.texinfo
@@ -1,95 +1,336 @@
-@node sb-concurrency
+@c Generated by the sb-manual contrib. Do not edit.
+
+@node sb concurrency
@section sb-concurrency
-@cindex Concurrency
-@cindex Sb-concurrency
+
+@menu
+* Queue: sb concurrency queue.
+* Mailbox (lock-free): sb concurrency mailbox.
+* Gates: sb concurrency gates.
+* Frlocks, aka Fast Read Locks: sb concurrency frlocks.
+@end menu
Additional data structures, synchronization primitives and tools for
concurrent programming. Similiar to Java's @code{java.util.concurrent}
package.
-@page
-@anchor{Section sb-concurrency:queue}
+@node sb concurrency queue
@subsection Queue
-@cindex Queue, lock-free
@code{sb-concurrency:queue} is a lock-free, thread-safe FIFO queue
datatype.
-@*@*
-The implementation is based on @cite{An Optimistic Approach to
-Lock-Free FIFO Queues} by Edya Ladan-Mozes and Nir Shavit.
-@*@*
+
+The implementation is based on @emph{An Optimistic Approach to Lock-Free
+FIFO Queues} by Edya Ladan-Mozes and Nir Shavit.
+
Before SBCL 1.0.38, this implementation resided in its own contrib
-(@pxref{sb-queue}) which is still provided for backwards-compatibility
-but which has since been deprecated.
+(see @ref{sb queue}), which is still provided for
+backwards-compatibility, but which has since been deprecated.
-@include struct-sb-concurrency-queue.texinfo
+@anchor{Structure sb-concurrency queue}
+@ttindex @sortas{queue sb-concurrency} queue [sb-concurrency]
+@deffn{Structure} sb-concurrency:queue
+Lock-free thread safe FIFO queue.
-@include fun-sb-concurrency-dequeue.texinfo
-@include fun-sb-concurrency-enqueue.texinfo
-@include fun-sb-concurrency-list-queue-contents.texinfo
-@include fun-sb-concurrency-make-queue.texinfo
-@include fun-sb-concurrency-queue-count.texinfo
-@include fun-sb-concurrency-queue-empty-p.texinfo
-@include fun-sb-concurrency-queue-name.texinfo
-@include fun-sb-concurrency-queuep.texinfo
-
-@page
+Use @code{enqueue} to add objects to the queue, and @code{dequeue} to remove them.
+@end deffn
+@anchor{Function sb-concurrency dequeue}
+@ffindex @sortas{dequeue sb-concurrency} dequeue [sb-concurrency]
+@deffn{Function} sb-concurrency:dequeue queue
+Retrieves the oldest value in @code{queue} and returns it as the primary value,
+and @code{t} as secondary value. If the queue is empty, returns @code{nil} as both primary
+and secondary value.
+@end deffn
+@anchor{Function sb-concurrency enqueue}
+@ffindex @sortas{enqueue sb-concurrency} enqueue [sb-concurrency]
+@deffn{Function} sb-concurrency:enqueue value queue
+Adds @code{value} to the end of @code{queue}. Returns @code{value}.
+@end deffn
+@anchor{Function sb-concurrency list-queue-contents}
+@ffindex @sortas{list-queue-contents sb-concurrency} list-queue-contents [sb-concurrency]
+@deffn{Function} sb-concurrency:list-queue-contents queue
+Returns the contents of @code{queue} as a list without removing them from the
+@code{queue}. Mainly useful for manual examination of queue state, as the list may be
+out of date by the time it is returned, and concurrent dequeue operations may
+in the worse case force the queue-traversal to be restarted several times.
+@end deffn
+@anchor{Function sb-concurrency make-queue}
+@ffindex @sortas{make-queue sb-concurrency} make-queue [sb-concurrency]
+@deffn{Function} sb-concurrency:make-queue &key name initial-contents
+Returns a new @code{queue} with @code{name} and contents of the @code{initial-contents}
+sequence enqueued.
+@end deffn
+@anchor{Function sb-concurrency queue-count}
+@ffindex @sortas{queue-count sb-concurrency} queue-count [sb-concurrency]
+@deffn{Function} sb-concurrency:queue-count queue
+Returns the number of objects in @code{queue}. Mainly useful for manual
+examination of queue state, and in @code{print-object} methods: inefficient as it
+must walk the entire queue.
+@end deffn
+@anchor{Function sb-concurrency queue-empty-p}
+@ffindex @sortas{queue-empty-p sb-concurrency} queue-empty-p [sb-concurrency]
+@deffn{Function} sb-concurrency:queue-empty-p queue
+Returns @code{t} if @code{queue} is empty, @code{nil} otherwise.
+@end deffn
+@anchor{Function sb-concurrency queue-name}
+@ffindex @sortas{queue-name sb-concurrency} queue-name [sb-concurrency]
+@deffn{Function} sb-concurrency:queue-name instance
+Name of a @code{queue}. Can be assigned to using @code{setf}. Queue names
+can be arbitrary printable objects, and need not be unique.
+@end deffn
+@anchor{Function sb-concurrency queuep}
+@ffindex @sortas{queuep sb-concurrency} queuep [sb-concurrency]
+@deffn{Function} sb-concurrency:queuep object
+Returns true if argument is a @code{queue}, @code{nil} otherwise.
+@end deffn
+@node sb concurrency mailbox
@subsection Mailbox (lock-free)
-@cindex Mailbox, lock-free
-@code{sb-concurrency:mailbox} is a lock-free message queue where one
-or multiple ends can send messages to one or multiple receivers. The
-difference to @ref{Section sb-concurrency:queue, queues} is that the receiving
-end may block until a message arrives.
-@*@*
-Built on top of the @ref{Structure sb-concurrency queue, queue} implementation.
+@code{sb-concurrency:mailbox} is a lock-free message queue where one or
+multiple ends can send messages to one or multiple receivers. The
+difference to @ref{sb concurrency queue} is that the receiving end may
+block until a message arrives.
-@include struct-sb-concurrency-mailbox.texinfo
+Built on top of the @ref{sb concurrency queue} implementation.
-@include fun-sb-concurrency-list-mailbox-messages.texinfo
-@include fun-sb-concurrency-mailbox-count.texinfo
-@include fun-sb-concurrency-mailbox-empty-p.texinfo
-@include fun-sb-concurrency-mailbox-name.texinfo
-@include fun-sb-concurrency-mailboxp.texinfo
-@include fun-sb-concurrency-make-mailbox.texinfo
-@include fun-sb-concurrency-receive-message.texinfo
-@include fun-sb-concurrency-receive-message-no-hang.texinfo
-@include fun-sb-concurrency-receive-pending-messages.texinfo
-@include fun-sb-concurrency-send-message.texinfo
+@anchor{Structure sb-concurrency mailbox}
+@ttindex @sortas{mailbox sb-concurrency} mailbox [sb-concurrency]
+@deffn{Structure} sb-concurrency:mailbox
+Mailbox aka message queue.
-@page
-@anchor{Section sb-concurrency:gate}
+@code{send-message} adds a message to the mailbox, @code{receive-message} waits till
+a message becomes available, whereas @code{receive-message-no-hang} is a non-blocking
+variant, and @code{receive-pending-messages} empties the entire mailbox in one go.
+
+Messages can be arbitrary objects.
+@end deffn
+@anchor{Function sb-concurrency list-mailbox-messages}
+@ffindex @sortas{list-mailbox-messages sb-concurrency} list-mailbox-messages [sb-concurrency]
+@deffn{Function} sb-concurrency:list-mailbox-messages mailbox
+Returns a fresh list containing all the messages in @code{mailbox}. Does not
+remove messages from the mailbox.
+@end deffn
+@anchor{Function sb-concurrency mailbox-count}
+@ffindex @sortas{mailbox-count sb-concurrency} mailbox-count [sb-concurrency]
+@deffn{Function} sb-concurrency:mailbox-count mailbox
+Returns the number of messages currently in @code{mailbox}.
+@end deffn
+@anchor{Function sb-concurrency mailbox-empty-p}
+@ffindex @sortas{mailbox-empty-p sb-concurrency} mailbox-empty-p [sb-concurrency]
+@deffn{Function} sb-concurrency:mailbox-empty-p mailbox
+Returns true if @code{mailbox} is currently empty, @code{nil} otherwise.
+@end deffn
+@anchor{Function sb-concurrency mailbox-name}
+@ffindex @sortas{mailbox-name sb-concurrency} mailbox-name [sb-concurrency]
+@deffn{Function} sb-concurrency:mailbox-name instance
+Name of a @code{mailbox}. @code{setf}able.
+@end deffn
+@anchor{Function sb-concurrency mailboxp}
+@ffindex @sortas{mailboxp sb-concurrency} mailboxp [sb-concurrency]
+@deffn{Function} sb-concurrency:mailboxp object
+Returns true if argument is a @code{mailbox}, @code{nil} otherwise.
+@end deffn
+@anchor{Function sb-concurrency make-mailbox}
+@ffindex @sortas{make-mailbox sb-concurrency} make-mailbox [sb-concurrency]
+@deffn{Function} sb-concurrency:make-mailbox &key name initial-contents
+Returns a new @code{mailbox} with messages in @code{initial-contents} enqueued.
+@end deffn
+@anchor{Function sb-concurrency receive-message}
+@ffindex @sortas{receive-message sb-concurrency} receive-message [sb-concurrency]
+@deffn{Function} sb-concurrency:receive-message mailbox &key timeout
+Removes the oldest message from @code{mailbox} and returns it as the primary
+value, and a secondary value of @code{t}. If @code{mailbox} is empty waits until a message
+arrives.
+
+If @code{timeout} is provided, and no message arrives within the specified interval,
+returns primary and secondary value of @code{nil}.
+@end deffn
+@anchor{Function sb-concurrency receive-message-no-hang}
+@ffindex @sortas{receive-message-no-hang sb-concurrency} receive-message-no-hang [sb-concurrency]
+@deffn{Function} sb-concurrency:receive-message-no-hang mailbox
+The non-blocking variant of @code{receive-message}. Returns two values,
+the message removed from @code{mailbox}, and a flag specifying whether a
+message could be received.
+@end deffn
+@anchor{Function sb-concurrency receive-pending-messages}
+@ffindex @sortas{receive-pending-messages sb-concurrency} receive-pending-messages [sb-concurrency]
+@deffn{Function} sb-concurrency:receive-pending-messages mailbox &optional n
+Removes and returns all (or at most @code{n}) currently pending messages
+from @code{mailbox}, or returns @code{nil} if no messages are pending.
+
+@quotation
+@emph{Note}: Concurrent threads may be snarfing messages during the run
+of this function, so even @code{x} and @code{y} appearing right next to each
+other in the result does not necessarily mean that @code{y} was the
+message sent right after @code{x}.
+@end quotation
+@end deffn
+@anchor{Function sb-concurrency send-message}
+@ffindex @sortas{send-message sb-concurrency} send-message [sb-concurrency]
+@deffn{Function} sb-concurrency:send-message mailbox message
+Adds a @code{message} to @code{mailbox}. Message can be any object.
+@end deffn
+@node sb concurrency gates
@subsection Gates
-@cindex Gate
@code{sb-concurrency:gate} is a synchronization object suitable for when
multiple threads must wait for a single event before proceeding.
-@include struct-sb-concurrency-gate.texinfo
+@anchor{Structure sb-concurrency gate}
+@ttindex @sortas{gate sb-concurrency} gate [sb-concurrency]
+@deffn{Structure} sb-concurrency:gate
+@code{gate} type. Gates are synchronization constructs suitable for making
+multiple threads wait for single event before proceeding.
-@include fun-sb-concurrency-close-gate.texinfo
-@include fun-sb-concurrency-gate-name.texinfo
-@include fun-sb-concurrency-gate-open-p.texinfo
-@include fun-sb-concurrency-gatep.texinfo
-@include fun-sb-concurrency-make-gate.texinfo
-@include fun-sb-concurrency-open-gate.texinfo
-@include fun-sb-concurrency-wait-on-gate.texinfo
-
-@page
-@anchor{Section sb-concurrency:frlock}
+Use @code{wait-on-gate} to wait for a gate to open, @code{open-gate} to open one,
+and @code{close-gate} to close an open gate. @code{gate-open-p} can be used to test
+the state of a gate without blocking.
+@end deffn
+@anchor{Function sb-concurrency close-gate}
+@ffindex @sortas{close-gate sb-concurrency} close-gate [sb-concurrency]
+@deffn{Function} sb-concurrency:close-gate gate
+Closes @code{gate}. Returns @code{t} if the gate was previously open, and @code{nil}
+if the gate was already closed.
+@end deffn
+@anchor{Function sb-concurrency gate-name}
+@ffindex @sortas{gate-name sb-concurrency} gate-name [sb-concurrency]
+@deffn{Function} sb-concurrency:gate-name instance
+Name of a @code{gate}. @code{setf}able.
+@end deffn
+@anchor{Function sb-concurrency gate-open-p}
+@ffindex @sortas{gate-open-p sb-concurrency} gate-open-p [sb-concurrency]
+@deffn{Function} sb-concurrency:gate-open-p gate
+Returns true if @code{gate} is open.
+@end deffn
+@anchor{Function sb-concurrency gatep}
+@ffindex @sortas{gatep sb-concurrency} gatep [sb-concurrency]
+@deffn{Function} sb-concurrency:gatep object
+Returns true if the argument is a @code{gate}.
+@end deffn
+@anchor{Function sb-concurrency make-gate}
+@ffindex @sortas{make-gate sb-concurrency} make-gate [sb-concurrency]
+@deffn{Function} sb-concurrency:make-gate &key name open
+Makes a new gate. Gate will be initially open if @code{open} is true, and closed if @code{open}
+is @code{nil} (the default.) @code{name}, if provided, is the name of the gate, used when printing
+the gate.
+@end deffn
+@anchor{Function sb-concurrency open-gate}
+@ffindex @sortas{open-gate sb-concurrency} open-gate [sb-concurrency]
+@deffn{Function} sb-concurrency:open-gate gate
+Opens @code{gate}. Returns @code{t} if the gate was previously closed, and @code{nil}
+if the gate was already open.
+@end deffn
+@anchor{Function sb-concurrency wait-on-gate}
+@ffindex @sortas{wait-on-gate sb-concurrency} wait-on-gate [sb-concurrency]
+@deffn{Function} sb-concurrency:wait-on-gate gate &key timeout
+Waits for @code{gate} to open, or @code{timeout} seconds to pass. Returns @code{t}
+if the gate was opened in time, and @code{nil} otherwise.
+@end deffn
+@node sb concurrency frlocks
@subsection Frlocks, aka Fast Read Locks
-@cindex Frlock
-@cindex Fast Read Lock
-@include struct-sb-concurrency-frlock.texinfo
+@anchor{Structure sb-concurrency frlock}
+@ttindex @sortas{frlock sb-concurrency} frlock [sb-concurrency]
+@deffn{Structure} sb-concurrency:frlock
+FRlock, aka Fast Read Lock.
-@include macro-sb-concurrency-frlock-read.texinfo
-@include macro-sb-concurrency-frlock-write.texinfo
+Fast Read Locks allow multiple readers and one potential writer to operate in
+parallel while providing for consistency for readers and mutual exclusion for
+writers.
-@include fun-sb-concurrency-make-frlock.texinfo
-@include fun-sb-concurrency-frlock-name.texinfo
+Readers gain entry to protected regions without waiting, but need to retry if
+a writer operated inside the region while they were reading. This makes frlocks
+very efficient when readers are much more common than writers.
-@include fun-sb-concurrency-frlock-read-begin.texinfo
-@include fun-sb-concurrency-frlock-read-end.texinfo
-@include fun-sb-concurrency-grab-frlock-write-lock.texinfo
-@include fun-sb-concurrency-release-frlock-write-lock.texinfo
+FRlocks are @emph{not} suitable when it is not safe at all for readers and writers
+to operate on the same data in parallel: they provide consistency, not
+exclusion between readers and writers. Hence using an frlock to e.g. protect
+an SBCL hash-table is unsafe. If multiple readers operating in parallel with
+a writer would be safe but inconsistent without a lock, frlocks are suitable.
+
+The recommended interface to use is @code{frlock-read} and @code{frlock-write}, but those
+needing it can also use a lower-level interface.
+
+Example:
+
+@example
+;; Values returned by FOO are always consistent so that
+;; the third value is the sum of the two first ones.
+(let ((a 0)
+ (b 0)
+ (c 0)
+ (lk (make-frlock)))
+ (defun foo ()
+ (frlock-read (lk) a b c))
+ (defun bar (x y)
+ (frlock-write (lk)
+ (setf a x
+ b y
+ c (+ x y)))))
+@end example
+@end deffn
+@anchor{Macro sb-concurrency frlock-read}
+@ffindex @sortas{frlock-read sb-concurrency} frlock-read [sb-concurrency]
+@deffn{Macro} sb-concurrency:frlock-read (frlock) &body value-forms
+Evaluates @code{value-forms} under @code{frlock} till it obtains a consistent
+set, and returns that as multiple values.
+@end deffn
+@anchor{Macro sb-concurrency frlock-write}
+@ffindex @sortas{frlock-write sb-concurrency} frlock-write [sb-concurrency]
+@deffn{Macro} sb-concurrency:frlock-write (frlock &key wait-p timeout) &body body
+Executes @code{body} while holding @code{frlock} for writing.
+@end deffn
+@anchor{Function sb-concurrency make-frlock}
+@ffindex @sortas{make-frlock sb-concurrency} make-frlock [sb-concurrency]
+@deffn{Function} sb-concurrency:make-frlock &key name
+Returns a new @code{frlock} with @code{name}.
+@end deffn
+@anchor{Function sb-concurrency frlock-name}
+@ffindex @sortas{frlock-name sb-concurrency} frlock-name [sb-concurrency]
+@deffn{Function} sb-concurrency:frlock-name instance
+Name of an @code{frlock}. @code{setf}able.
+@end deffn
+@anchor{Function sb-concurrency frlock-read-begin}
+@ffindex @sortas{frlock-read-begin sb-concurrency} frlock-read-begin [sb-concurrency]
+@deffn{Function} sb-concurrency:frlock-read-begin frlock
+Start a read sequence on @code{frlock}. Returns a read-token and an epoch to be
+validated later.
+
+Using @code{frlock-read} instead is recommended.
+@end deffn
+@anchor{Function sb-concurrency frlock-read-end}
+@ffindex @sortas{frlock-read-end sb-concurrency} frlock-read-end [sb-concurrency]
+@deffn{Function} sb-concurrency:frlock-read-end frlock
+Ends a read sequence on @code{frlock}. Returns a token and an epoch. If the token
+and epoch are @code{eql} to the read-token and epoch returned by @code{frlock-read-begin},
+the values read under the @code{frlock} are consistent and can be used: if the values
+differ, the values are inconsistent and the read must be restated.
+
+Using @code{frlock-read} instead is recommended.
+
+Example:
+
+@example
+(multiple-value-bind (t0 e0) (frlock-read-begin *fr*)
+ (let ((a (get-a))
+ (b (get-b)))
+ (multiple-value-bind (t1 e1) (frlock-read-end *fr*)
+ (if (and (eql t0 t1) (eql e0 e1))
+ (list :a a :b b)
+ :aborted))))
+@end example
+@end deffn
+@anchor{Function sb-concurrency grab-frlock-write-lock}
+@ffindex @sortas{grab-frlock-write-lock sb-concurrency} grab-frlock-write-lock [sb-concurrency]
+@deffn{Function} sb-concurrency:grab-frlock-write-lock frlock &key wait-p timeout
+Acquires @code{frlock} for writing, invalidating existing and future read-tokens
+for the duration. Returns @code{t} on success, and @code{nil} if the lock wasn't acquired
+due to e.g. a timeout. Using @code{frlock-write} instead is recommended.
+@end deffn
+@anchor{Function sb-concurrency release-frlock-write-lock}
+@ffindex @sortas{release-frlock-write-lock sb-concurrency} release-frlock-write-lock [sb-concurrency]
+@deffn{Function} sb-concurrency:release-frlock-write-lock frlock
+Releases @code{frlock} after writing, allowing valid read-tokens to be acquired again.
+Signals an error if the current thread doesn't hold @code{frlock} for writing. Using @code{frlock-write}
+instead is recommended.
+@end deffn
diff --git a/contrib/sb-cover/sb-cover.texinfo b/contrib/sb-cover/sb-cover.texinfo
index 30da233aa..42627c73a 100644
--- a/contrib/sb-cover/sb-cover.texinfo
+++ b/contrib/sb-cover/sb-cover.texinfo
@@ -1,19 +1,20 @@
-@node sb-cover
+@c Generated by the sb-manual contrib. Do not edit.
+
+@node sb cover
@section sb-cover
-@cindex Code Coverage
The @code{sb-cover} module provides a code coverage tool for SBCL. The
-tool has support for expression coverage, and for some branch coverage.
-Coverage reports are only generated for code compiled using
-@code{compile-file} with the value of the
+tool has support for expression coverage, and for some branch
+coverage. Coverage reports are only generated for code compiled
+using @code{compile-file} with the value of the
@code{sb-cover:store-coverage-data} optimization quality set to 3.
-As of SBCL 1.0.6 @code{sb-cover} is still experimental, and the
+As of SBCL 1.0.6, @code{sb-cover} is still experimental, and the
interfaces documented here might change in later versions.
-@subsection Example Usage
+How to use it:
-@lisp
+@example
;;; Load SB-COVER
(require :sb-cover)
@@ -32,27 +33,76 @@ interfaces documented here might change in later versions.
;;; Turn off instrumentation
(declaim (optimize (sb-cover:store-coverage-data 0)))
-@end lisp
+@end example
-@c @subsection Output
-@c Write some documentation about how to interpret the results
+@anchor{Function sb-cover report}
+@ffindex @sortas{report sb-cover} report [sb-cover]
+@deffn{Function} sb-cover:report directory &key form-mode if-matches external-format
+Print a code coverage report of all instrumented files into @code{directory}.
+If @code{directory} does not exist, it will be created. The main report will be
+printed to the file cover-index.html. The external format of the source
+files can be specified with the @code{external-format} parameter.
-@subsection Functions
+If the keyword argument @code{:form-mode} has the value @code{:car}, the annotations
+in the coverage report will be placed on the @code{car}s of any cons-forms,
+while if it has the value @code{:whole} the whole form will be annotated (the
+default). The former mode shows explicitly which forms were
+instrumented, while the latter mode is generally easier to read.
-@include fun-sb-cover-report.texinfo
-
-@include fun-sb-cover-reset-coverage.texinfo
-
-@include fun-sb-cover-clear-coverage.texinfo
-
-@include fun-sb-cover-save-coverage.texinfo
-
-@include fun-sb-cover-save-coverage-in-file.texinfo
-
-@include fun-sb-cover-restore-coverage.texinfo
-
-@include fun-sb-cover-restore-coverage-from-file.texinfo
-
-@include fun-sb-cover-merge-coverage.texinfo
-
-@include fun-sb-cover-merge-coverage-from-file.texinfo
+The keyword argument @code{if-matches} should be a designator for a function
+of one argument, called for the namestring of each file with code
+coverage info. If it returns true, the file's info is included in the
+report, otherwise ignored. The default value is @code{cl:identity}.
+@end deffn
+@anchor{Function sb-cover reset-coverage}
+@ffindex @sortas{reset-coverage sb-cover} reset-coverage [sb-cover]
+@deffn{Function} sb-cover:reset-coverage &optional object
+Reset all coverage data back to the @code{Not executed} state.
+@end deffn
+@anchor{Function sb-cover clear-coverage}
+@ffindex @sortas{clear-coverage sb-cover} clear-coverage [sb-cover]
+@deffn{Function} sb-cover:clear-coverage
+Clear all files from the coverage database. The files will be re-entered
+into the database when the FASL files (produced by compiling
+@code{store-coverage-data} optimization policy set to 3) are loaded again into the
+image.
+@end deffn
+@anchor{Function sb-cover save-coverage}
+@ffindex @sortas{save-coverage sb-cover} save-coverage [sb-cover]
+@deffn{Function} sb-cover:save-coverage
+Returns an opaque representation of the current code coverage state.
+The only operation that may be done on the state is passing it to
+@code{restore-coverage}. The representation is guaranteed to be readably printable.
+A representation that has been printed and read back will work identically
+in @code{restore-coverage}.
+@end deffn
+@anchor{Function sb-cover save-coverage-in-file}
+@ffindex @sortas{save-coverage-in-file sb-cover} save-coverage-in-file [sb-cover]
+@deffn{Function} sb-cover:save-coverage-in-file pathname
+Call @code{save-coverage} and write the results of that operation into the
+file designated by @code{pathname}.
+@end deffn
+@anchor{Function sb-cover restore-coverage}
+@ffindex @sortas{restore-coverage sb-cover} restore-coverage [sb-cover]
+@deffn{Function} sb-cover:restore-coverage coverage-state
+Restore the code coverage data back to an earlier state produced by
+@code{save-coverage}.
+@end deffn
+@anchor{Function sb-cover restore-coverage-from-file}
+@ffindex @sortas{restore-coverage-from-file sb-cover} restore-coverage-from-file [sb-cover]
+@deffn{Function} sb-cover:restore-coverage-from-file pathname
+@code{read} the contents of the file designated by @code{pathname} and pass the
+result to @code{restore-coverage}.
+@end deffn
+@anchor{Function sb-cover merge-coverage}
+@ffindex @sortas{merge-coverage sb-cover} merge-coverage [sb-cover]
+@deffn{Function} sb-cover:merge-coverage coverage-state
+Merge the code coverage data to include covered code from an earlier
+state produced by @code{save-coverage}.
+@end deffn
+@anchor{Function sb-cover merge-coverage-from-file}
+@ffindex @sortas{merge-coverage-from-file sb-cover} merge-coverage-from-file [sb-cover]
+@deffn{Function} sb-cover:merge-coverage-from-file pathname
+@code{read} the contents of the file designated by @code{pathname} and pass the
+result to @code{merge-coverage}.
+@end deffn
diff --git a/contrib/sb-grovel/sb-grovel.texinfo b/contrib/sb-grovel/sb-grovel.texinfo
index c1badd134..ac40e122a 100644
--- a/contrib/sb-grovel/sb-grovel.texinfo
+++ b/contrib/sb-grovel/sb-grovel.texinfo
@@ -1,42 +1,47 @@
-@node sb-grovel
+@c Generated by the sb-manual contrib. Do not edit.
+
+@node sb grovel
@section sb-grovel
-@cindex Foreign Function Interface, generation
+
+@menu
+* Using sb-grovel in your own ASDF System: using sb grovel.
+* Contents of a grovel-constants-file: sb grovel constants file.
+* Programming with sb-grovel's structure types: sb grovel structures.
+* Traps and Pitfalls: sb grovel traps.
+@end menu
The @code{sb-grovel} module helps in generation of foreign function
interfaces. It aids in extracting constants' values from the C
-compiler and in generating SB-ALIEN structure and union types,
-@pxref{Defining Foreign Types}.
+compiler and in generating sb-alien structure and union types,
+@ref{defining foreign types}.
-The ASDF(@uref{http://www.cliki.net/ASDF}) component type
-GROVEL-CONSTANTS-FILE has its PERFORM
-@c @xref for PERFORM when asdf manual is included?
-operation defined to write out a C source file, compile it, and run
-it. The output from this program is Lisp, which is then itself
-compiled and loaded.
+The ASDF (@url{http://www.cliki.net/ASDF}) component type
+GROVEL-CONSTANTS-FILE has its @code{asdf:perform} operation defined to
+write out a C source file, compile it, and run it. The output from
+this program is Lisp, which is then itself compiled and loaded.
-sb-grovel is used in a few contributed modules, and it is currently
-compatible only to SBCL. However, if you want to use it, here are a
-few directions.
+@code{sb-grovel} is used in a few contributed modules, and it is
+currently compatible only to SBCL. However, if you want to use it,
+here are a few directions.
-@subsection Using sb-grovel in your own ASDF system
+@node using sb grovel
+@subsection Using sb-grovel in your own ASDF System
-@enumerate
+@itemize
+@item Create a Lisp package for the foreign constants/functions to go
+@end itemize
+into.
-@item
-Create a Lisp package for the foreign constants/functions to go into.
+@itemize
+@item Make your system depend on the @code{sb-grovel} system.
-@item
-Make your system depend on the 'sb-grovel system.
+@item Create a grovel-constants data file -- for an example, see
+ @code{example-constants.lisp} in the @code{contrib/sb-grovel/} directory in
+ the SBCL source distribution.
-@item
-Create a grovel-constants data file - for an example, see
-example-constants.lisp in the contrib/sb-grovel/ directory in the SBCL
-source distribution.
+@item Add it as a component in your system. For example:
-@item
-Add it as a component in your system. e.g.
-
-@lisp
+@example
(eval-when (:compile-toplevel :load-toplevel :execute)
(require :sb-grovel))
@@ -53,34 +58,35 @@ Add it as a component in your system. e.g.
((:file "defpackage")
(grovel-constants-file "example-constants"
:package :example-package)))))
-@end lisp
+@end example
+@end itemize
-Make sure to specify the package you chose in step 1
+Make sure to specify the package you chose in step 1.
-@item
-Build stuff.
-
-@end enumerate
+@itemize
+@item Build stuff.
+@end itemize
+@node sb grovel constants file
@subsection Contents of a grovel-constants-file
The grovel-constants-file, typically named @code{constants.lisp},
-comprises lisp expressions describing the foreign things that you want
-to grovel for. A @code{constants.lisp} file contains two sections:
+comprises lisp expressions describing the foreign things that you
+want to grovel for. A @code{constants.lisp} file contains two sections:
@itemize
-@item
-a list of headers to include in the C program, for example:
-@lisp
+@item a list of headers to include in the C program, for example:
+
+@example
("sys/types.h" "sys/socket.h" "sys/stat.h" "unistd.h" "sys/un.h"
"netinet/in.h" "netinet/in_systm.h" "netinet/ip.h" "net/if.h"
- "netdb.h" "errno.h" "netinet/tcp.h" "fcntl.h" "signal.h" )
-@end lisp
+ "netdb.h" "errno.h" "netinet/tcp.h" "fcntl.h" "signal.h")
+@end example
-@item
-A list of sb-grovel clauses describing the things you want to grovel
-from the C compiler, for example:
-@lisp
+@item A list of sb-grovel clauses describing the things you want to
+ grovel from the C compiler, for example:
+
+@example
((:integer af-local
#+(or sunos solaris) "AF_UNIX"
#-(or sunos solaris) "AF_LOCAL"
@@ -89,149 +95,151 @@ from the C compiler, for example:
(integer dev "dev_t" "st_dev")
(integer atime "time_t" "st_atime")))
(:function getpid ("getpid" int )))
-@end lisp
+@end example
@end itemize
-There are two types of things that sb-grovel can sensibly extract from
-the C compiler: constant integers and structure layouts. It is also
-possible to define foreign functions in the constants.lisp file, but
-these definitions don't use any information from the C program; they
-expand directly to @code{sb-alien:define-alien-routine}
-(@pxref{The define-alien-routine Macro}) forms.
+There are two types of things that sb-grovel can sensibly extract
+from the C compiler: constant integers and structure layouts. It is
+also possible to define foreign functions in the constants.lisp
+file, but these definitions don't use any information from the C
+program; they expand directly to @code{sb-alien:define-alien-routine}
+forms.
Here's how to use the grovel clauses:
@itemize
-@item
-@code{:integer} - constant expressions in C. Used in this form:
-@lisp
+@item @code{:integer}: constant expressions in C. Used in this form:
+
+@example
(:integer lisp-variable-name "C expression" &optional doc export)
-@end lisp
+@end example
-@code{"C expression"} will be typically be the name of a constant. But
-other forms are possible.
+@code{"C expression"} will be typically be the name of a constant,
+but other forms are possible.
-@item
-@code{:enum}
-@lisp
+@item @code{:enum}:
+
+@example
(:enum lisp-type-name ((lisp-enumerated-name c-enumerated-name) ...)))
-@end lisp
+@end example
-An @code{sb-alien:enum} type with name @code{lisp-type-name} will be defined.
-The symbols are the @code{lisp-enumerated-name}s, and the values
-are grovelled from the @code{c-enumerated-name}s.
+An @code{sb-alien:enum} type with name @code{lisp-type-name} will be
+defined. The symbols are the @code{lisp-enumerated-name}s, and the
+values are grovelled from the @code{c-enumerated-name}s.
-@item
-@code{:structure} - alien structure definitions look like this:
-@lisp
+@item @code{:structure}: alien structure definitions look like this:
+
+@example
(:structure lisp-struct-name ("struct c_structure"
(type-designator lisp-element-name
"c_element_type" "c_element_name"
:distrust-length nil)
; ...
))
-@end lisp
+@end example
@code{type-designator} is a reference to a type whose size (and type
-constraints) will be groveled for. sb-grovel accepts a form of type
-designator that doesn't quite conform to either lisp nor sb-alien's
-type specifiers. Here's a list of type designators that sb-grovel
-currently accepts:
+constraints) will be groveled for. sb-grovel accepts a form of
+type designator that doesn't quite conform to either lisp nor
+sb-alien's type specifiers. Here's a list of type designators
+that sb-grovel currently accepts:
+
@itemize
-@item
-@code{integer} - a C integral type; sb-grovel will infer the exact
-type from size information extracted from the C program. All common C
-integer types can be grovelled for with this type designator, but it
-is not possible to grovel for bit fields yet.
+@item @code{integer}: a C integral type; sb-grovel will infer the exact
+ type from size information extracted from the C program. All
+ common C integer types can be grovelled for with this type
+ designator, but it is not possible to grovel for bit fields
+ yet.
-@item
-@code{(unsigned n)} - an unsigned integer variable that is @code{n}
-bytes long. No size information from the C program will be used.
-@item
-@code{(signed n)} - an signed integer variable that is @code{n} bytes
-long. No size information from the C program will be used.
+@item @code{(unsigned n)}: an unsigned integer variable that is @code{n} bytes
+ long. No size information from the C program will be used.
-@item
-@code{c-string} - an array of @code{char} in the structure. sb-grovel
-will use the array's length from the C program, unless you pass it the
-@code{:distrust-length} keyword argument with non-@code{nil} value
-(this might be required for structures such as solaris's @code{struct
-dirent}).
+@item @code{(signed n)}: an signed integer variable that is @code{n} bytes
+ long. No size information from the C program will be used.
-@item
-@code{c-string-pointer} - a pointer to a C string, corresponding to
-the @code{sb-alien:c-string} type (@pxref{Foreign Type Specifiers}).
-@item
-@code{(array alien-type)} - An array of the previously-declared alien
-type. The array's size will be determined from the output of the C
-program and the alien type's size.
-@item
-@code{(array alien-type n)} - An array of the previously-declared alien
-type. The array's size will be assumed as being @code{n}.
-@end itemize
+@item @code{c-string}: an array of @code{char} in the structure. sb-grovel
+ will use the array's length from the C program, unless you
+ pass it the @code{:distrust-length} keyword argument with non-@code{nil}
+ value (this might be required for structures such as solaris's
+ @code{struct dirent}).
+
+@item @code{sb-grovel::c-string-pointer}: a pointer to a C string,
+ corresponding to the @code{sb-alien:c-string} type (see
+ @ref{foreign type specifiers}).
+
+@item @code{(array alien-type)}: an array of the previously-declared
+ @code{alien-type}. The array's size will be determined from the
+ output of the C program and the alien type's size.
+@item @code{(array alien-type n):} an array of the previously-declared
+ @code{alien-type}. The array's size will be assumed as being @code{n}.
+@end itemize
+@end itemize
-Note that @code{c-string} and @code{c-string-pointer} do not have the
-same meaning. If you declare that an element is of type
+Note that @code{c-string} and @code{sb-grovel::c-string-pointer} do not have
+the same meaning. If you declare that an element is of type
@code{c-string}, it will be treated as if the string is a part of the
structure, whereas if you declare that the element is of type
-@code{c-string-pointer}, a @emph{pointer to a string} will be the
+@code{sb-grovel::c-string-pointer}, a @emph{pointer to a string} will be the
structure member.
-@item
-@code{:function} - alien function definitions are similar to
-@code{define-alien-routine} definitions, because they expand to such
-forms when the lisp program is loaded. @xref{Foreign Function Calls}.
+@itemize
+@item @code{:function}: alien function definitions are similar to
+ @code{define-alien-routine} definitions, because they expand to such
+ forms when the lisp program is loaded. See
+ @ref{foreign function calls}.
-@lisp
-(:function lisp-function-name ("alien_function_name" alien-return-type
- (argument alien-type)
- (argument2 alien-type)))
-@end lisp
+@example
+(:function lisp-function-name
+ ("alien_function_name" alien-return-type
+ (argument alien-type)
+ (argument2 alien-type)))
+@end example
@end itemize
-
+@node sb grovel structures
@subsection Programming with sb-grovel's structure types
Let us assume that you have a grovelled structure definition:
-@lisp
- (:structure mystruct ("struct my_structure"
- (integer myint "int" "st_int")
- (c-string mystring "char[]" "st_str")))
-@end lisp
+
+@example
+(:structure mystruct ("struct my_structure"
+ (integer myint "int" "st_int")
+ (c-string mystring "char[]" "st_str")))
+@end example
What can you do with it? Here's a short interface document:
@itemize
-@item
-Creating and destroying objects:
+@item Creating and destroying objects:
+
@itemize
-@item
-Function @code{(allocate-mystruct)} - allocates an object of type @code{mystruct}and
-returns a system area pointer to it.
-@item
-Macro @code{(with-mystruct var ((member init) [...]) &body body)} -
-allocates an object of type @code{mystruct} that is valid in
-@var{body}. If @var{body} terminates or control unwinds out of
-@var{body}, the object pointed to by @var{var} will be deallocated.
+@item Function @code{(allocate-mystruct)} allocates an object of type
+ @code{mystruct} and returns a system area pointer to it.
+
+@item Macro @code{(with-mystruct var ((member init) [...]) &body body)}
+ allocates an object of type @code{mystruct} that is valid in
+ @code{body}. If @code{body} terminates or performs an non-local exit,
+ the object pointed to by @code{var} will be deallocated.
@end itemize
-@item
-Accessing structure members:
+@item Accessing structure members:
+
@itemize
-@item
-@code{(mystruct-myint var)} and @code{(mystruct-mystring var)} return
-the value of the respective fields in @code{mystruct}.
-@item
-@code{(setf (mystruct-myint var) new-val)} and
-@code{(setf (mystruct-mystring var) new-val)} sets the value of the respective
-structure member to the value of @var{new-val}. Notice that in
-@code{(setf (mystruct-mystring var) new-val)}'s case, new-val is a lisp
-string.
+@item @code{(mystruct-myint var)} and @code{(mystruct-mystring var)} return
+ the value of the respective fields in @code{mystruct}.
+
+@item @code{(setf (mystruct-myint var) new-val)} and
+ @code{(setf (mystruct-mystring var) new-val)} sets the value of the
+ respective structure member to the value of @code{new-val}. Notice
+ that in @code{(setf (mystruct-mystring var) new-val)}'s case,
+ @code{new-val} is a lisp string.
@end itemize
@end itemize
-@subsubsection Traps and Pitfalls
+@node sb grovel traps
+@subsection Traps and Pitfalls
+
Basically, you can treat functions and data structure definitions that
sb-grovel spits out as if they were alien routines and types. This has
a few implications that might not be immediately obvious (especially
@@ -239,13 +247,12 @@ if you have programmed in a previous version of sb-grovel that didn't
use alien types):
@itemize
-@item
-You must take care of grovel-allocated structures yourself. They are
-alien types, so the garbage collector will not collect them when you
-drop the last reference.
+@item You must take care of grovel-allocated structures yourself. They
+ are alien types, so the garbage collector will not collect them
+ when you drop the last reference.
-@item
-If you use the @code{with-mystruct} macro, be sure that no references
-to the variable thus allocated leaks out. It will be deallocated when
-the block exits.
+@item If you use the @code{with-mystruct} macro, be sure that no references
+ to the variable thus allocated leaks out. It will be deallocated
+ when the block exits.
@end itemize
+
diff --git a/contrib/sb-introspect/sb-introspect.texinfo b/contrib/sb-introspect/sb-introspect.texinfo
index b4b63a5af..7a8c2d3f7 100644
--- a/contrib/sb-introspect/sb-introspect.texinfo
+++ b/contrib/sb-introspect/sb-introspect.texinfo
@@ -1,61 +1,363 @@
-@node sb-introspect
+@c Generated by the sb-manual contrib. Do not edit.
+
+@node sb introspect
@section sb-introspect
-@cindex Introspection Library
-
-The @code{sb-introspect} module is about finding definitions, as well
-as querying their properties and relationships in the running image.
@menu
-* Finding Definitions::
-* Special Variables in sb-introspect::
-* Functions::
-* Types and Classes::
-* Allocation::
+* Finding Definitions: finding definitions.
+* Special Variables: sb introspect variables.
+* Functions: sb introspect functions.
+* Types and Classes: sb introspect types.
+* Allocation: sb introspect allocation.
@end menu
+The @code{sb-introspect} module is about finding definitions, as well
+as querying their properties and relationships in the running image.
-@node Finding Definitions
+@node finding definitions
@subsection Finding Definitions
-@include struct-sb-introspect-definition-source.texinfo
-@include fun-sb-introspect-definition-source-pathname.texinfo
-@include fun-sb-introspect-definition-source-form-path.texinfo
-@include fun-sb-introspect-definition-source-form-number.texinfo
-@include fun-sb-introspect-definition-source-character-offset.texinfo
-@include fun-sb-introspect-definition-source-file-write-date.texinfo
-@include fun-sb-introspect-definition-source-plist.texinfo
-
-@include fun-sb-introspect-find-definition-source.texinfo
-@include fun-sb-introspect-find-definition-sources-by-name.texinfo
-
-@node Special Variables in sb-introspect
+@anchor{Structure sb-introspect definition-source}
+@ttindex @sortas{definition-source sb-introspect} definition-source [sb-introspect]
+@deffn{Structure} sb-introspect:definition-source
+This structure identifies a sexp in a compiled file.
+Despite the name, the source location may not correspond to a
+definition but to e.g. a function call (see @code{who-calls}).
+@end deffn
+@anchor{Function sb-introspect definition-source-pathname}
+@ffindex @sortas{definition-source-pathname sb-introspect} definition-source-pathname [sb-introspect]
+@deffn{Function} sb-introspect:definition-source-pathname instance
+Pathname of the source file.
+This is @code{nil} if the source location is not in a compiled file.
+@end deffn
+@anchor{Function sb-introspect definition-source-form-path}
+@ffindex @sortas{definition-source-form-path sb-introspect} definition-source-form-path [sb-introspect]
+@deffn{Function} sb-introspect:definition-source-form-path instance
+List of indices that identify the sexp in the
+file given by @code{definition-source-pathname}. The first element in the
+list is the index of the top-level form that contains the sexp. If the
+file was compiled at a high enough debug level, then the rest of the
+elements recursively index into the list structure of the top-level
+form.
+
+Thus, the form path is somewhat stable regarding edits in the file,
+but it gets invalidated by, for example, inserting a new top-level
+form before the sexp in question.
+@end deffn
+@anchor{Function sb-introspect definition-source-form-number}
+@ffindex @sortas{definition-source-form-number sb-introspect} definition-source-form-number [sb-introspect]
+@deffn{Function} sb-introspect:definition-source-form-number instance
+Depth-first index of the sexp within the top-level
+form identified by the first element of @code{definition-source-form-path}.
+That is, this is the index of the sexp in the list of subexpressions
+of the top-level form ordered according to depth-first traversal. 0
+corresponds to the top-level form itself.
+
+When combined with the index of the top-level form (given by the first
+element of @code{definition-source-form-path}), the form number allows
+reconstruction of the rest of the form path, which may be missing.
+This requires parsing the source file. Currently, this job is
+delegated to e.g. SLIME.
+@end deffn
+@anchor{Function sb-introspect definition-source-character-offset}
+@ffindex @sortas{definition-source-character-offset sb-introspect} definition-source-character-offset [sb-introspect]
+@deffn{Function} sb-introspect:definition-source-character-offset instance
+Character offset of the top-level form containing
+the sexp.
+@end deffn
+@anchor{Function sb-introspect definition-source-file-write-date}
+@ffindex @sortas{definition-source-file-write-date sb-introspect} definition-source-file-write-date [sb-introspect]
+@deffn{Function} sb-introspect:definition-source-file-write-date instance
+@code{file-write-date} of @code{definition-source-pathname} at
+the time of compilation. @code{nil} if not compiled from a file.
+@end deffn
+@anchor{Function sb-introspect definition-source-plist}
+@ffindex @sortas{definition-source-plist sb-introspect} definition-source-plist [sb-introspect]
+@deffn{Function} sb-introspect:definition-source-plist instance
+The @code{source-plist} from @code{with-compilation-unit} in effect
+when the file was compiled.
+@end deffn
+@anchor{Function sb-introspect find-definition-source}
+@ffindex @sortas{find-definition-source sb-introspect} find-definition-source [sb-introspect]
+@deffn{Function} sb-introspect:find-definition-source object
+Return the @code{definition-source} corresponding to the definition of @code{object}
+or @code{nil} if there is no corresponding definition. @code{object} must be a
+@code{package}, @code{function}, @code{method}, @code{method-combination}, @code{sb-mop:slot-definition},
+@code{standard-object}, @code{structure-object}, @code{condition}, @code{class}, @code{structure-class},
+or a subclass of @code{condition}. An error is signalled for other types.
+
+A @code{definition-source} object is always returned for definitions that
+exist, but the source location (e.g. @code{definition-source-pathname}) may
+be missing.
+
+For definitions that do not define an object (e.g. @code{defvar}), use
+@code{find-definition-sources-by-name}.
+@end deffn
+@anchor{Function sb-introspect find-definition-sources-by-name}
+@ffindex @sortas{find-definition-sources-by-name sb-introspect} find-definition-sources-by-name [sb-introspect]
+@deffn{Function} sb-introspect:find-definition-sources-by-name name type
+Returns a list of @code{definition-source}s for definitions of @code{name} with
+the given definition @code{type}. A @code{definition-source} object is always
+returned for definitions that exist, but the source location (e.g.
+@code{definition-source-pathname}) may be missing. @code{type} can currently be one
+of the following.
+
+@itemize
+@item Public definition types:
+
+@code{:class}
+@code{:compiler-macro}
+@code{:condition}
+@code{:constant}
+@code{:function}
+@code{:generic-function}
+@code{:macro}
+@code{:method}
+@code{:method-combination}
+@code{:package}
+@code{:setf-expander}
+@code{:structure}
+@code{:symbol-macro}
+@code{:type}
+@code{:alien-type}
+@code{:alien-callback}
+@code{:variable}
+@code{:declaration}
+
+@item Internal definition types:
+
+@code{:optimizer}
+@code{:source-transform}
+@code{:transform}
+@code{:vop}
+@code{:ir1-convert}
+@end itemize
+
+Definition types are disjoint. For example, @code{:type} refers to @code{deftype}s
+but not @code{class}es or @code{sb-alien:define-alien-type}, as those are of
+definition type @code{:class} and @code{:alien-type}, respectively. @code{:function} does
+not include @code{:generic-function}, @code{:class} does not include @code{:structure},
+etc. @code{:variable} refers to non-constant dynamic variables (e.g. those
+defined with @code{defvar}, @code{defparameter}, @code{sb-ext:defglobal} or
+@code{sb-alien:define-alien-variable} but not with @code{defconstant}).
+
+Valid @code{name}s are generally @code{symbol}s with the following exceptions:
+
+@itemize
+@item For @code{:compiler-macro}, @code{:function}, @code{:generic-function} and @code{:method},
+ anything that's @code{valid-function-name-p} is valid.
+
+@item For @code{:package}, string designators are valid.
+@end itemize
+
+If an unsupported @code{type} is requested or @code{name} is invalid, this function
+returns @code{nil}.
+@end deffn
+@node sb introspect variables
@subsection Special Variables
-@include fun-sb-introspect-who-binds.texinfo
-@include fun-sb-introspect-who-references.texinfo
-@include fun-sb-introspect-who-sets.texinfo
-
-@node Functions
+@anchor{Function sb-introspect who-binds}
+@ffindex @sortas{who-binds sb-introspect} who-binds [sb-introspect]
+@deffn{Function} sb-introspect:who-binds symbol
+Find the source locations where the special variable @code{symbol} is bound,
+and return them as an alist of function or macro name,
+@code{definition-source} pairs.
+@end deffn
+@anchor{Function sb-introspect who-references}
+@ffindex @sortas{who-references sb-introspect} who-references [sb-introspect]
+@deffn{Function} sb-introspect:who-references symbol
+Find the source locations where the special variable @code{symbol} is read,
+and return them as an alist of function or macro name,
+@code{definition-source} pairs.
+@end deffn
+@anchor{Function sb-introspect who-sets}
+@ffindex @sortas{who-sets sb-introspect} who-sets [sb-introspect]
+@deffn{Function} sb-introspect:who-sets symbol
+Find the source locations where the special variable @code{symbol} is set,
+and return them as an alist of function or macro name,
+@code{definition-source} pairs.
+@end deffn
+@node sb introspect functions
@subsection Functions
-@include fun-sb-introspect-function-lambda-list.texinfo
-@include fun-sb-introspect-function-type.texinfo
-@include fun-sb-introspect-method-combination-lambda-list.texinfo
-@include fun-sb-introspect-valid-function-name-p.texinfo
-@include fun-sb-introspect-find-function-callers.texinfo
-@include fun-sb-introspect-find-function-callees.texinfo
-@include fun-sb-introspect-who-calls.texinfo
-@include fun-sb-introspect-who-macroexpands.texinfo
+@anchor{Function sb-introspect function-lambda-list}
+@ffindex @sortas{function-lambda-list sb-introspect} function-lambda-list [sb-introspect]
+@deffn{Function} sb-introspect:function-lambda-list function
+Return the lambda list of @code{function}.
+@code{function} must be a function object or a function name in the sense of
+@code{valid-function-name-p}. Works for special operators, macros, simple
+functions, interpreted functions, and generic functions.
-@node Types and Classes
+The second return value indicates whether the lambda list could not be
+determined (e.g. because the function was compiled with @code{debug} 0).
+@end deffn
+@anchor{Function sb-introspect function-type}
+@ffindex @sortas{function-type sb-introspect} function-type [sb-introspect]
+@deffn{Function} sb-introspect:function-type function-designator
+Returns the ftype of @code{function-designator} or @code{nil}.
+@end deffn
+@anchor{Function sb-introspect method-combination-lambda-list}
+@ffindex @sortas{method-combination-lambda-list sb-introspect} method-combination-lambda-list [sb-introspect]
+@deffn{Function} sb-introspect:method-combination-lambda-list method-combination
+Return the lambda list of the @code{method-combination} designator.
+@code{method-combination} can be a method combination object,
+or a method combination name.
+@end deffn
+@anchor{Function sb-introspect valid-function-name-p}
+@ffindex @sortas{valid-function-name-p sb-introspect} valid-function-name-p [sb-introspect]
+@deffn{Function} sb-introspect:valid-function-name-p name
+See if @code{name} is a valid function name. In addition to the ANSI
+definition of function name, which is symbols plus lists like (@code{setf}
+@code{symbol}), SBCL allows (@code{sb-ext:cas} @code{symbol}) and various internal
+constructs.
+@end deffn
+@anchor{Function sb-introspect find-function-callers}
+@ffindex @sortas{find-function-callers sb-introspect} find-function-callers [sb-introspect]
+@deffn{Function} sb-introspect:find-function-callers function &optional spaces
+List functions that call @code{function} by searching @code{spaces} for code objects.
+This can make previously garbage objects live.
+
+@code{spaces} should be a list of the symbols @code{:dynamic}, @code{:static}, @code{:read-only},
+or @code{:immobile} on @code{#+immobile-space}. The shorthand (@code{:all}) is also
+accepted.
+@end deffn
+@anchor{Function sb-introspect find-function-callees}
+@ffindex @sortas{find-function-callees sb-introspect} find-function-callees [sb-introspect]
+@deffn{Function} sb-introspect:find-function-callees function
+Return functions called by @code{function}.
+@end deffn
+@anchor{Function sb-introspect who-calls}
+@ffindex @sortas{who-calls sb-introspect} who-calls [sb-introspect]
+@deffn{Function} sb-introspect:who-calls function-name
+Find the source locations where the global function @code{function-name} is
+called, and return them as an alist of function or macro name,
+@code{definition-source} pairs.
+@end deffn
+@anchor{Function sb-introspect who-macroexpands}
+@ffindex @sortas{who-macroexpands sb-introspect} who-macroexpands [sb-introspect]
+@deffn{Function} sb-introspect:who-macroexpands macro-name
+Find the source locations where the macro @code{macro-name} is expanded, and
+return them as an alist of function or macro name, @code{definition-source}
+pairs.
+@end deffn
+@node sb introspect types
@subsection Types and Classes
-@include fun-sb-introspect-deftype-lambda-list.texinfo
-@include fun-sb-introspect-who-specializes-directly.texinfo
-@include fun-sb-introspect-who-specializes-generally.texinfo
+@anchor{Function sb-introspect deftype-lambda-list}
+@ffindex @sortas{deftype-lambda-list sb-introspect} deftype-lambda-list [sb-introspect]
+@deffn{Function} sb-introspect:deftype-lambda-list type-specifier-name
+Returns the lambda list of @code{type-specifier-name} as the first return
+value, and a flag whether the arglist could be found as the second
+value.
-@node Allocation
+@code{type-specifier-name} must be a symbol. This function can find the
+lambda list of derived type specifiers (e.g. those defined with
+@code{deftype}) and classes with compound type specifier syntaxes (e.g. the
+class @code{float}). It returns @code{nil}, @code{nil} for other type specifiers (e.g. @code{and},
+@code{or}, @code{not}) and types (e.g. @code{list}).
+@end deffn
+@anchor{Function sb-introspect who-specializes-directly}
+@ffindex @sortas{who-specializes-directly sb-introspect} who-specializes-directly [sb-introspect]
+@deffn{Function} sb-introspect:who-specializes-directly class-designator
+Find the source locations of methods directly specializing on
+@code{class-designator}, and return them as an alist of generic function
+name, @code{definition-source} pairs.
+
+A method matches the criterion either if it specializes on the same
+class as @code{class-designator} designates, or if it eql-specializes on an
+instance of the designated class.
+
+Experimental.
+@end deffn
+@anchor{Function sb-introspect who-specializes-generally}
+@ffindex @sortas{who-specializes-generally sb-introspect} who-specializes-generally [sb-introspect]
+@deffn{Function} sb-introspect:who-specializes-generally class-designator
+Find the source locations of methods specializing on
+@code{class-designator} or a subclass of it, and return them as an alist of
+generic function name, @code{definition-source} pairs.
+@code{definition-source-description} identifies the method.
+
+A method matches the criterion either if it specializes on the
+designated class itself or a subclass of it (this includes CLASS-EQ
+specializers), or if it eql-specializes on an instance of the
+designated class or a subclass of it.
+
+Experimental.
+@end deffn
+@node sb introspect allocation
@subsection Allocation
-@include fun-sb-introspect-allocation-information.texinfo
-@include fun-sb-introspect-map-root.texinfo
+@anchor{Function sb-introspect allocation-information}
+@ffindex @sortas{allocation-information sb-introspect} allocation-information [sb-introspect]
+@deffn{Function} sb-introspect:allocation-information object
+Returns information about the allocation of @code{object}. The primary return
+value indicates the general type of allocation: @code{:immediate}, @code{:heap},
+@code{:stack}, or @code{:foreign}.
+
+Non-NIL secondary return values provide additional information about
+the allocation.
+
+For @code{:heap} objects the secondary value is a plist:
+
+ @code{:space}
+ Indicates the heap segment the object is allocated in.
+
+ @code{:generation}
+ The current generation of the object: 0 for nursery, 6 for pseudo-static
+ generation loaded from core. (GENCGC and @code{:space} @code{:dynamic} only.)
+
+ @code{:large}
+ Indicates a "large" object subject to non-copying
+ promotion. (GENCGC and @code{:space} @code{:dynamic} only.)
+
+ @code{:boxed}
+ Indicates that the object is allocated in a boxed region. Unboxed
+ allocation is used for e.g. specialized arrays after they have survived one
+ collection. (GENCGC and @code{:space} @code{:dynamic} only.)
+
+ @code{:pinned}
+ Indicates that the page(s) on which the object resides are kept live due
+ to conservative references. Note that object may reside on a pinned page
+ even if @code{:pinned} is @code{nil} if the GC has not had the need to mark the page
+ as pinned. (GENCGC and @code{:space} @code{:dynamic} only.)
+
+ @code{:write-protected}
+ Indicates that the page on which the object starts is write-protected,
+ which indicates for @code{:boxed} objects that it hasn't been written to since
+ the last GC of its generation. (GENCGC and @code{:space} @code{:dynamic} only.)
+
+ @code{:page}
+ The index of the page the object resides on. (GENCGC and @code{:space} @code{:dynamic}
+ only.)
+
+For @code{:stack} objects, the secondary value is the thread on whose stack
+the object is allocated.
+
+Expected use-cases include introspection to gain insight into allocation and
+GC behaviour and restricting memoization to heap-allocated arguments.
+
+Experimental: interface subject to change.
+@end deffn
+@anchor{Function sb-introspect map-root}
+@ffindex @sortas{map-root sb-introspect} map-root [sb-introspect]
+@deffn{Function} sb-introspect:map-root function object &key simple ext
+Call @code{function} with all non-immediate objects pointed to by @code{object}.
+Returns @code{object}.
+
+If @code{simple} is true (default is @code{nil}), elides those pointers that are not
+notionally part of certain built-in objects but backpointers to a
+conceptual parent: e.g. elides the pointer from a @code{symbol} to the
+corresponding @code{package}.
+
+If @code{ext} is true (default is @code{t}), includes some pointers that are not
+actually contained in the object but found in certain well-known
+indirect containers: @code{fdefinition}s, @code{eql} specializers, classes, and
+thread-local symbol values in other threads fall into this category.
+
+@quotation
+@emph{Note}: calling @code{map-root} with a THREAD does not currently map over
+conservative roots from the thread registers and interrupt contexts.
+@end quotation
+
+Experimental: interface subject to change.
+@end deffn
diff --git a/contrib/sb-md5/sb-md5.texinfo b/contrib/sb-md5/sb-md5.texinfo
index 02a229792..5f2706545 100644
--- a/contrib/sb-md5/sb-md5.texinfo
+++ b/contrib/sb-md5/sb-md5.texinfo
@@ -1,27 +1,48 @@
-@node sb-md5
+@c Generated by the sb-manual contrib. Do not edit.
+
+@node sb md5
@section sb-md5
-@cindex Hashing, cryptographic
The @code{sb-md5} module implements the RFC1321 MD5 Message Digest
-Algorithm. [FIXME cite]
-
-@include fun-sb-md5-md5sum-file.texinfo
-
-@include fun-sb-md5-md5sum-sequence.texinfo
-
-@include fun-sb-md5-md5sum-stream.texinfo
-
-@include fun-sb-md5-md5sum-string.texinfo
-
-@subsection Credits
+Algorithm.
+@anchor{Function sb-md5 md5sum-file}
+@ffindex @sortas{md5sum-file sb-md5} md5sum-file [sb-md5]
+@deffn{Function} sb-md5:md5sum-file pathname
+Calculate the MD5 message-digest of the file specified by @code{pathname}.
+@end deffn
+@anchor{Function sb-md5 md5sum-sequence}
+@ffindex @sortas{md5sum-sequence sb-md5} md5sum-sequence [sb-md5]
+@deffn{Function} sb-md5:md5sum-sequence sequence &key start end
+Calculate the MD5 message-digest of data in @code{sequence}, which should
+be a 1d @code{simple-array} with element type (@code{unsigned-byte} 8). On CMU CL
+and SBCL non-simple and non-1d arrays with this element-type are also
+supported.
+@end deffn
+@anchor{Function sb-md5 md5sum-stream}
+@ffindex @sortas{md5sum-stream sb-md5} md5sum-stream [sb-md5]
+@deffn{Function} sb-md5:md5sum-stream stream
+Calculate an MD5 message-digest of the contents of @code{stream}. Its
+element-type has to be (@code{unsigned-byte} 8). Use on character streams is
+DEPRECATED, as this will not work correctly on implementations with
+@code{char-code-limit} > 256 and ignores character coding issues.
+@end deffn
+@anchor{Function sb-md5 md5sum-string}
+@ffindex @sortas{md5sum-string sb-md5} md5sum-string [sb-md5]
+@deffn{Function} sb-md5:md5sum-string string &key external-format start end
+Calculate the MD5 message-digest of the binary representation of
+@code{string} (as octets) in the external format specified by
+@code{external-format}. The boundaries @code{start} and @code{end} refer to character
+positions in the string, not to octets in the resulting binary
+representation. The permissible external format specifiers are
+determined by the underlying implementation.
+@end deffn
The implementation for CMUCL was largely done by Pierre Mai, with help
-from members of the @code{cmucl-help} mailing list. Since CMUCL and
-SBCL are similar in many respects, it was not too difficult to extend
-the low-level implementation optimizations for CMUCL to SBCL.
-Following this, SBCL's compiler was extended to implement efficient
-compilation of modular arithmetic (@pxref{Modular arithmetic}), which
+from members of the @code{cmucl-help} mailing list. Since CMUCL and SBCL
+are similar in many respects, it was not too difficult to extend the
+low-level implementation optimizations for CMUCL to SBCL. Following
+this, SBCL's compiler was extended to implement efficient
+compilation of modular arithmetic (@ref{modular arithmetic}), which
enabled the implementation to be expressed in portable arithmetical
-terms, apart from the use of @code{rotate-byte} for bitwise rotation.
-@findex @sbrotatebyte{rotate-byte}
+terms, apart from the use of @ref{sb rotate byte} for bitwise rotation.
diff --git a/contrib/sb-posix/sb-posix.texinfo b/contrib/sb-posix/sb-posix.texinfo
index 2b6dfd32a..5cde44e64 100644
--- a/contrib/sb-posix/sb-posix.texinfo
+++ b/contrib/sb-posix/sb-posix.texinfo
@@ -1,220 +1,317 @@
-@node sb-posix
+@c Generated by the sb-manual contrib. Do not edit.
+
+@node sb posix
@section sb-posix
-@cindex Operating System Interface
-@cindex System Calls
-@cindex Posix
+
+@menu
+* Lisp names for C names: sb posix lisp names.
+* Types: sb posix types.
+* Function Parameters: sb posix function parameters.
+* Function Return Values: sb posix function return values.
+* Lisp Objects and C structures: sb posix lisp objects and c structures.
+* Functions with Idiosyncratic Bindings: sb posix idiosyncracies.
+* Extensions to POSIX: sb posix extensions to posix.
+@end menu
Sb-posix is the supported interface for calling out to the operating
-system.@footnote{The functionality contained in the package
-@code{SB-UNIX} is for SBCL internal use only; its contents are likely to
-change from version to version.}
+system.
-The scope of this interface is ``operating system calls on a typical
-Unixlike platform''. This is section 2 of the Unix manual, plus section
-3 calls that are (a) typically found in libc, but (b) not part of the C
-standard. For example, we intend to provide support for
-@code{opendir()} and @code{readdir()}, but not for @code{printf()}.
-That said, if your favourite system call is not included yet, you are
+@quotation
+@emph{Note}: The functionality contained in the package @code{sb-unix} is
+for SBCL internal use only; its contents are likely to change from
+version to version.
+@end quotation
+
+The scope of this interface is "operating system calls on a typical
+Unixlike platform". This is section 2 of the Unix manual, plus
+section 3 calls that are (a) typically found in libc, but (b) not
+part of the C standard. For example, we intend to provide support
+for @code{opendir(3)} and @code{readdir(3)} but not for @code{printf(3)}. That
+said, if your favourite system call is not included yet, you are
encouraged to submit a patch to the SBCL mailing list.
-Some facilities are omitted where they offer absolutely no additional
-use over some portable function, or would be actively dangerous to the
-consistency of Lisp. Not all functions are available on all
-platforms.
+Some facilities are omitted where they offer absolutely no
+additional use over some portable function, or would be actively
+dangerous to the consistency of Lisp. Not all functions are
+available on all platforms.
-Sb-posix functions do not implicitly take measures to provide thread-safety
-or reentrancy beyond whatever the underlying C library does, except in
-cases where doing so is necessary to maintain the consistency of the
-Lisp image. For example, the bindings to the user and group database
-accessing functions are neither thread-safe nor reentrant unless the
-underlying libc happens to make them so (but @pxref{Extensions to
-POSIX}).
+Sb-posix functions do not implicitly take measures to provide
+thread-safety or reentrancy beyond whatever the underlying C library
+does, except in cases where doing so is necessary to maintain the
+consistency of the Lisp image. For example, the bindings to the user
+and group database accessing functions are neither thread-safe nor
+reentrant unless the underlying libc happens to make them so (but
+see @ref{sb posix extensions to posix}).
-@menu
-* Lisp names for C names::
-* Types::
-* Function Parameters::
-* Function Return Values::
-* Lisp objects and C structures::
-* Functions with idiosyncratic bindings::
-* Extensions to POSIX::
-@end menu
+@node sb posix lisp names
+@subsection Lisp names for C names
-
-@node Lisp names for C names
-@subsection Lisp names for C names
-
-All symbols are in the @code{SB-POSIX} package. This package contains a
+All symbols are in the @code{sb-posix} package. This package contains a
Lisp function for each supported Unix system call or function, a
-variable or constant for each supported Unix constant, an object type
-for each supported Unix structure type, and a slot name for each
-supported Unix structure member. A symbol name is derived from the C
-binding's name, by (a) uppercasing, then (b) removing leading
+variable or constant for each supported Unix constant, an object
+type for each supported Unix structure type, and a slot name for
+each supported Unix structure member. A symbol name is derived from
+the C binding's name, by (a) uppercasing, then (b) removing leading
underscores (@code{#\_}) then replacing remaining underscore characters
with the hyphen (@code{#\-}). The requirement to uppercase is so that in
a standard upcasing reader the user may write @code{sb-posix:creat}
instead of @code{sb-posix:|creat|} as would otherise be required.
-No other changes to ``Lispify'' symbol names are made, so @code{creat()}
-becomes @code{CREAT}, not @code{CREATE}.
+No other changes to "Lispify" symbol names are made, so
+@code{creat} becomes @code{CREAT}, not @code{CREATE}.
-The user is encouraged not to @code{(USE-PACKAGE :SB-POSIX)} but instead
-to use the @code{SB-POSIX:} prefix on all references, as some of the
-symbols symbols contained in the SB-POSIX package have the same name as
-CL symbols (@code{OPEN}, @code{CLOSE}, @code{SIGNAL} etc).
+The user is encouraged not to @code{(use-package :sb-posix)} but instead
+to use the @code{sb-posix:} prefix on all references, as some of the
+symbols symbols contained in the @code{sb-posix} package have the same
+name as CL symbols (e.g. @code{open}, @code{close}, @code{signal}). Also, see
+@ref{package local nicknames}.
-@node Types
+@node sb posix types
@subsection Types
+@menu
+* File-descriptors: sb posix file descriptors.
+* Filenames: sb posix filenames.
+@end menu
+
Generally, marshalling between Lisp and C data types is done using
-SBCL's FFI. @xref{Foreign Function Interface}.
+SBCL's FFI. See @ref{foreign function interface}.
-Some functions accept objects such as filenames or file descriptors. In
-the C binding to POSIX these are represented as strings and small
-integers respectively. For the Lisp programmer's convenience we
-introduce designators such that CL pathnames or open streams can be
-passed to these functions. For example, @code{rename} accepts both
-pathnames and strings as its arguments.
+Some functions accept objects such as filenames or file descriptors.
+In the C binding to POSIX, these are represented as strings and
+small integers respectively. For the Lisp programmer's convenience
+we introduce designators such that CL pathnames or open streams can
+be passed to these functions. For example, @code{sb-posix:rename} accepts
+both pathnames and strings as its arguments.
-@menu
-* File-descriptors::
-* Filenames::
-@end menu
-
-@node File-descriptors
+@node sb posix file descriptors
@subsubsection File-descriptors
-@include type-sb-posix-file-descriptor.texinfo
-@include type-sb-posix-file-descriptor-designator.texinfo
-@include fun-sb-posix-file-descriptor.texinfo
+@anchor{Type sb-posix file-descriptor}
+@ttindex @sortas{file-descriptor sb-posix} file-descriptor [sb-posix]
+@deffn{Type} sb-posix:file-descriptor
+A @code{fixnum} designating a native file descriptor.
-@node Filenames
+@code{sb-sys:make-fd-stream} can be used to construct a @code{file-stream} associated with a
+native file descriptor.
+
+Note that mixing I/O operations on a @code{file-stream} with operations directly on its
+descriptor may produce unexpected results if the stream is buffered.
+@end deffn
+@anchor{Type sb-posix file-descriptor-designator}
+@ttindex @sortas{file-descriptor-designator sb-posix} file-descriptor-designator [sb-posix]
+@deffn{Type} sb-posix:file-descriptor-designator
+Designator for a @code{file-descriptor}: either a fixnum designating
+itself, or a @code{file-stream} designating the underlying file-descriptor.
+@end deffn
+@anchor{Function sb-posix file-descriptor}
+@ffindex @sortas{file-descriptor sb-posix} file-descriptor [sb-posix]
+@deffn{Function} sb-posix:file-descriptor file-descriptor
+Converts @code{file-descriptor-designator} into a @code{file-descriptor}.
+@end deffn
+@node sb posix filenames
@subsubsection Filenames
-@include type-sb-posix-filename.texinfo
-@include type-sb-posix-filename-designator.texinfo
-@include fun-sb-posix-filename.texinfo
+@anchor{Type sb-posix filename}
+@ttindex @sortas{filename sb-posix} filename [sb-posix]
+@deffn{Type} sb-posix:filename
+A @code{string} designating a filename in native namestring syntax.
-@node Function Parameters
+Note that native namestring syntax is distinct from Lisp namestring syntax:
+
+@example
+(pathname "/foo*/bar")
+@end example
+
+is a wild pathname with a pattern-matching directory component.
+@code{sb-ext:parse-native-namestring} may be used to construct Lisp pathnames that
+denote POSIX filenames as understood by system calls, and
+@code{sb-ext:native-namestring} can be used to coerce them into strings in the native
+namestring syntax.
+
+Note also that POSIX filename syntax does not distinguish the names of files
+from the names of directories: in order to parse the name of a directory in
+POSIX filename syntax into a pathname @code{my-defaults} for which
+
+@example
+(merge-pathnames (make-pathname :name "FOO" :case :common)
+ my-defaults)
+@end example
+
+returns a pathname that denotes a file in the directory, supply a true
+@code{:as-directory} argument to @code{sb-ext:parse-native-namestring}. Likewise, to supply
+the name of a directory to a POSIX function in non-directory syntax, supply a
+true @code{:as-file} argument to @code{sb-ext:native-namestring}.
+@end deffn
+@anchor{Type sb-posix filename-designator}
+@ttindex @sortas{filename-designator sb-posix} filename-designator [sb-posix]
+@deffn{Type} sb-posix:filename-designator
+Designator for a @code{filename}: a @code{string} designating itself, or a
+designator for a @code{pathname} designating the corresponding native namestring.
+@end deffn
+@anchor{Function sb-posix filename}
+@ffindex @sortas{filename sb-posix} filename [sb-posix]
+@deffn{Function} sb-posix:filename filename
+Converts @code{filename-designator} into a @code{filename}.
+@end deffn
+@node sb posix function parameters
@subsection Function Parameters
-The calling convention is modelled after that of CMUCL's @code{UNIX}
+The calling convention is modelled after that of CMUCL's @code{unix}
package: in particular, it's like the C interface except that:
-@enumerate a
-@item
-Length arguments are omitted or optional where the sensible value
-is obvious. For example, @code{read} would be defined this way:
+@itemize
+@item Length arguments are omitted or optional where the sensible value
+ is obvious. For example, @code{read} would be defined this way:
-@lisp
+@example
(read fd buffer &optional (length (length buffer))) => bytes-read
-@end lisp
+@end example
-@item
-Where C simulates ``out'' parameters using pointers (for instance, in
-@code{pipe()} or @code{socketpair()}) these may be optional or omitted
-in the Lisp interface: if not provided, appropriate objects will be
-allocated and returned (using multiple return values if necessary).
+@item Where C simulates "out" parameters using pointers (for instance,
+ in @code{pipe(2)} or @code{socketpair(2)}), these may be optional or omitted
+ in the Lisp interface: if not provided, appropriate objects will
+ be allocated and returned (using multiple return values if
+ necessary).
-@item
-Some functions accept objects such as filenames or file descriptors.
-Wherever these are specified as such in the C bindings, the Lisp
-interface accepts designators for them as specified in the 'Types'
-section above.
+@item Some functions accept objects such as filenames or file
+ descriptors. Wherever these are specified as such in the C
+ bindings, the Lisp interface accepts designators for them as
+ specified in the @ref{sb posix types} section above.
-@item
-A few functions have been included in sb-posix that do not correspond
-exactly with their C counterparts. These are described in
-@xref{Functions with idiosyncratic bindings}.
+@item A few functions have been included in sb-posix that do not
+ correspond exactly with their C counterparts. These are described
+ in @ref{sb posix idiosyncracies}.
+@end itemize
-@end enumerate
-
-@node Function Return Values
-@subsection Function Return Values
+@node sb posix function return values
+@subsection Function Return Values
The return value is usually the same as for the C binding, except in
-error cases: where the C function is defined as returning some sentinel
-value and setting @code{errno} on error, we instead signal an error of
-type @code{SYSCALL-ERROR}. The actual error value (@code{errno}) is
-stored in this condition and can be accessed with @code{SYSCALL-ERRNO}.
+error cases: where the C function is defined as returning some
+sentinel value and setting @code{errno} on error, we instead signal an
+error of type @code{sb-posix:syscall-error}. The actual error
+value (@code{errno}) is stored in this condition and can be accessed with
+@code{sb-posix:syscall-errno}.
-We do not automatically translate the returned value into ``Lispy''
-objects -- for example, @code{SB-POSIX:OPEN} returns a small integer,
-not a stream. Exception: boolean-returning functions (or, more
-commonly, macros) do not return a C integer, but instead a Lisp
-boolean.
+We do not automatically translate the returned value into lispy
+objects -- for example, @code{sb-posix:open} returns a small integer, not a
+stream. Exception: boolean-returning functions (or, more commonly,
+macros) do not return a C integer but instead a Lisp boolean.
-@node Lisp objects and C structures
-@subsection Lisp objects and C structures
+@node sb posix lisp objects and c structures
+@subsection Lisp Objects and C structures
Sb-posix provides various Lisp object types to stand in for C
-structures in the POSIX library. Lisp bindings to C functions that
+structures in the POSIX library. Lisp bindings to C functions that
accept, manipulate, or return C structures accept, manipulate, or
return instances of these Lisp types instead of instances of alien
types.
-The names of the Lisp types are chosen according to the general rules
-described above. For example Lisp objects of type @code{STAT} stand
-in for C structures of type @code{struct stat}.
-
-Accessors are provided for each standard field in the structure. These
-are named @code{@var{structure-name}-@var{field-name}} where the two
-components are chosen according to the general name conversion rules,
-with the exception that in cases where all fields in a given structure
-have a common prefix, that prefix is omitted. For example,
-@code{stat.st_dev} in C becomes @code{STAT-DEV} in Lisp.
-
-@c This was in the README, but it proves to be false about sb-posix.
-@ignore
-For each Lisp object type corresponding to a C structure type, there
-is a @code{make-@var{structure-name}} function that takes keyword
-arguments with names deriving from each documented field name
-according to the name conversion rules for accessors.
-@end ignore
+The names of the Lisp types are chosen according to the general
+rules described above. For example Lisp objects of type
+@code{sb-posix:stat} stand in for C structures of type @code{struct stat}.
+Accessors are provided for each standard field in the structure.
+These are named @code{<structure-name>-<field-name>} where the two
+components are chosen according to the general name conversion
+rules, with the exception that in cases where all fields in a given
+structure have a common prefix, that prefix is omitted. For example,
+@code{stat.st_dev} in C becomes @code{stat-dev} in Lisp.
Because sb-posix might not support all semi-standard or
-implementation-dependent members of all structure types on your system
-(patches welcome), here is an enumeration of all supported Lisp
-objects corresponding to supported POSIX structures, and the supported
-slots for those structures.
+implementation-dependent members of all structure types on your
+system (patches welcome), here is an enumeration of all supported
+Lisp objects corresponding to supported POSIX structures, and the
+supported slots for those structures.
-@include class-sb-posix-flock.texinfo
-@include class-sb-posix-passwd.texinfo
-@include class-sb-posix-group.texinfo
-@include class-sb-posix-stat.texinfo
-@include class-sb-posix-termios.texinfo
-@include class-sb-posix-timeval.texinfo
-
-@node Functions with idiosyncratic bindings
-@subsection Functions with idiosyncratic bindings
+@anchor{Class sb-posix flock}
+@ttindex @sortas{flock sb-posix} flock [sb-posix]
+@deffn{Class} sb-posix:flock
+Class representing locks used in @code{fcntl(2)}.
+@end deffn
+@anchor{Class sb-posix passwd}
+@ttindex @sortas{passwd sb-posix} passwd [sb-posix]
+@deffn{Class} sb-posix:passwd
+Instances of this class represent entries in the system's user database.
+@end deffn
+@anchor{Class sb-posix group}
+@ttindex @sortas{group sb-posix} group [sb-posix]
+@deffn{Class} sb-posix:group
+Instances of this class represent entries in the system's group database.
+@end deffn
+@anchor{Class sb-posix stat}
+@ttindex @sortas{stat sb-posix} stat [sb-posix]
+@deffn{Class} sb-posix:stat
+Instances of this class represent POSIX file metadata.
+@end deffn
+@anchor{Class sb-posix termios}
+@ttindex @sortas{termios sb-posix} termios [sb-posix]
+@deffn{Class} sb-posix:termios
+Instances of this class represent I/O characteristics of the terminal.
+@end deffn
+@anchor{Class sb-posix timeval}
+@ttindex @sortas{timeval sb-posix} timeval [sb-posix]
+@deffn{Class} sb-posix:timeval
+Instances of this class represent time values.
+@end deffn
+@node sb posix idiosyncracies
+@subsection Functions with Idiosyncratic Bindings
A few functions in sb-posix don't correspond directly to their C
counterparts.
-@include fun-sb-posix-getcwd.texinfo
-@include fun-sb-posix-readlink.texinfo
-@include fun-sb-posix-syslog.texinfo
-
-
-@node Extensions to POSIX
+@anchor{Function sb-posix getcwd}
+@ffindex @sortas{getcwd sb-posix} getcwd [sb-posix]
+@deffn{Function} sb-posix:getcwd
+Returns the process's current working directory as a string.
+@end deffn
+@anchor{Function sb-posix readlink}
+@ffindex @sortas{readlink sb-posix} readlink [sb-posix]
+@deffn{Function} sb-posix:readlink pathspec
+Returns the resolved target of a symbolic link as a string.
+@end deffn
+@anchor{Function sb-posix syslog}
+@ffindex @sortas{syslog sb-posix} syslog [sb-posix]
+@deffn{Function} sb-posix:syslog priority format &rest args
+Send a message to the syslog facility, with severity level
+@code{priority}. The message will be formatted as by @code{cl:format} (rather
+than C's @code{printf}) with format string @code{format} and arguments @code{args}.
+@end deffn
+@node sb posix extensions to posix
@subsection Extensions to POSIX
Some of POSIX's standardized operators are not safe to use on their
-own, so @code{SB-POSIX} exports a few ``helpers'' that do not
-correspond exactly to functionality present in the POSIX standard.
+own, so @code{sb-posix} exports a few helpers that do not correspond
+exactly to functionality present in the POSIX standard.
-The user and group database accessing routines are not required to be
-thread-safe or reentrant, and so can only be used safely if all
+The user and group database accessing routines are not required to
+be thread-safe or reentrant and so can only be used safely if all
clients coordinate around their use. Since it would be logically
impossible for independently developed programs to coordinate,
-@code{SB-POSIX} exports two iteration macros,
-@code{SB-POSIX:DO-PASSWDS} and
-@code{SB-POSIX:DO-GROUPS}, each of which iterates over the respective
-database while preventing the keyed accesses (@code{SB-POSIX:GETPWNAM},
-@code{SB-POSIX:GETPWUID}, @code{SB-POSIX:GETGRNAM},
-@code{SB-POSIX:GETGRGID})
-from running until iteration completes.
+@code{sb-posix} exports two iteration macros, @code{sb-posix:do-passwds} and
+@code{sb-posix:do-groups}, each of which iterates over the respective
+database while preventing the keyed accesses (@code{sb-posix:getpwnam},
+@code{sb-posix:getpwuid}, @code{sb-posix:getgrnam}, @code{sb-posix:getgrgid}) from
+running until iteration completes.
-@include macro-sb-posix-do-passwds.texinfo
-@include macro-sb-posix-do-groups.texinfo
+@anchor{Macro sb-posix do-passwds}
+@ffindex @sortas{do-passwds sb-posix} do-passwds [sb-posix]
+@deffn{Macro} sb-posix:do-passwds (passwd &optional result) &body body
+Evaluate @code{body} with @code{passwd} bound to successive entries from the passwd
+database, and return @code{result}. An implicit block named @code{nil} surrounds
+the form; an implicit @code{tagbody} surrounds @code{body}. It is unspecified
+whether @code{passwd} is assigned, rebound, or destructively modified upon
+each iteration. It is an error to use any operator that accesses the
+@code{passwd} database during the dynamic extent of @code{do-passwds}.
+@end deffn
+@anchor{Macro sb-posix do-groups}
+@ffindex @sortas{do-groups sb-posix} do-groups [sb-posix]
+@deffn{Macro} sb-posix:do-groups (group &optional result) &body body
+Evaluate @code{body} with @code{group} bound to successive entries from the group
+database, and return @code{result}. An implicit block named @code{nil} surrounds
+the form; an implicit @code{tagbody} surrounds @code{body}. It is unspecified
+whether @code{group} is assigned, rebound, or destructively modified upon
+each iteration. It is an error to use any operator that accesses the
+@code{group} database during the dynamic extent of @code{do-groups}.
+@end deffn
diff --git a/contrib/sb-queue/sb-queue.texinfo b/contrib/sb-queue/sb-queue.texinfo
index 9d74313b9..738bc3392 100644
--- a/contrib/sb-queue/sb-queue.texinfo
+++ b/contrib/sb-queue/sb-queue.texinfo
@@ -1,6 +1,8 @@
-@node sb-queue
+@c Generated by the sb-manual contrib. Do not edit.
+
+@node sb queue
@section sb-queue
-@cindex Queue, FIFO
Since SBCL 1.0.38, the @code{sb-queue} module has been merged into the
-@code{sb-concurrency} module (@pxref{sb-concurrency}.)
+@code{sb-concurrency} module. See @ref{sb concurrency}.
+
diff --git a/contrib/sb-rotate-byte/sb-rotate-byte.texinfo b/contrib/sb-rotate-byte/sb-rotate-byte.texinfo
index 54736e26d..1a095f5ca 100644
--- a/contrib/sb-rotate-byte/sb-rotate-byte.texinfo
+++ b/contrib/sb-rotate-byte/sb-rotate-byte.texinfo
@@ -1,18 +1,22 @@
-@node sb-rotate-byte
+@c Generated by the sb-manual contrib. Do not edit.
+
+@node sb rotate byte
@section sb-rotate-byte
-@cindex Modular arithmetic
-@cindex Arithmetic, modular
-@cindex Arithmetic, hardware
The @code{sb-rotate-byte} module offers an interface to bitwise
-rotation, with an efficient implementation for operations which can be
-performed directly using the platform's arithmetic routines. It
-implements the specification at
-@uref{http://www.cliki.net/ROTATE-BYTE}.
-@comment FIXME: except when someone scribbles all over it. Hmm.
+rotation, with an efficient implementation for operations which can
+be performed directly using the platform's arithmetic routines. It
+implements the specification at @url{http://www.cliki.net/ROTATE-BYTE}.
Bitwise rotation is a component of various cryptographic or hashing
-algorithms: MD5, SHA-1, etc.; often these algorithms are specified on
-32-bit rings. [FIXME cite cite cite].
+algorithms: MD5, SHA-1, etc.; often these algorithms are specified
+on 32-bit rings.
-@include fun-sb-rotate-byte-rotate-byte.texinfo
+@anchor{Function sb-rotate-byte rotate-byte}
+@ffindex @sortas{rotate-byte sb-rotate-byte} rotate-byte [sb-rotate-byte]
+@deffn{Function} sb-rotate-byte:rotate-byte count bytespec integer
+Rotates a field of bits within @code{integer}; specifically, returns an
+integer that contains the bits of @code{integer} rotated @code{count} times
+leftwards within the byte specified by @code{bytespec}, and elsewhere
+contains the bits of @code{integer}.
+@end deffn
diff --git a/contrib/sb-simple-streams/sb-simple-streams.texinfo b/contrib/sb-simple-streams/sb-simple-streams.texinfo
index 44ba91426..41403c01d 100644
--- a/contrib/sb-simple-streams/sb-simple-streams.texinfo
+++ b/contrib/sb-simple-streams/sb-simple-streams.texinfo
@@ -1,25 +1,27 @@
+@c Generated by the sb-manual contrib. Do not edit.
+
+@node sb simple streams
+@section Simple Streams
+
Simple streams are an extensible streams protocol that avoids some
-problems with Gray streams.
+problems with @ref{gray streams}.
Documentation about simple streams is available at:
-@uref{http://www.franz.com/support/documentation/6.2/doc/streams.htm}
+@url{http://www.franz.com/support/documentation/6.2/doc/streams.htm}
The implementation should be considered Alpha-quality; the basic
framework is there, but many classes are just stubs at the moment.
-See @file{SYS:CONTRIB;SB-SIMPLE-STREAMS;SIMPLE-STREAM-TEST.LISP} for
+See @code{SYS:CONTRIB;SB-SIMPLE-STREAMS;SIMPLE-STREAM-TEST.LISP} for
things that should work.
Known differences to the ACL behaviour:
@itemize
+@item @code{sb-simple-streams:open} does not return a @code{simple-stream} by
+ default. See its @code{:class} argument.
-@item
-@code{open} not return a simple-stream by default. This can be
-adjusted; see default-open-class in the file cl.lisp
-
-@item
-@code{write-vector} is unimplemented.
-
+@item @code{write-vector} is unimplemented.
@end itemize
+
diff --git a/contrib/sb-sprof/sb-sprof.texinfo b/contrib/sb-sprof/sb-sprof.texinfo
index 2fec2ebac..7a6685fee 100644
--- a/contrib/sb-sprof/sb-sprof.texinfo
+++ b/contrib/sb-sprof/sb-sprof.texinfo
@@ -1,23 +1,28 @@
-@cindex Profiling, statistical
+@c Generated by the sb-manual contrib. Do not edit.
+
+@node statistical profiler
+@section Statistical Profiler
The @code{sb-sprof} module, loadable by
-@lisp
+
+@example
(require :sb-sprof)
-@end lisp
+@end example
+
provides an alternate profiler which works by taking samples of the
program execution at regular intervals, instead of instrumenting
-functions like @code{sb-profile:profile} does. You might find
-@code{sb-sprof} more useful than the deterministic profiler when profiling
-functions in the @code{common-lisp}-package, SBCL internals, or code
-where the instrumenting overhead is excessive.
+functions as @code{sb-profile:profile} does. You might find @code{sb-sprof} more
+useful than the deterministic profiler when profiling functions in the
+@code{common-lisp} package, SBCL internals, or code where the instrumenting
+overhead is excessive.
Additionally @code{sb-sprof} includes a limited deterministic profiler
which can be used for reporting the amounts of calls to some functions
during
-@subsection Example Usage
+@strong{Example usage:}
-@lisp
+@example
(in-package :cl-user)
(require :sb-sprof)
@@ -71,15 +76,15 @@ during
:mode :alloc
:report :flat)
(bar 1000))
-@end lisp
+@end example
-@subsection Output
+@strong{Output:}
The flat report format will show a table of all functions that the
-profiler encountered on the call stack during sampling, ordered by the
-number of samples taken while executing that function.
+profiler encountered on the call stack during sampling, ordered by
+the number of samples taken while executing that function.
-@lisp
+@example
Self Total Cumul
Nr Count % Count % Count % Calls Function
------------------------------------------------------------------------
@@ -87,26 +92,26 @@ number of samples taken while executing that function.
2 64 22.6 64 22.6 133 47.0 - SB-VM::GENERIC-+
3 39 13.8 256 90.5 172 60.8 1 CPU-TEST
4 31 11.0 31 11.0 203 71.7 - SB-KERNEL:TWO-ARG-XOR
-@end lisp
+@end example
For each function, the table will show three absolute and relative
-sample counts. The Self column shows samples taken while directly
-executing that function. The Total column shows samples taken while
-executing that function or functions called from it (sampled to a
-platform-specific depth). The Cumul column shows the sum of all
-Self columns up to and including that line in the table.
+sample counts. The @code{Self} column shows samples taken while directly
+executing that function. The @code{Total} column shows samples taken
+while executing that function or functions called from it (sampled
+to a platform-specific depth). The @code{Cumul} column shows the sum of
+all @code{Self} columns up to and including that line in the table.
-Additionally the Calls column will record the amount of calls that were
-made to the function during the profiling run. This value will only
-be reported for functions that have been explicitly marked for call counting
-with @code{profile-call-counts}.
+Additionally the @code{Calls} column will record the amount of calls that
+were made to the function during the profiling run. This value will
+only be reported for functions that have been explicitly marked for
+call counting with @code{sb-sprof:profile-call-counts}.
-The profiler also hooks into the disassembler such that instructions which
-have been sampled are annotated with their relative frequency of
-sampling. This information is not stored across different sampling
-runs.
+The profiler also hooks into the disassembler such that instructions
+which have been sampled are annotated with their relative frequency
+of sampling. This information is not stored across different
+sampling runs.
-@lisp
+@example
; 6CF: 702E JO L4 ; 6/242 samples
; 6D1: D1E3 SHL EBX, 1
; 6D3: 702A JO L4
@@ -114,44 +119,231 @@ runs.
; 6D8: 756D JNE L8
; 6DA: 8BC3 MOV EAX, EBX ; 5/242 samples
; 6DC: L3: 83F900 CMP ECX, 0 ; 4/242 samples
-@end lisp
+@end example
-@subsection Platform support
+@strong{Platform support}
-Allocation profiling is only supported on SBCL builds that use
-the generational garbage collector. Tracking of call stacks at a
-depth of more than two levels is only supported on x86 and x86-64.
+Allocation profiling is only supported on SBCL builds that use the
+generational garbage collector. Tracking of call stacks at a depth
+of more than two levels is only supported on x86 and x86-64.
-@subsection Macros
+@strong{Macros}
-@include macro-sb-sprof-with-profiling.texinfo
-@include macro-sb-sprof-with-sampling.texinfo
+@anchor{Macro sb-sprof with-profiling}
+@ffindex @sortas{with-profiling sb-sprof} with-profiling [sb-sprof]
+@deffn{Macro} sb-sprof:with-profiling (&key sample-interval alloc-interval max-samples reset mode loop max-depth show-progress threads report) &body body
+Evaluate @code{body} with statistical profiling turned on. If @code{loop} is true,
+loop around the @code{body} until a sufficient number of samples has been collected.
+Returns the values from the last evaluation of @code{body}.
-@subsection Functions
+The following keyword args are recognized:
-@include fun-sb-sprof-map-traces.texinfo
+@itemize
+@item @code{:sample-interval} @code{<n>}
-@include fun-sb-sprof-sample-pc.texinfo
+Take a sample every <n> seconds. Default is @code{*sample-interval*}.
-@include fun-sb-sprof-report.texinfo
+@item @code{:mode} @code{<mode>}
-@include fun-sb-sprof-reset.texinfo
+If @code{:cpu}, run the profiler in CPU profiling mode. If @code{:alloc}, run
+the profiler in allocation profiling mode. If @code{:time}, run the
+profiler in wallclock profiling mode.
-@include fun-sb-sprof-start-profiling.texinfo
+@item @code{:max-samples} @code{<max>}
-@include fun-sb-sprof-stop-profiling.texinfo
+If @code{:loop} is @code{nil} (the default), collect no more than @code{<max>}
+samples. If @code{:loop} is @code{t}, repeat evaluating body until @code{<max>}
+samples are taken. Default is @code{*max-samples*}.
-@include fun-sb-sprof-profile-call-counts.texinfo
+@item @code{:report} @code{<type>}
-@include fun-sb-sprof-unprofile-call-counts.texinfo
+If specified, call @code{report} with @code{:type} @code{<type>} at the end.
-@subsection Variables
+@item @code{:reset} @code{<bool>}
-@include var-sb-sprof-star-max-samples-star.texinfo
+If true, call @code{reset} at the beginning.
-@include var-sb-sprof-star-sample-interval-star.texinfo
+@item @code{:threads} @code{<list-form>}
-@subsection Credits
+Form that evaluates to the list threads to profile, or @code{:all} to
+indicate that all threads should be profiled. Defaults to all
+threads.
+
+@code{:threads} has no effect on call-counting at the moment.
+
+On some platforms (e.g. Darwin) the signals used by the profiler
+are not properly delivered to threads in proportion to their CPU
+usage when doing @code{:cpu} profiling. If you see empty call graphs, or
+are obviously missing several samples from certain threads, you
+may be falling afoul of this. In this case using @code{:mode} @code{:time} is
+likely to work better.
+
+@item @code{:loop} @code{<bool>}
+
+If false (the default), evaluate @code{body} only once. If true
+repeatedly evaluate @code{body}.
+@end itemize
+@end deffn
+@anchor{Macro sb-sprof with-sampling}
+@ffindex @sortas{with-sampling sb-sprof} with-sampling [sb-sprof]
+@deffn{Macro} sb-sprof:with-sampling (&optional on) &body body
+Evaluate body with statistical sampling turned on or off in the current thread.
+@end deffn
+@strong{Functions}
+
+@anchor{Function sb-sprof map-traces}
+@ffindex @sortas{map-traces sb-sprof} map-traces [sb-sprof]
+@deffn{Function} sb-sprof:map-traces function samples
+Call @code{function} on each trace in @code{samples}
+
+The signature of @code{function} must be compatible with (thread trace).
+
+@code{function} is called once for each trace where @code{thread} is the
+@code{sb-thread:thread} instance that was sampled to produce @code{trace}, and @code{trace}
+is an opaque object to be passed to @code{map-trace-pc-locs}.
+
+EXPERIMENTAL: Interface subject to change.
+@end deffn
+@anchor{Function sb-sprof sample-pc}
+@ffindex @sortas{sample-pc sb-sprof} sample-pc [sb-sprof]
+@deffn{Function} sb-sprof:sample-pc info pc-or-offset
+Extract and return program counter from @code{info} and @code{pc-or-offset}.
+
+Can be applied to the arguments passed by @code{map-trace-pc-locs} and
+@code{map-all-pc-locs}.
+
+EXPERIMENTAL: Interface subject to change.
+@end deffn
+@anchor{Function sb-sprof report}
+@ffindex @sortas{report sb-sprof} report [sb-sprof]
+@deffn{Function} sb-sprof:report &key type max min-percent call-graph sort-by sort-order stream show-progress
+Report statistical profiling results. The following keyword
+ args are recognized:
+
+@itemize
+@item @code{:type} @code{<type>}
+
+Specifies the type of report to generate. If @code{:flat}, show flat
+report, if @code{:graph} show a call graph and a flat report. If nil,
+don't print out a report.
+
+@item @code{:stream} @code{<stream>}
+
+Specify a stream to print the report on. Default is
+@code{*standard-output*}.
+
+@item @code{:max} @code{<max>}
+
+Don't show more than @code{<max>} entries in the flat report.
+
+@item @code{:min-percent} @code{<min-percent>}
+
+Don't show functions taking less than @code{<min-percent>} of the
+total time in the flat report.
+
+@item @code{:sort-by} @code{<column>}
+
+If @code{:samples}, sort flat report by number of samples taken.
+If @code{:cumulative-samples}, sort flat report by cumulative number of samples
+taken (shows how much time each function spent on stack.) Default
+is @code{*report-sort-by*}.
+
+@item @code{:sort-order} @code{<order>}
+
+If @code{:descending}, sort flat report in descending order. If @code{:ascending},
+sort flat report in ascending order. Default is @code{*report-sort-order*}.
+
+@item @code{:show-progress} @code{<bool>}
+
+ If true, print progress messages while generating the call graph.
+
+@item @code{:call-graph} @code{<graph>}
+
+ Print a report from @code{<graph>} instead of the latest profiling
+ results.
+@end itemize
+
+Value of this function is a @code{call-graph} object representing the
+resulting call-graph, or @code{nil} if there are no samples (e.g. right after
+calling @code{reset}.)
+
+Profiling is stopped before the call graph is generated.
+@end deffn
+@anchor{Function sb-sprof reset}
+@ffindex @sortas{reset sb-sprof} reset [sb-sprof]
+@deffn{Function} sb-sprof:reset
+Reset the profiler.
+@end deffn
+@anchor{Function sb-sprof start-profiling}
+@ffindex @sortas{start-profiling sb-sprof} start-profiling [sb-sprof]
+@deffn{Function} sb-sprof:start-profiling &key max-samples mode sample-interval alloc-interval max-depth threads
+Start profiling statistically in the current thread if not already profiling.
+The following keyword args are recognized:
+
+@itemize
+@item @code{:sample-interval} @code{<n>}
+
+Take a sample every @code{<n>} seconds. Default is @code{*sample-interval*}.
+
+@item @code{:mode} @code{<mode>}
+
+If @code{:cpu}, run the profiler in CPU profiling mode. If @code{:alloc}, run
+the profiler in allocation profiling mode. If @code{:time}, run the
+profiler in wallclock profiling mode.
+
+@item @code{:max-samples} @code{<max>}
+
+Maximum number of stack traces to collect. Default is
+@code{*max-samples*}.
+
+@item @code{:threads} @code{<list>}
+
+List threads to profile, or @code{:all} to indicate that all threads
+should be profiled. Defaults to @code{:all}.
+
+@code{:threads} has no effect on call-counting at the moment.
+
+On some platforms (e.g. Darwin) the signals used by the profiler
+are not properly delivered to threads in proportion to their CPU
+usage when doing @code{:cpu} profiling. If you see empty call graphs, or
+are obviously missing several samples from certain threads, you
+may be falling afoul of this.
+@end itemize
+@end deffn
+@anchor{Function sb-sprof stop-profiling}
+@ffindex @sortas{stop-profiling sb-sprof} stop-profiling [sb-sprof]
+@deffn{Function} sb-sprof:stop-profiling
+Stop profiling if profiling.
+@end deffn
+@anchor{Function sb-sprof profile-call-counts}
+@ffindex @sortas{profile-call-counts sb-sprof} profile-call-counts [sb-sprof]
+@deffn{Function} sb-sprof:profile-call-counts &rest names
+Mark the functions named by @code{names} as being subject to call counting
+during statistical profiling. If a string is used as a name, it will
+be interpreted as a package name. In this case call counting will be
+done for all functions with names like @code{x} or @code{(setf x)}, where @code{x} is
+a symbol with the package as its home package.
+@end deffn
+@anchor{Function sb-sprof unprofile-call-counts}
+@ffindex @sortas{unprofile-call-counts sb-sprof} unprofile-call-counts [sb-sprof]
+@deffn{Function} sb-sprof:unprofile-call-counts
+Clear all call counting information. Call counting will be done for no
+functions during statistical profiling.
+@end deffn
+@strong{Variables}
+
+@anchor{Variable sb-sprof *max-samples*}
+@vvindex @sortas{max-samples* sb-sprof} *max-samples* [sb-sprof]
+@deffn{Variable} sb-sprof:*max-samples*
+Default maximum number of stack traces collected.
+@end deffn
+@anchor{Variable sb-sprof *sample-interval*}
+@vvindex @sortas{sample-interval* sb-sprof} *sample-interval* [sb-sprof]
+@deffn{Variable} sb-sprof:*sample-interval*
+Default number of seconds between samples.
+@end deffn
+@strong{Credits}
+
+@code{sb-sprof} is an SBCL port, with enhancements, of Gerd Moellmann's
+statistical profiler for CMUCL.
-@code{sb-sprof} is an SBCL port, with enhancements, of Gerd
-Moellmann's statistical profiler for CMUCL.
diff --git a/doc/manual/.gitignore b/doc/manual/.gitignore
index 1d1476538..ff13bfc84 100644
--- a/doc/manual/.gitignore
+++ b/doc/manual/.gitignore
@@ -28,5 +28,6 @@ sbcl.info*
sbcl.pdf
sbcl.ps
sbcl/
+sbcl-contento.texinfo
variables.texinfo
generated-texinfo-stamp
diff --git a/doc/manual/README b/doc/manual/README
index 24385c503..1b9939862 100644
--- a/doc/manual/README
+++ b/doc/manual/README
@@ -1,6 +1,5 @@
-With the exception of sbcl.texinfo, backmatter.texinfo,
-sbcl-menu.texinf and sbcl-contents.texinfo all other Texinfo files are
-from SB-MANUAL::GENERATE-TEXINFO.
+With the exception of sbcl.texinfo, backmatter.texinfo, all other
+Texinfo files are from SB-MANUAL::GENERATE-TEXINFO.
With the exception of variables.texinfo, the generated files are under
version control, to keep a closer eye on the Markdown-to-Texinfo
diff --git a/doc/manual/beyond-ansi.texinfo b/doc/manual/beyond-ansi.texinfo
index 6ffb2cbfe..8bef4aae5 100644
--- a/doc/manual/beyond-ansi.texinfo
+++ b/doc/manual/beyond-ansi.texinfo
@@ -1,152 +1,129 @@
-@node Beyond the ANSI Standard
-@comment node-name, next, previous, up
+@c Generated by the sb-manual contrib. Do not edit.
+
+@node beyond the ansi standard
@chapter Beyond the ANSI Standard
+@menu
+* Reader Extensions: reader extensions.
+* Package-Local Nicknames: package local nicknames.
+* Package Variance: package variance.
+* Garbage Collection: garbage collection.
+* Generic Function Dispatch: generic function dispatch.
+* Extended Slot Access: extended slot access.
+* Metaobject Protocol: metaobject protocol.
+* Extensible Sequences: extensible sequences.
+* Support For Unix: support for unix.
+* Unicode Support: unicode support.
+* Customization Hooks for Users: customization hooks for users.
+* Tools To Help Developers: tools to help developers.
+* Resolution of Name Conflicts: resolution of name conflicts.
+* Hash Table Extensions: hash table extensions.
+* Random Number Generation: random number generation.
+* Timeouts and Deadlines: timeouts and deadlines.
+* Miscellaneous Extensions: miscellaneous extensions.
+* Stale Extensions: stale extensions.
+* Efficiency Hacks: efficiency hacks.
+@end menu
+
SBCL is derived from CMUCL, which implements many extensions to the
ANSI standard. SBCL doesn't support as many extensions as CMUCL, but
-it still has quite a few. @xref{Contributed Modules}.
+it still has quite a few. See @ref{contributed modules}.
-@menu
-* Reader Extensions::
-* Package-Local Nicknames::
-* Package Variance::
-* Garbage Collection::
-* Generic Function Dispatch::
-* Slot Access::
-* Metaobject Protocol::
-* Extensible Sequences::
-* Support For Unix::
-* Unicode Support::
-* Customization Hooks for Users::
-* Tools To Help Developers::
-* Resolution of Name Conflicts::
-* Hash Table Extensions::
-* Random Number Generation::
-* Timeouts and Deadlines::
-* Miscellaneous Extensions::
-* Stale Extensions::
-* Efficiency Hacks::
-@end menu
-
-@node Reader Extensions
-@comment node-name, next, previous, up
+@node reader extensions
@section Reader Extensions
-@cindex Reader Extensions
+@menu
+* Extended Package Prefix Syntax: extended package prefix syntax.
+* Symbol Name Normalization: symbol name normalization.
+* Decimal Syntax for Rationals: decimal syntax for rationals.
+@end menu
+
+@node extended package prefix syntax
@subsection Extended Package Prefix Syntax
-@cindex Extended Package Prefix Syntax
-@cindex Package Prefix Syntax, extended
-@vindex @cl{@earmuffs{package}}
-@cindex Interning Symbols
-@cindex Symbols, interning
-@findex @cl{intern}
SBCL supports extended package prefix syntax, which allows specifying
-an alternate package instead of @code{*package*} for the reader to use
-as the default package for interning symbols:
+an alternate package instead of @code{*package*} for the reader to use as
+the default package for interning symbols:
-@lisp
-@var{package-name}::@var{form-with-interning-into-package}
-@end lisp
+@example
+<package-name>::<form-with-interning-into-package>
+@end example
Example:
-@lisp
- 'foo::(bar quux zot) == '(foo::bar foo::quux foo::zot)
-@end lisp
+@example
+'foo::(bar quux zot) == '(foo::bar foo::quux foo::zot)
+@end example
-@cindex Package Locks
-@vindex @cl{@earmuffs{package}}
-@code{*package*} is not rebound during the course of reading a form
-with extended package prefix syntax; if @code{foo::bar} would cause a
+@code{*package*} is not rebound during the course of reading a form with
+extended package prefix syntax; if @code{foo::bar} would cause a
read-time package lock violation, so does @code{foo::(bar)}.
+@node symbol name normalization
@subsection Symbol Name Normalization
-@cindex Symbol Name Normalization
-@cindex Normalization, Symbol Name
-@cindex Unicode
-@cindex NFKC
-SBCL also extends the reader to normalize all symbols to Normalization
-Form KC in builds with Unicode enabled. Whether symbols are normalized
-is controlled by
+SBCL also extends the reader to normalize all symbols to @emph{Normalization
+Form KC} in builds with Unicode enabled. Whether symbols are
+normalized is controlled by
-@include fun-sb-ext-readtable-normalization.texinfo
-
-Symbols created by
-@findex @cl{intern}
-@code{intern} and similar functions are not affected by this setting. If
-@code{sb-ext:readtable-normalization} is @code{t}, symbols that are not
-normalized are escaped during printing.
+@anchor{Function sb-ext readtable-normalization}
+@ffindex @sortas{readtable-normalization sb-ext} readtable-normalization [sb-ext]
+@deffn{Function} sb-ext:readtable-normalization readtable
+Returns @code{t} if @code{readtable} normalizes symbols to NFKC, and @code{nil} otherwise.
+The @code{readtable-normalization} of the standard readtable is @code{t}.
+@end deffn
+Symbols created by @code{intern} and similar functions are not affected by
+this setting. If @code{sb-ext:readtable-normalization} is @code{t}, symbols that
+are not normalized are escaped during printing.
+@node decimal syntax for rationals
@subsection Decimal Syntax for Rationals
-@cindex Decimal Syntax for Rationals
-@cindex Rational, decimal syntax for
-@tindex @cl{float}
SBCL supports a decimal syntax for rationals, modelled after the
-standard syntax for floating-point numbers. If a number with
-floating-point syntax has an exponent marker of @code{r} or @code{R}
-(rather than one of the standard exponent markers), it is read as the
-rational with the exact value of the decimal number expressed as a
-float.
+standard syntax for floating-point numbers. If a number with
+floating-point syntax has an exponent marker of @code{r} or @code{r}
+(rather than one of the standard exponent markers), it is read as
+the rational with the exact value of the decimal number expressed as
+a float.
-@vindex @cl{@earmuffs{read-default-float-format}}
-@tindex @cl{rational}
-@findex @cl{read}
-@findex @cl{read-from-string}
In addition, setting or binding the value of
-@code{*read-default-float-format*} to @code{rational} around a call to
-@code{read} or @code{read-from-string} has the effect that
-floating-point numbers without exponent markers are read as rational
-numbers, as if there had been an explicit @code{r} or @code{R} marker.
+@code{*read-default-float-format*} to @code{rational} around a call to @code{read} or
+@code{read-from-string} has the effect that floating-point numbers without
+exponent markers are read as rational numbers, as if there had been
+an explicit @code{r} or @code{r} marker.
-@vindex @cl{@earmuffs{read-default-float-format}}
-@tindex @cl{rational}
Floating point numbers of all types are printed with an exponent
-marker while the value of @code{*read-default-float-format*} is
-@code{rational}; however, rational numbers are printed in their
-standard syntax, irrespective of the value of
-@code{*read-default-float-format*}.
+marker while the value of @code{*read-default-float-format*} is @code{rational};
+however, rational numbers are printed in their standard syntax,
+irrespective of the value of @code{*read-default-float-format*}.
-@node Package-Local Nicknames
-@comment node-name, next, previous, up
+@node package local nicknames
@section Package-Local Nicknames
-@cindex Package-Local Nicknames
-@cindex Nicknames, Package-local
SBCL allows giving packages local nicknames: they allow short and
easy-to-use names to be used without fear of name conflict associated
with normal nicknames.
A local nickname is valid only when inside the package for which it
-has been specified. Different packages can use same local nickname for
-different global names, or different local nickname for same global
-name.
+has been specified. Different packages can use same local nickname
+for different global names, or different local nickname for same
+global name.
-@vindex @cl{@earmuffs{features}}
-Symbol @code{:package-local-nicknames} in @code{*features*} denotes
-the support for this feature.
+The symbol @code{:package-local-nicknames} in @code{*features*} denotes the
+support for this feature.
-@findex @cl{defpackage}
-@defmac @cl{defpackage} name [[option]]* @result{} package
+@code{defpackage} options are extended to include
-Options are extended to include
+@example
+:local-nicknames (<local-nickname> <actual-package-name>)*
+@end example
-@itemize
-@item
-@code{:local-nicknames (@var{local-nickname} @var{actual-package-name})*}
-
-The package has the specified local nicknames for the corresponding
-actual packages.
-@end itemize
+with the semantics of adding the package package-local nicknames
+@code{<local-nickname>}s for the corresponding @code{<actual-package-name>}s.
Example:
-@findex @cl{find-symbol}
-@findex @cl{find-package}
-@vindex @cl{@earmuffs{package}}
-@lisp
+@example
(defpackage :bar (:intern "X"))
(defpackage :foo (:intern "X"))
(defpackage :quux (:use :cl) (:local-nicknames (:bar :foo) (:foo :bar)))
@@ -156,207 +133,542 @@ Example:
(find-symbol "X" :foo)) ; => BAR::X
(let ((*package* (find-package :quux)))
(find-symbol "X" :bar)) ; => FOO::X
-@end lisp
-@end defmac
+@end example
-@include fun-sb-ext-package-local-nicknames.texinfo
-@include fun-sb-ext-package-locally-nicknamed-by-list.texinfo
-@include fun-sb-ext-add-package-local-nickname.texinfo
-@include fun-sb-ext-remove-package-local-nickname.texinfo
+@anchor{Function sb-ext package-local-nicknames}
+@ffindex @sortas{package-local-nicknames sb-ext} package-local-nicknames [sb-ext]
+@deffn{Function} sb-ext:package-local-nicknames package-designator
+Returns an alist of @code{(local-nickname . actual-package)} describing the
+nicknames local to the designated package.
-@node Package Variance
-@comment node-name, next, previous, up
+When in the designated package, calls to @code{find-package} with the any of the
+local-nicknames will return the corresponding actual-package instead. This
+also affects all implied calls to @code{find-package}, including those performed by
+the reader.
+
+When printing a package prefix for a symbol with a package local nickname, the
+local nickname is used instead of the real name in order to preserve
+print-read consistency.
+
+Experimental: interface subject to change.
+@end deffn
+@anchor{Function sb-ext package-locally-nicknamed-by-list}
+@ffindex @sortas{package-locally-nicknamed-by-list sb-ext} package-locally-nicknamed-by-list [sb-ext]
+@deffn{Function} sb-ext:package-locally-nicknamed-by-list package-designator
+Returns a list of packages which have a local nickname for the designated
+package.
+
+Experimental: interface subject to change.
+@end deffn
+@anchor{Function sb-ext add-package-local-nickname}
+@ffindex @sortas{add-package-local-nickname sb-ext} add-package-local-nickname [sb-ext]
+@deffn{Function} sb-ext:add-package-local-nickname local-nickname actual-package &optional package-designator
+Adds @code{local-nickname} for @code{actual-package} in the designated package, defaulting
+to current package. @code{local-nickname} must be a string designator, and
+@code{actual-package} must be a package designator.
+
+Returns the designated package.
+
+Signals a continuable error if @code{local-nickname} is already a package
+local nickname for a different package, or if @code{local-nickname} is one of
+@code{"CL"}, @code{"COMMON-LISP"}, @code{"KEYWORD"}, or if @code{local-nickname} is a
+global name or nickname for the package to which the nickname would be
+added.
+
+When in the designated package, calls to @code{find-package} with the @code{local-nickname}
+will return the package the designated @code{actual-package} instead. This also
+affects all implied calls to @code{find-package}, including those performed by the
+reader.
+
+When printing a package prefix for a symbol with a package local nickname,
+local nickname is used instead of the real name in order to preserve
+print-read consistency.
+
+Experimental: interface subject to change.
+@end deffn
+@anchor{Function sb-ext remove-package-local-nickname}
+@ffindex @sortas{remove-package-local-nickname sb-ext} remove-package-local-nickname [sb-ext]
+@deffn{Function} sb-ext:remove-package-local-nickname old-nickname &optional package-designator
+If the designated package had @code{old-nickname} as a local nickname for
+another package, it is removed. Returns true if the nickname existed and was
+removed, and @code{nil} otherwise.
+
+Experimental: interface subject to change.
+@end deffn
+@node package variance
@section Package Variance
-Common Lisp standard specifies that ``If the new definition is at
-variance with the current state of that package, the consequences are
-undefined;'' SBCL by default signals a full warning and retains as
-much of the package state as possible.
+@code{defpackage} @code{clhs} specifies that @emph{if the new definition is at
+variance with the current state of that package, the consequences
+are undefined}. SBCL by default signals a full warning and retains
+as much of the package state as possible. This can be adjusted with
+the following variable.
-This can be adjusted using @code{sb-ext:*on-package-variance*}:
+@anchor{Variable sb-ext *on-package-variance*}
+@vvindex @sortas{on-package-variance* sb-ext} *on-package-variance* [sb-ext]
+@deffn{Variable} sb-ext:*on-package-variance*
+Specifies behavior when redefining a package using @code{defpackage} and the
+definition is in variance with the current state of the package.
-@include var-sb-ext-star-on-package-variance-star.texinfo
+The value should be of the form:
-@node Garbage Collection
-@comment node-name, next, previous, up
+@example
+(:warn [t | packages-names] :error [t | package-names])
+@end example
+
+specifying which packages get which behaviour -- with @code{t} signifying the
+default unless otherwise specified. If default is not specified, @code{:warn}
+is used.
+
+@itemize
+@item @code{:warn} keeps as much state as possible and causes SBCL to signal a
+ full warning.
+
+@item @code{:error} causes SBCL to signal an error when the variant @code{defpackage}
+ form is executed, with restarts provided for user to specify what
+ action should be taken.
+@end itemize
+
+Example:
+
+@example
+(setf *on-package-variance* '(:warn (:swank :swank-backend) :error t))
+@end example
+
+specifies to signal a warning if SWANK package is in variance, and an
+error otherwise.
+@end deffn
+@node garbage collection
@section Garbage Collection
-@cindex Garbage collection
+
+@menu
+* Finalization: finalization.
+* Weak Pointers: weak pointers.
+* Introspection and Tuning: introspection and tuning.
+* Tracing Live Objects Back to Roots: tracing live objects back to roots.
+@end menu
SBCL provides additional garbage collection functionality not
specified by ANSI.
-@include var-sb-ext-star-after-gc-hooks-star.texinfo
-@include fun-sb-ext-gc.texinfo
+@anchor{Function sb-ext gc}
+@ffindex @sortas{gc sb-ext} gc [sb-ext]
+@deffn{Function} sb-ext:gc &key full gen &allow-other-keys
+Initiate a garbage collection.
+The default is to initiate a nursery collection, which may in turn
+trigger a collection of one or more older generations as well. If FULL
+is true, all generations are collected. If GEN is provided, it can be
+used to specify the oldest generation guaranteed to be collected.
+@end deffn
+@anchor{Variable sb-ext *after-gc-hooks*}
+@vvindex @sortas{after-gc-hooks* sb-ext} *after-gc-hooks* [sb-ext]
+@deffn{Variable} sb-ext:*after-gc-hooks*
+Called after each garbage collection, except for garbage collections
+triggered during thread exits. In a multithreaded environment these hooks may
+run in any thread.
+@end deffn
+@node finalization
@subsection Finalization
-@cindex Finalization
Finalization allows code to be executed after an object has been
garbage collected. This is useful for example for releasing foreign
memory associated with a Lisp object.
-@include fun-sb-ext-finalize.texinfo
-@include fun-sb-ext-cancel-finalization.texinfo
+@anchor{Function sb-ext finalize}
+@ffindex @sortas{finalize sb-ext} finalize [sb-ext]
+@deffn{Function} sb-ext:finalize object function &key dont-save
+Arrange for the designated @code{function} to be called when there
+are no more references to @code{object}, including references in @code{function}
+itself.
+If @code{dont-save} is true, the finalizer will be cancelled when
+@code{save-lisp-and-die} is called: this is useful for finalizers
+deallocating system memory, which might otherwise be called with
+addresses from the old image.
+
+In a multithreaded environment @code{function} may be called in any
+thread. In both single and multithreaded environments @code{function}
+may be called in any dynamic scope: consequences are unspecified
+if @code{function} is not fully re-entrant.
+
+Errors from @code{function} are handled and cause a @code{warning} to be
+signalled in whichever thread the @code{function} was called in.
+
+Examples:
+
+@example
+;;; GOOD, assuming RELEASE-HANDLE is re-entrant.
+(let* ((handle (get-handle))
+ (object (make-object handle)))
+ (finalize object (lambda () (release-handle handle)))
+ object)
+@end example
+
+@example
+;;; BAD, finalizer refers to object being finalized, causing
+;;; it to be retained indefinitely!
+(let* ((handle (get-handle))
+ (object (make-object handle)))
+ (finalize object
+ (lambda ()
+ (release-handle (object-handle object)))))
+@end example
+
+@example
+;;; BAD, not re-entrant!
+(defvar *rec* nil)
+
+(defun oops ()
+ (when *rec*
+ (error "recursive OOPS"))
+ (let ((*rec* t))
+ (gc))) ; or just cons enough to cause one
+@end example
+
+@example
+(progn
+ (finalize "oops" #'oops)
+ (oops)) ; GC causes re-entry to #'oops due to the finalizer
+ ; -> ERROR, caught, WARNING signalled
+@end example
+@end deffn
+@anchor{Function sb-ext cancel-finalization}
+@ffindex @sortas{cancel-finalization sb-ext} cancel-finalization [sb-ext]
+@deffn{Function} sb-ext:cancel-finalization object
+Cancel all finalizations for @code{object}, returning @code{t} if it had a finalizer.
+@end deffn
+@node weak pointers
@subsection Weak Pointers
-@cindex Weak pointers
Weak pointers allow references to objects to be maintained without
keeping them from being garbage collected: useful for building caches
among other things.
-Hash tables can also have weak keys and values: @pxref{Hash Table
-Extensions}.
-
-@include fun-sb-ext-make-weak-pointer.texinfo
-@include fun-sb-ext-weak-pointer-value.texinfo
+Hash tables can also have weak keys and values. See
+@ref{hash table extensions}.
+@anchor{Function sb-ext make-weak-pointer}
+@ffindex @sortas{make-weak-pointer sb-ext} make-weak-pointer [sb-ext]
+@deffn{Function} sb-ext:make-weak-pointer object
+Allocate and return a weak pointer which points to @code{object}.
+@end deffn
+@anchor{Function sb-ext weak-pointer-value}
+@ffindex @sortas{weak-pointer-value sb-ext} weak-pointer-value [sb-ext]
+@deffn{Function} sb-ext:weak-pointer-value weak-pointer
+If @code{weak-pointer} is valid, return the value of @code{weak-pointer} and @code{t}.
+If the referent of @code{weak-pointer} has been garbage collected,
+returns the values @code{nil} and @code{nil}.
+@end deffn
+@node introspection and tuning
@subsection Introspection and Tuning
-@include var-sb-ext-star-gc-run-time-star.texinfo
-@include fun-sb-ext-bytes-consed-between-gcs.texinfo
-@include fun-sb-ext-dynamic-space-size.texinfo
-@include fun-sb-ext-get-bytes-consed.texinfo
-@include fun-sb-ext-gc-logfile.texinfo
-@include fun-sb-ext-generation-average-age.texinfo
-@include fun-sb-ext-generation-bytes-allocated.texinfo
-@include fun-sb-ext-generation-bytes-consed-between-gcs.texinfo
-@include fun-sb-ext-generation-minimum-age-before-gc.texinfo
-@include fun-sb-ext-generation-number-of-gcs-before-promotion.texinfo
-@include fun-sb-ext-generation-number-of-gcs.texinfo
+@anchor{Variable sb-ext *gc-run-time*}
+@vvindex @sortas{gc-run-time* sb-ext} *gc-run-time* [sb-ext]
+@deffn{Variable} sb-ext:*gc-run-time*
+Total CPU time spent doing garbage collection (as reported by
+@code{get-internal-run-time}.) Initialized to zero on startup. It is safe to bind
+this to zero in order to measure @code{gc} time inside a certain section of code, but
+doing so may interfere with results reported by eg. @code{time}.
+@end deffn
+@anchor{Variable sb-ext *gc-real-time*}
+@vvindex @sortas{gc-real-time* sb-ext} *gc-real-time* [sb-ext]
+@deffn{Variable} sb-ext:*gc-real-time*
+Total real time spent doing garbage collection (as reported by
+@code{get-internal-real-time}.) Initialized to zero on startup.
+@end deffn
+@anchor{Function sb-ext bytes-consed-between-gcs}
+@ffindex @sortas{bytes-consed-between-gcs sb-ext} bytes-consed-between-gcs [sb-ext]
+@deffn{Function} sb-ext:bytes-consed-between-gcs
+The amount of memory that will be allocated before the next garbage
+collection is initiated. This can be set with @code{setf}.
+On GENCGC platforms this is the nursery size, and defaults to 5% of dynamic
+space size.
+
+Note that currently, changes to this value are lost when saving core.
+@end deffn
+@anchor{Function sb-ext dynamic-space-size}
+@ffindex @sortas{dynamic-space-size sb-ext} dynamic-space-size [sb-ext]
+@deffn{Function} sb-ext:dynamic-space-size
+Size of the dynamic space in bytes.
+@end deffn
+@anchor{Function sb-ext get-bytes-consed}
+@ffindex @sortas{get-bytes-consed sb-ext} get-bytes-consed [sb-ext]
+@deffn{Function} sb-ext:get-bytes-consed
+Return the number of bytes consed since the program began. Typically
+this result will be a consed bignum, so if you have an
+application (e.g. profiling) which can't tolerate the overhead of
+consing bignums, you'll probably want either to hack in at a lower
+level (as the code in the @code{sb-profile} package does), or to design a
+more microefficient interface and submit it as a patch.
+@end deffn
+@anchor{Function sb-ext gc-logfile}
+@ffindex @sortas{gc-logfile sb-ext} gc-logfile [sb-ext]
+@deffn{Function} sb-ext:gc-logfile
+Return the pathname used to log garbage collections. Can be @code{setf}.
+Default is @code{nil}, meaning collections are not logged. If non-null, the
+designated file is opened before and after each collection, and generation
+statistics are appended to it.
+@end deffn
+@anchor{Function sb-ext generation-average-age}
+@ffindex @sortas{generation-average-age sb-ext} generation-average-age [sb-ext]
+@deffn{Function} sb-ext:generation-average-age generation
+Average age of memory allocated to GENERATION: average number of times
+objects allocated to the generation have seen younger objects promoted to it.
+Available on GENCGC platforms only.
+
+Experimental: interface subject to change.
+@end deffn
+@anchor{Function sb-ext generation-bytes-allocated}
+@ffindex @sortas{generation-bytes-allocated sb-ext} generation-bytes-allocated [sb-ext]
+@deffn{Function} sb-ext:generation-bytes-allocated generation
+Number of bytes allocated to GENERATION currently. Available on GENCGC
+platforms only.
+
+Experimental: interface subject to change.
+@end deffn
+@anchor{Function sb-ext generation-bytes-consed-between-gcs}
+@ffindex @sortas{generation-bytes-consed-between-gcs sb-ext} generation-bytes-consed-between-gcs [sb-ext]
+@deffn{Function} sb-ext:generation-bytes-consed-between-gcs generation
+Number of bytes that can be allocated to GENERATION before that
+generation is considered for garbage collection. This value is meaningless for
+generation 0 (the nursery): see @code{bytes-consed-between-gcs} instead. Default is
+5% of the dynamic space size divided by the number of non-nursery generations.
+Can be assigned to using @code{setf}. Available on GENCGC platforms only.
+
+Experimental: interface subject to change.
+@end deffn
+@anchor{Function sb-ext generation-minimum-age-before-gc}
+@ffindex @sortas{generation-minimum-age-before-gc sb-ext} generation-minimum-age-before-gc [sb-ext]
+@deffn{Function} sb-ext:generation-minimum-age-before-gc generation
+Minimum average age of objects allocated to GENERATION before that
+generation is may be garbage collected. Default is 0.75. See also
+@code{generation-average-age}. Can be assigned to using @code{setf}. Available on GENCGC
+platforms only.
+
+Experimental: interface subject to change.
+@end deffn
+@anchor{Function sb-ext generation-number-of-gcs-before-promotion}
+@ffindex @sortas{generation-number-of-gcs-before-promotion sb-ext} generation-number-of-gcs-before-promotion [sb-ext]
+@deffn{Function} sb-ext:generation-number-of-gcs-before-promotion generation
+Number of times garbage collection is done on GENERATION before
+automatic promotion to the next generation is triggered. Default is 1. Can be
+assigned to using @code{setf}. Available on GENCGC platforms only.
+
+Experimental: interface subject to change.
+@end deffn
+@anchor{Function sb-ext generation-number-of-gcs}
+@ffindex @sortas{generation-number-of-gcs sb-ext} generation-number-of-gcs [sb-ext]
+@deffn{Function} sb-ext:generation-number-of-gcs generation
+Number of times garbage collection has been done on GENERATION without
+promotion. Available on GENCGC platforms only.
+
+Experimental: interface subject to change.
+@end deffn
+@node tracing live objects back to roots
@subsection Tracing Live Objects Back to Roots
-@quotation note
This feature is intended to help expert users diagnose rare low-level
-issues and should not be needed during normal usage. On top of that,
-the interface and implementation are experimental and may change at any
-time without further notice.
-@end quotation
+issues and should not be needed during normal usage. On top of that,
+the interface and implementation are experimental and may change at
+any time without further notice.
-It is sometimes important to understand why a given object is retained
-in the Lisp image instead of being garbage collected. To help with this
-problem, SBCL provides a mechanism that searches through the different
-memory spaces, builds a path of references from a root to the object in
-question and finally reports this paths:
+It is sometimes important to understand why a given object is
+retained in the Lisp image instead of being garbage collected. To
+help with this problem, SBCL provides a mechanism that searches
+through the different memory spaces, builds a path of references
+from a root to the object in question and finally reports this
+paths:
-@include fun-sb-ext-search-roots.texinfo
+@anchor{Function sb-ext search-roots}
+@ffindex @sortas{search-roots sb-ext} search-roots [sb-ext]
+@deffn{Function} sb-ext:search-roots weak-pointers &key criterion ignore print
+Find roots keeping the targets of @code{weak-pointers} alive.
+@code{weak-pointers} must be a single @code{sb-ext:weak-pointer} or a list of those,
+pointing to objects for which roots should be searched.
+
+@code{criterion} determines just how rooty (how deep) a root must be in order
+to be considered. Possible values are:
+
+@itemize
+@item @code{:oldest}
+
+This says we can stop upon seeing an object in the oldest gen to
+@code{gc}, or older. This is the easiest test to satisfy.
+
+@item @code{:pseudo-static}
+
+This is usually the same as @code{:oldest}, unless the oldest gen to @code{gc}
+has been decreased.
+
+@item @code{:static}
+
+To find a root of an image-backed object, you want to stop only at
+a truly @code{:static} object.
+@end itemize
+
+@code{ignore} is a list of objects to treat as if nonexistent in the heap.
+It can often be useful for finding a path to an interned symbol other than
+through its package by specifying the package as an ignored object.
+
+@code{print} controls whether discovered paths should be returned or
+printed. Possible values are
+
+@itemize
+@item @code{:verbose}
+
+Return no values. Print discovered paths using a verbose format
+with each node of each path on a separate line.
+
+@item true (other than @code{:verbose})
+
+Return no values. Print discovered paths using a compact format
+with all nodes of each path on a single line.
+
+@item @code{nil}
+
+Do not print any output. Instead return the discovered paths as a
+list of lists. Each list has the form
+
+@example
+(TARGET . (ROOT NODE*))
+@end example
+
+where @code{target} is one of the target of one of the @code{weak-pointers}.
+
+@code{root} is a description of the root at which the path starts and has
+one of the following forms:
+
+@itemize
+@item @code{:static}
+
+If the root of the path is a non-collectible heap object.
+
+@item @code{:pinned}
+
+If an unknown thread stack pins the root of the path.
+
+@item @code{((thread-name | thread-object) symbol currentp)}
+
+If the path begins at a special binding of @code{symbol} in a thread.
+@code{currentp} is a @code{boolean} indicating whether the value is current
+or shadowed by another binding.
+
+@item @code{((thread-name | thread-object) guessed-pc)}
+
+If the path begins at a lexical variable in the function whose
+code contains @code{guessed-pc}.
+@end itemize
+
+Each @code{node} in the remainder of the path is a cons (@code{object} . @code{slot})
+indicating that the slot at index @code{slot} in @code{object} references the
+next path node.
+@end itemize
+
+Experimental: subject to change without prior notice.
+@end deffn
An example of using this could look like this:
-@lisp
-* (defvar *my-string* (list 1 2 "my string"))
-*MY-STRING*
+@itemize
+@item (defvar *my-string* (list 1 2 "my string"))
+@end itemize
+ *MY-STRING*
-* (sb-ext:search-roots (sb-ext:make-weak-pointer (third *my-string*)))
- -> ((SIMPLE-VECTOR 3)) #x10004E9EAF[2] -> (SYMBOL) #x5044100F[1] -> (CONS) #x100181FAE7[1] -> (CONS) #x100181FAF7[1] -> (CONS) #x100181FB07[0] -> #x100181F9AF
-@end lisp
+@itemize
+@item (sb-ext:search-roots (sb-ext:make-weak-pointer (third *my-string*)))
+@end itemize
+ -> ((@code{simple-vector} 3)) #x10004E9EAF[2] -> (@code{symbol}) #x5044100F[1] -> (@code{cons}) #x100181FAE7[1] -> (@code{cons}) #x100181FAF7[1] -> (@code{cons}) #x100181FB07[0] -> #x100181F9AF
-The single line of output on @code{cl:*standard-output*} shows the path
-from a root to @t{"my string"}: the path starts with SBCL's internal
+The single line of output on @code{*standard-output*} shows the path from a
+root to @code{"my string"}: the path starts with SBCL's internal
package system data structures followed by the symbol
-(@t{cl-user:*my-string*}) followed the three cons cells of the list.
+(@code{cl-user:*my-string*}) followed the three cons cells of the list.
The @code{:print :verbose} argument produces similar behavior but
-describe the path elements in more detail:
+describes the path elements in more detail:
-@lisp
-* (sb-ext:search-roots (sb-ext:make-weak-pointer (third *my-string*)) :print :verbose)
-Path to "my string":
- 6 10004E9EAF [ 2] a (simple-vector 3)
- 0 5044100F [ 1] COMMON-LISP-USER::*MY-STRING*
- 0 100181FAE7 [ 1] a cons
- 0 100181FAF7 [ 1] a cons
- 0 100181FB07 [ 0] a cons
-@end lisp
+@itemize
+@item (sb-ext:search-roots (sb-ext:make-weak-pointer (third *my-string*))
+ :print :verbose)
+@end itemize
+ Path to "my string":
+ 6 10004E9EAF [ 2] a (simple-vector 3)
+ 0 5044100F [ 1] COMMON-LISP-USER::*MY-STRING*
+ 0 100181FAE7 [ 1] a cons
+ 0 100181FAF7 [ 1] a cons
+ 0 100181FB07 [ 0] a cons
The @code{:print nil} argument is a bit different:
-@lisp
-* (sb-ext:search-roots (sb-ext:make-weak-pointer (third *my-string*)) :print nil)
-(("my string" :STATIC (#(*MY-STRING* 0 0) . 2) (*MY-STRING* . 1)
- ((1 2 "my string") . 1) ((2 "my string") . 1) (("my string") . 0)))
-@end lisp
+@itemize
+@item (sb-ext:search-roots (sb-ext:make-weak-pointer (third *my-string*))
+ :print nil)
+@end itemize
+ (("my string" @code{:static} (#(*MY-STRING* 0 0) . 2) (*MY-STRING* . 1)
+ ((1 2 "my string") . 1) ((2 "my string") . 1) (("my string") . 0)))
-There is no output on @code{cl:*standard-output*} and the return value
-is a single path for the target object @t{"my string"}. As before, the
+
+There is no output on @code{*standard-output*}, and the return value is a
+single path for the target object @code{"my string"}. As before, the
path shows the symbol and the three cons cells.
-@node Generic Function Dispatch
-@comment node-name, next, previous, up
+@node generic function dispatch
@section Generic Function Dispatch
-@findex @sbpcl{no-primary-method}
-@findex @cl{no-applicable-method}
If a generic function with standard or short method combination is
-called, and the set of applicable methods does not include any primary
-methods, then the generic function @code{no-primary-method} will be
-invoked, with the arguments to @code{no-primary-method} being the
-invoked generic function and its arguments, similar to the standard
-function @code{no-applicable-method}. As with
-@code{no-applicable-method}, the default method on
-@code{no-primary-method} signals an error; programmers may define
-methods on it.
+called, and the set of applicable methods does not include any
+primary methods, then the generic function @code{sb-pcl:no-primary-method}
+will be invoked with the arguments being the invoked generic
+function and its arguments, similar to the standard function
+@code{no-applicable-method}. As with @code{no-applicable-method}, the default
+method on @code{sb-pcl:no-primary-method} signals an error; programmers may
+define methods on it.
-@node Slot Access
-@comment node-name, next, previous, up
-@section Slot Access
+@node extended slot access
+@section Extended Slot Access
-@findex @cl{slot-value}
-@findex @setf{@cl{slot-value}}
-@findex @cl{slot-boundp}
-@findex @cl{slot-makunbound}
The slot access functions @code{slot-value}, @code{(setf slot-value)},
-@code{slot-boundp} and @code{slot-makunbound} are defined to function
-as expected on conditions (of metaclass @code{condition-class}) and,
-with some limitations, on structures (of metaclass
-@code{structure-class}).
+@code{slot-boundp} and @code{slot-makunbound} are defined to function as expected
+on conditions (of metaclass @code{sb-pcl::condition-class}) and, with some
+limitations, on structures (of metaclass @code{structure-class}).
For structures:
@itemize
-@item
-@findex @cl{defstruct}
-The name of a slot for the purposes of the slot access functions is
-the symbol used as the slot-name in the slot-description in the
-@code{defstruct} form;
+@item The name of a slot for the purposes of the slot access functions
+ is the symbol used as the slot-name in the slot-description in the
+ @code{defstruct} form;
-@item
-@findex @cl{slot-unbound}
-@findex @cl{slot-value}
-@findex @cl{slot-boundp}
-@cindex Unbound slots
-@code{slot-value} and @code{slot-boundp} function as expected,
-including (for @code{slot-value}) calling and respecting the return
-value of @code{slot-unbound} if the slot is unbound;
+@item @code{slot-value} and @code{slot-boundp} function as expected, including (for
+ @code{slot-value}) calling and respecting the return value of
+ @code{slot-unbound} if the slot is unbound;
-@item
-@findex @setf{@cl{slot-value}}
-@code{(setf slot-value)} functions as expected, including performing
-type checks to verify that the new value is of an appropriate type for
-the slot;
+@item @code{(setf slot-value)} functions as expected, including performing
+ type checks to verify that the new value is of an appropriate type
+ for the slot;
-@item
-@findex @cl{slot-makunbound}
-@cindex Unbound slots
-@code{slot-makunbound} makes the slot be unbound only when the slot
-corresponds to an @code{&aux} argument with no default in a
-by-order-of-arguments (BOA) constructor. In all other cases calling
-@code{slot-makunbound} on a structure signals an error.
-
-@item
-@findex @cl{slot-missing}
-If any of the slot access functions is called with a structure
-instance which does not have a slot of the given name,
-@code{slot-missing} is called and the return value of the effective
-method, if any, is respected.
+@item @code{slot-makunbound} makes the slot unbound only when the slot
+ corresponds to an @code{&aux} argument with no default in a
+ by-order-of-arguments (BOA) constructor. In all other cases
+ calling @code{slot-makunbound} on a structure signals an error.
+@item If any of the slot access functions is called with a structure
+ instance which does not have a slot of the given name,
+ @code{slot-missing} is called and the return value of the effective
+ method, if any, is respected.
@end itemize
-@node Metaobject Protocol
-@comment node-name, next, previous, up
+@node metaobject protocol
@section Metaobject Protocol
+@menu
+* AMOP Compatibility of Metaobject Protocol: amop compatibility of metaobject protocol.
+* Metaobject Protocol Extensions: metaobject protocol extensions.
+@end menu
+
+@node amop compatibility of metaobject protocol
@subsection AMOP Compatibility of Metaobject Protocol
SBCL supports a metaobject protocol which is intended to be compatible
@@ -364,486 +676,604 @@ with AMOP; present exceptions to this (as distinct from current bugs)
are:
@itemize
+@item @code{sb-mop:compute-effective-method} only returns one value, not two.
+ There is no record of what the second return value was meant to
+ indicate, and apparently no clients for it.
-@item
-@findex @sbmop{compute-effective-method}
-@code{compute-effective-method} only returns one value, not two.
-
-There is no record of what the second return value was meant to
-indicate, and apparently no clients for it.
-
-@item
-@tindex @cl{generic-function}
-@tindex @cl{standard-generic-function}
-@tindex @sbmop{funcallable-standard-object}
-@tindex @cl{standard-object}
-@tindex @cl{function}
-The direct superclasses of @code{funcallable-standard-object} are
-@code{(function standard-object)}, not @code{(standard-object function)}.
+@item The direct superclasses of @code{sb-mop:funcallable-standard-object} are
+ (@code{function} @code{standard-object}) instead of the correct (@code{standard-object}
+ @code{function}).
This is to ensure that the @code{standard-object} class is the last of
-the standardized classes before @code{t} appearing in the class
+the standardized classes before class @code{t} appearing in the
precedence list of @code{generic-function} and
-@code{standard-generic-function}, as required by section 1.4.4.5 of the
-ANSI specification.
+@code{standard-generic-function}, as required by @code{clhs} @code{1.4.4.5}.
-@item
-@findex @cl{ensure-generic-function}
-@findex @sbmop{generic-function-declarations}
-the arguments @code{:declare} and @code{:declarations} to
-@code{ensure-generic-function} are both accepted, with the leftmost
-argument defining the declarations to be stored and returned by
-@code{generic-function-declarations}.
+@item The arguments @code{:declare} and @code{:declarations} are both accepted by
+ @code{ensure-generic-function}, with the leftmost argument defining the
+ declarations to be stored and returned by
+ @code{sb-mop:generic-function-declarations}.
Where AMOP specifies @code{:declarations} as the keyword argument to
@code{ensure-generic-function}, the Common Lisp standard specifies
-@code{:declare}. Portable code should use @code{:declare}.
+ @code{:declare}. Portable code should use @code{:declare}.
-@item
-@findex @sbmop{validate-superclass}
-@findex @sbmop{finalize-inheritance}
-@tindex @cl{standard-class}
-@tindex @sbmop{funcallable-standard-class}
-@tindex @cl{function}
-@findex @sbmop{class-prototype}
-although SBCL obeys the requirement in AMOP that
-@code{validate-superclass} should treat @code{standard-class} and
-@code{funcallable-standard-class} as compatible metaclasses, we
-impose an additional requirement at class finalization time: a class
-of metaclass @code{funcallable-standard-class} must have
-@code{function} in its superclasses, and a class of metaclass
-@code{standard-class} must not.
+@item Although SBCL obeys the requirement in AMOP that
+ @code{sb-mop:validate-superclass} should treat @code{standard-class} and
+ @code{sb-mop:funcallable-standard-class} as compatible metaclasses, we
+ impose an additional requirement at class finalization time: a
+ class of metaclass @code{sb-mop:funcallable-standard-class} must have
+ @code{function} in its superclasses, and a class of metaclass
+ @code{standard-class} must not.
-@findex @cl{typep}
-@findex @cl{class-of}
-@findex @cl{subtypep}
After a class has been finalized, it is associated with a class
-prototype which is accessible by a standard mop function
-@code{class-prototype}. The user can then ask whether this object is a
-@code{function} or not in several different ways: whether it is a
-function according to @code{typep}; whether its @code{class-of} is
-@code{subtypep} @code{function}, or whether @code{function} appears in
-the superclasses of the class. The additional consistency requirement
-comes from the desire to make all of these answers the same.
+prototype which is accessible by a standard MOP function
+@code{sb-mop:class-prototype}. The user can then ask whether this
+object is a @code{function} or not in several different ways: whether
+it is a function according to @code{typep}; whether its @code{class-of} is
+@code{subtypep} @code{function}, or whether @code{function} appears in the
+superclasses of the class. The additional consistency
+requirement comes from the desire to make all of these answers
+the same.
The following class definitions are bad, and will lead to errors
either immediately or if an instance is created:
-@lisp
+
+@example
(defclass bad-object (funcallable-standard-object)
()
(:metaclass standard-class))
-@end lisp
-@lisp
(defclass bad-funcallable-object (standard-object)
()
(:metaclass funcallable-standard-class))
-@end lisp
+@end example
+
The following definition is acceptable:
-@lisp
+
+@example
(defclass mixin ()
((slot :initarg slot)))
(defclass funcallable-object (funcallable-standard-object mixin)
()
(:metaclass funcallable-standard-class))
-@end lisp
+@end example
+
and leads to a class whose instances are funcallable and have one slot.
-@tindex @sbmop{funcallable-standard-object}
Note that this requirement also applies to the class
-@code{funcallable-standard-object}, which has metaclass
-@code{funcallable-standard-class} rather than
-@code{standard-class} as AMOP specifies.
+@code{sb-mop:funcallable-standard-object}, which has metaclass
+@code{sb-mop:funcallable-standard-class} rather than @code{standard-class} as
+AMOP specifies.
-@item
-the requirement that ``No portable class @math{C_p} may inherit, by
-virtue of being a direct or indirect subclass of a specified class, any
-slot for which the name is a symbol accessible in the
-@code{common-lisp-user} package or exported by any package defined in
-the ANSI Common Lisp standard.'' is interpreted to mean that the
-standardized classes themselves should not have slots named by external
-symbols of public packages.
+@item The requirement that @emph{no portable class may inherit, by virtue of
+ being a direct or indirect subclass of a specified class, any slot
+ for which the name is a symbol accessible in the
+ @code{common-lisp-user} package or exported by any package defined in
+ the ANSI Common Lisp standard}. is interpreted to mean that the
+ standardized classes themselves should not have slots named by
+ external symbols of public packages.
-The rationale behind the restriction is likely to be similar to the ANSI
-Common Lisp restriction on defining functions, variables and types named
-by symbols in the Common Lisp package: preventing two independent pieces
-of software from colliding with each other.
+The rationale behind the restriction is likely to be similar to
+the ANSI Common Lisp restriction on defining functions,
+variables and types named by symbols in the Common Lisp package:
+preventing two independent pieces of software from colliding
+with each other.
-@item
-@findex @sbmop{slot-value-using-class}
-@findex @setf{@sbmop{slot-value-using-class}}
-@findex @sbmop{slot-boundp-using-class}
-specializations of the @code{new-value} argument to @code{(setf
-slot-value-using-class)} are not allowed: all user-defined methods must
-have a specializer of the class @code{t}.
+@item Specializations of the @code{new-value} argument to (@code{setf}
+ @code{sb-mop:slot-value-using-class}) are not allowed: all user-defined
+ methods must have a specializer of the class @code{t}.
This prohibition is motivated by a separation of layers: the
-@code{slot-value-using-class} family of functions is intended for use in
-implementing different and new slot allocation strategies, rather than
-in performing application-level dispatching. Additionally, with this
-requirement, there is a one-to-one mapping between metaclass, class and
-slot-definition-class tuples and effective methods of @code{(setf
-slot-value-using-class)}, which permits optimization of @code{(setf
-slot-value-using-class)}'s discriminating function in the same manner as
-for @code{slot-value-using-class} and @code{slot-boundp-using-class}.
+@code{sb-mop:slot-value-using-class} family of functions is intended
+for use in implementing different and new slot allocation
+strategies, rather than in performing application-level
+dispatching. Additionally, with this requirement, there is a
+one-to-one mapping between metaclass, class and
+slot-definition-class tuples and effective methods of (@code{setf}
+@code{sb-mop:slot-value-using-class}), which permits optimization
+of (@code{setf} @code{sb-mop:slot-value-using-class})'s discriminating
+function in the same manner as for @code{sb-mop:slot-value-using-class}
+and @code{sb-mop:slot-boundp-using-class}.
Note that application code may specialize on the @code{new-value}
argument of slot accessors.
-@item
-@findex @cl{defclass}
-@findex @sbmop{ensure-class}
-@findex @sbmop{ensure-class-using-class}
-@findex @cl{find-class}
-@findex @cl{class-name}
-the class named by the @code{name} argument to @code{ensure-class}, if
-any, is only redefined if it is the proper name of that class;
-otherwise, a new class is created.
+@item The class named by the @code{name} argument to @code{sb-mop:ensure-class}, if any, is
+ only redefined if it is the proper name of that class; otherwise,
+ a new class is created.
-This is consistent with the description of @code{ensure-class} in AMOP
-as the functional version of @code{defclass}, which has this behaviour;
-however, it is not consistent with the weaker requirement in AMOP, which
-states that any class found by @code{find-class}, no matter what its
-@code{class-name}, is redefined.
+This is consistent with the description @code{sb-mop:ensure-class} in
+AMOP as the functional version of @code{defclass}, which has this
+behaviour; however, it is not consistent with the weaker
+requirement in AMOP, which states that any class found by
+@code{find-class}, no matter what its @code{class-name}, is
+redefined.
-@item
-@findex @sbmop{slot-definition-name}
-@tindex @cl{structure-class}
-@findex @cl{defstruct}
-an error is not signaled in the case of the @code{:name} initialization
-argument for @code{slot-definition} objects being a constant, when the
-slot definition is of type @code{structure-slot-definition} (i.e. it is
-associated with a class of type @code{structure-class}).
+@item An error is not signaled in the case of the @code{:name} initialization
+ argument for @code{sb-mop:slot-definition} objects being a constant, when
+ the slot definition is of type @code{sb-pcl::structure-slot-definition}
+ (i.e. it is associated with a class of type @code{structure-class}).
-This allows code which uses constant names for structure slots to
-continue working as specified in ANSI, while enforcing the constraint
-for all other types of slot.
+This allows code which uses constant names for structure slots
+to continue working as specified in ANSI, while enforcing the
+constraint for all other types of slot.
-@item
-@tindex @cl{t}
-@tindex @cl{built-in-class}
-@findex @sbmop{validate-superclass}
-@findex @cl{defclass}
-the class named @code{t} is not an instance of the @code{built-in-class}
-metaclass.
+@item The class @code{t} is not an instance of the @code{built-in-class} metaclass.
-AMOP specifies, in the ``Inheritance Structure of Metaobject Classes''
-section, that the class named @code{t} should be an instance of
-@code{built-in-class}. However, it also specifies that
-@code{validate-superclass} should return true (indicating that a direct
-superclass relationship is permissible) if the second argument is the
-class named @code{t}. Also, ANSI specifies that classes with metaclass
-@code{built-in-class} may not be subclassed using @code{defclass}, and
-also that the class named @code{t} is the universal superclass,
+AMOP specifies, in the _Inheritance Structure of Metaobject
+Classes_ section, that the class @code{t} should be an instance of
+@code{built-in-class}. However, it also specifies that
+@code{sb-mop:validate-superclass} should return true (indicating that a
+direct superclass relationship is permissible) if the second
+argument is the class @code{t}. Also, ANSI specifies that classes with
+metaclass @code{built-in-class} may not be subclassed using @code{defclass},
+and also that the class @code{t} is the universal superclass,
inconsistent with it being a @code{built-in-class}.
-@item
-@findex @cl{change-class}
-@findex @cl{defclass}
-@findex @sbmop{ensure-class}
-@findex @sbmop{ensure-class-using-class}
-@findex @sbmop{slot-value-using-class}
-@findex @setf{@sbmop{slot-value-using-class}}
-@findex @sbmop{slot-boundp-using-class}
-@findex @sbmop{slot-definition-allocation}
-uses of @code{change-class} and redefinitions of classes with
-@code{defclass} (or the functional interfaces @code{ensure-class} or
-@code{ensure-class-using-class}) must ensure that for each slot with
-allocation @code{:instance} or @code{:class}, the set of applicable
-methods on the @code{slot-value-using-class} family of generic
-functions is the same before and after the change.
+@item Uses of @code{change-class} and redefinitions of classes with
+ @code{defclass} (or the functional interfaces @code{sb-mop:ensure-class} or
+ @code{sb-mop:ensure-class-using-class}) must ensure that for each slot
+ with allocation @code{:instance} or @code{:class}, the set of applicable methods
+ on the @code{sb-mop:slot-value-using-class} family of generic functions
+ is the same before and after the change.
This is required for correct operation of the protocol to update
-instances for the new or redefined class, and can be seen as part of
-the contract of the @code{:instance} or @code{:class} allocations.
-
-@item
-@findex @cl{no-applicable-method}
-@findex @sbpcl{no-primary-method}
-@findex @sbmop{compute-discriminating-function}
-@findex @cl{compute-applicable-methods}
-@findex @sbmop{compute-effective-method}
-Metaobject protocol users may wish to override
-@code{compute-discriminating-function} for their own generic function
-classes. Overriding implementations of
-@code{compute-discriminating-function} must, in order to participate
-in the @code{no-applicable-method} and @code{no-primary-method}
-protocols, perform appropriate checks on the return value of
-@code{compute-applicable-methods} before processing the effective
-method; the standard effective method contains error-invoking forms,
-but those forms have no access to the generic function invocation's
-arguments.
+instances for the new or redefined class, and can be seen as
+part of the contract of the @code{:instance} or @code{:class} allocations.
+@item Metaobject protocol users may wish to override
+ @code{sb-mop:compute-discriminating-function} for their own generic
+ function classes. Overriding implementations of
+ @code{sb-mop:compute-discriminating-function} must, in order to
+ participate in the @code{no-applicable-method} and
+ @code{sb-pcl:no-primary-method} protocols, perform appropriate checks on
+ the return value of @code{compute-applicable-methods} before processing
+ the effective method; the standard effective method contains
+ error-invoking forms, but those forms have no access to the
+ generic function invocation's arguments.
@end itemize
+@node metaobject protocol extensions
@subsection Metaobject Protocol Extensions
In addition, SBCL supports extensions to the Metaobject protocol from
AMOP; at present, they are:
@itemize
+@item Compile-time support for generating specializer metaobjects from
+ specializer names in @code{defmethod} forms is provided by the
+ @code{sb-pcl:make-method-specializers-form} function, which returns a
+ form which, when evaluated in the lexical environment of the
+ @code{defmethod}, returns a list of specializer metaobjects. This
+ operator suffers from similar restrictions to those affecting
+ @code{sb-mop:make-method-lambda}, namely that the generic function must
+ be defined when the @code{defmethod} form is expanded, so that the
+ correct method of @code{sb-pcl:make-method-specializers-form} is invoked.
+ The system-provided method on @code{sb-pcl:make-method-specializers-form}
+ generates a call to @code{find-class} for each symbol specializer name,
+ and a call to @code{sb-mop:intern-eql-specializer} for each
+ @code{(EQL <x>)} specializer name.
-@item
-@findex @cl{defmethod}
-@findex @cl{find-class}
-@findex @sbmop{intern-eql-specializer}
-@findex @sbpcl{make-method-specializers-form}
-@findex @sbmop{make-method-lambda}
-compile-time support for generating specializer metaobjects from
-specializer names in @code{defmethod} forms is provided by the
-@code{make-method-specializers-form} function, which returns a form
-which, when evaluated in the lexical environment of the
-@code{defmethod}, returns a list of specializer metaobjects. This
-operator suffers from similar restrictions to those affecting
-@code{make-method-lambda}, namely that the generic function must be
-defined when the @code{defmethod} form is expanded, so that the
-correct method of @code{make-method-specializers-form} is invoked.
-The system-provided method on @code{make-method-specializers-form}
-generates a call to @code{find-class} for each symbol specializer
-name, and a call to @code{intern-eql-specializer} for each @code{(eql
-@var{x})} specializer name.
-
-@item
-@findex @cl{find-method}
-@findex @sbpcl{parse-specializer-using-class}
-@findex @sbpcl{unparse-specializer-using-class}
-run-time support for converting between specializer names and
-specializer metaobjects, mostly for the purposes of
-@code{find-method}, is provided by
-@code{parse-specializer-using-class} and
-@code{unparse-specializer-using-class}, which dispatch on their first
-argument, the generic function associated with a method with the given
-specializer. The system-provided methods on those methods convert
-between classes and proper names and between lists of the form
-@code{(eql @var{x})} and interned eql specializer objects.
-
-@item
-@vindex @sbpcl{@earstuds{slot-unbound}}
-@findex @sbmop{standard-instance-access}
-@findex @sbmop{funcallable-standard-instance-access}
-@cindex Unbound slots
-distinguishing unbound instance allocated slots from bound ones when
-using @code{standard-instance-access} and
-@code{funcallable-standard-instance-access} is possible by comparison
-to the symbol-macro @code{+slot-unbound+}.
+@item Run-time support for converting between specializer names and
+ specializer metaobjects, mostly for the purposes of @code{find-method},
+ is provided by @code{sb-pcl:parse-specializer-using-class} and
+ @code{sb-pcl:unparse-specializer-using-class}, which dispatch on their
+ first argument, the generic function associated with a method with
+ the given specializer. The system-provided methods on those
+ methods convert between classes and proper names and between lists
+ of the form @code{(EQL <x>)} and interned eql specializer objects.
+@item Distinguishing unbound instance allocated slots from bound ones
+ when using @code{sb-mop:standard-instance-access} and
+ @code{sb-mop:funcallable-standard-instance-access} is possible by
+ comparison to the symbol-macro @code{sb-pcl:+slot-unbound+}.
@end itemize
-@node Extensible Sequences
-@comment node-name, next, previous, up
+@node extensible sequences
@section Extensible Sequences
@menu
-* Iterator Protocol::
-* Simple Iterator Protocol::
+* Iterator Protocol: exseq iterator protocol.
+* Simple Iterator Protocol: exseq simple iterator protocol.
@end menu
-@tindex @cl{sequence}
-@tindex @cl{vector}
-@findex @cl{find}
-@findex @cl{subseq}
ANSI Common Lisp has a class @code{sequence} with subclasses @code{list} and
-@code{vector} on which the ``sequence functions'' like @code{find},
-@code{subseq}, etc. operate. As an extension to the ANSI specification,
-SBCL allows additional subclasses of @code{sequence} to be defined
-@footnote{A motivation, rationale and additional examples for the design
-of this extension can be found in the paper @cite{Rhodes, Christophe
-(2007): User-extensible sequences in Common Lisp} available for download
-at
-@url{http://www.doc.gold.ac.uk/~mas01cr/papers/ilc2007/sequences-20070301.pdf}.}.
+@code{vector}, on which the sequence functions like @code{find}, @code{subseq}, etc.
+operate. As an extension to the ANSI specification, SBCL allows
+additional subclasses of @code{sequence} to be defined.
+
+@quotation
+A motivation, rationale and additional examples for the design of
+this extension can be found in the paper @emph{Rhodes,
+Christophe (2007): User-extensible sequences in Common Lisp}
+available for download at
+@url{http://www.doc.gold.ac.uk/~mas01cr/papers/ilc2007/sequences-20070301.pdf}.
+@end quotation
-@findex @cl{coerce}
-@findex @cl{subseq}
-@findex @cl{make-instance}
-@tindex @cl{list}
Users of this extension just make instances of @code{sequence} subclasses
and transparently operate on them using sequence functions:
-@lisp
+
+@example
(coerce (subseq (make-instance 'my-sequence) 5 10) 'list)
-@end lisp
+@end example
+
From this perspective, no distinction between builtin and user-defined
@code{sequence} subclasses should be necessary.
Providers of the extension, that is of user-defined @code{sequence}
-subclasses, have to adhere to a ``sequence protocol'' which consists of
-a set of generic functions in the @code{sequence} package.
+subclasses, have to adhere to a @emph{sequence protocol} which consists
+of a set of generic functions in the @code{sequence} package.
-@tindex @cl{sequence}
-@tindex @cl{standard-object}
A minimal @code{sequence} subclass has to specify @code{standard-object} and
@code{sequence} as its superclasses and has to be the specializer of the
@code{sequence} parameter of methods on at least the following generic
functions:
-@include fun-sb-sequence-length.texinfo
-@include fun-sb-sequence-elt.texinfo
-@include fun-sb-sequence-setf-elt.texinfo
-@include fun-sb-sequence-adjust-sequence.texinfo
-@include fun-sb-sequence-make-sequence-like.texinfo
-
-@tindex @cl{sequence}
-@findex @sequence{make-sequence-like}
-@findex @cl{subseq}
-@findex @cl{copy-seq}
-@findex @sequence{adjust-sequence}
+@anchor{Generic function sb-sequence length}
+@ffindex @sortas{length sb-sequence} length [sb-sequence]
+@deffn{Generic function} sb-sequence:length sequence
+Returns the length of @code{sequence} or signals a
+@code{sequence:protocol-unimplemented} error if the sequence protocol is
+not implemented for the class of @code{sequence}.
+@end deffn
+@anchor{Generic function sb-sequence elt}
+@ffindex @sortas{elt sb-sequence} elt [sb-sequence]
+@deffn{Generic function} sb-sequence:elt sequence index
+Returns the element at position @code{index} of @code{sequence} or signals a
+@code{sequence:protocol-unimplemented} error if the sequence protocol is
+not implemented for the class of @code{sequence}.
+@end deffn
+@anchor{Setf generic function sb-sequence elt}
+@ffindex @sortas{elt sb-sequence} elt [sb-sequence]
+@deffn{Setf generic function} sb-sequence:elt sequence index
+Returns the element at position @code{index} of @code{sequence} or signals a
+@code{sequence:protocol-unimplemented} error if the sequence protocol is
+not implemented for the class of @code{sequence}.
+@end deffn
+@anchor{Generic function sb-sequence adjust-sequence}
+@ffindex @sortas{adjust-sequence sb-sequence} adjust-sequence [sb-sequence]
+@deffn{Generic function} sb-sequence:adjust-sequence sequence length &key initial-element initial-contents
+Returns destructively modified @code{sequence} or a freshly allocated
+sequence of the same class as @code{sequence} of length @code{length}. Elements
+of the returned sequence are initialized to @code{initial-element}, if
+supplied, initialized to @code{initial-contents} if supplied, or identical
+to the elements of @code{sequence} if neither is supplied. Signals a
+@code{sequence:protocol-unimplemented} error if the sequence protocol is
+not implemented for the class of @code{sequence}.
+@end deffn
+@anchor{Generic function sb-sequence make-sequence-like}
+@ffindex @sortas{make-sequence-like sb-sequence} make-sequence-like [sb-sequence]
+@deffn{Generic function} sb-sequence:make-sequence-like sequence length &key initial-element initial-contents
+Returns a freshly allocated sequence of length @code{length} and of the
+same class as @code{sequence}. Elements of the new sequence are
+initialized to @code{initial-element}, if supplied, initialized to
+@code{initial-contents} if supplied, or undefined if neither is supplied.
+Signals a @code{sequence:protocol-unimplemented} error if the sequence
+protocol is not implemented for the class of @code{sequence}.
+@end deffn
@code{make-sequence-like} is needed for functions returning
-freshly-allocated sequences such as @code{subseq} or
-@code{copy-seq}. @code{adjust-sequence} is needed for functions which
-destructively modify their arguments such as @code{delete}. In fact, all
-other sequence functions can be implemented in terms of the above
-functions and actually are, if no additional methods are
-defined. However, relying on these generic implementations, in
-particular not implementing the iterator protocol can incur a high
-performance penalty @xref{Iterator Protocol}.
+freshly-allocated sequences such as @code{subseq} or @code{copy-seq}.
+@code{adjust-sequence} is needed for functions which destructively modify
+their arguments such as @code{delete}. In fact, all other sequence
+functions can be implemented in terms of the above functions and
+actually are, if no additional methods are defined. However, relying
+on these generic implementations, in particular not implementing the
+@ref{exseq iterator protocol} can incur a high performance penalty.
When the sequence protocol is only partially implemented for a given
-@code{sequence} subclass, an attempt to apply one of the missing
-operations to instances of that class signals the following condition:
-
-@include condition-sb-sequence-protocol-unimplemented.texinfo
+@code{sequence} subclass, an attempt to apply one of the missing operations
+to instances of that class signals the following condition:
+@anchor{Condition sb-sequence protocol-unimplemented}
+@ttindex @sortas{protocol-unimplemented sb-sequence} protocol-unimplemented [sb-sequence]
+@deffn{Condition} sb-sequence:protocol-unimplemented
+This error is signaled if a sequence operation is applied to an
+instance of a sequence class that does not support the
+operation.
+@end deffn
In addition to the mandatory functions above, methods on the sequence
functions listed below can be defined.
-There are two noteworthy irregularities:
-@itemize
-@item
-The function @code{sb-sequence:emptyp} does not have a counterpart in
-the @code{cl} package. It is intended to be used instead of
-@code{length} when working with lazy or infinite sequences.
-
-@item
-The functions @code{map}, @code{concatenate} and @code{merge} receive a
-type designator specifying the type of the constructed sequence as their
-first argument. However, the corresponding generic functions
-@code{sb-sequence:map}, @code{sb-sequence:concatenate} and
-@code{sb-sequence:merge} receive a prototype instance of the requested
-@code{sequence} subclass instead.
-@end itemize
-
-@include fun-sb-sequence-emptyp.texinfo
+There are some noteworthy irregularities:
@itemize
-@item
-@code{sb-sequence:count}, @code{sb-sequence:count-if}, @code{sb-sequence:count-if-not}
-
-@item
-@code{sb-sequence:find}, @code{sb-sequence:find-if}, @code{sb-sequence:find-if-not}
-
-@item
-@code{sb-sequence:position}, @code{sb-sequence:position-if}, @code{sb-sequence:position-if-not}
-
-@item
-@code{sb-sequence:subseq}
-
-@item
-@code{sb-sequence:copy-seq}
-
-@item
-@code{sb-sequence:fill}
-
-@item
-@include fun-sb-sequence-map.texinfo
-
-@item
-@code{sb-sequence:nsubstitute}, @code{sb-sequence:nsubstitute-if},
-@code{sb-sequence:nsubstitute-if-not}, @code{sb-sequence:substitute},
-@code{sb-sequence:substitute-if}, @code{sb-sequence:substitute-if-not}
-
-@item
-@code{sb-sequence:replace}
-
-@item
-@code{sb-sequence:nreverse}, @code{sb-sequence:reverse}
-
-@item
-@include fun-sb-sequence-concatenate.texinfo
-
-@item
-@code{sb-sequence:reduce}
-
-@item
-@code{sb-sequence:mismatch}
-
-@item
-@code{sb-sequence:search}
-
-@item
-@code{sb-sequence:delete}, @code{sb-sequence:delete-if}, @code{sb-sequence:delete-if-not},
-@code{sb-sequence:remove}, @code{sb-sequence:remove-if}, @code{sb-sequence:remove-if-not},
-
-@item
-@code{sb-sequence:delete-duplicates}, @code{sb-sequence:remove-duplicates}
-
-@item
-@code{sb-sequence:sort}, @code{sb-sequence:stable-sort}
-
-@item
-@include fun-sb-sequence-merge.texinfo
+@item The function @code{sb-sequence:emptyp} does not have a counterpart in the
+ @code{cl} package. It is intended to be used instead of
+ @code{sb-sequence:length} when working with lazy or infinite sequences.
+
+@item @code{sb-sequence:dosequence} does not have a direct counterpart either.
+ It is like @code{dolist} in spirit but traverses generic sequences.
+
+@item The functions @code{map}, @code{concatenate} and @code{merge} receive a type designator
+ specifying the type of the constructed sequence as their first
+ argument. However, the corresponding generic functions
+ @code{sb-sequence:map}, @code{sb-sequence:concatenate} and @code{sb-sequence:merge}
+ receive a prototype instance of the requested @code{sequence} subclass
+ instead.
+
+@item @code{cl:map-into} has no generic sequence counterpart, as its lambda
+ list does not provide reasonable specialization opportunities, but
+ it supports extensible sequences directly.
@end itemize
-@findex @cl{dolist}
-In the spirit of @code{dolist}, generic sequences can be traversed using
-the macro
-
-@include macro-sb-sequence-dosequence.texinfo
-
-@node Iterator Protocol
-@comment node-name, next, previous, up
+@anchor{Generic function sb-sequence emptyp}
+@ffindex @sortas{emptyp sb-sequence} emptyp [sb-sequence]
+@deffn{Generic function} sb-sequence:emptyp sequence
+Returns @code{t} if @code{sequence} is an empty sequence and @code{nil}
+otherwise. Signals an error if @code{sequence} is not a sequence.
+@end deffn
+@anchor{Macro sb-sequence dosequence}
+@ffindex @sortas{dosequence sb-sequence} dosequence [sb-sequence]
+@deffn{Macro} sb-sequence:dosequence (element sequence &optional return) &body body
+Executes @code{body} with @code{element} subsequently bound to each element of
+@code{sequence}, then returns @code{return}.
+@end deffn
+The remaining list parallels the @emph{Sequence Dictionary}, @code{17.3} @code{clhs}.
+
+@anchor{Generic function sb-sequence copy-seq}
+@ffindex @sortas{copy-seq sb-sequence} copy-seq [sb-sequence]
+@deffn{Generic function} sb-sequence:copy-seq sequence
+@end deffn
+@anchor{Generic function sb-sequence fill}
+@ffindex @sortas{fill sb-sequence} fill [sb-sequence]
+@deffn{Generic function} sb-sequence:fill sequence item &key start end
+@end deffn
+@anchor{Generic function sb-sequence subseq}
+@ffindex @sortas{subseq sb-sequence} subseq [sb-sequence]
+@deffn{Generic function} sb-sequence:subseq sequence start &optional end
+@end deffn
+@anchor{Function sb-sequence map}
+@ffindex @sortas{map sb-sequence} map [sb-sequence]
+@deffn{Function} sb-sequence:map result-prototype function sequence &rest sequences
+Implements @code{cl:map} for extended sequences.
+
+@code{result-prototype} corresponds to the @code{result-type} of @code{cl:map} but
+receives a prototype instance of an extended sequence class
+instead of a type specifier. By dispatching on @code{result-prototype},
+methods on this generic function specify how extended sequence
+classes act when they are specified as the result type in a @code{cl:map}
+call. @code{result-prototype} may not be fully initialized and thus
+should only be used for dispatch and to determine its class.
+
+Another difference to @code{cl:map} is that @code{function} is a function, not a
+function designator.
+@end deffn
+@anchor{Generic function sb-sequence reduce}
+@ffindex @sortas{reduce sb-sequence} reduce [sb-sequence]
+@deffn{Generic function} sb-sequence:reduce function sequence &key from-end start end initial-value key
+@end deffn
+@anchor{Generic function sb-sequence search}
+@ffindex @sortas{search sb-sequence} search [sb-sequence]
+@deffn{Generic function} sb-sequence:search sequence1 sequence2 &key from-end start1 end1 start2 end2 test test-not key
+@end deffn
+@anchor{Generic function sb-sequence mismatch}
+@ffindex @sortas{mismatch sb-sequence} mismatch [sb-sequence]
+@deffn{Generic function} sb-sequence:mismatch sequence1 sequence2 &key from-end start1 end1 start2 end2 test test-not key
+@end deffn
+@anchor{Generic function sb-sequence replace}
+@ffindex @sortas{replace sb-sequence} replace [sb-sequence]
+@deffn{Generic function} sb-sequence:replace sequence1 sequence2 &key start1 end1 start2 end2
+@end deffn
+@anchor{Function sb-sequence concatenate}
+@ffindex @sortas{concatenate sb-sequence} concatenate [sb-sequence]
+@deffn{Function} sb-sequence:concatenate result-prototype &rest sequences
+Implements @code{cl:concatenate} for extended sequences.
+
+@code{result-prototype} corresponds to the @code{result-type} of @code{cl:concatenate}
+but receives a prototype instance of an extended sequence class
+instead of a type specifier. By dispatching on @code{result-prototype},
+methods on this generic function specify how extended sequence
+classes act when they are specified as the result type in a
+@code{cl:concatenate} call. @code{result-prototype} may not be fully initialized
+and thus should only be used for dispatch and to determine its
+class.
+@end deffn
+@anchor{Function sb-sequence merge}
+@ffindex @sortas{merge sb-sequence} merge [sb-sequence]
+@deffn{Function} sb-sequence:merge result-prototype sequence1 sequence2 predicate &key key
+Implements @code{cl:merge} for extended sequences.
+
+@code{result-prototype} corresponds to the @code{result-type} of @code{cl:merge} but
+receives a prototype instance of an extended sequence class
+instead of a type specifier. By dispatching on @code{result-prototype},
+methods on this generic function specify how extended sequence
+classes act when they are specified as the result type in a
+@code{cl:merge} call. @code{result-prototype} may not be fully initialized and
+thus should only be used for dispatch and to determine its class.
+
+Another difference to @code{cl:merge} is that @code{predicate} is a function,
+not a function designator.
+@end deffn
+Counting:
+
+@anchor{Generic function sb-sequence count}
+@ffindex @sortas{count sb-sequence} count [sb-sequence]
+@deffn{Generic function} sb-sequence:count item sequence &key from-end start end test test-not key
+@end deffn
+@anchor{Generic function sb-sequence count-if}
+@ffindex @sortas{count-if sb-sequence} count-if [sb-sequence]
+@deffn{Generic function} sb-sequence:count-if pred sequence &key from-end start end key
+@end deffn
+@anchor{Generic function sb-sequence count-if-not}
+@ffindex @sortas{count-if-not sb-sequence} count-if-not [sb-sequence]
+@deffn{Generic function} sb-sequence:count-if-not pred sequence &key from-end start end key
+@end deffn
+Reversing:
+
+@anchor{Generic function sb-sequence reverse}
+@ffindex @sortas{reverse sb-sequence} reverse [sb-sequence]
+@deffn{Generic function} sb-sequence:reverse sequence
+@end deffn
+@anchor{Generic function sb-sequence nreverse}
+@ffindex @sortas{nreverse sb-sequence} nreverse [sb-sequence]
+@deffn{Generic function} sb-sequence:nreverse sequence
+@end deffn
+Sorting:
+
+@anchor{Generic function sb-sequence sort}
+@ffindex @sortas{sort sb-sequence} sort [sb-sequence]
+@deffn{Generic function} sb-sequence:sort sequence predicate &key key
+@end deffn
+@anchor{Generic function sb-sequence stable-sort}
+@ffindex @sortas{stable-sort sb-sequence} stable-sort [sb-sequence]
+@deffn{Generic function} sb-sequence:stable-sort sequence predicate &key key
+@end deffn
+Finding an element:
+
+@anchor{Generic function sb-sequence find}
+@ffindex @sortas{find sb-sequence} find [sb-sequence]
+@deffn{Generic function} sb-sequence:find item sequence &key from-end start end test test-not key
+@end deffn
+@anchor{Generic function sb-sequence find-if}
+@ffindex @sortas{find-if sb-sequence} find-if [sb-sequence]
+@deffn{Generic function} sb-sequence:find-if pred sequence &key from-end start end key
+@end deffn
+@anchor{Generic function sb-sequence find-if-not}
+@ffindex @sortas{find-if-not sb-sequence} find-if-not [sb-sequence]
+@deffn{Generic function} sb-sequence:find-if-not pred sequence &key from-end start end key
+@end deffn
+Finding a position:
+
+@anchor{Generic function sb-sequence position}
+@ffindex @sortas{position sb-sequence} position [sb-sequence]
+@deffn{Generic function} sb-sequence:position item sequence &key from-end start end test test-not key
+@end deffn
+@anchor{Generic function sb-sequence position-if}
+@ffindex @sortas{position-if sb-sequence} position-if [sb-sequence]
+@deffn{Generic function} sb-sequence:position-if pred sequence &key from-end start end key
+@end deffn
+@anchor{Generic function sb-sequence position-if-not}
+@ffindex @sortas{position-if-not sb-sequence} position-if-not [sb-sequence]
+@deffn{Generic function} sb-sequence:position-if-not pred sequence &key from-end start end key
+@end deffn
+Substituting elements:
+
+@anchor{Generic function sb-sequence substitute}
+@ffindex @sortas{substitute sb-sequence} substitute [sb-sequence]
+@deffn{Generic function} sb-sequence:substitute new old sequence &key start end from-end test test-not count key
+@end deffn
+@anchor{Generic function sb-sequence substitute-if}
+@ffindex @sortas{substitute-if sb-sequence} substitute-if [sb-sequence]
+@deffn{Generic function} sb-sequence:substitute-if new predicate sequence &key start end from-end count key
+@end deffn
+@anchor{Generic function sb-sequence substitute-if-not}
+@ffindex @sortas{substitute-if-not sb-sequence} substitute-if-not [sb-sequence]
+@deffn{Generic function} sb-sequence:substitute-if-not new predicate sequence &key start end from-end count key
+@end deffn
+@anchor{Generic function sb-sequence nsubstitute}
+@ffindex @sortas{nsubstitute sb-sequence} nsubstitute [sb-sequence]
+@deffn{Generic function} sb-sequence:nsubstitute new old sequence &key start end from-end test test-not count key
+@end deffn
+@anchor{Generic function sb-sequence nsubstitute-if}
+@ffindex @sortas{nsubstitute-if sb-sequence} nsubstitute-if [sb-sequence]
+@deffn{Generic function} sb-sequence:nsubstitute-if new predicate sequence &key start end from-end count key
+@end deffn
+@anchor{Generic function sb-sequence nsubstitute-if-not}
+@ffindex @sortas{nsubstitute-if-not sb-sequence} nsubstitute-if-not [sb-sequence]
+@deffn{Generic function} sb-sequence:nsubstitute-if-not new predicate sequence &key start end from-end count key
+@end deffn
+Removing elements:
+
+@anchor{Generic function sb-sequence remove}
+@ffindex @sortas{remove sb-sequence} remove [sb-sequence]
+@deffn{Generic function} sb-sequence:remove item sequence &key from-end test test-not start end count key
+@end deffn
+@anchor{Generic function sb-sequence remove-if}
+@ffindex @sortas{remove-if sb-sequence} remove-if [sb-sequence]
+@deffn{Generic function} sb-sequence:remove-if predicate sequence &key from-end start end count key
+@end deffn
+@anchor{Generic function sb-sequence remove-if-not}
+@ffindex @sortas{remove-if-not sb-sequence} remove-if-not [sb-sequence]
+@deffn{Generic function} sb-sequence:remove-if-not predicate sequence &key from-end start end count key
+@end deffn
+@anchor{Generic function sb-sequence delete}
+@ffindex @sortas{delete sb-sequence} delete [sb-sequence]
+@deffn{Generic function} sb-sequence:delete item sequence &key from-end test test-not start end count key
+@end deffn
+@anchor{Generic function sb-sequence delete-if}
+@ffindex @sortas{delete-if sb-sequence} delete-if [sb-sequence]
+@deffn{Generic function} sb-sequence:delete-if predicate sequence &key from-end start end count key
+@end deffn
+@anchor{Generic function sb-sequence delete-if-not}
+@ffindex @sortas{delete-if-not sb-sequence} delete-if-not [sb-sequence]
+@deffn{Generic function} sb-sequence:delete-if-not predicate sequence &key from-end start end count key
+@end deffn
+Removing duplicates:
+
+@anchor{Generic function sb-sequence remove-duplicates}
+@ffindex @sortas{remove-duplicates sb-sequence} remove-duplicates [sb-sequence]
+@deffn{Generic function} sb-sequence:remove-duplicates sequence &key from-end test test-not start end key
+@end deffn
+@anchor{Generic function sb-sequence delete-duplicates}
+@ffindex @sortas{delete-duplicates sb-sequence} delete-duplicates [sb-sequence]
+@deffn{Generic function} sb-sequence:delete-duplicates sequence &key from-end test test-not start end key
+@end deffn
+@node exseq iterator protocol
@subsection Iterator Protocol
-The iterator protocol allows subsequently accessing some or all elements
-of a sequence in forward or reverse direction. Users first call
-@code{make-sequence-iterator} to create an iteration state and
-receive functions to query and mutate it. These functions allow, among
-other things, moving to, retrieving or modifying elements of the
-sequence. An iteration state consists of a state object, a limit object,
-a from-end indicator and the following six functions to query or mutate
-this state:
-@findex @sequence{make-sequence-iterator}
-@deffn {Function} @code{step function} sequence iterator from-end
-Moves the iterator one position forward or backward in the associated
-sequence depending on the iteration direction.
-@end deffn
-@deffn {Function} @code{endp function} sequence iterator limit from-end
-Returns non-@code{nil} when the iterator has reached the end of the
-associated sequence with respect to the iteration direction.
-@end deffn
-@deffn {Function} @code{element function} sequence iterator
-Returns the sequence element associated to the current position of the
-iteration.
-@end deffn
-@deffn {Function} @code{setf element function} new-value sequence iterator
-Destructively modifies the associates sequence by replacing the sequence
-element associated to the current iteration position with a new value.
-@end deffn
-@deffn {Function} @code{index function} sequence iterator
-Returns the position of the iteration in the associated sequence.
-@end deffn
-@deffn {Function} @code{copy function} sequence iterator
-Returns a copy of the iteration state which can be mutated independently
-of the copied iteration state.
-@end deffn
+The general iterator protocol allows subsequently accessing some or
+all elements of a sequence in forward or reverse direction. Users
+first call @code{sb-sequence:make-sequence-iterator} to create an iteration
+state and receive functions to query and mutate it. These functions
+allow, among other things, moving to, retrieving or modifying
+elements of the sequence. The iteration state consists of a state
+object, a limit object, a from-end indicator and six functions to
+query or mutate this state.
An iterator is created by calling:
-@include fun-sb-sequence-make-sequence-iterator.texinfo
+@anchor{Function sb-sequence make-sequence-iterator}
+@ffindex @sortas{make-sequence-iterator sb-sequence} make-sequence-iterator [sb-sequence]
+@deffn{Function} sb-sequence:make-sequence-iterator sequence &key from-end start end
+Returns a sequence iterator for @code{sequence} or, if @code{start} and/or @code{end}
+are supplied, the subsequence bounded by @code{start} and @code{end} as nine
+values:
-@findex @sequence{make-sequence-iterator}
-@findex @sequence{make-simple-sequence-iterator}
-@tindex @cl{sequence}
-Note that @code{make-sequence-iterator} calls
-@code{make-simple-sequence-iterator} when there is no specialized
-method for a particular @code{sequence} subclass. @xref{Simple Iterator
-Protocol}.
+1. iterator state
+2. limit
+3. from-end
+4. step function
+5. endp function
+6. element function
+7. setf element function
+8. index function
+9. copy state function
+If @code{from-end} is @code{nil}, the constructed iterator visits the specified
+elements in the order in which they appear in @code{sequence}. Otherwise,
+the elements are visited in the opposite order.
+
+The six functions (items 4-9 in the list) have the same contract as
+the generic functions described in
+@ref{exseq simple iterator protocol}. In fact, when there is
+no specialized method for a particular @code{sequence} subclass,
+@code{sb-sequence:make-sequence-iterator} calls
+@code{sb-sequence:make-simple-sequence-iterator} and returns those six
+generic functions.
+@end deffn
The following convenience macros simplify traversing sequences using
iterators:
-@include macro-sb-sequence-with-sequence-iterator.texinfo
-@include macro-sb-sequence-with-sequence-iterator-functions.texinfo
-
-@node Simple Iterator Protocol
-@comment node-name, next, previous, up
+@anchor{Macro sb-sequence with-sequence-iterator}
+@ffindex @sortas{with-sequence-iterator sb-sequence} with-sequence-iterator [sb-sequence]
+@deffn{Macro} sb-sequence:with-sequence-iterator (&optional iterator limit from-end-p step endp element set-element index copy) (sequence &key from-end start end) &body body
+Executes @code{body} with the elements of @code{vars} bound to the iteration
+state returned by @code{sequence:make-sequence-iterator} for @code{sequence} and
+@code{args}. Elements of @code{vars} may be @code{nil} in which case the corresponding
+value returned by @code{sequence:make-sequence-iterator} is ignored.
+@end deffn
+@anchor{Macro sb-sequence with-sequence-iterator-functions}
+@ffindex @sortas{with-sequence-iterator-functions sb-sequence} with-sequence-iterator-functions [sb-sequence]
+@deffn{Macro} sb-sequence:with-sequence-iterator-functions (&optional step endp elt setf index copy) (sequence &rest args &key from-end start end) &body body
+Executes @code{body} with the names @code{step}, @code{endp}, @code{elt}, @code{setf}, @code{index} and @code{copy}
+bound to local functions which execute the iteration state query and
+mutation functions returned by @code{sequence:make-sequence-iterator} for
+@code{sequence} and @code{args}. When some names are not supplied or @code{nil} is supplied
+for a given name, no local functions are established for those names.
+The functions established for @code{step}, @code{endp}, @code{elt}, @code{setf}, @code{index} and @code{copy}
+have dynamic extent.
+@end deffn
+@node exseq simple iterator protocol
@subsection Simple Iterator Protocol
For cases in which the full flexibility and performance of the general
@@ -851,496 +1281,1157 @@ sequence iterator protocol is not required, there is a simplified
sequence iterator protocol consisting of a few generic functions which
can be specialized for iterator classes:
-@include fun-sb-sequence-iterator-step.texinfo
-@include fun-sb-sequence-iterator-endp.texinfo
-@include fun-sb-sequence-iterator-element.texinfo
-@include fun-sb-sequence-setf-iterator-element.texinfo
-@include fun-sb-sequence-iterator-index.texinfo
-@include fun-sb-sequence-iterator-copy.texinfo
-
+@anchor{Generic function sb-sequence iterator-step}
+@ffindex @sortas{iterator-step sb-sequence} iterator-step [sb-sequence]
+@deffn{Generic function} sb-sequence:iterator-step sequence iterator from-end
+Moves @code{iterator} one position forward or backward in @code{sequence}
+depending on the iteration direction encoded in @code{from-end}.
+@end deffn
+@anchor{Generic function sb-sequence iterator-endp}
+@ffindex @sortas{iterator-endp sb-sequence} iterator-endp [sb-sequence]
+@deffn{Generic function} sb-sequence:iterator-endp sequence iterator limit from-end
+Returns non-@code{nil} when @code{iterator} has reached @code{limit} (which may
+correspond to the end of @code{sequence}) with respect to the iteration
+direction encoded in @code{from-end}.
+@end deffn
+@anchor{Generic function sb-sequence iterator-element}
+@ffindex @sortas{iterator-element sb-sequence} iterator-element [sb-sequence]
+@deffn{Generic function} sb-sequence:iterator-element sequence iterator
+Returns the element of @code{sequence} associated to the position of
+@code{iterator}.
+@end deffn
+@anchor{Setf generic function sb-sequence iterator-element}
+@ffindex @sortas{iterator-element sb-sequence} iterator-element [sb-sequence]
+@deffn{Setf generic function} sb-sequence:iterator-element sequence iterator
+Returns the element of @code{sequence} associated to the position of
+@code{iterator}.
+@end deffn
+@anchor{Generic function sb-sequence iterator-index}
+@ffindex @sortas{iterator-index sb-sequence} iterator-index [sb-sequence]
+@deffn{Generic function} sb-sequence:iterator-index sequence iterator
+Returns the position of @code{iterator} in @code{sequence}.
+@end deffn
+@anchor{Generic function sb-sequence iterator-copy}
+@ffindex @sortas{iterator-copy sb-sequence} iterator-copy [sb-sequence]
+@deffn{Generic function} sb-sequence:iterator-copy sequence iterator
+Returns a copy of @code{iterator} which also traverses @code{sequence} but can
+be mutated independently of @code{iterator}.
+@end deffn
Iterator objects implementing the above simple iteration protocol are
created by calling the following generic function:
-@include fun-sb-sequence-make-simple-sequence-iterator.texinfo
+@anchor{Generic function sb-sequence make-simple-sequence-iterator}
+@ffindex @sortas{make-simple-sequence-iterator sb-sequence} make-simple-sequence-iterator [sb-sequence]
+@deffn{Generic function} sb-sequence:make-simple-sequence-iterator sequence &key from-end start end
+Returns a sequence iterator for @code{sequence}, @code{start}, @code{end} and @code{from-end}
+as three values:
-@node Support For Unix
-@comment node-name, next, previous, up
+1. iterator state
+2. limit
+3. from-end
+
+The returned iterator can be used with the generic iterator
+functions described in @ref{exseq simple iterator protocol}.
+@end deffn
+@node support for unix
@section Support For Unix
@menu
-* Command-line arguments::
-* Querying the process environment::
-* Running external programs::
+* Running external programs: running external programs.
@end menu
-@node Command-line arguments
-@subsection Command-line arguments
-@vindex @sbext{@earmuffs{posix-argv}}
+@anchor{Variable sb-ext *posix-argv*}
+@vvindex @sortas{posix-argv* sb-ext} *posix-argv* [sb-ext]
+@deffn{Variable} sb-ext:*posix-argv*
+A list of strings related to the UNIX command line (@code{argv} in C).
-The UNIX command line can be read from the variable
-@code{sb-ext:*posix-argv*}.
-
-@node Querying the process environment
-@subsection Querying the process environment
-
-The UNIX environment can be queried with the
-@code{sb-ext:posix-getenv} function.
-
-@include fun-sb-ext-posix-getenv.texinfo
-
-@node Running external programs
+@ref{runtime options} are processed and removed by the runtime.
+The default toplevel (see @code{sb-ext:save-lisp-and-die}) also removes the
+@ref{toplevel options} that it processes.
+@end deffn
+@anchor{Function sb-ext posix-getenv}
+@ffindex @sortas{posix-getenv sb-ext} posix-getenv [sb-ext]
+@deffn{Function} sb-ext:posix-getenv name
+Return the @code{value} part of the environment string @code{name=value} which
+corresponds to @code{name}, or @code{nil} if there is none. See @code{getenv(3)}.
+@end deffn
+@anchor{Function sb-ext posix-environ}
+@ffindex @sortas{posix-environ sb-ext} posix-environ [sb-ext]
+@deffn{Function} sb-ext:posix-environ
+Return the Unix environment as a list of @code{simple-string}s. See @code{man environ}.
+@end deffn
+@node running external programs
@subsection Running external programs
External programs can be run with @code{sb-ext:run-program}.
-@footnote{In SBCL versions prior to 1.0.13, @code{sb-ext:run-program}
-searched for executables in a manner somewhat incompatible with other
-languages. As of this version, SBCL uses the system library routine
-@code{execvp(3)}, and no longer contains the function,
+
+@quotation
+@emph{Note}: In SBCL versions prior to 1.0.13, @code{sb-ext:run-program}
+searched for executables in a manner somewhat incompatible with
+other languages. As of this version, SBCL uses the system library
+routine @code{execvp(3)}, and no longer contains the function
@code{find-executable-in-search-path}, which implemented the old
-search. Users who need this function may find it
-in @file{run-program.lisp} versions 1.67 and earlier in SBCL's CVS
+search. Users who need this function may find it in
+@code{run-program.lisp} versions 1.67 and earlier in SBCL's CVS
repository here
-@url{http://sbcl.cvs.sourceforge.net/sbcl/sbcl/src/code/run-program.lisp?view=log}. However,
-we caution such users that this search routine finds executables that
-system library routines do not.}
+@url{http://sbcl.cvs.sourceforge.net/sbcl/sbcl/src/code/run-program.lisp?view=log}.
+However, we caution such users that this search routine finds
+executables that system library routines do not.
+@end quotation
-@include fun-sb-ext-run-program.texinfo
+@anchor{Function sb-ext run-program}
+@ffindex @sortas{run-program sb-ext} run-program [sb-ext]
+@deffn{Function} sb-ext:run-program program args &key env environment wait search pty input if-input-does-not-exist output if-output-exists error if-error-exists status-hook external-format directory preserve-fds use-posix-spawn
+@code{run-program} creates a new process specified by @code{program}.
+@code{args} is a list of strings to be passed literally to the new program.
+In POSIX environments, this list becomes the array supplied as the second
+parameter to the execv() or execvp() system call, each list element becoming
+one array element. The strings should not contain shell escaping, as there is
+no shell involvement. Further note that while conventionally the process
+receives its own pathname in argv[0], that is automatic, and the 0th string
+should not be present in @code{args}.
-When @code{sb-ext:run-program} is called with @code{wait} equal to
-NIL, an instance of class @var{sb-ext:process} is returned. The
-following functions are available for use with processes:
+The program arguments and the environment are encoded using the
+default external format for streams.
-@include fun-sb-ext-process-p.texinfo
+@code{run-program} will return a @code{process} structure. See the CMU Common Lisp
+Users Manual for details about the @code{process} structure.
-@include fun-sb-ext-process-input.texinfo
+Notes about Unix environments (as in the @code{:environment} and @code{:env} args):
-@include fun-sb-ext-process-output.texinfo
+@itemize
+@item The SBCL implementation of @code{run-program}, like Perl and many other
+ programs, but unlike the original CMU CL implementation, copies the
+ Unix environment by default.
-@include fun-sb-ext-process-error.texinfo
+@item Running Unix programs from a setuid process, or in any other
+ situation where the Unix environment is under the control of someone
+ else, is a mother lode of security problems. If you are
+ contemplating doing this, read about it first. (The Perl community
+ has a lot of good documentation about this and other security issues
+ in script-like programs.)
+@end itemize
-@include fun-sb-ext-process-alive-p.texinfo
+The @code{&key} arguments have the following meanings:
-@include fun-sb-ext-process-status.texinfo
+@itemize
+@item @code{:environment}
-@include fun-sb-ext-process-wait.texinfo
+A list of @code{string}s describing the new Unix environment
+(as in "man environ"). The default is to copy the environment of
+the current process.
-@include fun-sb-ext-process-exit-code.texinfo
+@item @code{:env}
-@include fun-sb-ext-process-core-dumped.texinfo
+An alternative lossy representation of the new Unix environment,
+for compatibility with CMU CL.
-@include fun-sb-ext-process-close.texinfo
+@item @code{:search}
-@include fun-sb-ext-process-kill.texinfo
+Look for @code{program} in each of the directories in the child's $PATH
+environment variable. Otherwise an absolute pathname is required.
-@node Unicode Support
-@comment node-name, next, previous, up
+@item @code{:wait}
+
+If non-@code{nil} (default), wait until the created process finishes. If
+@code{nil}, continue running Lisp until the program finishes.
+
+@item @code{:pty} (not supported on win32)
+
+Either @code{t}, @code{nil}, or a stream. Unless @code{nil}, the subprocess is
+established under a @code{pty}. If @code{:pty} is a stream, all output to this
+pty is sent to this stream, otherwise the @code{process-pty} slot is
+filled in with a stream connected to pty that can read output and
+write input.
+
+@item @code{:input}
+
+Either @code{t}, @code{nil} (the default), a pathname, a stream, or @code{:stream}.
+
+@itemize
+@item @code{t}: the standard input for the current process is inherited.
+@item @code{nil}: @code{/dev/null} (nul on win32) is used.
+@item Pathname: the specified file is used.
+@item Stream: all the input is read from that stream and sent to the
+ subprocess.
+@item @code{:stream}: the @code{process-input} slot is filled in with a stream that
+ sends its output to the process.
+@end itemize
+
+@item @code{:if-input-does-not-exist} (when @code{:input} is the name of a file)
+
+It is one of:
+
+@itemize
+@item @code{:error} to generate an error
+@item @code{:create} to create an empty file
+@item @code{nil} (the default) to return @code{nil} from @code{run-program}
+@end itemize
+
+@item @code{:output}
+
+Either @code{t}, @code{nil} (the default), a pathname, a stream, or @code{:stream}.
+
+@itemize
+@item @code{t}: the standard output for the current process is inherited.
+@item @code{nil}: @code{/dev/null} (nul on win32) is used.
+@item Pathname: the specified file is used.
+@item Stream: all the output from the process is written to this stream.
+@item @code{:stream}: the @code{process-output} slot is filled in with a stream that
+ can be read to get the output.
+@end itemize
+
+@item @code{:error}
+
+Same as @code{:output}, additionally accepts @code{:output}, making all error
+output routed to the same place as normal output. Defaults to
+@code{:output}.
+
+@item @code{:if-output-exists} (when @code{:output} is the name of a file)
+
+It is one of:
+
+@itemize
+@item @code{:error} (the default) to generate an error
+@item @code{:supersede} to supersede the file with output from the program
+@item @code{:append} to append output from the program to the file
+@item @code{nil} to return @code{nil} from @code{run-program}, without doing anything
+@end itemize
+
+@item @code{:if-error-exists}
+
+Same as @code{:if-output-exists}, controlling @code{:error} output to files.
+Ignored when @code{:error} @code{:output}. Defaults to @code{:error}.
+
+@item @code{:status-hook}
+
+This is a function the system calls whenever the status of the
+process changes. The function takes the process as an argument.
+
+@item @code{:external-format}
+
+The external-format to use for @code{:input}, @code{:output}, and @code{:error} @code{:stream}s.
+
+@item @code{:directory}
+
+Specifies the directory in which the program should be run.
+@code{nil} (the default) means the directory is unchanged.
+
+@item @code{:preserve-fds}
+
+A sequence of file descriptors which should remain open in the child
+process.
+@end itemize
+
+Windows specific options:
+
+@itemize
+@item @code{:escape-arguments} (default @code{t})
+
+Controls escaping of the arguments passed to CreateProcess.
+
+@item @code{:window} (default @code{nil})
+
+When @code{nil}, the subprocess decides how it will display its window.
+The following options control how the subprocess window should be
+displayed: @code{:hide}, @code{:show-normal}, @code{:show-maximized},
+@code{:show-minimized}, @code{:show-no-activate}, @code{:show-min-no-active},
+@code{:show-na}.
+
+@quotation
+@emph{Note}: console application subprocesses may or may not display
+a console window depending on whether the SBCL runtime is itself
+a console or GUI application. Invoke @code{cmd /c start} to
+consistently display a console window or use the @code{:window}
+@code{:hide} option to consistently hide the console window.
+@end quotation
+@end itemize
+@end deffn
+When @code{sb-ext:run-program} is called with @code{:wait} @code{nil}, an process object
+is returned. The following functions are available for use with
+processes:
+
+@anchor{Function sb-ext process-p}
+@ffindex @sortas{process-p sb-ext} process-p [sb-ext]
+@deffn{Function} sb-ext:process-p object
+@code{t} if @code{object} is a @code{process}, @code{nil} otherwise.
+@end deffn
+@anchor{Function sb-ext process-input}
+@ffindex @sortas{process-input sb-ext} process-input [sb-ext]
+@deffn{Function} sb-ext:process-input instance
+The input stream of the process or @code{nil}.
+@end deffn
+@anchor{Function sb-ext process-output}
+@ffindex @sortas{process-output sb-ext} process-output [sb-ext]
+@deffn{Function} sb-ext:process-output instance
+The output stream of the process or @code{nil}.
+@end deffn
+@anchor{Function sb-ext process-error}
+@ffindex @sortas{process-error sb-ext} process-error [sb-ext]
+@deffn{Function} sb-ext:process-error instance
+The error stream of the process or @code{nil}.
+@end deffn
+@anchor{Function sb-ext process-alive-p}
+@ffindex @sortas{process-alive-p sb-ext} process-alive-p [sb-ext]
+@deffn{Function} sb-ext:process-alive-p process
+Return @code{t} if @code{process} is still alive, @code{nil} otherwise. Can return a false
+positive on a closed process.
+@end deffn
+@anchor{Function sb-ext process-status}
+@ffindex @sortas{process-status sb-ext} process-status [sb-ext]
+@deffn{Function} sb-ext:process-status process
+Return the current status of @code{process}. The result is one of @code{:running},
+@code{:stopped}, @code{:exited}, @code{:signaled}.
+@end deffn
+@anchor{Function sb-ext process-wait}
+@ffindex @sortas{process-wait sb-ext} process-wait [sb-ext]
+@deffn{Function} sb-ext:process-wait process &optional check-for-stopped
+Wait for @code{process} to quit running for some reason. When
+@code{check-for-stopped} is @code{t}, also returns when @code{process} is stopped. Returns
+@code{process}.
+@end deffn
+@anchor{Function sb-ext process-exit-code}
+@ffindex @sortas{process-exit-code sb-ext} process-exit-code [sb-ext]
+@deffn{Function} sb-ext:process-exit-code process
+The exit code or the signal of a stopped process.
+@end deffn
+@anchor{Function sb-ext process-core-dumped}
+@ffindex @sortas{process-core-dumped sb-ext} process-core-dumped [sb-ext]
+@deffn{Function} sb-ext:process-core-dumped instance
+@code{t} if a core image was dumped by the process.
+@end deffn
+@anchor{Function sb-ext process-close}
+@ffindex @sortas{process-close sb-ext} process-close [sb-ext]
+@deffn{Function} sb-ext:process-close process
+Close all streams connected to @code{process}, stop maintaining the
+status slot. After @code{process-close}, @code{process-alive-p} and
+@code{process-exit-code} can return stale information about a process, so
+should not be used.
+@end deffn
+@anchor{Function sb-ext process-kill}
+@ffindex @sortas{process-kill sb-ext} process-kill [sb-ext]
+@deffn{Function} sb-ext:process-kill process signal &optional whom
+Hand @code{signal} to @code{process}. If @code{whom} is @code{:pid}, use the kill Unix system call. If
+@code{whom} is @code{:process-group}, use the @code{killpg(1)} Unix system call.
+Returns @code{t} if successful, otherwise returns @code{nil} and error
+number (two values).
+@end deffn
+@node unicode support
@section Unicode Support
-@cindex Unicode
+
+@menu
+* Unicode property access: unicode property access.
+* String operations: string operations.
+* Breaking strings: breaking strings.
+@end menu
SBCL provides support for working with Unicode text and querying the
standard Unicode database for information about individual codepoints.
Unicode-related functions are located in the @code{sb-unicode} package.
-@cindex Character Names
-@cindex Name, of character
-@findex @cl{name-char}
-@findex @cl{char-name}
SBCL also extends ANSI character literal syntax to support Unicode
-codepoints. You can either specify a character by its Unicode name, with
-spaces replaced by underscores, if a unique name exists @footnote{Please
-note that the codepoint U+1F5CF (PAGE) introduced in Unicode 7.0 is
-named @code{UNICODE_PAGE}, since the name ``Page'' is required to be
-assigned to form-feed (U+0C) by the ANSI standard.} or
-by giving its hexadecimal codepoint preceded by a ``U'', an optional
-``+'', and an arbitrary number of leading zeros. You may also input the
-character directly into your source code if it can be encoded in your
-file. If a character had an assigned name in Unicode 1.0 that was
-distinct from its current name, you may also use that name (with spaces
-replaced by underscores) to specify the character, unless the name is
-already associated with a codepoint in the latest Unicode standard (such
-as ``BELL'').
+codepoints. You can either specify a character by its Unicode name,
+with spaces replaced by underscores if a unique name exists or by
+giving its hexadecimal codepoint preceded by a @code{u}, an optional
+@code{+}, and an arbitrary number of leading zeros. You may also input
+the character directly into your source code if it can be encoded in
+your file. If a character had an assigned name in Unicode 1.0 that
+was distinct from its current name, you may also use that name (with
+spaces replaced by underscores) to specify the character, unless the
+name is already associated with a codepoint in the latest Unicode
+standard (such as @code{bell}).
-For example, you can specify the codepoint U+00E1 (``Latin
-Small Letter A With Acute'') as
-@itemize @bullet
-@item
-@code{#\LATIN_SMALL_LETTER_A_WITH_ACUTE}
-@item
-@code{#\LATIN_SMALL_LETTER_A_ACUTE}
-@item
-@code{#\á} assuming a Unicode source file
-@item
-@code{#\U00E1}
-@item
-@code{#\UE1}
-@item
-@code{#\U+00E1}
+@quotation
+@emph{Note}: Please note that the codepoint @code{u+1f5cf} (Page) introduced
+in Unicode 7.0 is named @code{unicode_page}, since the name @emph{Page} is
+required to be assigned to form-feed (@code{u+0c}) by the ANSI
+standard.
+@end quotation
+
+For example, you can specify the codepoint @code{u+00e1} ( @emph{Latin Small
+Letter A With Acute}) as
+
+@itemize
+@item @code{#\latin_small_letter_a_with_acute}
+@item @code{#\latin_small_letter_a_acute}
+@item @code{#\á} (assuming a Unicode source file)
+@item @code{#\u00e1}
+@item @code{#\ue1}
+@item @code{#\u+00e1}
@end itemize
+@node unicode property access
@subsection Unicode property access
-The following functions can be used to find information about a Unicode
-codepoint.
-
-@include fun-sb-unicode-general-category.texinfo
-
-@include fun-sb-unicode-bidi-class.texinfo
-
-@include fun-sb-unicode-combining-class.texinfo
-
-@include fun-sb-unicode-decimal-value.texinfo
-
-@include fun-sb-unicode-digit-value.texinfo
-
-@include fun-sb-unicode-numeric-value.texinfo
-
-@include fun-sb-unicode-mirrored-p.texinfo
-
-@include fun-sb-unicode-bidi-mirroring-glyph.texinfo
-
-@include fun-sb-unicode-age.texinfo
-
-@include fun-sb-unicode-hangul-syllable-type.texinfo
-
-@include fun-sb-unicode-east-asian-width.texinfo
-
-@include fun-sb-unicode-script.texinfo
-
-@include fun-sb-unicode-char-block.texinfo
-
-@include fun-sb-unicode-unicode-1-name.texinfo
-
-@include fun-sb-unicode-proplist-p.texinfo
-
-@include fun-sb-unicode-uppercase-p.texinfo
-
-@include fun-sb-unicode-lowercase-p.texinfo
-
-@include fun-sb-unicode-cased-p.texinfo
-
-@include fun-sb-unicode-case-ignorable-p.texinfo
-
-@include fun-sb-unicode-alphabetic-p.texinfo
-
-@include fun-sb-unicode-ideographic-p.texinfo
-
-@include fun-sb-unicode-math-p.texinfo
-
-@include fun-sb-unicode-whitespace-p.texinfo
-
-@include fun-sb-unicode-soft-dotted-p.texinfo
-
-@include fun-sb-unicode-hex-digit-p.texinfo
-
-@include fun-sb-unicode-default-ignorable-p.texinfo
-
-@include fun-sb-unicode-grapheme-break-class.texinfo
-
-@include fun-sb-unicode-word-break-class.texinfo
-
-@include fun-sb-unicode-sentence-break-class.texinfo
-
-@include fun-sb-unicode-line-break-class.texinfo
-
+The following functions can be used to find information about a
+Unicode codepoint.
+
+@anchor{Function sb-unicode general-category}
+@ffindex @sortas{general-category sb-unicode} general-category [sb-unicode]
+@deffn{Function} sb-unicode:general-category character
+Returns the general category of @code{character} as it appears in UnicodeData.txt
+@end deffn
+@anchor{Function sb-unicode bidi-class}
+@ffindex @sortas{bidi-class sb-unicode} bidi-class [sb-unicode]
+@deffn{Function} sb-unicode:bidi-class character
+Returns the bidirectional class of @code{character}
+@end deffn
+@anchor{Function sb-unicode combining-class}
+@ffindex @sortas{combining-class sb-unicode} combining-class [sb-unicode]
+@deffn{Function} sb-unicode:combining-class character
+Returns the canonical combining class (CCC) of @code{character}
+@end deffn
+@anchor{Function sb-unicode decimal-value}
+@ffindex @sortas{decimal-value sb-unicode} decimal-value [sb-unicode]
+@deffn{Function} sb-unicode:decimal-value character
+Returns the decimal digit value associated with @code{character} or @code{nil} if
+there is no such value.
+
+The only characters in Unicode with a decimal digit value are those
+that are part of a range of characters that encode the digits 0-9.
+Because of this, @code{(decimal-digit c) <=> (digit-char-p c 10)} in
+@code{#+sb-unicode} builds
+@end deffn
+@anchor{Function sb-unicode digit-value}
+@ffindex @sortas{digit-value sb-unicode} digit-value [sb-unicode]
+@deffn{Function} sb-unicode:digit-value character
+Returns the Unicode digit value of @code{character} or @code{nil} if it doesn't exist.
+
+Digit values are guaranteed to be integers between 0 and 9 inclusive.
+All characters with decimal digit values have the same digit value,
+but there are characters (such as digits of number systems without a 0 value)
+that have a digit value but no decimal digit value
+@end deffn
+@anchor{Function sb-unicode numeric-value}
+@ffindex @sortas{numeric-value sb-unicode} numeric-value [sb-unicode]
+@deffn{Function} sb-unicode:numeric-value character
+Returns the numeric value of @code{character} or @code{nil} if there is no such value.
+Numeric value is the most general of the Unicode numeric properties.
+The only constraint on the numeric value is that it be a rational number.
+@end deffn
+@anchor{Function sb-unicode mirrored-p}
+@ffindex @sortas{mirrored-p sb-unicode} mirrored-p [sb-unicode]
+@deffn{Function} sb-unicode:mirrored-p character
+Returns @code{t} if @code{character} needs to be mirrored in bidirectional text.
+Otherwise, returns @code{nil}.
+@end deffn
+@anchor{Function sb-unicode bidi-mirroring-glyph}
+@ffindex @sortas{bidi-mirroring-glyph sb-unicode} bidi-mirroring-glyph [sb-unicode]
+@deffn{Function} sb-unicode:bidi-mirroring-glyph character
+Returns the mirror image of @code{character} if it exists.
+Otherwise, returns @code{nil}.
+@end deffn
+@anchor{Function sb-unicode age}
+@ffindex @sortas{age sb-unicode} age [sb-unicode]
+@deffn{Function} sb-unicode:age character
+Returns the version of Unicode in which @code{character} was assigned as a pair
+of values, both integers, representing the major and minor version respectively.
+If @code{character} is not assigned in Unicode, returns @code{nil} for both values.
+@end deffn
+@anchor{Function sb-unicode hangul-syllable-type}
+@ffindex @sortas{hangul-syllable-type sb-unicode} hangul-syllable-type [sb-unicode]
+@deffn{Function} sb-unicode:hangul-syllable-type character
+Returns the Hangul syllable type of @code{character}.
+The syllable type can be one of @code{:l}, @code{:v}, @code{:t}, @code{:lv}, or @code{:lvt}.
+If the character is not a Hangul syllable or Jamo, returns @code{nil}
+@end deffn
+@anchor{Function sb-unicode east-asian-width}
+@ffindex @sortas{east-asian-width sb-unicode} east-asian-width [sb-unicode]
+@deffn{Function} sb-unicode:east-asian-width character
+Returns the East Asian Width property of @code{character} as
+one of the keywords @code{:n} (Narrow), @code{:a} (Ambiguous), @code{:h} (Halfwidth),
+@code{:w} (Wide), @code{:f} (Fullwidth), or @code{:na} (Not applicable)
+@end deffn
+@anchor{Function sb-unicode script}
+@ffindex @sortas{script sb-unicode} script [sb-unicode]
+@deffn{Function} sb-unicode:script character
+Returns the Script property of @code{character} as a keyword.
+If @code{character} does not have a known script, returns @code{:unknown}
+@end deffn
+@anchor{Function sb-unicode char-block}
+@ffindex @sortas{char-block sb-unicode} char-block [sb-unicode]
+@deffn{Function} sb-unicode:char-block character
+Returns the Unicode block in which @code{character} resides as a keyword.
+If @code{character} does not have a known block, returns @code{:no-block}
+@end deffn
+@anchor{Function sb-unicode unicode-1-name}
+@ffindex @sortas{unicode-1-name sb-unicode} unicode-1-name [sb-unicode]
+@deffn{Function} sb-unicode:unicode-1-name character
+Returns the name assigned to @code{character} in Unicode 1.0 if it is distinct
+from the name currently assigned to @code{character}. Otherwise, returns @code{nil}.
+This property has been officially obsoleted by the Unicode standard, and
+is only included for backwards compatibility.
+@end deffn
+@anchor{Function sb-unicode proplist-p}
+@ffindex @sortas{proplist-p sb-unicode} proplist-p [sb-unicode]
+@deffn{Function} sb-unicode:proplist-p character property
+Returns @code{t} if @code{character} has the specified @code{property}.
+@code{property} is a keyword representing one of the properties from PropList.txt,
+with underscores replaced by dashes.
+@end deffn
+@anchor{Function sb-unicode uppercase-p}
+@ffindex @sortas{uppercase-p sb-unicode} uppercase-p [sb-unicode]
+@deffn{Function} sb-unicode:uppercase-p character
+Returns @code{t} if @code{character} has the Unicode property Uppercase and @code{nil} otherwise
+@end deffn
+@anchor{Function sb-unicode lowercase-p}
+@ffindex @sortas{lowercase-p sb-unicode} lowercase-p [sb-unicode]
+@deffn{Function} sb-unicode:lowercase-p character
+Returns @code{t} if @code{character} has the Unicode property Lowercase and @code{nil} otherwise
+@end deffn
+@anchor{Function sb-unicode cased-p}
+@ffindex @sortas{cased-p sb-unicode} cased-p [sb-unicode]
+@deffn{Function} sb-unicode:cased-p character
+Returns @code{t} if @code{character} has a (Unicode) case, and @code{nil} otherwise
+@end deffn
+@anchor{Function sb-unicode case-ignorable-p}
+@ffindex @sortas{case-ignorable-p sb-unicode} case-ignorable-p [sb-unicode]
+@deffn{Function} sb-unicode:case-ignorable-p character
+Returns @code{t} if @code{character} is Case Ignorable as defined in Unicode 6.3, Chapter
+3
+@end deffn
+@anchor{Function sb-unicode alphabetic-p}
+@ffindex @sortas{alphabetic-p sb-unicode} alphabetic-p [sb-unicode]
+@deffn{Function} sb-unicode:alphabetic-p character
+Returns @code{t} if @code{character} is Alphabetic according to the Unicode standard
+and @code{nil} otherwise
+@end deffn
+@anchor{Function sb-unicode ideographic-p}
+@ffindex @sortas{ideographic-p sb-unicode} ideographic-p [sb-unicode]
+@deffn{Function} sb-unicode:ideographic-p character
+Returns @code{t} if @code{character} has the Unicode property Ideographic,
+which loosely corresponds to the set of "Chinese characters"
+@end deffn
+@anchor{Function sb-unicode math-p}
+@ffindex @sortas{math-p sb-unicode} math-p [sb-unicode]
+@deffn{Function} sb-unicode:math-p character
+Returns @code{t} if @code{character} is a mathematical symbol according to Unicode and
+@code{nil} otherwise
+@end deffn
+@anchor{Function sb-unicode whitespace-p}
+@ffindex @sortas{whitespace-p sb-unicode} whitespace-p [sb-unicode]
+@deffn{Function} sb-unicode:whitespace-p character
+Returns @code{t} if @code{character} is whitespace according to Unicode
+and @code{nil} otherwise
+@end deffn
+@anchor{Function sb-unicode soft-dotted-p}
+@ffindex @sortas{soft-dotted-p sb-unicode} soft-dotted-p [sb-unicode]
+@deffn{Function} sb-unicode:soft-dotted-p character
+Returns @code{t} if @code{character} has a soft dot (such as the dots on i and j) which
+disappears when accents are placed on top of it. and @code{nil} otherwise
+@end deffn
+@anchor{Function sb-unicode hex-digit-p}
+@ffindex @sortas{hex-digit-p sb-unicode} hex-digit-p [sb-unicode]
+@deffn{Function} sb-unicode:hex-digit-p character &key ascii
+Returns @code{t} if @code{character} is a hexadecimal digit and @code{nil} otherwise.
+If @code{:ascii} is non-@code{nil}, fullwidth equivalents of the Latin letters A through F
+are excluded.
+@end deffn
+@anchor{Function sb-unicode default-ignorable-p}
+@ffindex @sortas{default-ignorable-p sb-unicode} default-ignorable-p [sb-unicode]
+@deffn{Function} sb-unicode:default-ignorable-p character
+Returns @code{t} if @code{character} is a Default@emph{Ignorable}Code_Point
+@end deffn
+@anchor{Function sb-unicode grapheme-break-class}
+@ffindex @sortas{grapheme-break-class sb-unicode} grapheme-break-class [sb-unicode]
+@deffn{Function} sb-unicode:grapheme-break-class character
+Returns the grapheme breaking class of @code{character}, as specified in UAX #29.
+@end deffn
+@anchor{Function sb-unicode word-break-class}
+@ffindex @sortas{word-break-class sb-unicode} word-break-class [sb-unicode]
+@deffn{Function} sb-unicode:word-break-class character
+Returns the word breaking class of @code{character}, as specified in UAX #29.
+@end deffn
+@anchor{Function sb-unicode sentence-break-class}
+@ffindex @sortas{sentence-break-class sb-unicode} sentence-break-class [sb-unicode]
+@deffn{Function} sb-unicode:sentence-break-class character
+Returns the sentence breaking class of @code{character}, as specified in UAX #29.
+@end deffn
+@anchor{Function sb-unicode line-break-class}
+@ffindex @sortas{line-break-class sb-unicode} line-break-class [sb-unicode]
+@deffn{Function} sb-unicode:line-break-class character &key resolve
+Returns the line breaking class of @code{character}, as specified in UAX #14.
+If @code{:resolve} is @code{nil}, returns the character class found in the property file.
+If @code{:resolve} is non-@code{nil}, certain line-breaking classes will be mapped to other
+classes as specified in the applicable standards. Additionally, if @code{:resolve}
+is @code{:east-asian}, Ambigious (class @code{:ai}) characters will be mapped to the
+Ideographic (@code{:id}) class instead of Alphabetic (@code{:al}).
+@end deffn
+@node string operations
@subsection String operations
-@cindex Normalization, String
SBCL can normalize strings using:
-@include fun-sb-unicode-normalize-string.texinfo
-
-@include fun-sb-unicode-normalized-p.texinfo
-
+@anchor{Function sb-unicode normalize-string}
+@ffindex @sortas{normalize-string sb-unicode} normalize-string [sb-unicode]
+@deffn{Function} sb-unicode:normalize-string string &optional form filter
+Normalize @code{string} to the Unicode normalization form @code{form}.
+Acceptable values for form are @code{:nfd}, @code{:nfc}, @code{:nfkd}, and @code{:nfkc}.
+If @code{filter} is a function it is called on each decomposed character and
+only characters for which it returns @code{t} are collected.
+@end deffn
+@anchor{Function sb-unicode normalized-p}
+@ffindex @sortas{normalized-p sb-unicode} normalized-p [sb-unicode]
+@deffn{Function} sb-unicode:normalized-p string &optional form
+Tests if @code{string} is normalized to @code{form}
+@end deffn
SBCL implements the full range of Unicode case operations with the
functions
-@include fun-sb-unicode-uppercase.texinfo
-
-@include fun-sb-unicode-lowercase.texinfo
-
-@include fun-sb-unicode-titlecase.texinfo
-
-@include fun-sb-unicode-casefold.texinfo
-
-@findex @cl{string-upcase}
-@findex @cl{char-downcase}
-@findex @cl{both-case-p}
+@anchor{Function sb-unicode uppercase}
+@ffindex @sortas{uppercase sb-unicode} uppercase [sb-unicode]
+@deffn{Function} sb-unicode:uppercase string &key locale
+Returns the full uppercase of @code{string} according to the Unicode standard.
+The result is not guaranteed to have the same length as the input. If @code{:locale}
+is @code{nil}, no language-specific case transformations are applied. If @code{:locale} is a
+keyword representing a two-letter ISO country code, the case transforms of that
+locale are used. If @code{:locale} is @code{t}, the user's current locale is used (Unix and
+Win32 only).
+@end deffn
+@anchor{Function sb-unicode lowercase}
+@ffindex @sortas{lowercase sb-unicode} lowercase [sb-unicode]
+@deffn{Function} sb-unicode:lowercase string &key locale
+Returns the full lowercase of @code{string} according to the Unicode standard.
+The result is not guaranteed to have the same length as the input.
+@code{:locale} has the same semantics as the @code{:locale} argument to @code{uppercase}.
+@end deffn
+@anchor{Function sb-unicode titlecase}
+@ffindex @sortas{titlecase sb-unicode} titlecase [sb-unicode]
+@deffn{Function} sb-unicode:titlecase string &key locale
+Returns the titlecase of @code{string}. The resulting string can
+be longer than the input.
+@code{:locale} has the same semantics as the @code{:locale} argument to @code{uppercase}.
+@end deffn
+@anchor{Function sb-unicode casefold}
+@ffindex @sortas{casefold sb-unicode} casefold [sb-unicode]
+@deffn{Function} sb-unicode:casefold string
+Returns the full casefolding of @code{string} according to the Unicode standard.
+Casefolding removes case information in a way that allows the results to be used
+for case-insensitive comparisons.
+The result is not guaranteed to have the same length as the input.
+@end deffn
It also extends standard Common Lisp case functions such as
-@code{string-upcase} and @code{string-downcase} to support a subset of
-Unicode's casing behavior. Specifically, a character is
-@code{both-case-p} if its case mapping in Unicode is one-to-one and
-invertable.
+@code{string-upcase} and @code{string-downcase} to support a subset of Unicode's
+casing behavior. Specifically, a character is @code{both-case-p} if its
+case mapping in Unicode is one-to-one and invertable.
The @code{sb-unicode} package also provides functions for
-collating/sorting strings according to the Unicode Collation Algorithm.
-
-@include fun-sb-unicode-unicode-lt.texinfo
-
-@include fun-sb-unicode-unicode=.texinfo
-
-@include fun-sb-unicode-unicode-equal.texinfo
-
-@include fun-sb-unicode-unicode-lt=.texinfo
-
-@include fun-sb-unicode-unicode-gt.texinfo
-
-@include fun-sb-unicode-unicode-gt=.texinfo
-
-The following functions are provided for detecting visually confusable strings:
-
-@include fun-sb-unicode-confusable-p.texinfo
-
+collating/sorting strings according to the Unicode Collation
+Algorithm.
+
+@anchor{Function sb-unicode unicode<}
+@ffindex @sortas{unicode< sb-unicode} unicode< [sb-unicode]
+@deffn{Function} sb-unicode:unicode< string1 string2 &key start1 end1 start2 end2
+Determines whether @code{string1} sorts before @code{string2} using the Unicode Collation
+Algorithm. The function uses an untailored Default Unicode Collation Element Table
+to produce the sort keys. The function uses the Shifted method for dealing
+with variable-weight characters, as described in UTS #10
+@end deffn
+@anchor{Function sb-unicode unicode=}
+@ffindex @sortas{unicode= sb-unicode} unicode= [sb-unicode]
+@deffn{Function} sb-unicode:unicode= string1 string2 &key start1 end1 start2 end2 strict
+Determines whether @code{string1} and @code{string2} are canonically equivalent according
+to Unicode. The @code{start} and @code{end} arguments behave like the arguments to @code{string=}.
+If @code{:strict} is @code{nil}, @code{unicode=} tests compatibility equavalence instead.
+@end deffn
+@anchor{Function sb-unicode unicode-equal}
+@ffindex @sortas{unicode-equal sb-unicode} unicode-equal [sb-unicode]
+@deffn{Function} sb-unicode:unicode-equal string1 string2 &key start1 end1 start2 end2 strict
+Determines whether @code{string1} and @code{string2} are canonically equivalent after
+casefolding (that is, ignoring case differences) according to Unicode. The
+@code{start} and @code{end} arguments behave like the arguments to @code{string=}. If @code{:strict} is
+@code{nil}, @code{unicode=} tests compatibility equavalence instead.
+@end deffn
+@anchor{Function sb-unicode unicode<=}
+@ffindex @sortas{unicode<= sb-unicode} unicode<= [sb-unicode]
+@deffn{Function} sb-unicode:unicode<= string1 string2 &key start1 end1 start2 end2
+Tests if @code{string1} and @code{string2} are either @code{unicode<} or @code{unicode=}
+@end deffn
+@anchor{Function sb-unicode unicode>}
+@ffindex @sortas{unicode> sb-unicode} unicode> [sb-unicode]
+@deffn{Function} sb-unicode:unicode> string1 string2 &key start1 end1 start2 end2
+Tests if @code{string2} is @code{unicode<} @code{string1}.
+@end deffn
+@anchor{Function sb-unicode unicode>=}
+@ffindex @sortas{unicode>= sb-unicode} unicode>= [sb-unicode]
+@deffn{Function} sb-unicode:unicode>= string1 string2 &key start1 end1 start2 end2
+Tests if @code{string1} and @code{string2} are either @code{unicode=} or @code{unicode>}
+@end deffn
+The following functions are provided for detecting visually
+confusable strings:
+
+@anchor{Function sb-unicode confusable-p}
+@ffindex @sortas{confusable-p sb-unicode} confusable-p [sb-unicode]
+@deffn{Function} sb-unicode:confusable-p string1 string2 &key start1 end1 start2 end2
+Determines whether @code{string1} and @code{string2} could be visually confusable
+according to the IDNA confusableSummary.txt table
+@end deffn
+@node breaking strings
@subsection Breaking strings
The @code{sb-unicode} package includes several functions for breaking a
Unicode string into useful parts.
-@include fun-sb-unicode-graphemes.texinfo
-
-@include fun-sb-unicode-words.texinfo
-
-@include fun-sb-unicode-sentences.texinfo
-
-@include fun-sb-unicode-lines.texinfo
-
-@node Customization Hooks for Users
-@comment node-name, next, previous, up
+@anchor{Function sb-unicode graphemes}
+@ffindex @sortas{graphemes sb-unicode} graphemes [sb-unicode]
+@deffn{Function} sb-unicode:graphemes string
+Breaks @code{string} into graphemes according to the default
+grapheme breaking rules specified in UAX #29, returning a list of strings.
+@end deffn
+@anchor{Function sb-unicode words}
+@ffindex @sortas{words sb-unicode} words [sb-unicode]
+@deffn{Function} sb-unicode:words string
+Breaks @code{string} into words according to the default
+word breaking rules specified in UAX #29. Returns a list of strings
+@end deffn
+@anchor{Function sb-unicode sentences}
+@ffindex @sortas{sentences sb-unicode} sentences [sb-unicode]
+@deffn{Function} sb-unicode:sentences string
+Breaks @code{string} into sentences according to the default
+sentence breaking rules specified in UAX #29
+@end deffn
+@anchor{Function sb-unicode lines}
+@ffindex @sortas{lines sb-unicode} lines [sb-unicode]
+@deffn{Function} sb-unicode:lines string &key margin
+Breaks @code{string} into lines that are no wider than @code{:margin} according to the
+line breaking rules outlined in UAX #14. Combining marks will always be kept
+together with their base characters, and spaces (but not other types of
+whitespace) will be removed from the end of lines. If @code{:margin} is unspecified,
+it defaults to 80 characters
+@end deffn
+@node customization hooks for users
@section Customization Hooks for Users
The toplevel repl prompt may be customized, and the function
-that reads user input may be replaced completely.
-@c <!-- FIXME but I don't currently remember how -->
+that reads user input may be replaced completely. See the @code{:toplevel}
+argument of @code{sb-ext:save-lisp-and-die}.
The behaviour of @code{require} when called with only one argument is
-implementation-defined. In SBCL, @code{require} behaves in the
-following way:
-
-@include fun-common-lisp-require.texinfo
-@include var-sb-ext-star-module-provider-functions-star.texinfo
+implementation-defined. In SBCL, @code{require} behaves in the following
+way:
+@anchor{Function common-lisp require}
+@ffindex @sortas{require common-lisp} require [common-lisp]
+@deffn{Function} require module-name &optional pathnames
+Loads a module, unless it already has been loaded. @code{pathnames}, if supplied,
+is a designator for a list of pathnames to be loaded if the module
+needs to be. If @code{pathnames} is not supplied, functions from the list
+@code{*module-provider-functions*} are called in order with @code{module-name}
+as an argument, until one of them returns non-@code{nil}. User code is
+responsible for calling @code{provide} to indicate a successful load of the
+module.
+@end deffn
+@anchor{Variable sb-ext *module-provider-functions*}
+@vvindex @sortas{module-provider-functions* sb-ext} *module-provider-functions* [sb-ext]
+@deffn{Variable} sb-ext:*module-provider-functions*
+See @code{require}.
+@end deffn
Although SBCL does not provide a resident editor, the @code{ed}
function can be customized to hook into user-provided editing
mechanisms as follows:
-@include fun-common-lisp-ed.texinfo
-@include var-sb-ext-star-ed-functions-star.texinfo
+@anchor{Function common-lisp ed}
+@ffindex @sortas{ed common-lisp} ed [common-lisp]
+@deffn{Function} ed &optional x
+Starts the editor (on a file or a function if named). Functions
+from the list @code{*ed-functions*} are called in order with @code{x} as an argument
+until one of them returns non-@code{nil}; these functions are responsible for
+signalling a @code{file-error} to indicate failure to perform an operation on
+the file system.
+@end deffn
+@anchor{Variable sb-ext *ed-functions*}
+@vvindex @sortas{ed-functions* sb-ext} *ed-functions* [sb-ext]
+@deffn{Variable} sb-ext:*ed-functions*
+See @code{ed}.
+@end deffn
+Conditions of type @code{warning} and @code{style-warning} are sometimes signaled at
+runtime, especially during execution of Common Lisp defining forms
+such as @code{defun}, @code{defmethod}, etc. To muffle these warnings at runtime,
+SBCL provides a variable @code{sb-ext:*muffled-warnings*}:
-Conditions of type @code{warning} and @code{style-warning} are
-sometimes signaled at runtime, especially during execution of Common
-Lisp defining forms such as @code{defun}, @code{defmethod}, etc. To
-muffle these warnings at runtime, SBCL provides a variable
-@code{sb-ext:*muffled-warnings*}:
-
-@include var-sb-ext-star-muffled-warnings-star.texinfo
-
-@node Tools To Help Developers
-@comment node-name, next, previous, up
+@anchor{Variable sb-ext *muffled-warnings*}
+@vvindex @sortas{muffled-warnings* sb-ext} *muffled-warnings* [sb-ext]
+@deffn{Variable} sb-ext:*muffled-warnings*
+A type that ought to specify a subtype of @code{warning}. Whenever a
+warning is signaled, if the warning is of this type and is not
+handled by any other handler, it will be muffled.
+@end deffn
+@node tools to help developers
@section Tools To Help Developers
-@findex @cl{trace}
-@findex @cl{inspect}
-SBCL provides a profiler and other extensions to the ANSI @code{trace}
-facility. For more information, see @ref{Macro common-lisp trace}.
+SBCL provides a profiler and other extensions to the @code{trace}
+facility.
The debugger supports a number of options. Its documentation is
-accessed by typing @kbd{help} at the debugger prompt. @xref{Debugger}.
+accessed by typing @code{help} at the debugger prompt. See @ref{debugger}.
-Documentation for @code{inspect} is accessed by typing @kbd{help} at
-the @code{inspect} prompt.
+Documentation for the command @code{inspect} is accessed by typing
+@code{help} at the @code{inspect} prompt.
-@node Resolution of Name Conflicts
+@node resolution of name conflicts
@section Resolution of Name Conflicts
-@tindex @sbext{name-conflict}
-@findex @sbext{name-conflict-symbols}
-The ANSI standard (section 11.1.1.2.5) requires that name conflicts in
-packages be resolvable in favour of any of the conflicting symbols. In
-the interactive debugger, this is achieved by prompting for the symbol
-in whose favour the conflict should be resolved; for programmatic use,
-the @code{sb-ext:resolve-conflict} restart should be invoked with one
-argument, which should be a member of the list returned by the condition
-accessor @code{sb-ext:name-conflict-symbols}.
+@code{clhs} @code{11.1.1.2.5} requires that name conflicts in packages be
+resolvable in favour of any of the conflicting symbols. In the
+interactive debugger, this is achieved by prompting for the symbol
+in whose favour the conflict should be resolved; for programmatic
+use, the @code{sb-ext:resolve-conflict} restart should be invoked
+with one argument, which should be a member of the list returned by
+the condition accessor @code{sb-ext:name-conflict-symbols}.
-@node Hash Table Extensions
-@comment node-name, next, previous, up
+@node hash table extensions
@section Hash Table Extensions
-@cindex Hash tables
Hash table extensions supported by SBCL are all controlled by keyword
arguments to @code{make-hash-table}.
-@include fun-common-lisp-make-hash-table.texinfo
+@anchor{Function common-lisp make-hash-table}
+@ffindex @sortas{make-hash-table common-lisp} make-hash-table [common-lisp]
+@deffn{Function} make-hash-table &key test size rehash-size rehash-threshold hash-function weakness synchronized
+Create and return a new hash table. The keywords are as follows:
-@include macro-sb-ext-define-hash-table-test.texinfo
+@itemize
+@item @code{:test}
-@include macro-sb-ext-with-locked-hash-table.texinfo
+Determines how keys are compared. Must a designator for one of
+the standard hash table tests, or a hash table test defined
+using @code{sb-ext:define-hash-table-test}. Additionally, when an
+explicit @code{hash-function} is provided (see below), any two argument
+equivalence predicate can be used as the @code{test}.
-@include fun-sb-ext-hash-table-synchronized-p.texinfo
+@item @code{:size}
-@include fun-sb-ext-hash-table-weakness.texinfo
+A hint as to how many elements will be put in this hash table.
-@node Random Number Generation
-@comment node-name, next, previous, up
+@item @code{:rehash-size}
+
+Indicates how to expand the table when it fills up. If an
+integer, add space for that many elements. If a floating point
+number (which must be greater than 1.0), multiply the size by
+that amount.
+
+@item @code{:rehash-threshold}
+
+Indicates how dense the table can become before forcing a
+rehash. Can be any positive number <=1, with density approaching
+zero as the threshold approaches 0. Density 1 means an average
+of one entry per bucket.
+
+@item @code{:hash-function}
+
+If unsupplied, a hash function based on the @code{test} argument is
+used, which then must be one of the standardized hash table test
+functions, or one for which a default hash function has been
+defined using @code{sb-ext:define-hash-table-test}. If @code{hash-function} is
+specified, the @code{test} argument can be any two argument predicate
+consistent with it. The @code{hash-function} is expected to return a
+non-negative fixnum hash code. If @code{test} is neither standard nor
+defined by @code{define-hash-table-test}, then the @code{hash-function} must
+be specified.
+
+@item @code{:weakness}
+
+When @code{:weakness} is not @code{nil}, garbage collection may remove entries
+from the hash table. The value of @code{:weakness} specifies how the
+presence of a key or value in the hash table preserves their
+entries from garbage collection.
+
+Valid values are:
+
+@itemize
+@item @code{:key} means that the key of an entry must be live to guarantee
+ that the entry is preserved.
+
+@item @code{:value} means that the value of an entry must be live to
+ guarantee that the entry is preserved.
+
+@item @code{:key-and-value} means that both the key and the value must be
+ live to guarantee that the entry is preserved.
+
+@item @code{:key-or-value} means that either the key or the value must be
+ live to guarantee that the entry is preserved.
+
+@item @code{nil} (the default) means that entries are always preserved.
+@end itemize
+
+@item @code{:synchronized}
+
+If @code{nil} (the default), the hash-table may have multiple
+concurrent readers, but results are undefined if a thread writes
+to the hash-table concurrently with another reader or writer. If
+@code{t}, all concurrent accesses are safe, but note that CLHS
+3.6 (Traversal Rules and Side Effects) remains in force. See
+also: @code{sb-ext:with-locked-hash-table}.
+@end itemize
+@end deffn
+@anchor{Macro sb-ext define-hash-table-test}
+@ffindex @sortas{define-hash-table-test sb-ext} define-hash-table-test [sb-ext]
+@deffn{Macro} sb-ext:define-hash-table-test name hash-function
+Defines @code{name} as a new kind of hash table test for use with the @code{:test}
+argument to @code{make-hash-table}, and associates a default @code{hash-function} with it.
+
+@code{name} must be a symbol naming a global two argument equivalence predicate.
+Afterwards both '@code{name} and #'@code{name} can be used with @code{:test} argument. In both
+cases @code{hash-table-test} will return the symbol @code{name}.
+
+@code{hash-function} must be a symbol naming a global hash function consistent with
+the predicate, or be a @code{lambda} form implementing one in the current lexical
+environment. The hash function must compute the same hash code for any two
+objects for which @code{name} returns true, and subsequent calls with already hashed
+objects must always return the same hash code.
+
+@quotation
+@emph{Note}: The @code{:hash-function} keyword argument to @code{make-hash-table} can
+be used to override the specified default hash-function.
+@end quotation
+
+Attempting to define @code{name} in a locked package as hash-table test causes a
+package lock violation.
+
+Examples:
+
+@example
+;; We want to use objects of type FOO as keys (by their
+;; names.) EQUALP would work, but would make the names
+;; case-insensitive -- which we don't want.
+(defstruct foo (name nil :type (or null string)))
+
+;; Define an equivalence test function and a hash function.
+(defun foo-name= (f1 f2) (equal (foo-name f1) (foo-name f2)))
+(defun sxhash-foo-name (f) (sxhash (foo-name f)))
+
+(define-hash-table-test foo-name= sxhash-foo-name)
+
+;; #'foo-name would work too.
+(defun make-foo-table () (make-hash-table :test 'foo-name=))
+@end example
+
+@example
+(defun == (x y) (= x y))
+
+(define-hash-table-test ==
+ (lambda (x)
+ ;; Hash codes must be consistent with test, so
+ ;; not (SXHASH X), since
+ ;; (= 1 1.0) => T
+ ;; (= (SXHASH 1) (SXHASH 1.0)) => NIL
+ ;; Note: this doesn't deal with complex numbers or
+ ;; bignums too large to represent as double floats.
+ (sxhash (coerce x 'double-float))))
+
+;; #'== would work too
+(defun make-number-table () (make-hash-table :test '==))
+@end example
+@end deffn
+@anchor{Macro sb-ext with-locked-hash-table}
+@ffindex @sortas{with-locked-hash-table sb-ext} with-locked-hash-table [sb-ext]
+@deffn{Macro} sb-ext:with-locked-hash-table (hash-table) &body body
+Limits concurrent accesses to @code{hash-table} for the duration of @code{body}.
+If @code{hash-table} is synchronized, @code{body} will execute with exclusive
+ownership of the table. If @code{hash-table} is not synchronized, @code{body} will
+execute with other @code{with-locked-hash-table} bodies excluded -- exclusion
+of hash-table accesses not surrounded by @code{with-locked-hash-table} is
+unspecified.
+@end deffn
+@anchor{Function sb-ext hash-table-synchronized-p}
+@ffindex @sortas{hash-table-synchronized-p sb-ext} hash-table-synchronized-p [sb-ext]
+@deffn{Function} sb-ext:hash-table-synchronized-p ht
+Returns @code{t} if @code{hash-table} is synchronized.
+@end deffn
+@anchor{Function sb-ext hash-table-weakness}
+@ffindex @sortas{hash-table-weakness sb-ext} hash-table-weakness [sb-ext]
+@deffn{Function} sb-ext:hash-table-weakness ht
+Return the @code{weakness} of @code{hash-table} which is one of @code{nil}, @code{:key},
+@code{:value}, @code{:key-and-value}, @code{:key-or-value}.
+@end deffn
+@node random number generation
@section Random Number Generation
-@cindex Random Number Generation
-@vindex @cl{@earmuffs{random-state}}
-@findex @cl{make-random-state}
The initial value of @code{*random-state*} is the same each time SBCL
-is started. This makes it possible for user code to obtain repeatable
-pseudo random numbers using only standard-provided functionality. See
-@code{seed-random-state} below for an SBCL extension that allows to
-seed the random number generator from given data for an additional
-possibility to achieve this. Non-repeatable random numbers can always
-be obtained using @code{(make-random-state t)}.
+is started. This makes it possible for user code to obtain
+repeatable pseudo random numbers using only standard-provided
+functionality. See @code{sb-ext:seed-random-state} below for an SBCL
+extension that allows to seed the random number generator from given
+data for an additional possibility to achieve this. Non-repeatable
+random numbers can always be obtained using (@code{make-random-state} @code{t}).
-@findex @cl{random}
The sequence of numbers produced by repeated calls to @code{random}
starting with the same random state and using the same sequence of
-@code{limit} arguments is guaranteed to be reproducible only in the
-same version of SBCL on the same platform, using the same code under
-the same evaluator mode and compiler optimization qualities. Just two
-examples of differences that may occur otherwise: calls to
-@code{random} can be compiled differently depending on how much is
-known about the @code{limit} argument at compile time, yielding
-different results even if called with the same argument at run time,
-and the results can differ depending on the machine's word size, for
-example for limits that are fixnums under 64-bit word size but bignums
-under 32-bit word size.
-
-@include fun-sb-ext-seed-random-state.texinfo
-
-@tindex @cl{float}
+@code{limit} arguments is guaranteed to be reproducible only in the same
+version of SBCL on the same platform, using the same code under the
+same evaluator mode and compiler optimization qualities. Just two
+examples of differences that may occur otherwise: calls to @code{random}
+can be compiled differently depending on how much is known about the
+@code{limit} argument at compile time, yielding different results even if
+called with the same argument at run time, and the results can
+differ depending on the machine's word size, for example for limits
+that are fixnums under 64-bit word size but bignums under 32-bit
+word size.
+
+@anchor{Function sb-ext seed-random-state}
+@ffindex @sortas{seed-random-state sb-ext} seed-random-state [sb-ext]
+@deffn{Function} sb-ext:seed-random-state &optional state
+Make a random state object. The optional @code{state} argument specifies a seed
+for deterministic pseudo-random number generation.
+
+As per the Common Lisp standard for @code{make-random-state},
+
+@itemize
+@item If @code{state} is @code{nil} or not supplied, return a copy of the default
+ @code{*random-state*}.
+@item If @code{state} is a random state, return a copy of it.
+@item If @code{state} is @code{t}, return a randomly initialized state (using operating-system
+ provided randomness where available, otherwise a poor substitute based on
+ internal time and pid).
+@end itemize
+
+As a supported SBCL extension, we also support receiving as a seed an object
+of the following types:
+
+@itemize
+@item (@code{simple-array} (@code{unsigned-byte} 8) (*))
+@item @code{unsigned-byte}
+@end itemize
+
+While we support arguments of any size and will mix the provided bits into
+the random state, it is probably overkill to provide more than 256 bits worth
+of actual information.
+
+This particular SBCL version also accepts an argument of the following type:
+(@code{simple-array} (@code{unsigned-byte} 32) (*))
+
+This particular SBCL version uses the popular MT19937 PRNG algorithm, and its
+internal state only effectively contains about 19937 bits of information.
+@url{http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html}
+@end deffn
Some notes on random floats: The standard doesn't prescribe a specific
-method of generating random floats. The following paragraph describes
-SBCL's current implementation and should be taken as purely
-informational, that is, user code should not depend on any of its
-specific properties. The method used has been chosen because it is
-common, conceptually simple and fast.
+method of generating random floats. The following paragraph
+describes SBCL's current implementation and should be taken as
+purely informational, that is, user code should not depend on any of
+its specific properties. The method used has been chosen because it
+is common, conceptually simple and fast.
-@findex @cl{expt}
-@findex @cl{random}
To generate random floats, SBCL evaluates code that has an equivalent
effect as
-@lisp
+
+@example
(* limit
(float (/ (random (expt 2 23)) (expt 2 23)) 1.0f0))
-@end lisp
-(for single-floats) and correspondingly (with @code{52} and
-@code{1.0d0} instead of @code{23} and @code{1.0f0}) for double-floats.
-Note especially that this means that zero is a possible return value
-occurring with probability @code{(expt 2 -23)} respectively
-@code{(expt 2 -52)}. Also note that there exist twice as many
-equidistant floats between 0 and 1 as are generated. For example, the
-largest number that @code{(random 1.0f0)} ever returns is
-@code{(float (/ (1- (expt 2 23)) (expt 2 23)) 1.0f0)} while
-@code{(float (/ (1- (expt 2 24)) (expt 2 24)) 1.0f0)} is the
-largest single-float less than 1. This is a side effect of the fact
-that the implementation uses the fastest possible conversion from bits
-to floats.
+@end example
+
+(for @code{single-float}s) and correspondingly (with @code{52} and @code{1.0d0}
+instead of @code{23} and @code{1.0f0}) for @code{double-float}s. Note especially that
+this means that zero is a possible return value occurring with
+probability @code{(expt 2 -23)} and @code{(expt 2 -52)}, respectively. Also
+note that there exist twice as many equidistant floats between 0 and
+1 as are generated. For example, the largest number that
+@code{(random 1.0f0)} ever returns is @code{(float (/ (1- (expt 2 23)) (expt 2
+23)) 1.0f0)} while @code{(float (/ (1- (expt 2 24)) (expt 2 24)) 1.0f0)}
+is the largest @code{single-float} less than 1. This is a side effect of
+the fact that the implementation uses the fastest possible
+conversion from bits to floats.
SBCL currently uses the Mersenne Twister as its random number
generator, specifically the 32-bit version under both 32- and 64-bit
word size. The seeding algorithm has been improved several times by
the authors of the Mersenne Twister; SBCL uses the third version
-(from 2002) which is still the most recent as of June 2012. The
+(from 2002), which is still the most recent as of June 2012. The
implementation has been tested to provide output identical to the
recommended C implementation.
While the Mersenne Twister generates random numbers of much better
statistical quality than other widely used generators, it uses only
linear operations modulo 2 and thus fails some statistical
-tests@footnote{See chapter 7 "Testing widely used RNGs" in
-@cite{TestU01: A C Library for Empirical Testing of Random Number
-Generators} by Pierre L'Ecuyer and Richard Simard, ACM Transactions on
-Mathematical Software, Vol. 33, article 22, 2007.}.
-For example, the distribution of ranks of (sufficiently large) random
-binary matrices is much distorted compared to the theoretically
-expected one when the matrices are generated by the Mersenne Twister.
-Thus, applications that are sensitive to this aspect should use a
-different type of generator.
+tests.
-@node Timeouts and Deadlines
-@comment node-name, next, previous, up
+(See chapter 7 @emph{Testing widely used RNGs} in @emph{TestU01: A C Library
+for Empirical Testing of Random Number Generators} by Pierre
+L'Ecuyer and Richard Simard, ACM Transactions on Mathematical
+Software, Vol. 33, article 22, 2007.)
+
+For example, the distribution of ranks of (sufficiently large)
+random binary matrices is much distorted compared to the
+theoretically expected one when the matrices are generated by the
+Mersenne Twister. Thus, applications that are sensitive to this
+aspect should use a different type of generator.
+
+@node timeouts and deadlines
@section Timeouts and Deadlines
+@menu
+* Timeout Parameters: timeout parameters.
+* Synchronous Timeouts: synchronous timeouts.
+* Asynchronous Timeouts: asynchronous timeouts.
+* Operations Supporting Timeouts and Deadlines: operations supporting timeouts and deadlines.
+@end menu
+
SBCL supports three different ways of restricting the execution time
available to individual operations or parts of computations:
-@table @strong
+@itemize
+@item @emph{Timeout Parameters}: Some operations such as thread
+ synchronization primitives accept a @code{:timeout} parameter. See
+ @ref{timeout parameters}.
-@item Timeout Parameters
-Some operations such as thread synchronization primitives accept a
-@code{:timeout} parameter. @xref{Timeout Parameters}.
+@item @emph{Synchronous Timeouts (Deadlines)}: Certain operations that may
+ suspend execution for extended periods of time such as @code{cl:sleep},
+ thread synchronization primitives, IO and waiting for external
+ processes respect deadlines established for a part of a
+ computation. See @ref{synchronous timeouts}.
-@item Synchronous Timeouts (Deadlines)
-@findex @cl{sleep}
-Certain operations that may suspend execution for extended periods of
-time such as @code{cl:sleep}, thread synchronization primitives, IO and
-waiting for external processes respect deadlines established for a part
-of a computation. @xref{Synchronous Timeouts (Deadlines)}.
+@item @emph{Asynchronous Timeouts}: Asynchronous timeouts can interrupt most
+ computations at (almost) any point. Thus, this kind of timeouts is
+ the most versatile but it is also somewhat unsafe. See
+ @ref{asynchronous timeouts}.
+@end itemize
-@item Asynchronous Timeouts
-Asynchronous timeouts can interrupt most computations at (almost) any
-point. Thus, this kind of timeouts is the most versatile but it is also
-somewhat unsafe. @xref{Asynchronous Timeouts}.
-
-@end table
-
-@menu
-* Timeout Parameters::
-* Synchronous Timeouts (Deadlines)::
-* Asynchronous Timeouts::
-* Operations Supporting Timeouts and Deadlines::
-@end menu
-
-@node Timeout Parameters
+@node timeout parameters
@subsection Timeout Parameters
-@cindex Timeout
-@tindex @sbthread{join-thread-error}
-Certain operations accept @code{:timeout} keyword arguments. These
-only affect the specific operation and must be specified at each call
+Certain operations accept @code{:timeout} keyword arguments. These only
+affect the specific operation and must be specified at each call
site by passing a @code{:timeout} keyword argument and a corresponding
timeout value to the respective operation. Expiration of the timeout
-before the operation completes results in either a normal return with
-a return value indicating the timeout or in the signaling of a
+before the operation completes results in either a normal return
+with a return value indicating the timeout or in the signaling of a
specialized condition such as @code{sb-thread:join-thread-error}.
Example:
-@lisp
+@example
(defun join-thread-within-5-seconds (thread)
(multiple-value-bind (value result)
(sb-thread:join-thread thread :default nil :timeout 5)
(when (eq result :timeout)
(error "Could not join ~A within 5 seconds" thread))
value))
-@end lisp
+@end example
-@findex @sbthread{join-thread}
The above code attempts to join the specified thread for up to five
seconds, returning its value in case of success. If the thread is
still running after the five seconds have elapsed,
-@code{sb-thread:join-thread} indicates the timeout in its second
-return value. If a @code{:default} value was not provided,
-@code{sb-thread:join-thread} would signal a
-@code{sb-thread:join-thread-error} instead.
+@code{sb-thread:join-thread} indicates the timeout in its second return
+value. If a @code{:default} value was not provided, @code{sb-thread:join-thread}
+would signal a @code{sb-thread:join-thread-error} instead.
To wait for an arbitrary condition, optionally with a timeout, the
@code{sb-ext:wait-for} macro can be used:
-@include macro-sb-ext-wait-for.texinfo
+@anchor{Macro sb-ext wait-for}
+@ffindex @sortas{wait-for sb-ext} wait-for [sb-ext]
+@deffn{Macro} sb-ext:wait-for test-form &key timeout
+Wait until @code{test-form} evaluates to true, then return its primary value.
+If @code{timeout} is provided, waits at most approximately @code{timeout} seconds before
+returning @code{nil}.
-@c @code{sb-sys:make-fd-stream} also takes a @code{:timeout} argument
-@c resulting in @code{sb-sys:io-timeout}, but that seems to niche to
-@c document here.
+If @code{with-deadline} has been used to provide a global deadline, signals a
+@code{deadline-timeout} if @code{test-form} doesn't evaluate to true before the
+deadline.
-@node Synchronous Timeouts (Deadlines)
-@subsection Synchronous Timeouts (Deadlines)
-@cindex Timeout
-@cindex Synchronous Timeout
-@cindex Deadline
+Experimental: subject to change without prior notice.
+@end deffn
+@node synchronous timeouts
+@subsection Synchronous Timeouts
Deadlines, in contrast to timeout parameters, are established for a
dynamic scope using the @code{sb-sys:with-deadline} macro and indirectly
@@ -1348,25 +2439,57 @@ affect operations within that scope. In case of nested uses, the
effective deadline is the one that expires first unless an inner use
explicitly overrides outer deadlines.
-@include macro-sb-sys-with-deadline.texinfo
+@anchor{Macro sb-sys with-deadline}
+@ffindex @sortas{with-deadline sb-sys} with-deadline [sb-sys]
+@deffn{Macro} sb-sys:with-deadline (&key seconds override) &body body
+Arranges for a @code{timeout} condition to be signalled if an operation
+respecting deadlines occurs either after the deadline has passed, or
+would take longer than the time left to complete.
+Currently only @code{sleep}, blocking IO operations, @code{sb-thread:get-mutex}, and
+@code{sb-thread:condition-wait} respect deadlines, but this includes their
+implicit uses inside SBCL itself.
+
+Unless @code{override} is true, existing deadlines can only be restricted,
+not extended. Deadlines are per thread: children are unaffected by
+their parent's deadlines.
+
+Experimental.
+@end deffn
Expiration of deadlines set up this way only has an effect when it
happens before or during the execution of a deadline-aware operation
-(@pxref{Operations Supporting Timeouts and Deadlines}). In this case, a
+(@ref{operations supporting timeouts and deadlines}). In this case, a
@code{sb-sys:deadline-timeout} is signaled. A handler for this condition
-type may use the @code{sb-sys:defer-deadline} or
-@code{sb-sys:cancel-deadline} restarts to defer or cancel the deadline
-respectively and resume execution of the interrupted operation.
-
-@include condition-sb-sys-deadline-timeout.texinfo
+type may use the @code{sb-sys:defer-deadline} or @code{sb-sys:cancel-deadline}
+restarts to defer or cancel the deadline respectively and resume
+execution of the interrupted operation.
+@anchor{Condition sb-sys deadline-timeout}
+@ttindex @sortas{deadline-timeout sb-sys} deadline-timeout [sb-sys]
+@deffn{Condition} sb-sys:deadline-timeout
+Signaled when an operation in the context of a deadline takes
+longer than permitted by the deadline.
+@end deffn
+@anchor{Function sb-sys defer-deadline}
+@ffindex @sortas{defer-deadline sb-sys} defer-deadline [sb-sys]
+@deffn{Function} sb-sys:defer-deadline seconds &optional condition
+Find the @code{defer-deadline} restart associated with @code{condition}, and
+invoke it with @code{seconds} as argument (deferring the deadline by that many
+seconds.) Otherwise return @code{nil} if the restart is not found.
+@end deffn
+@anchor{Function sb-sys cancel-deadline}
+@ffindex @sortas{cancel-deadline sb-sys} cancel-deadline [sb-sys]
+@deffn{Function} sb-sys:cancel-deadline &optional condition
+Find and invoke the @code{cancel-deadline} restart associated with
+@code{condition}, or return @code{nil} if the restart is not found.
+@end deffn
When a thread is executing the debugger, signaling of
-@code{sb-sys:deadline-timeout} conditions for that thread is deferred
-until it exits the debugger.
+@code{sb-sys:deadline-timeout} conditions for that thread is deferred until
+it exits the debugger.
Example:
-@lisp
+@example
(defun read-input ()
(list (read-line) (read-line)))
@@ -1375,117 +2498,194 @@ Example:
(read-input)
(sleep 2)
(sb-ext:run-program "my-program"))
-@end lisp
+@end example
-@findex @cl{read-line}
-@findex @cl{sleep}
-@findex @sbext{run-program}
-The above code establishes a deadline of five seconds within which the
-body of the @code{do-it} function should execute. All calls of
+The above code establishes a deadline of five seconds within which
+the body of the @code{do-it} function should execute. All calls of
deadline-aware functions in the dynamic scope, in this case two
-@code{read-line} calls, a @code{sleep} call and a
-@code{sb-ext:run-program} call, are affected by the deadline. If, for
-example, the first @code{read-line} call completes in one second and the
-second @code{read-line} call completes in three seconds, a
-@code{sb-sys:deadline-timeout} condition will be signaled after the
-@code{sleep} call has been executing for one second.
+@code{read-line} calls, a @code{sleep} call and a @code{sb-ext:run-program} call, are
+affected by the deadline. If, for example, the first @code{read-line} call
+completes in one second and the second @code{read-line} call completes in
+three seconds, a @code{sb-sys:deadline-timeout} condition will be signaled
+after the @code{sleep} call has been executing for one second.
-@node Asynchronous Timeouts
+@node asynchronous timeouts
@subsection Asynchronous Timeouts
-@cindex Timeout
-@cindex Asynchronous Timeout
Asynchronous timeouts are established for a dynamic scope using the
-@code{sb-sys:with-timeout} macro:
+@code{sb-ext:with-timeout} macro:
-@include macro-sb-ext-with-timeout.texinfo
+@anchor{Macro sb-ext with-timeout}
+@ffindex @sortas{with-timeout sb-ext} with-timeout [sb-ext]
+@deffn{Macro} sb-ext:with-timeout expires &body body
+Execute the body, asynchronously interrupting it and signalling a @code{timeout}
+condition after at least @code{expires} seconds have passed.
+Note that it is never safe to unwind from an asynchronous condition. Consider:
+
+@example
+(defun call-with-foo (function)
+ (let (foo)
+ (unwind-protect
+ (progn
+ (setf foo (get-foo))
+ (funcall function foo))
+ (when foo
+ (release-foo foo)))))
+@end example
+
+If @code{timeout} occurs after @code{get-foo} has executed, but before the
+assignment, then @code{release-foo} will be missed. While individual sites
+like this can be made proof against asynchronous unwinds, this doesn't
+solve the fundamental issue, as all the frames potentially unwound
+through need to be proofed, which includes both system and application
+code -- and in essence proofing everything will make the system
+uninterruptible.
+@end deffn
Expiration of the timeout will cause the operation being executed at
that moment to be interrupted by an asynchronously signaled
@code{sb-ext:timeout} condition, (almost) irregardless of the operation
and its context.
-@include condition-sb-ext-timeout.texinfo
-
-@node Operations Supporting Timeouts and Deadlines
-@comment node-name,
+@anchor{Condition sb-ext timeout}
+@ttindex @sortas{timeout sb-ext} timeout [sb-ext]
+@deffn{Condition} sb-ext:timeout
+Signaled when an operation does not complete within an allotted time budget.
+@end deffn
+@node operations supporting timeouts and deadlines
@subsection Operations Supporting Timeouts and Deadlines
-@multitable @columnfractions .5 .25 .25
-@headitem Operation @tab Timeout Parameter @tab Affected by Deadlines
-@item @code{cl:sleep} @tab - @tab since SBCL 1.4.3
-@item @code{cl:read-line}, etc. @tab no @tab yes
-@item @ref{Macro sb-ext wait-for,,@code{wait-for}}@: @tab yes @tab yes
-@item @ref{Function sb-ext process-wait,,@code{process-wait}}@: @tab no @tab yes
-@item @ref{Function sb-thread grab-mutex,,@code{grab-mutex}}@: @tab yes @tab yes
-@item @ref{Function sb-thread condition-wait,,@code{condition-wait}}@: @tab yes @tab yes
-@item @ref{Function sb-thread wait-on-semaphore,,@code{wait-on-semaphore}}@: @tab yes @tab yes
-@item @ref{Function sb-thread join-thread,,@code{join-thread}}@: @tab yes @tab yes
-@item @ref{Function sb-concurrency receive-message,,@code{receive-message}}@: @tab yes @tab yes?
-@item @ref{Function sb-concurrency wait-on-gate,,@code{wait-on-gate}}@: @tab yes @tab yes?
-@item @ref{Macro sb-concurrency frlock-write,,@code{frlock-write}}@: @tab yes @tab yes?
-@item @ref{Function sb-concurrency grab-frlock-write-lock,,@code{grab-frlock-write-lock}}@: @tab yes @tab yes?
-@end multitable
+@example
+| Operation | Timeout parameter | Affected by deadlines |
+|------------------------+-------------------+-----------------------|
+| cl:sleep | - | since SBCL 1.4.3 |
+| cl:read-line, etc. | no | yes |
+| wait-for | yes | yes |
+| process-wait | no | yes |
+| grab-mutex | yes | yes |
+| condition-wait | yes | yes |
+| wait-on-semaphore | yes | yes |
+| join-thread | yes | yes |
+| receive-message | yes | yes? |
+| wait-on-gate | yes | yes? |
+| frlock-write | yes | yes? |
+| grab-frlock-write-lock | yes | yes? |
+@end example
-@node Miscellaneous Extensions
-@comment node-name, next, previous, up
+@node miscellaneous extensions
@section Miscellaneous Extensions
-@include fun-sb-ext-array-storage-vector.texinfo
-@include fun-sb-ext-delete-directory.texinfo
-@include fun-sb-ext-get-time-of-day.texinfo
-@include fun-sb-ext-assert-version-gt=.texinfo
-@include fun-sb-ext-unencapsulated-function.texinfo
-
-@node Stale Extensions
-@comment node-name, next, previous, up
+@anchor{Function sb-ext array-storage-vector}
+@ffindex @sortas{array-storage-vector sb-ext} array-storage-vector [sb-ext]
+@deffn{Function} sb-ext:array-storage-vector array
+Returns the underlying storage vector of @code{array}, which must be a non-displaced array.
+
+In SBCL, if @code{array} is a of type (@code{simple-array} * (*)), it is its own storage
+vector. Multidimensional arrays, arrays with fill pointers, and adjustable
+arrays have an underlying storage vector with the same @code{array-element-type} as
+@code{array}, which this function returns.
+
+@quotation
+@emph{Note}: the underlying vector is an implementation detail. Even
+though this function exposes it, changes in the implementation may
+cause this function to be removed without further warning.
+@end quotation
+@end deffn
+@anchor{Function sb-ext delete-directory}
+@ffindex @sortas{delete-directory sb-ext} delete-directory [sb-ext]
+@deffn{Function} sb-ext:delete-directory pathspec &key recursive
+Deletes the directory designated by @code{pathspec} (a pathname designator).
+Returns the truename of the directory deleted.
+
+If @code{recursive} is false (the default), signals an error unless the directory is
+empty. If @code{recursive} is true, first deletes all files and subdirectories. If
+@code{recursive} is true and the directory contains symbolic links, the links are
+deleted, not the files and directories they point to.
+
+Signals an error if @code{pathspec} designates a file or a symbolic link instead of a
+directory, or if the directory could not be deleted for any reason.
+
+Both
+
+@example
+(DELETE-DIRECTORY "/tmp/foo")
+(DELETE-DIRECTORY "/tmp/foo/")
+@end example
+
+delete the @code{"foo"} subdirectory of @code{"/tmp"}, or signal an error if
+it does not exist or if is a file or a symbolic link.
+@end deffn
+@anchor{Function sb-ext get-time-of-day}
+@ffindex @sortas{get-time-of-day sb-ext} get-time-of-day [sb-ext]
+@deffn{Function} sb-ext:get-time-of-day
+Return the number of seconds and microseconds since the beginning of
+the UNIX epoch (January 1st 1970.)
+@end deffn
+@anchor{Function sb-ext assert-version->=}
+@ffindex @sortas{assert-version->= sb-ext} assert-version->= [sb-ext]
+@deffn{Function} sb-ext:assert-version->= &rest subversions
+Asserts that the current SBCL is of version equal to or greater than
+the version specified in the arguments. A continuable error is signaled
+otherwise.
+
+The arguments specify a sequence of subversion numbers in big endian order.
+They are compared lexicographically with the runtime version, and versions
+are treated as though trailed by an unbounded number of 0s.
+
+For example, (@code{assert-version->=} 1 1 4) asserts that the current SBCL
+is version 1.1.4[.0.0...] or greater, and (@code{assert-version->=} 1) that
+it is version 1[.0.0...] or greater.
+@end deffn
+@anchor{Function sb-ext unencapsulated-function}
+@ffindex @sortas{unencapsulated-function sb-ext} unencapsulated-function [sb-ext]
+@deffn{Function} sb-ext:unencapsulated-function function
+Return the innermost function within any encapsulations of the
+function designated by @code{function}. The identity of the returned
+function is not affected by encapsulations.
+
+Note that the unencapsulated function may be @code{eq} to the designated
+function even in the presence of encapsulations. For generic
+functions, this is currently always the case.
+@end deffn
+@node stale extensions
@section Stale Extensions
SBCL has inherited from CMUCL various hooks to allow the user to
tweak and monitor the garbage collection process. These are somewhat
stale code, and their interface might need to be cleaned up. If you
-have urgent need of them, look at the code in @file{src/code/gc.lisp}
-and bring it up on the developers' mailing list.
+have urgent need of them, look at the code in @code{src/code/gc.lisp} and
+bring it up on the developers' mailing list.
-@findex @sbext{float-denormalized-p}
SBCL has various hooks inherited from CMUCL, like
-@code{sb-ext:float-denormalized-p}, to allow a program to take
-advantage of IEEE floating point arithmetic properties which aren't
-conveniently or efficiently expressible using the ANSI standard. These
-look good, and their interface looks good, but IEEE support is
-slightly broken due to a stupid decision to remove some support for
-infinities (because it wasn't in the ANSI spec and it didn't occur to
-me that it was in the IEEE spec). If you need this stuff, take a look
-at the code and bring it up on the developers' mailing
-list.
+@code{sb-ext:float-denormalized-p}, to allow a program to take advantage of
+IEEE floating point arithmetic properties which aren't conveniently
+or efficiently expressible using the ANSI standard. These look good,
+and their interface looks good, but IEEE support is slightly broken
+due to a stupid decision to remove some support for infinities
+(because it wasn't in the ANSI spec and it didn't occur to me that
+it was in the IEEE spec). If you need this stuff, take a look at the
+code and bring it up on the developers' mailing list.
-
-@node Efficiency Hacks
-@comment node-name, next, previous, up
+@node efficiency hacks
@section Efficiency Hacks
-@findex @sbext{purify}
-The @code{sb-ext:purify} function causes SBCL first to collect all
-garbage, then to mark all uncollected objects as permanent, never again
-attempting to collect them as garbage. This can cause a large increase
-in efficiency when using a primitive garbage collector, or a more
-moderate increase in efficiency when using a more sophisticated garbage
-collector which is well suited to the program's memory usage pattern. It
-also allows permanent code to be frozen at fixed addresses, a
-precondition for using copy-on-write to share code between multiple Lisp
-processes. This is less important with modern generational garbage
-collectors, but not all SBCL platforms use such a garbage collector.
+The @code{sb-ext:purify} function (available when @code{#+cheneygc}) causes
+SBCL first to collect all garbage, then to mark all uncollected
+objects as permanent, never again attempting to collect them as
+garbage. This can cause a large increase in efficiency when using a
+primitive garbage collector, or a more moderate increase in
+efficiency when using a more sophisticated garbage collector which
+is well suited to the program's memory usage pattern. It also allows
+permanent code to be frozen at fixed addresses, a precondition for
+using copy-on-write to share code between multiple Lisp processes.
+This is less important with modern generational garbage collectors,
+but not all SBCL platforms use such a garbage collector.
-@comment @include fun-sb-ext-purify.texinfo
+The @code{sb-ext:truly-the} special form declares the type of the result of
+the operations, producing its argument; the declaration is not
+checked. In short: don't use it.
-The @code{sb-ext:truly-the} special form declares the type of the
-result of the operations, producing its argument; the declaration is
-not checked. In short: don't use it.
+The @code{sb-ext:freeze-type} declaration declares that a type will never
+change, which can make type testing (e.g. with @code{typep}) more efficient
+for structure types.
-@include special-operator-sb-ext-truly-the.texinfo
-
-@cindex @code{freeze-type} declaration
-@cindex Declaration, @code{freeze-type}
-The @code{sb-ext:freeze-type} declaration declares that a
-type will never change, which can make type testing
-(@code{typep}, etc.) more efficient for structure types.
diff --git a/doc/manual/compiler.texinfo b/doc/manual/compiler.texinfo
index 8fa517a1c..066eb0eea 100644
--- a/doc/manual/compiler.texinfo
+++ b/doc/manual/compiler.texinfo
@@ -1,39 +1,36 @@
-@node Compiler
-@comment node-name, next, previous, up
+@c Generated by the sb-manual contrib. Do not edit.
+
+@node compiler
@chapter Compiler
+@menu
+* Diagnostic Messages: diagnostic messages.
+* Handling of Types: handling of types.
+* Compiler Policy: compiler policy.
+* Compiler Errors: compiler errors.
+* Open Coding and Inline Expansion: open coding and inline expansion.
+* Interpreter: interpreter.
+* Advanced Compiler Use and Efficiency Hints: advanced compiler use and efficiency hints.
+@end menu
+
This chapter will discuss most compiler issues other than efficiency,
including compiler error messages, the SBCL compiler's unusual
approach to type safety in the presence of type declarations, the
effects of various compiler optimization policies, and the way that
inlining and open coding may cause optimized code to differ from a
naive translation. Efficiency issues are sufficiently varied and
-separate that they have their own chapter, @ref{Efficiency}.
+separate that they have their own chapter, @ref{efficiency}.
-@menu
-* Diagnostic Messages::
-* Handling of Types::
-* Compiler Policy::
-* Compiler Errors::
-* Open Coding and Inline Expansion::
-* Interpreter::
-* Advanced Compiler Use and Efficiency Hints::
-@end menu
-
-@node Diagnostic Messages
-@comment node-name, next, previous, up
+@node diagnostic messages
@section Diagnostic Messages
-@cindex Messages, Compiler
-@cindex Compiler messages
@menu
-* Controlling Verbosity::
-* Diagnostic Severity::
-* Understanding Compiler Diagnostics::
+* Controlling Verbosity: controlling verbosity.
+* Diagnostic Severity: diagnostic severity.
+* Understanding Compiler Diagnostics: understanding compiler diagnostics.
@end menu
-@node Controlling Verbosity
-@comment node-name, next, previous, up
+@node controlling verbosity
@subsection Controlling Verbosity
The compiler can be quite verbose in its diagnostic reporting, rather
@@ -41,19 +38,21 @@ more then some users would prefer -- the amount of noise emitted can
be controlled, however.
To control emission of compiler diagnostics (of any severity other
-than @code{error}: @pxref{Diagnostic Severity}) use the
-@code{sb-ext:muffle-conditions} and @code{sb-ext:unmuffle-conditions}
-declarations, specifying the type of condition that is to be muffled
-(the muffling is done using an associated @code{muffle-warning} restart).
+than @code{error}: @ref{diagnostic severity}) use the @code{sb-ext:muffle-conditions}
+and @code{sb-ext:unmuffle-conditions} declarations, specifying the type of
+condition that is to be muffled (the muffling is done using an
+associated @code{muffle-warning} restart).
Global control:
-@lisp
+
+@example
;;; Muffle compiler-notes globally
(declaim (sb-ext:muffle-conditions sb-ext:compiler-note))
-@end lisp
+@end example
Local control:
-@lisp
+
+@example
;;; Muffle compiler-notes based on lexical scope
(defun foo (x)
(declare (optimize speed) (fixnum x)
@@ -63,140 +62,117 @@ Local control:
(declare (sb-ext:unmuffle-conditions sb-ext:compiler-note))
;; this one gives a compiler note
(* x -5))))
-@end lisp
+@end example
-@deffn {Declaration} @sbext{muffle-conditions}
-Syntax: type*
+@itemize
+@item [@strong{declaration}] @code{sb-ext:muffle-conditions}
-Muffles the diagnostic messages that would be caused by compile-time
-signals of given types.
-@end deffn
+Syntax: @code{(sb-ext:muffle-conditions &rest types)}.
-@deffn {Declaration} @sbext{unmuffle-conditions}
-Syntax: type*
+Muffle the diagnostic messages that would be caused by
+compile-time signals of TYPES.
-Cancels the effect of a previous @code{sb-ext:muffle-conditions}
+@item [@strong{declaration}] @code{sb-ext:unmuffle-conditions}
+
+Syntax: @code{(sb-ext:muffle-conditions &rest types)}.
+
+Cancel the effect of a previous @code{sb-ext:muffle-conditions}
declaration.
-@end deffn
+@end itemize
Various details of @emph{how} the compiler messages are printed can be
-controlled via the alist
-@code{sb-ext:*compiler-print-variable-alist*}.
+controlled via the alist @code{sb-ext:*compiler-print-variable-alist*}.
-@include var-sb-ext-star-compiler-print-variable-alist-star.texinfo
+@anchor{Variable sb-ext *compiler-print-variable-alist*}
+@vvindex @sortas{compiler-print-variable-alist* sb-ext} *compiler-print-variable-alist* [sb-ext]
+@deffn{Variable} sb-ext:*compiler-print-variable-alist*
+An association list describing new bindings for special variables
+to be used by the compiler for error-reporting, etc.
+E.g. ((@code{*print-length*} . 10) (@code{*print-level*} . 6) (@code{*print-pretty*} .
+@code{nil})).
+The variables in the @code{car} positions are bound to the values in the @code{cdr}
+during the execution of some debug commands. When evaluating arbitrary
+expressions in the debugger, the normal values of the printer control
+variables are in effect.
+
+Initially empty, @code{*compiler-print-variable-alist*} is typically used
+to specify bindings for printer control variables.
+@end deffn
For information about muffling warnings signaled outside of the
-compiler, see @ref{Customization Hooks for Users}.
+compiler, see @ref{customization hooks for users}.
-@c <!-- FIXME: How much control over error messages is in SBCL?
-@c _ How much should be? How much of this documentation should
-@c _ we save or adapt?
-@c _
-@c _ %%\node Error Message Parameterization, , Read Errors, Interpreting Error Messages
-@c _ \subsection{Error Message Parameterization}
-@c _ \cpsubindex{error messages}{verbosity}
-@c _ \cpsubindex{verbosity}{of error messages}
-@c _
-@c _ There is some control over the verbosity of error messages. See also
-@c _ \varref{undefined-warning-limit}, \code{*efficiency-note-limit*} and
-@c _ \varref{efficiency-note-cost-threshold}.
-@c _
-@c _ \begin{defvar}{}{enclosing-source-cutoff}
-@c _
-@c _ This variable specifies the number of enclosing actual source forms
-@c _ that are printed in full, rather than in the abbreviated processing
-@c _ path format. Increasing the value from its default of \code{1}
-@c _ allows you to see more of the guts of the macroexpanded source,
-@c _ which is useful when debugging macros.
-@c _ \end{defvar}
-@c _
-@c _ \begin{defmac}{extensions:}{define-source-context}{%
-@c _ \args{\var{name} \var{lambda-list} \mstar{form}}}
-@c _
-@c _ This macro defines how to extract an abbreviated source context from
-@c _ the \var{name}d form when it appears in the compiler input.
-@c _ \var{lambda-list} is a \code{defmacro} style lambda-list used to
-@c _ parse the arguments. The \var{body} should return a list of
-@c _ subforms that can be printed on about one line. There are
-@c _ predefined methods for \code{defstruct}, \code{defmethod}, etc. If
-@c _ no method is defined, then the first two subforms are returned.
-@c _ Note that this facility implicitly determines the string name
-@c _ associated with anonymous functions.
-@c _ \end{defmac}
-@c _
-@c _ -->
-
-@node Diagnostic Severity
-@comment node-name, next, previous, up
+@node diagnostic severity
@subsection Diagnostic Severity
-@cindex Severity of compiler messages
-@cindex Compiler Diagnostic Severity
-@tindex @cl{error}
-@tindex @cl{warning}
-@tindex @cl{style-warning}
-@tindex @sbext{compiler-note}
-@tindex @sbext{code-deletion-note}
There are four levels of compiler diagnostic severity:
-@enumerate 1
+@itemize
@item error
@item warning
@item style warning
@item note
-@end enumerate
+@end itemize
The first three levels correspond to condition classes which are
defined in the ANSI standard for Common Lisp and which have special
-significance to the @code{compile} and @code{compile-file} functions.
-These levels of compiler error severity occur when the compiler
-handles conditions of these classes.
+significance to the @code{compile} and @code{compile-file} functions. These levels
+of compiler error severity occur when the compiler handles
+conditions of these classes.
-The fourth level of compiler error severity, @emph{note}, corresponds
-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
+The fourth level of compiler error severity, @emph{note}, corresponds 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 after proving that the code in question is
-unreachable.
+subtype of @code{sb-ext:compiler-note}, is signalled when the compiler
+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.
+allow more fine-grained control over emission of diagnostic
+messages.
-@include condition-sb-ext-compiler-note.texinfo
-@include condition-sb-ext-code-deletion-note.texinfo
+@anchor{Condition sb-ext compiler-note}
+@ttindex @sortas{compiler-note sb-ext} compiler-note [sb-ext]
+@deffn{Condition} sb-ext:compiler-note
+Root of the hierarchy of conditions representing information discovered
+by the compiler that the user might wish to know, but which does not merit
+a @code{style-warning} (or any more serious condition).
+@end deffn
+@anchor{Condition sb-ext code-deletion-note}
+@ttindex @sortas{code-deletion-note sb-ext} code-deletion-note [sb-ext]
+@deffn{Condition} sb-ext:code-deletion-note
+A condition type signalled when the compiler deletes code that the user
+has written, having proved that it is unreachable.
+@end deffn
+@node understanding compiler diagnostics
+@subsection Understanding Compiler Diagnostics
-
-@node Understanding Compiler Diagnostics
-@comment node-name, next, previous, up
-@subsection Understanding Compile Diagnostics
+@menu
+* Parts of a Compiler Diagnostic: parts of a compiler diagnostic.
+* Original and Actual Source: original and actual source.
+* Processing Path: processing path.
+@end menu
The messages emitted by the compiler contain a lot of detail in a
terse format, so they may be confusing at first. The messages will be
illustrated using this example program:
-@lisp
+@example
(defmacro zoq (x)
`(roq (ploq (+ ,x 3))))
(defun foo (y)
(declare (symbol y))
(zoq y))
-@end lisp
+@end example
-The main problem with this program is that it is trying to add
-@code{3} to a symbol. Note also that the functions @code{roq} and
-@code{ploq} aren't defined anywhere.
+The main problem with this program is that it is trying to add @code{3}
+to a symbol. Note also that the functions @code{roq} and @code{ploq} aren't
+defined anywhere.
-@menu
-* The Parts of a Compiler Diagnostic::
-* The Original and Actual Source::
-* The Processing Path::
-@end menu
-
-@node The Parts of a Compiler Diagnostic
-@comment node-name, next, previous, up
-@subsubsection The Parts of a Compiler Diagnostic
+@node parts of a compiler diagnostic
+@subsubsection Parts of a Compiler Diagnostic
When processing this program, the compiler will produce this warning:
@@ -215,98 +191,78 @@ When processing this program, the compiler will produce this warning:
In this example we see each of the six possible parts of a compiler
diagnostic:
-@enumerate
+@itemize
+@item @code{file: /tmp/foo.lisp} is the name of the file that the compiler
+ read the relevant code from. The file name is displayed because it
+ may not be immediately obvious when there is an error during
+ compilation of a large system, especially when
+ @code{with-compilation-unit} is used to delay undefined warnings.
-@item
-@findex @cl{with-compilation-unit}
-@samp{file: /tmp/foo.lisp} This is the name of the file that the
-compiler read the relevant code from. The file name is displayed
-because it may not be immediately obvious when there is an error
-during compilation of a large system, especially when
-@code{with-compilation-unit} is used to delay undefined warnings.
+@item @code{in: DEFUN FOO} is the definition top level form responsible for
+ the diagnostic. It is obtained by taking the first two elements of
+ the enclosing form whose first element is a symbol beginning with
+ @code{def}. If there is no such enclosing @code{def} form, then the
+ outermost form is used. If there are multiple @code{def} forms, then
+ they are all printed from the outside in, separated by @code{=>}s. In
+ this example, the problem was in the @code{defun} for @code{foo}.
-@item
-@samp{in: DEFUN FOO} This is the definition top level form responsible
-for the diagnostic. It is obtained by taking the first two elements of
-the enclosing form whose first element is a symbol beginning with
-``@samp{def}''. If there is no such enclosing ``@samp{def}'' form,
-then the outermost form is used. If there are multiple @samp{def}
-forms, then they are all printed from the outside in, separated by
-@samp{=>}'s. In this example, the problem was in the @code{defun} for
-@code{foo}.
+@item @code{(zoq y)} is the @emph{original source} form responsible for the
+ diagnostic. Original source means that the form directly appeared
+ in the original input to the compiler, i.e. in the lambda passed
+ to @code{compile} or in the top level form read from the source file. In
+ this example, the expansion of the @code{zoq} macro was responsible for
+ the message.
-@item
-@cindex Original Source
-@samp{(ZOQ Y)} This is the @dfn{original source} form responsible for
-the diagnostic. Original source means that the form directly appeared
-in the original input to the compiler, i.e. in the lambda passed to
-@code{compile} or in the top level form read from the source file. In
-this example, the expansion of the @code{zoq} macro was responsible
-for the message.
+@item @code{--> roq ploq} This is the @emph{processing path} that the compiler
+ used to produce the code that caused the message to be emitted.
+ The processing path is a representation of the evaluated forms
+ enclosing the actual source that the compiler encountered when
+ processing the original source. The path is the first element of
+ each form, or the form itself if the form is not a list. These
+ forms result from the expansion of macros or source-to-source
+ transformation done by the compiler. In this example, the
+ enclosing evaluated forms are the calls to @code{roq} and @code{ploq}. These
+ calls resulted from the expansion of the @code{zoq} macro.
-@item
-@cindex Processing Path
-@samp{--> ROQ PLOQ} This is the @dfn{processing path} that the
-compiler used to produce the code that caused the message to be
-emitted. The processing path is a representation of the evaluated
-forms enclosing the actual source that the compiler encountered when
-processing the original source. The path is the first element of each
-form, or the form itself if the form is not a list. These forms result
-from the expansion of macros or source-to-source transformation done
-by the compiler. In this example, the enclosing evaluated forms are
-the calls to @code{roq} and @code{ploq}. These calls resulted from the
-expansion of the @code{zoq} macro.
+@item @code{==> (+ y 3)} is the @emph{actual source} responsible for the
+ diagnostic. If the actual source appears in the explanation, then
+ we print the next enclosing evaluated form, instead of printing
+ the actual source twice. (This is the form that would otherwise
+ have been the last form of the processing path.) In this example,
+ the problem is with the evaluation of the reference to the
+ variable @code{y}.
-@item
-@cindex Actual Source
-@samp{==> (+ Y 3)} This is the @dfn{actual source} responsible for the
-diagnostic. If the actual source appears in the explanation, then we
-print the next enclosing evaluated form, instead of printing the
-actual source twice. (This is the form that would otherwise have been
-the last form of the processing path.) In this example, the problem is
-with the evaluation of the reference to the variable @code{y}.
-
-@item
-@samp{caught WARNING: Asserted type NUMBER conflicts with derived type
-(VALUES SYMBOL &OPTIONAL).} This is the @dfn{explanation} of the
-problem. In this example, the problem is that, while the call to
-@code{+} requires that its arguments are all of type @code{number},
-the compiler has derived that @code{y} will evaluate to a
-@code{symbol}. Note that @samp{(VALUES SYMBOL &OPTIONAL)} expresses
-that @code{y} evaluates to precisely one value.
-
-@end enumerate
+@item @code{caught WARNING: Asserted type NUMBER conflicts with derived type
+ (VALUES SYMBOL &OPTIONAL).} is the @emph{explanation} of the problem.
+ In this example, the problem is that, while the call to @code{+}
+ requires that its arguments are all of type @code{number}, the compiler
+ has derived that Y will evaluate to a @code{symbol}. Note that
+ @code{(values symbol &optional)} expresses that @code{y} evaluates to
+ precisely one value.
+@end itemize
Note that each part of the message is distinctively marked:
@itemize
+@item @code{file:} and @code{in:} mark the file and definition, respectively.
-@item
- @samp{file:} and @samp{in:} mark the file and definition,
-respectively.
+@item The original source is an indented form with no prefix.
-@item
-The original source is an indented form with no prefix.
+@item Each line of the processing path is prefixed with @code{-->}.
-@item
-Each line of the processing path is prefixed with @samp{-->}
-
-@item
-The actual source form is indented like the original source, but is
-marked by a preceding @samp{==>} line.
-@comment no it isn't.
-
-@item
-The explanation is prefixed with the diagnostic severity, which can be
-@samp{caught ERROR:}, @samp{caught WARNING:}, @samp{caught
-STYLE-WARNING:}, or @samp{note:}.
+@item The actual source form is indented like the original source, but
+ is marked by a preceding @code{==>} line. (FIXME: no it isn't.)
+@item The explanation is prefixed with the diagnostic severity, which
+ can be @code{caught ERROR:}, @code{caught WARNING:}, @code{caught
+ STYLE-WARNING:}, or @code{note:}.
@end itemize
Each part of the message is more specific than the preceding one. If
-consecutive messages are for nearby locations, then the front part of
-the messages would be the same. In this case, the compiler omits as
-much of the second message as in common with the first. For example:
+consecutive messages are for nearby locations, then the front part
+of the messages would be the same. In this case, the compiler omits
+as much of the second message as in common with the first. For
+example:
@example
; file: /tmp/foo.lisp
@@ -325,27 +281,22 @@ much of the second message as in common with the first. For example:
; caught STYLE-WARNING:
; undefined function: ROQ
@end example
-@comment fixing that weird blank line might be good
In this example, the file, definition and original source are
identical for the two messages, so the compiler omits them in the
second message. If consecutive messages are entirely identical, then
-the compiler prints only the first message, followed by: @samp{[Last
-message occurs @var{repeats} times]} where @var{repeats} is the number
-of times the message was given.
+the compiler prints only the first message, followed by: @code{[Last
+message occurs <repeats> times]} where @code{<repeats>} is the number of
+times the message was given.
If the source was not from a file, then no file line is printed. If
the actual source is the same as the original source, then the
processing path and actual source will be omitted. If no forms
-intervene between the original source and the actual source, then the
-processing path will also be omitted.
+intervene between the original source and the actual source, then
+the processing path will also be omitted.
-
-@node The Original and Actual Source
-@comment node-name, next, previous, up
-@subsubsection The Original and Actual Source
-@cindex Original Source
-@cindex Actual Source
+@node original and actual source
+@subsubsection Original and Actual Source
The @emph{original source} displayed will almost always be a list. If
the actual source for an message is a symbol, the original source will
@@ -354,8 +305,8 @@ offending symbol does appear in the original source, the compiler will
print the enclosing list and then print the symbol as the actual
source (as though the symbol were introduced by a macro.)
-When the @emph{actual source} is displayed (and is not a symbol), it
-will always be code that resulted from the expansion of a macro or a
+When the @emph{actual source} is displayed (and is not a symbol), it will
+always be code that resulted from the expansion of a macro or a
source-to-source compiler optimization. This is code that did not
appear in the original source program; it was introduced by the
compiler.
@@ -364,13 +315,13 @@ Keep in mind that when the compiler displays a source form in an
diagnostic message, it always displays the most specific (innermost)
responsible form. For example, compiling this function
-@lisp
+@example
(defun bar (x)
(let (a)
(declare (fixnum a))
(setq a (foo x))
a))
-@end lisp
+@end example
gives this error message
@@ -386,25 +337,21 @@ gives this error message
; Asserted type FIXNUM conflicts with derived type (VALUES NULL &OPTIONAL).
@end example
-This message is not saying ``there is a problem somewhere in this
-@code{let}'' -- it is saying that there is a problem with the
-@code{let} itself. In this example, the problem is that @code{a}'s
-@code{nil} initial value is not a @code{fixnum}.
+This message is not saying that there is a problem somewhere in this
+@code{let} -- it is saying that there is a problem with the @code{let} itself. In
+this example, the problem is that @code{a}'s @code{nil} initial value is not a
+@code{fixnum}.
-@node The Processing Path
-@comment node-name, next, previous, up
-@subsubsection The Processing Path
-@cindex Processing Path
-@cindex Macroexpansion
-@cindex Source-to-source transformation
+@node processing path
+@subsubsection Processing Path
The processing path is mainly useful for debugging macros, so if you
don't write macros, you can probably ignore it. Consider this example:
-@lisp
+@example
(defun foo (n)
(dotimes (i n *undefined*)))
-@end lisp
+@end example
Compiling results in this error message:
@@ -422,16 +369,15 @@ Compiling results in this error message:
Note that @code{do} appears in the processing path. This is because
@code{dotimes} expands into:
-@lisp
+@example
(do ((i 0 (1+ i)) (#:g1 n))
((>= i #:g1) *undefined*)
(declare (type unsigned-byte i)))
-@end lisp
+@end example
-The rest of the processing path results from the expansion of
-@code{do}:
+The rest of the processing path results from the expansion of @code{do}:
-@lisp
+@example
(block nil
(let ((i 0) (#:g1 n))
(declare (type unsigned-byte i))
@@ -439,59 +385,42 @@ The rest of the processing path results from the expansion of
#:g2 (psetq i (1+ i))
#:g3 (unless (>= i #:g1) (go #:g2))
(return-from nil (progn *undefined*)))))
-@end lisp
+@end example
-In this example, the compiler descended into the @code{block},
-@code{let}, @code{tagbody} and @code{return-from} to reach the
-@code{progn} printed as the actual source. This is a place where the
-``actual source appears in explanation'' rule was applied. The
-innermost actual source form was the symbol @code{*undefined*} itself,
-but that also appeared in the explanation, so the compiler backed out
-one level.
+In this example, the compiler descended into the @code{block}, @code{let}, @code{tagbody}
+and @code{return-from} to reach the @code{progn} printed as the actual source.
+This is a place where the "actual source appears in explanation"
+rule was applied. The innermost actual source form was the symbol
+@emph{undefined} itself, but that also appeared in the explanation, so
+the compiler backed out one level.
-
-
-
-
-@node Handling of Types
-@comment node-name, next, previous, up
+@node handling of types
@section Handling of Types
+@menu
+* Declarations as Assertions: declarations as assertions.
+* Precise Type Checking: precise type checking.
+* Getting Existing Programs to Run: getting existing programs to run.
+* Implementation Limitations: implementation limitations.
+@end menu
+
One of the most important features of the SBCL compiler (similar to
-the original CMUCL compiler, also known as @dfn{Python}) is its fairly
+the original CMUCL compiler, also known as @emph{Python}) is its fairly
sophisticated understanding of the Common Lisp type system and its
conservative approach to the implementation of type declarations.
These two features reward the use of type declarations throughout
development, even when high performance is not a concern. Also, as
-discussed in the chapter on performance (@pxref{Efficiency}), the use
-of appropriate type declarations can be very important for performance
-as well.
+discussed in the chapter on performance (see @ref{efficiency}), the use
+of appropriate type declarations can be very important for
+performance as well.
-@findex @cl{satisfies}
The SBCL compiler also has a greater knowledge of the Common Lisp
-type system than other compilers. Support is incomplete only for types
-involving the @code{satisfies} type specifier.
+type system than other compilers. Support is incomplete only for
+types involving the @code{satisfies} type specifier.
-@c <!-- FIXME: See also sections \ref{advanced-type-stuff}
-@c and \ref{type-inference}, once we snarf them from the
-@c CMU CL manual. -->
-@c
-@c Also see my paper on improving Baker, when I get round to it.
-@c
-@c Whose paper?
-
-@menu
-* Declarations as Assertions::
-* Precise Type Checking::
-* Getting Existing Programs to Run::
-* Implementation Limitations::
-@end menu
-
-@node Declarations as Assertions
-@comment node-name, next, previous, up
+@node declarations as assertions
@subsection Declarations as Assertions
-@cindex Safety optimization quality
The SBCL compiler treats type declarations differently from most other
Lisp compilers. Under default compilation policy the compiler doesn't
@@ -499,85 +428,75 @@ blindly believe type declarations, but considers them assertions about
the program that should be checked: all type declarations that have
not been proven to always hold are asserted at runtime.
-@quotation
@emph{Remaining bugs in the compiler's handling of types unfortunately
-provide some exceptions to this rule, see @ref{Implementation
-Limitations}.}
-@end quotation
+provide some exceptions to this rule, see
+@ref{implementation limitations}.}
CLOS slot types form a notable exception. Types declared using the
-@code{:type} slot option in @code{defclass} are asserted if and only
-if the class was defined in @emph{safe code} and the slot access
-location is in @emph{safe code} as well. This laxness does not pose
-any internal consistency issues, as the CLOS slot types are not
-available for the type inferencer, nor do CLOS slot types provide any
-efficiency benefits.
+@code{:type} slot option in @code{defclass} are asserted if and only if the class
+was defined in @emph{safe code} and the slot access location is in @emph{safe
+code} as well. This laxness does not pose any internal consistency
+issues, as the CLOS slot types are not available for the type
+inferencer, nor do CLOS slot types provide any efficiency benefits.
There are three type checking policies available in SBCL, selectable
via @code{optimize} declarations.
-@table @strong
+@itemize
+@item @strong{Full Type Checks}
-@c FIXME: This should be properly integrated with general policy
-@c stuff, once that gets cleaned up.
-
-@item Full Type Checks
-All declarations are considered assertions to be checked at runtime,
-and all type checks are precise. The default compilation policy
-provides full type checks.
+All declarations are considered assertions to be checked at
+runtime, and all type checks are precise. The default
+compilation policy provides full type checks.
Used when @code{(or (>= safety 2) (>= safety speed 1))}.
-@item Weak Type Checks
-Declared types may be simplified into faster to check supertypes: for
-example, @code{(or (integer -17 -7) (integer 7 17))} is simplified
-into @code{(integer -17 17)}.
+@item @strong{Weak Type Checks}
-@strong{Note}: it is relatively easy to corrupt the heap when weak
-type checks are used if the program contains type-errors.
+Declared types may be simplified into faster to check
+supertypes: for example, @code{(or (integer -17 -7) (integer 7 17))}
+is simplified into @code{(integer -17 17)}.
-Used when @code{(and (< safety 2) (< safety speed))}
+@quotation
+@strong{Warning}: It is relatively easy to corrupt the heap when
+weak type checks are used if the program contains type-errors.
+@end quotation
+
+Used when @code{(and (< safety 2) (< safety speed))}.
+
+@item @strong{No Type Checks}
-@item No Type Checks
All declarations are believed without assertions. Also disables
argument count and array bounds checking.
-@strong{Note}: any type errors in code where type checks are not
+@quotation
+@strong{Warning}: Any type errors in code where type checks are not
performed are liable to corrupt the heap.
+@end quotation
Used when @code{(= safety 0)}.
+@end itemize
-@end table
-
-@node Precise Type Checking
-@comment node-name, next, previous, up
+@node precise type checking
@subsection Precise Type Checking
-@cindex Precise type checking
-@cindex Type checking, precise
Precise checking means that the check is done as though @code{typep}
had been called with the exact type specifier that appeared in the
declaration.
-If a variable is declared to be @code{(integer 3 17)} then its value
-must always be an integer between @code{3} and @code{17}. If multiple
-type declarations apply to a single variable, then all the
-declarations must be correct; it is as though all the types were
-intersected producing a single @code{and} type specifier.
+If a variable is declared to be @code{(integer 3 17)}, then its value
+must always be an integer between @code{3} and @code{17}. If multiple type
+declarations apply to a single variable, then all the declarations
+must be correct; it is as though all the types were intersected
+producing a single @code{and} type specifier.
-To gain maximum benefit from the compiler's type checking, you should
-always declare the types of function arguments and structure slots as
-precisely as possible. This often involves the use of @code{or},
+To gain maximum benefit from the compiler's type checking, you
+should always declare the types of function arguments and structure
+slots as precisely as possible. This often involves the use of @code{or},
@code{member}, and other list-style type specifiers.
-
-@node Getting Existing Programs to Run
-@comment node-name, next, previous, up
+@node getting existing programs to run
@subsection Getting Existing Programs to Run
-@cindex Existing programs, to run
-@cindex Types, portability
-@cindex Compatibility with other Lisps
-@c (should also have an entry in the non-ANSI-isms section)-->
Since SBCL's compiler does much more comprehensive type checking than
most Lisp compilers, SBCL may detect type errors in programs that have
@@ -587,322 +506,289 @@ if parts of the program have never been tested.
Some incorrect declarations can only be detected by run-time type
checking. It is very important to initially compile a program with
-full type checks (high @code{safety} optimization) and then test this
-safe version. After the checking version has been tested, then you can
-consider weakening or eliminating type checks. @emph{This applies
-even to previously debugged programs,} because the SBCL compiler does
-much more type inference than other Common Lisp compilers, so an
+full type checks (high @code{safety} optimization) and then test this safe
+version. After the checking version has been tested, then you can
+consider weakening or eliminating type checks. @emph{This applies even to
+previously debugged programs} because the SBCL compiler does much
+more type inference than other Common Lisp compilers, so an
incorrect declaration can do more damage.
-The most common problem is with variables whose constant initial value
-doesn't match the type declaration. Incorrect constant initial values
-will always be flagged by a compile-time type error, and they are
-simple to fix once located. Consider this code fragment:
+The most common problem is with variables whose constant initial
+value doesn't match the type declaration. Incorrect constant initial
+values will always be flagged by a compile-time type error, and they
+are simple to fix once located. Consider this code fragment:
-@lisp
+@example
(prog (foo)
(declare (fixnum foo))
(setq foo ...)
...)
-@end lisp
+@end example
-Here @code{foo} is given an initial value of @code{nil}, but is
-declared to be a @code{fixnum}. Even if it is never read, the initial
-value of a variable must match the declared type. There are two ways
-to fix this problem. Change the declaration
+Here @code{foo} is given an initial value of @code{nil} but is declared to be a
+@code{fixnum}. Even if it is never read, the initial value of a variable
+must match the declared type. There are two ways to fix this
+problem. Change the declaration
-@lisp
+@example
(prog (foo)
(declare (type (or fixnum null) foo))
(setq foo ...)
...)
-@end lisp
+@end example
or change the initial value
-@lisp
+@example
(prog ((foo 0))
(declare (fixnum foo))
(setq foo ...)
...)
-@end lisp
+@end example
It is generally preferable to change to a legal initial value rather
-than to weaken the declaration, but sometimes it is simpler to weaken
-the declaration than to try to make an initial value of the
+than to weaken the declaration, but sometimes it is simpler to
+weaken the declaration than to try to make an initial value of the
appropriate type.
Another declaration problem occasionally encountered is incorrect
-declarations on @code{defmacro} arguments. This can happen when a
-function is converted into a macro. Consider this macro:
+declarations on @code{defmacro} arguments. This can happen when a function
+is converted into a macro. Consider this macro:
-@lisp
+@example
(defmacro my-1+ (x)
(declare (fixnum x))
`(the fixnum (1+ ,x)))
-@end lisp
+@end example
-Although legal and well-defined Common Lisp code, this meaning of this
-definition is almost certainly not what the writer intended. For
-example, this call is illegal:
+Although legal and well-defined Common Lisp code, this meaning of
+this definition is almost certainly not what the writer intended.
+For example, this call is illegal:
-@lisp
+@example
(my-1+ (+ 4 5))
-@end lisp
+@end example
-This call is illegal because the argument to the macro is @code{(+ 4
-5)}, which is a @code{list}, not a @code{fixnum}. Because of macro
-semantics, it is hardly ever useful to declare the types of macro
-arguments. If you really want to assert something about the type of
-the result of evaluating a macro argument, then put a @code{the} in
-the expansion:
+This call is illegal because the argument to the macro is @code{(+ 4 5)},
+which is a @code{list}, not a @code{fixnum}. Because of macro semantics, it is
+hardly ever useful to declare the types of macro arguments. If you
+really want to assert something about the type of the result of
+evaluating a macro argument, then put a @code{the} in the expansion:
-@lisp
+@example
(defmacro my-1+ (x)
`(the fixnum (1+ (the fixnum ,x))))
-@end lisp
+@end example
+
In this case, it would be stylistically preferable to change this
macro back to a function and declare it inline.
-@c <!--FIXME: <xref>inline-expansion, once we crib the
-@c relevant text from the CMU CL manual.-->
Some more subtle problems are caused by incorrect declarations that
-can't be detected at compile time. Consider this code:
+can't be detected at compile time. Consider this code:
-@lisp
-(do ((pos 0 (position #\a string :start (1+ pos))))
+@example
+(do ((pos 0 (position #a string :start (1+ pos))))
((null pos))
(declare (fixnum pos))
...)
-@end lisp
+@end example
-Although @code{pos} is almost always a @code{fixnum}, it is @code{nil}
-at the end of the loop. If this example is compiled with full type
-checks (the default), then running it will signal a type error at the
-end of the loop. If compiled without type checks, the program will go
-into an infinite loop (or perhaps @code{position} will complain
-because @code{(1+ nil)} isn't a sensible start.) Why? Because if you
-compile without type checks, the compiler just quietly believes the
-type declaration. Since the compiler believes that @code{pos} is
-always a @code{fixnum}, it believes that @code{pos} is never
-@code{nil}, so @code{(null pos)} is never true, and the loop exit test
-is optimized away. Such errors are sometimes flagged by unreachable
-code notes, but it is still important to initially compile and test
-any system with full type checks, even if the system works fine when
-compiled using other compilers.
+Although @code{pos} is almost always a @code{fixnum}, it is @code{nil} at the end of
+the loop. If this example is compiled with full type checks (the
+default), then running it will signal a type error at the end of the
+loop. If compiled without type checks, the program will go into an
+infinite loop (or perhaps @code{position} will complain because @code{(1+ nil)}
+isn't a sensible start.) Why? Because if you compile without type
+checks, the compiler just quietly believes the type declaration.
+Since the compiler believes that @code{pos} is always a @code{fixnum}, it
+believes that @code{pos} is never @code{nil}, so @code{(null pos)} is never true, and
+the loop exit test is optimized away. Such errors are sometimes
+flagged by unreachable code notes, but it is still important to
+initially compile and test any system with full type checks, even if
+the system works fine when compiled using other compilers.
In this case, the fix is to weaken the type declaration to @code{(or
-fixnum null)} @footnote{Actually, this declaration is unnecessary in
-SBCL, since it already knows that @code{position} returns a
-non-negative @code{fixnum} or @code{nil}.}.
+fixnum null)}. (Actually, this declaration is unnecessary in SBCL,
+since it already knows that @code{position} returns a non-negative @code{fixnum}
+or @code{nil}.)
-Note that there is usually little performance penalty for weakening a
-declaration in this way. Any numeric operations in the body can still
-assume that the variable is a @code{fixnum}, since @code{nil} is not a
-legal numeric argument. Another possible fix would be to say:
+Note that there is usually little performance penalty for weakening
+a declaration in this way. Any numeric operations in the body can
+still assume that the variable is a @code{fixnum}, since @code{nil} is not a legal
+numeric argument. Another possible fix would be to say:
-@lisp
-(do ((pos 0 (position #\a string :start (1+ pos))))
+@example
+(do ((pos 0 (position #a string :start (1+ pos))))
((null pos))
(let ((pos pos))
(declare (fixnum pos))
...))
-@end lisp
+@end example
-This would be preferable in some circumstances, since it would allow a
-non-standard representation to be used for the local @code{pos}
+This would be preferable in some circumstances, since it would allow
+a non-standard representation to be used for the local @code{pos}
variable in the loop body.
-@c <!-- FIXME: <xref>ND-variables, once we crib the text from the
-@c CMU CL manual. -->
-@node Implementation Limitations
-@comment node-name, next, previous, up
+@node implementation limitations
@subsection Implementation Limitations
-If an FTYPE is placed after the function definition the function won't
+If an @code{ftype} is placed after the function definition the function won't
perform any type checks, and the calls to the function will blindly
trust the declared types.
-@code{(optimize (debug 3))} will not trust any FTYPE declarations.
+(@code{optimize} (@code{debug} 3)) will not trust any @code{ftype} declarations.
-@node Compiler Policy
-@comment node-name, next, previous, up
+@node compiler policy
@section Compiler Policy
Compiler policy is controlled by the @code{optimize} declaration,
-supporting all ANSI optimization qualities (@code{debug},
-@code{safety}, @code{space}, and @code{speed}).@footnote{A deprecated
-extension @code{sb-ext:inhibit-warnings} is still supported, but
-liable to go away at any time.}
+supporting all ANSI optimization qualities (@code{debug}, safety, space,
+and speed). (A deprecated extension @code{sb-ext:inhibit-warnings} is still
+supported but liable to go away at any time.)
For effects of various optimization qualities on type-safety and
-debuggability see @ref{Declarations as Assertions} and @ref{Debugger
-Policy Control}.
-
-Ordinarily, when the @code{speed} quality is high, the compiler emits
-notes to notify the programmer about its inability to apply various
-optimizations. For selective muffling of these notes @xref{Controlling
-Verbosity}.
-
-The value of @code{space} mostly influences the compiler's decision
-whether to inline operations, which tend to increase the size of
-programs. Use the value @code{0} with caution, since it can cause the
-compiler to inline operations so indiscriminately that the net effect
-is to slow the program by causing cache misses or even swapping.
-
-@c <!-- FIXME: old CMU CL compiler policy, should perhaps be adapted
-@c _ for SBCL. (Unfortunately, the CMU CL docs are out of sync with the
-@c _ CMU CL code, so adapting this requires not only reformatting
-@c _ the documentation, but rooting out code rot.)
-@c _
-@c _<sect2 id="compiler-policy"><title>Compiler Policy</1000
-@c _ INDEX {policy}{compiler}
-@c _ INDEX compiler policy
-@c _
-@c _<para>The policy is what tells the compiler <emphasis>how</emphasis> to
-@c _compile a program. This is logically (and often textually) distinct
-@c _from the program itself. Broad control of policy is provided by the
-@c _<parameter>optimize</parameter> declaration; other declarations and variables
-@c _control more specific aspects of compilation.
-@c _
-@c _\begin{comment}
-@c _* The Optimize Declaration::
-@c _* The Optimize-Interface Declaration::
-@c _\end{comment}
-@c _
-@c _%%\node The Optimize Declaration, The Optimize-Interface Declaration, Compiler Policy, Compiler Policy
-@c _\subsection{The Optimize Declaration}
-@c _\label{optimize-declaration}
-@c _\cindex{optimize declaration}
-@c _\cpsubindex{declarations}{\code{optimize}}
-@c _
-@c _The \code{optimize} declaration recognizes six different
-@c _\var{qualities}. The qualities are conceptually independent aspects
-@c _of program performance. In reality, increasing one quality tends to
-@c _have adverse effects on other qualities. The compiler compares the
-@c _relative values of qualities when it needs to make a trade-off; i.e.,
-@c _if \code{speed} is greater than \code{safety}, then improve speed at
-@c _the cost of safety.
-@c _
-@c _The default for all qualities (except \code{debug}) is \code{1}.
-@c _Whenever qualities are equal, ties are broken according to a broad
-@c _idea of what a good default environment is supposed to be. Generally
-@c _this downplays \code{speed}, \code{compile-speed} and \code{space} in
-@c _favor of \code{safety} and \code{debug}. Novice and casual users
-@c _should stick to the default policy. Advanced users often want to
-@c _improve speed and memory usage at the cost of safety and
-@c _debuggability.
-@c _
-@c _If the value for a quality is \code{0} or \code{3}, then it may have a
-@c _special interpretation. A value of \code{0} means ``totally
-@c _unimportant'', and a \code{3} means ``ultimately important.'' These
-@c _extreme optimization values enable ``heroic'' compilation strategies
-@c _that are not always desirable and sometimes self-defeating.
-@c _Specifying more than one quality as \code{3} is not desirable, since
-@c _it doesn't tell the compiler which quality is most important.
-@c _
-@c _
-@c _These are the optimization qualities:
-@c _\begin{Lentry}
-@c _
-@c _\item[\code{speed}] \cindex{speed optimization quality}How fast the
-@c _ program should is run. \code{speed 3} enables some optimizations
-@c _ that hurt debuggability.
-@c _
-@c _\item[\code{compilation-speed}] \cindex{compilation-speed optimization
-@c _ quality}How fast the compiler should run. Note that increasing
-@c _ this above \code{safety} weakens type checking.
-@c _
-@c _\item[\code{space}] \cindex{space optimization quality}How much space
-@c _ the compiled code should take up. Inline expansion is mostly
-@c _ inhibited when \code{space} is greater than \code{speed}. A value
-@c _ of \code{0} enables indiscriminate inline expansion. Wide use of a
-@c _ \code{0} value is not recommended, as it may waste so much space
-@c _ that run time is slowed. \xlref{inline-expansion} for a discussion
-@c _ of inline expansion.
-@c _
-@c _\item[\code{debug}] \cindex{debug optimization quality}How debuggable
-@c _ the program should be. The quality is treated differently from the
-@c _ other qualities: each value indicates a particular level of debugger
-@c _ information; it is not compared with the other qualities.
-@c _ \xlref{debugger-policy} for more details.
-@c _
-@c _\item[\code{safety}] \cindex{safety optimization quality}How much
-@c _ error checking should be done. If \code{speed}, \code{space} or
-@c _ \code{compilation-speed} is more important than \code{safety}, then
-@c _ type checking is weakened (\pxlref{weakened-type-checks}). If
-@c _ \code{safety} if \code{0}, then no run time error checking is done.
-@c _ In addition to suppressing type checks, \code{0} also suppresses
-@c _ argument count checking, unbound-symbol checking and array bounds
-@c _ checks.
-@c _ ... and checking of tag existence in RETURN-FROM and GO.
-@c _
-@c _\item[\code{extensions:inhibit-warnings}] \cindex{inhibit-warnings
-@c _ optimization quality}This is a CMU extension that determines how
-@c _ little (or how much) diagnostic output should be printed during
-@c _ compilation. This quality is compared to other qualities to
-@c _ determine whether to print style notes and warnings concerning those
-@c _ qualities. If \code{speed} is greater than \code{inhibit-warnings},
-@c _ then notes about how to improve speed will be printed, etc. The
-@c _ default value is \code{1}, so raising the value for any standard
-@c _ quality above its default enables notes for that quality. If
-@c _ \code{inhibit-warnings} is \code{3}, then all notes and most
-@c _ non-serious warnings are inhibited. This is useful with
-@c _ \code{declare} to suppress warnings about unavoidable problems.
-@c _\end{Lentry}
-@c _
-@c _%%\node The Optimize-Interface Declaration, , The Optimize Declaration, Compiler Policy
-@c _\subsection{The Optimize-Interface Declaration}
-@c _\label{optimize-interface-declaration}
-@c _\cindex{optimize-interface declaration}
-@c _\cpsubindex{declarations}{\code{optimize-interface}}
-@c _
-@c _The \code{extensions:optimize-interface} declaration is identical in
-@c _syntax to the \code{optimize} declaration, but it specifies the policy
-@c _used during compilation of code the compiler automatically generates
-@c _to check the number and type of arguments supplied to a function. It
-@c _is useful to specify this policy separately, since even thoroughly
-@c _debugged functions are vulnerable to being passed the wrong arguments.
-@c _The \code{optimize-interface} declaration can specify that arguments
-@c _should be checked even when the general \code{optimize} policy is
-@c _unsafe.
-@c _
-@c _Note that this argument checking is the checking of user-supplied
-@c _arguments to any functions defined within the scope of the
-@c _declaration, \code{not} the checking of arguments to \llisp{}
-@c _primitives that appear in those definitions.
-@c _
-@c _The idea behind this declaration is that it allows the definition of
-@c _functions that appear fully safe to other callers, but that do no
-@c _internal error checking. Of course, it is possible that arguments may
-@c _be invalid in ways other than having incorrect type. Functions
-@c _compiled unsafely must still protect themselves against things like
-@c _user-supplied array indices that are out of bounds and improper lists.
-@c _See also the \kwd{context-declarations} option to
-@c _\macref{with-compilation-unit}.
-@c _
-@c _(end of section on compiler policy)
-@c _-->
-
-@include fun-sb-ext-describe-compiler-policy.texinfo
-@include fun-sb-ext-restrict-compiler-policy.texinfo
-@include macro-common-lisp-with-compilation-unit.texinfo
-
-@node Compiler Errors
-@comment node-name, next, previous, up
+debuggability see @ref{declarations as assertions} and
+@ref{debugger policy control}.
+
+Ordinarily, when the speed quality is high, the compiler emits notes
+to notify the programmer about its inability to apply various
+optimizations. For selective muffling of these notes, see
+@ref{controlling verbosity}.
+
+The value of space mostly influences the compiler's decision whether
+to inline operations, which tend to increase the size of programs.
+Use the value @code{0} with caution, since it can cause the compiler to
+inline operations so indiscriminately that the net effect is to slow
+the program by causing cache misses or even swapping.
+
+@anchor{Function sb-ext describe-compiler-policy}
+@ffindex @sortas{describe-compiler-policy sb-ext} describe-compiler-policy [sb-ext]
+@deffn{Function} sb-ext:describe-compiler-policy &optional spec
+Print all global optimization settings, augmented by @code{spec}.
+@end deffn
+@anchor{Function sb-ext restrict-compiler-policy}
+@ffindex @sortas{restrict-compiler-policy sb-ext} restrict-compiler-policy [sb-ext]
+@deffn{Function} sb-ext:restrict-compiler-policy &optional quality min max
+Assign a minimum value to an optimization quality. @code{quality} is the name of
+the optimization quality to restrict, @code{min} (defaulting to zero) is the
+minimum allowed value, and @code{max} (defaults to 3) is the maximum.
+
+Returns the alist describing the current policy restrictions.
+
+If @code{quality} is @code{nil} or not given, nothing is done.
+
+Otherwise, if @code{min} is zero or @code{max} is 3 or neither are given, any
+existing restrictions of @code{quality} are removed.
+
+See also @code{:policy} option in @code{with-compilation-unit}.
+@end deffn
+@anchor{Macro common-lisp with-compilation-unit}
+@ffindex @sortas{with-compilation-unit common-lisp} with-compilation-unit [common-lisp]
+@deffn{Macro} with-compilation-unit options &body body
+Affects compilations that take place within its dynamic extent. It is
+intended to be eg. wrapped around the compilation of all files in the same system.
+
+Following options are defined:
+
+@itemize
+@item @code{:override} @code{<boolean-form>}
+
+One of the effects of this form is to delay undefined warnings
+until the end of the form, instead of giving them at the end of
+each compilation. If @code{override} is @code{nil} (the default), then the
+outermost @code{with-compilation-unit} form grabs the undefined warnings.
+Specifying @code{:override} true causes that form to grab any enclosed
+warnings, even if it is enclosed by another @code{with-compilation-unit}.
+
+@item @code{:policy} @code{<optimize-declaration-form>}
+
+Provides dynamic scoping for global compiler optimization
+qualities and restrictions, limiting effects of subsequent
+@code{optimize} proclamations and calls to
+@code{sb-ext:restrict-compiler-policy} to the dynamic scope of @code{body}.
+
+If @code{:override} is false, the specified @code{:policy} is merged with
+current global policy. If @code{:override} is true, current global
+policy, including any restrictions, is discarded in favor of the
+specified
+@code{:policy}.
+
+Supplying @code{:policy} @code{nil} is equivalent to the option not being
+supplied at all, i.e. dynamic scoping of policy does not take
+place.
+
+This option is an SBCL-specific experimental extension: Interface
+subject to change.
+
+@item @code{:source-namestring} @code{<namestring-form>}
+
+Attaches the value returned by the @code{<namestring-form>} to the
+internal debug-source information as the namestring of the source
+file. Normally the namestring of the input-file for @code{compile-file}
+is used: this option can be used to provide source-file
+information for functions compiled using @code{compile}, or to override
+the input-file of @code{compile-file}.
+
+If both an outer and an inner @code{with-compilation-unit} provide a
+@code{:source-namestring}, the inner one takes precedence. Unaffected by
+@code{:override}.
+
+This is an SBCL-specific extension.
+
+@item @code{:source-plist} @code{<plist-form>}
+
+Attaches the value returned by the @code{<plist-form>} to internal
+debug-source information of functions compiled in within the
+dynamic extent of @code{body}.
+
+Primarily for use by development environments, in order to eg.
+associate function definitions with editor-buffers. Can be
+accessed using @code{sb-introspect:definition-source-plist}.
+
+If an outer @code{with-compilation-unit} form also provide a
+@code{source-plist}, it is appended to the end of the provided
+@code{source-plist}. Unaffected by @code{:override}.
+
+This is an SBCL-specific extension.
+@end itemize
+
+Examples:
+
+@example
+;; Prevent proclamations from the file leaking, and restrict
+;; SAFETY to 3 -- otherwise uses the current global policy.
+(with-compilation-unit (:policy '(optimize))
+ (restrict-compiler-policy 'safety 3)
+ (load "foo.lisp"))
+@end example
+
+@example
+;; Using default policy instead of the current global one,
+;; except for DEBUG 3.
+(with-compilation-unit (:policy '(optimize debug)
+ :override t)
+ (load "foo.lisp"))
+@end example
+
+@example
+;; Same as if :POLICY had not been specified at all: SAFETY 3
+;; proclamation leaks out from WITH-COMPILATION-UNIT.
+(with-compilation-unit (:policy nil)
+ (declaim (optimize safety))
+ (load "foo.lisp"))
+@end example
+@end deffn
+@node compiler errors
@section Compiler Errors
@menu
-* Type Errors at Compile Time::
-* Errors During Macroexpansion::
-* Read Errors::
+* Type Errors at Compile Time: type errors at compile time.
+* Errors During Macroexpansion: errors during macroexpansion.
+* Read Errors: read errors.
@end menu
-@node Type Errors at Compile Time
-@comment node-name, next, previous, up
+@node type errors at compile time
@subsection Type Errors at Compile Time
-@cindex Compile time type errors
-@cindex Type checking, at compile time
If the compiler can prove at compile time that some portion of the
program cannot be executed without a type error, then it will give a
@@ -915,7 +801,7 @@ incorrect program.
For example, consider this code fragment:
-@lisp
+@example
(defun raz (foo)
(let ((x (case foo
(:this 13)
@@ -923,7 +809,7 @@ For example, consider this code fragment:
(:the-other 42))))
(declare (fixnum x))
(foo x)))
-@end lisp
+@end example
Compilation produces this warning:
@@ -939,11 +825,10 @@ Compilation produces this warning:
; NIL
@end example
-In this case, the warning means that if @code{foo} isn't any of
-@code{:this}, @code{:that} or @code{:the-other}, then @code{x} will be
-initialized to @code{nil}, which the @code{fixnum} declaration makes
-illegal. The warning will go away if @code{ecase} is used instead of
-@code{case}, or if @code{:the-other} is changed to @code{t}.
+In this case, the warning means that if @code{foo} isn't any of @code{:this},
+@code{:that} or @code{:the-other}, then @code{x} will be initialized to @code{nil}, which
+the @code{fixnum} declaration makes illegal. The warning will go away if
+@code{ecase} is used instead of @code{case}, or if @code{:the-other} is changed to @code{t}.
This sort of spurious type warning happens moderately often in the
expansion of complex macros and in inline functions. In such cases,
@@ -952,22 +837,20 @@ compiler can't always prove this code is dead (could never be
executed), so it compiles the erroneous code (which will always signal
an error if it is executed) and gives a warning.
-@node Errors During Macroexpansion
-@comment node-name, next, previous, up
+@node errors during macroexpansion
@subsection Errors During Macroexpansion
-@cindex Macroexpansion, errors during
The compiler handles errors that happen during macroexpansion, turning
-them into compiler errors. If you want to debug the error (to debug a
-macro), you can set @code{*break-on-signals*} to @code{error}. For
-example, this definition:
+them into compiler errors. If you want to debug the error (to debug
+a macro), you can set @code{*break-on-signals*} to @code{error}. For example, this
+definition:
-@lisp
+@example
(defun foo (e l)
(do ((current l (cdr current))
((atom current) nil))
(when (eq (car current) e) (return current))))
-@end lisp
+@end example
gives this error:
@@ -983,22 +866,15 @@ gives this error:
; DO step variable is not a symbol: (ATOM CURRENT)
@end example
-
-@node Read Errors
-@comment node-name, next, previous, up
+@node read errors
@subsection Read Errors
-@cindex Read errors, compiler
SBCL's compiler does not attempt to recover from read errors when
reading a source file, but instead just reports the offending
character position and gives up on the entire source file.
-@node Open Coding and Inline Expansion
-@comment node-name, next, previous, up
+@node open coding and inline expansion
@section Open Coding and Inline Expansion
-@cindex Open-coding
-@cindex Inline expansion
-@cindex Static functions
Since Common Lisp forbids the redefinition of standard functions, the
compiler can have special knowledge of these standard functions
@@ -1007,89 +883,85 @@ coding, inline expansion, source transformation), but the implications
to the user are basically the same:
@itemize
+@item Attempts to redefine standard functions may be frustrated, since
+ the function may never be called. Although it is technically
+ illegal to redefine standard functions, users sometimes want to
+ implicitly redefine these functions when they are debugging using
+ the @code{trace} macro. Special-casing of standard functions can be
+ inhibited using the @code{notinline} declaration, but even then some
+ phases of analysis such as type inferencing are applied by the
+ compiler.
-@item
-Attempts to redefine standard functions may be frustrated, since the
-function may never be called. Although it is technically illegal to
-redefine standard functions, users sometimes want to implicitly
-redefine these functions when they are debugging using the
-@code{trace} macro. Special-casing of standard functions can be
-inhibited using the @code{notinline} declaration, but even then some
-phases of analysis such as type inferencing are applied by the
-compiler.
-
-@item
-The compiler can have multiple alternate implementations of standard
-functions that implement different trade-offs of speed, space and
-safety. This selection is based on the compiler policy, @ref{Compiler
-Policy}.
-
+@item The compiler can have multiple alternate implementations of
+ standard functions that implement different trade-offs of speed,
+ space and safety. This selection is based on the @ref{compiler policy}.
@end itemize
When a function call is @emph{open coded}, inline code whose effect is
equivalent to the function call is substituted for that function
-call. When a function call is @emph{closed coded}, it is usually left
-as is, although it might be turned into a call to a different function
-with different arguments. As an example, if @code{nthcdr} were to be
-open coded, then
+call. When a function call is @emph{closed coded}, it is usually left as
+is, although it might be turned into a call to a different function
+with different arguments. As an example, if @code{nthcdr} were to be open
+coded, then
-@lisp
+@example
(nthcdr 4 foobar)
-@end lisp
+@end example
might turn into
-@lisp
+@example
(cdr (cdr (cdr (cdr foobar))))
-@end lisp
+@end example
or even
-@lisp
+@example
(do ((i 0 (1+ i))
(list foobar (cdr foobar)))
((= i 4) list))
-@end lisp
+@end example
If @code{nth} is closed coded, then
-@lisp
+@example
(nth x l)
-@end lisp
+@end example
might stay the same, or turn into something like
-@lisp
+@example
(car (nthcdr x l))
-@end lisp
+@end example
In general, open coding sacrifices space for speed, but some functions
-(such as @code{car}) are so simple that they are always
-open-coded. Even when not open-coded, a call to a standard function
-may be transformed into a different function call (as in the last
-example) or compiled as @emph{static call}. Static function call uses
-a more efficient calling convention that forbids redefinition.
+(such as @code{car}) are so simple that they are always open-coded. Even
+when not open-coded, a call to a standard function may be
+transformed into a different function call (as in the last example)
+or compiled as @emph{static call}. Static function call uses a more
+efficient calling convention that forbids redefinition.
-@node Interpreter
-@comment node-name, next, previous, up
+@node interpreter
@section Interpreter
-@cindex Interpreter
-@findex @cl{eval}
-@vindex @sbext{@earmuffs{evaluator-mode}}
By default SBCL implements @code{eval} by calling the native code
compiler.
-SBCL also includes an interpreter for use in special cases where using
-the compiler is undesirable, for example due to compilation overhead.
-Unlike in some other Lisp implementations, in SBCL interpreted code is
-not safer or more debuggable than compiled code.
+SBCL also includes an interpreter for use in special cases where
+using the compiler is undesirable, for example due to compilation
+overhead. Unlike in some other Lisp implementations, in SBCL
+interpreted code is not safer or more debuggable than compiled code.
-@include var-sb-ext-star-evaluator-mode-star.texinfo
-
-@node Advanced Compiler Use and Efficiency Hints
-@comment node-name, next, previous, up
+@anchor{Variable sb-ext *evaluator-mode*}
+@vvindex @sortas{evaluator-mode* sb-ext} *evaluator-mode* [sb-ext]
+@deffn{Variable} sb-ext:*evaluator-mode*
+Toggle between different evaluator implementations. If set to @code{:compile},
+an implementation of @code{eval} that calls the compiler will be used. If set
+to @code{:interpret}, an interpreter will be used.
+@end deffn
+@node advanced compiler use and efficiency hints
@section Advanced Compiler Use and Efficiency Hints
+
For more advanced usages of the compiler, please see the chapter of the
same name in the CMUCL manual. Many aspects of the compiler have stayed
exactly the same, and there is a much more detailed explanation of the
@@ -1099,6 +971,7 @@ compilation, it does support CMUCL's block compilation facility allowing
whole program optimization and increased use of the local call
convention.
-Unlike CMUCL, SBCL is able to open-code forward-referenced type tests
-while block compiling. This helps for mutually referential
+Unlike CMUCL, SBCL is able to open-code forward-referenced type
+tests while block compiling. This helps for mutually referential
@code{defstruct}s in particular.
+
diff --git a/doc/manual/contrib-modules.texinfo b/doc/manual/contrib-modules.texinfo
index f5f06e085..5a6238c6e 100644
--- a/doc/manual/contrib-modules.texinfo
+++ b/doc/manual/contrib-modules.texinfo
@@ -1,52 +1,297 @@
-@node Contributed Modules
-@comment node-name, next, previous, up
+@c Generated by the sb-manual contrib. Do not edit.
+
+@node contributed modules
@chapter Contributed Modules
+@menu
+* sb-aclrepl: sb aclrepl.
+* sb-concurrency: sb concurrency.
+* sb-cover: sb cover.
+* sb-grovel: sb grovel.
+* sb-introspect: sb introspect.
+* sb-manual: sb manual.
+* sb-md5: sb md5.
+* sb-posix: sb posix.
+* sb-queue: sb queue.
+* sb-rotate-byte: sb rotate byte.
+* sb-simd: sb simd.
+@end menu
+
SBCL comes with a number of modules that are not part of the core
-system. These are loaded via @code{(require :@var{modulename})}
-(@pxref{Customization Hooks for Users}). This section contains
+system. These are loaded via @code{(require :<modulename>)}
+(see @ref{customization hooks for users}). This section contains
documentation (or pointers to documentation) for some of the
contributed modules.
+@include ../../contrib/sb-aclrepl/sb-aclrepl.texinfo
+@include ../../contrib/sb-concurrency/sb-concurrency.texinfo
+@include ../../contrib/sb-cover/sb-cover.texinfo
+@include ../../contrib/sb-grovel/sb-grovel.texinfo
+@include ../../contrib/sb-introspect/sb-introspect.texinfo
+@include ../../contrib/sb-manual/sb-manual.texinfo
+@include ../../contrib/sb-md5/sb-md5.texinfo
+@include ../../contrib/sb-posix/sb-posix.texinfo
+@include ../../contrib/sb-queue/sb-queue.texinfo
+@include ../../contrib/sb-rotate-byte/sb-rotate-byte.texinfo
+@node sb simd
+@section sb-simd
+
@menu
-* sb-aclrepl::
-* sb-concurrency::
-* sb-cover::
-* sb-grovel::
-* sb-introspect::
-* sb-md5::
-* sb-posix::
-* sb-queue::
-* sb-rotate-byte::
-* sb-simd::
+* Data Types: data types.
+* Casts: casts.
+* Constructors: constructors.
+* Unpackers: unpackers.
+* Reinterpret Casts: reinterpret casts.
+* Associatives: associatives.
+* Reducers: reducers.
+* Rounding: rounding.
+* Comparisons: comparisons.
+* Conditionals: conditionals.
+* Loads and Stores: loads and stores.
+* Specialized Scalar Operations: specialized scalar operations.
+* Instruction Set Dispatch: instruction set dispatch.
@end menu
-@page
-@include sb-aclrepl/sb-aclrepl.texinfo
+The @code{sb-simd} module provides a convenient interface for SIMD
+programming in SBCL. It provides one package per SIMD instruction
+set, plus functions and macros for querying whether an instruction
+set is available and what functions and data types it exports.
-@page
-@include sb-concurrency/sb-concurrency.texinfo
+@node data types
+@subsection Data Types
-@page
-@include sb-cover/sb-cover.texinfo
+The central data type in sb-simd is the SIMD pack. A SIMD pack
+is very similar to a specialized vector, except that its length must
+be a particular power of two that depends on its element type and
+the underlying hardware. The set of element types that are supported
+for SIMD packs is similar to that of SBCL's specialized array
+element types, except that there is currently no support for SIMD
+packs of complex numbers or characters.
-@page
-@include sb-grovel/sb-grovel.texinfo
+The supported scalar types are @code{f32}, @code{f64}, @code{s<n>}, and @code{u<n>},
+where @code{<n>} is either 8, 16, 32, or 64. These scalar types are
+abbreviations for the Common Lisp types @code{single-float}, @code{double-float},
+@code{signed-byte}, and @code{unsigned-byte}, respectively. For each scalar data
+type @code{x}, there exists one or more SIMD data type @code{x.y} with @code{y}
+elements. For example, in AVX there are two supported SIMD data
+types with element type @code{f64}, namely @code{f64.2} (128 bit) and
+@code{f64.4} (256 bit).
-@page
-@include sb-introspect/sb-introspect.texinfo
+SIMD packs are regular Common Lisp objects that have a type, a
+class, and can be passed as function arguments. The price for this
+is that SIMD packs have both a boxed and an unboxed representation.
+The unboxed representation of a SIMD pack has zero overhead and fits
+into a CPU register but can only be used within a function and when
+the compiler can statically determine the SIMD pack's type.
+Otherwise, the SIMD pack is boxed, i.e. spilled to the heap together
+with its type information. In practice, boxing of SIMD packs can
+usually be avoided via inlining, or by loading and storing them to
+specialized arrays instead of passing them around as function
+arguments.
-@page
-@include sb-md5/sb-md5.texinfo
+@node casts
+@subsection Casts
-@page
-@include sb-posix/sb-posix.texinfo
+For each scalar data type @code{x}, there is a function named @code{x}
+that is equivalent to @code{(lambda (v) (coerce v 'x))}. For each SIMD
+data type @code{x.y}, there is a function named @code{x.y} that ensures that
+its argument is of type @code{x.y}, or, if the argument is a number,
+calls the cast function of @code{x} and broadcasts the result.
-@page
-@include sb-queue/sb-queue.texinfo
+All functions provided by sb-simd (apart from the casts themselves)
+implicitly cast each argument to its expected type. So, to add the
+number five to each single float in a SIMD pack @code{x} of type @code{f32.8},
+it is sufficient to write @code{(f32.8+ x 5)}. We don't mention this
+implicit conversion explicitly in the following sections, so if any
+function description states that an argument must be of type @code{x.y},
+the argument can actually be of any type that is a suitable argument
+of the cast function named @code{x.y}.
-@page
-@include sb-rotate-byte/sb-rotate-byte.texinfo
+@node constructors
+@subsection Constructors
+
+For each SIMD data type @code{x.y}, there is a constructor named
+@code{make-x.y} that takes @code{y} arguments of type @code{x} and returns a SIMD
+pack whose elements are the supplied values.
+
+@node unpackers
+@subsection Unpackers
+
+For each SIMD data type @code{x.y}, there is a function named
+@code{x.y-values} that returns, as @code{y} multiple values, the elements of
+the supplied SIMD pack of type @code{x.y}.
+
+@node reinterpret casts
+@subsection Reinterpret Casts
+
+For each SIMD data type @code{x.y}, there is a function named
+@code{x.y!} that takes any SIMD pack or scalar datum and interprets its
+bits as a SIMD pack of type @code{x.y}. If the supplied datum has more
+bits than the resulting value, the excess bits are discarded. If the
+supplied datum has less bits than the resulting value, the missing
+bits are assumed to be zero.
+
+@node associatives
+@subsection Associatives
+
+For each associative binary function, e.g. @code{two-arg-x.y-op}, there
+is a function @code{x.y-op} that takes any number of arguments and
+combines them with this binary function in a tree-like fashion. If
+the binary function has an identity element, it is possible to call
+the function with zero arguments, in which case the identity element
+is returned. If there is no identity element, the function must
+receive at least one argument.
+
+Examples of associative functions are @code{sb-simd-avx:f32.8+}, for
+summing any number of 256 bit packs of single floats, and
+@code{sb-simd-fma:u8.32-max}, for computing the element-wise maximum of
+one or more 256 bit packs of 8 bit integers.
+
+@node reducers
+@subsection Reducers
+
+For binary functions @code{two-arg-x.y-op} that are not associative but
+have a neutral element, there are functions @code{x.y-op} that take any
+positive number of arguments and return the reduction of all
+arguments with the binary function. In the special case of a single
+supplied argument, the binary function is invoked on the neutral
+element and that argument. Reducers have been introduced to generate
+Lisp-style subtraction and division functions.
+
+Examples of reducers are @code{sb-simd-avx:f32.8/}, for successively
+dividing a pack of 32 bit single floats by all further supplied
+packs of 32 bit single floats, or @code{sb-simd-fma:u32.8-} for
+subtracting any number of supplied packs of 32 bit unsigned integers
+from the first supplied one, except in the case of a single
+argument, where @code{sb-simd-fma:u32.8-} simply negates all values in
+the pack.
+
+@node rounding
+@subsection Rounding
+
+For each floating-point SIMD data type @code{x.y}, there are several
+functions that round the values of a supplied SIMD pack to nearby
+floating-point values whose fractional digits are all zero. Those
+functions are @code{x.y-round}, @code{x.y-floor}, @code{x.y-ceiling}, and
+@code{x.y-truncate}, and they have the same semantics as the one argument
+versions of @code{cl:round}, @code{cl:floor}, @code{cl:ceiling}, and @code{cl:truncate},
+respectively.
+
+@node comparisons
+@subsection Comparisons
+
+For each SIMD data type @code{x.y}, there exist conversion functions
+@code{x.y<}, @code{x.y<=}, @code{x.y>}, @code{x.y>=}, and @code{x.y=} that check whether the
+supplied arguments are strictly monotonically increasing,
+monotonically increasing, strictly monotonically decreasing,
+monotonically decreasing, equal, or nowhere equal, respectively. In
+contrast to the Common Lisp functions @code{<}, @code{<=}, @code{>}, @code{>=}, @code{=}, and
+@code{/=}, the SIMD comparison functions don't return a generalized
+boolean but a SIMD pack of unsigned integers with @code{y} elements.
+The bits of each unsigned integer are either all one, if the values
+of the arguments at that position satisfy the test, or all zero, if
+they don't. We call a SIMD packs of such unsigned integers a mask.
+
+@node conditionals
+@subsection Conditionals
+
+The SIMD paradigm is inherently incompatible with fine-grained control
+flow. A piece of code containing an @code{if} special form cannot be
+vectorized in a straightforward way, because doing so would require
+as many instruction pointers and processor states as there are
+values in the desired SIMD data type. Instead, most SIMD instruction
+sets provide an operator for selecting values from one of two
+supplied SIMD packs based on a mask. The mask is a SIMD pack with as
+many elements as the other two arguments, but whose elements are
+unsigned integers whose bits must be either all zeros or all ones.
+This selection mechanism can be used to emulate the effect of an @code{if}
+special form, at the price that both operands have to be computed
+each time.
+
+In sb-simd, all conditional operations and comparisons emit suitable
+mask fields, and there is a @code{x.y-if} function for each SIMD data
+type with element type @code{x} and number of elements @code{y} whose first
+arguments must be a suitable mask, whose second and third argument
+must be objects that can be converted to the SIMD data type @code{x.y},
+and that returns a value of type @code{x.y} where each element is from
+the second operand if the corresponding mask bits are set, and from
+the third operand if the corresponding mask bits are not set.
+
+@node loads and stores
+@subsection Loads and Stores
+
+In practice, a SIMD pack @code{x.y} is usually not constructed by
+calling its constructor but by loading @code{y} consecutive elements from
+a specialized array with element type @code{x}. The functions for doing
+so are called @code{x.y-aref} and @code{x.y-row-major-aref}, and have similar
+semantics as Common Lisp's @code{aref} and @code{row-major-aref}. In addition to
+that, some instruction sets provide the functions
+@code{x.y-non-temporal-aref} and @code{x.y-non-temporal-row-major-aref}, for
+accessing a memory location without loading the referenced values
+into the CPU's cache.
+
+For each function @code{x.y-foo} for loading SIMD packs from an array,
+there also exists a corresponding function @code{(setf x.y-foo)} for
+storing a SIMD pack in the specified memory location. An exception
+to this rule is that some instruction sets (e.g., SSE) only provide
+functions for non-temporal stores but not for the corresponding
+non-temporal loads.
+
+One difficulty when treating the data of a Common Lisp array as a
+SIMD pack is that some hardware instructions require a particular
+alignment of the address being referenced. Luckily, most
+architectures provide instructions for unaligned loads and stores
+that are, at least on modern CPUs, not slower than their aligned
+equivalents. So by default we translate all array references as
+unaligned loads and stores. An exception are the instructions for
+non-temporal loads and stores, that always require a certain
+alignment. We do not handle this case specially, so without special
+handling by the user, non-temporal loads and stores will only work
+on certain array indices that depend on the actual placement of that
+array in memory.
+
+@node specialized scalar operations
+@subsection Specialized Scalar Operations
+
+Finally, for each SIMD function @code{x.y-op} that applies a certain
+operation @code{op} element-wise to the @code{y} elements of type @code{x}, there
+exists also a functions @code{x-op} for applying that operation only to a
+single element. For example, the SIMD function @code{f64.4+} has a
+corresponding function @code{f64+} that differs from @code{cl:+} in that it
+only accepts arguments of type double float, and that it adds its
+supplied arguments in a fixed order that is the same as the one used
+by @code{f64.4}.
+
+There are good reasons for exporting scalar functions from a SIMD
+library, too. The most obvious one is that they obey the same naming
+convention and hence make it easier to locate the correct functions.
+Another benefit is that the semantics of each scalar operation is
+precisely the same as that of the corresponding SIMD function, so
+they can be used to write reference implementations for testing. A
+final reason is that these scalar functions can be used to simplify
+the life of tools for automatic vectorization.
+
+@node instruction set dispatch
+@subsection Instruction Set Dispatch
+
+One challenge that is unique to image-based programming systems such as
+Lisp is that a program can run on one machine, be dumped as an image,
+and then resumed on another machine. While nobody expects this feature
+to work across machines with different architectures, it is quite likely
+that the machine where the image is dumped and the one where execution
+is resumed provide different instruction set extensions.
+
+As a practical example, consider a game developer that develops software
+on an x86-64 machine with all SIMD extensions up to AVX2, but then dumps
+it as an image and ships it to a customer whose machine only supports
+SIMD extensions up to SSE2. Ideally, the image should contain multiple
+optimized versions of all crucial functions, and dynamically select the
+most appropriate version based on the instruction set extensions that
+are actually available.
+
+This kind of run time instruction set dispatch is explicitly
+supported by means of the SB-SIMD-INTERNALS:INSTRUCTION-SET-CASE
+macro. The code resulting from an invocation of this macro compiles
+to an efficient jump table whose index is recomputed on each startup
+of the Lisp image.
-@page
-@include sb-simd/sb-simd.texinfo
diff --git a/doc/manual/debugger.texinfo b/doc/manual/debugger.texinfo
index a1658acd9..12503e683 100644
--- a/doc/manual/debugger.texinfo
+++ b/doc/manual/debugger.texinfo
@@ -1,38 +1,36 @@
-@node Debugger
-@comment node-name, next, previous, up
+@c Generated by the sb-manual contrib. Do not edit.
+
+@node debugger
@chapter Debugger
-@cindex Debugger
+
+@menu
+* Debugger Entry: debugger entry.
+* Debugger Command Loop: debugger command loop.
+* Stack Frames: stack frames.
+* Variable Access: variable access.
+* Source Location Printing: source location printing.
+* Debugger Policy Control: debugger policy control.
+* Exiting Commands: exiting commands.
+* Information Commands: information commands.
+* Breakpoint Commands: breakpoint commands.
+* Function Tracing: function tracing.
+* Single Stepping: single stepping.
+* Enabling and Disabling the Debugger: enabling and disabling the debugger.
+@end menu
This chapter documents the debugging facilities of SBCL, including
-the debugger, single-stepper and @code{trace}, and the effect of
-@code{(optimize debug)} declarations.
+the debugger, single-stepper and @code{trace}, and the effect of @code{(optimize
+debug)} declarations.
-@menu
-* Debugger Entry::
-* Debugger Command Loop::
-* Stack Frames::
-* Variable Access::
-* Source Location Printing::
-* Debugger Policy Control::
-* Exiting Commands::
-* Information Commands::
-* Breakpoint Commands::
-* Function Tracing::
-* Single Stepping::
-* Enabling and Disabling the Debugger::
-@end menu
-
-@node Debugger Entry
-@comment node-name, next, previous, up
+@node debugger entry
@section Debugger Entry
@menu
-* Debugger Banner::
-* Debugger Invocation::
+* Debugger Banner: debugger banner.
+* Debugger Invocation: debugger invocation.
@end menu
-@node Debugger Banner
-@comment node-name, next, previous, up
+@node debugger banner
@subsection Debugger Banner
When you enter the debugger, it looks something like this:
@@ -51,66 +49,70 @@ restarts (invokable by number or by possibly-abbreviated name):
@end example
The first group of lines describe what the error was that put us in
-the debugger. In this case @code{car} was called on @code{3}, causing
-a @code{type-error}.
+the debugger. In this case @code{car} was called on @code{3}, causing a
+@code{type-error}.
-This is followed by the ``beginner help line'', which appears only if
-@code{sb-debug:*debug-beginner-help-p*} is true (default).
+This is followed by the "beginner help line", which appears only
+if @code{sb-debug:*debug-beginner-help-p*} is true (default).
Next comes a listing of the active restart names, along with their
-descriptions -- the ways we can restart execution after this error. In
-this case, both options return to top-level. Restarts can be selected
-by entering the corresponding number or name.
+descriptions -- the ways we can restart execution after this error.
+In this case, both options return to top-level. Restarts can be
+selected by entering the corresponding number or name.
The current frame appears right underneath the restarts, immediately
followed by the debugger prompt.
-@node Debugger Invocation
-@comment node-name, next, previous, up
+@node debugger invocation
@subsection Debugger Invocation
The debugger is invoked when:
@itemize
+@item @code{error} is called, and the condition it signals is not handled.
-@item
-@code{error} is called, and the condition it signals is not handled.
-
-@item
-@code{break} is called, or @code{signal} is called with a condition
-that matches the current @code{*break-on-signals*}.
-
-@item
-the debugger is explicitly entered with the @code{invoke-debugger}
-function.
+@item @code{break} is called, or @code{signal} is called with a condition that matches
+ the current @code{*break-on-signals*}.
+@item The debugger is explicitly entered with the @code{invoke-debugger}
+ function.
@end itemize
When the debugger is invoked by a condition, ANSI mandates that the
-value of @code{*debugger-hook*}, if any, be called with two arguments:
-the condition that caused the debugger to be invoked and the previous
-value of @code{*debugger-hook*}. When this happens,
-@code{*debugger-hook*} is bound to NIL to prevent recursive errors.
-However, ANSI also mandates that @code{*debugger-hook*} not be invoked
-when the debugger is to be entered by the @code{break} function. For
-users who wish to provide an alternate debugger interface (and thus
-catch @code{break} entries into the debugger), SBCL provides
-@code{sb-ext:*invoke-debugger-hook*}, which is invoked during any
-entry into the debugger.
+value of @code{*debugger-hook*}, if any, be called with two arguments: the
+condition that caused the debugger to be invoked and the previous
+value of @code{*debugger-hook*}. When this happens, @code{*debugger-hook*} is
+bound to @code{nil} to prevent recursive errors. However, ANSI also
+mandates that @code{*debugger-hook*} not be invoked when the debugger is to
+be entered by the @code{break} function. For users who wish to provide an
+alternate debugger interface (and thus catch @code{break} entries into the
+debugger), SBCL provides @code{sb-ext:*invoke-debugger-hook*}, which is
+invoked during any entry into the debugger.
-@include var-sb-ext-star-invoke-debugger-hook-star.texinfo
+@anchor{Variable sb-ext *invoke-debugger-hook*}
+@vvindex @sortas{invoke-debugger-hook* sb-ext} *invoke-debugger-hook* [sb-ext]
+@deffn{Variable} sb-ext:*invoke-debugger-hook*
+This is either @code{nil} or a designator for a function of two arguments,
+to be run when the debugger is about to be entered. The function is
+run with @code{*invoke-debugger-hook*} bound to @code{nil} to minimize
+recursive errors, and receives as arguments the condition that
+triggered debugger entry and the previous value of
+@code{*invoke-debugger-hook*}.
-@node Debugger Command Loop
-@comment node-name, next, previous, up
+This mechanism is an SBCL extension similar to the standard @code{*debugger-hook*}.
+In contrast to @code{*debugger-hook*}, it is observed by @code{invoke-debugger} even when
+called by @code{break}.
+@end deffn
+@node debugger command loop
@section Debugger Command Loop
The debugger is an interactive read-eval-print loop much like the
normal top level, but some symbols are interpreted as debugger
commands instead of being evaluated. A debugger command starts with
-the symbol name of the command, possibly followed by some arguments on
-the same line. Some commands prompt for additional input. Debugger
-commands can be abbreviated by any unambiguous prefix: @command{help}
-can be typed as @samp{h}, @samp{he}, etc.
+the symbol name of the command, possibly followed by some arguments
+on the same line. Some commands prompt for additional input.
+Debugger commands can be abbreviated by any unambiguous prefix:
+@code{help} can be typed as @code{h}, @code{he}, etc.
The package is not significant in debugger commands; any symbol with
the name of a debugger command will work. If you want to show the
@@ -118,94 +120,91 @@ value of a variable that happens also to be the name of a debugger
command you can wrap the variable in a @code{progn} to hide it from
the command loop.
-The debugger prompt is ``@code{@var{frame}]}'', where @var{frame} is
-the number of the current frame. Frames are numbered starting from
-zero at the top (most recent call), increasing down to the bottom.
-The current frame is the frame that commands refer to.
+The debugger prompt is @code{<frame>]}, where @code{<frame>} is the number of
+the current frame. Frames are numbered starting from zero at the
+top (most recent call), increasing down to the bottom. The current
+frame is the frame that commands refer to.
It is possible to override the normal printing behaviour in the
debugger by using the @code{sb-ext:*debug-print-variable-alist*}.
-@include var-sb-ext-star-debug-print-variable-alist-star.texinfo
+@anchor{Variable sb-ext *debug-print-variable-alist*}
+@vvindex @sortas{debug-print-variable-alist* sb-ext} *debug-print-variable-alist* [sb-ext]
+@deffn{Variable} sb-ext:*debug-print-variable-alist*
+an association list describing new bindings for special variables
+to be used within the debugger. Eg.
-@node Stack Frames
-@comment node-name, next, previous, up
+ ((@code{*print-length*} . 10) (@code{*print-level*} . 6) (@code{*print-pretty*} . @code{nil}))
+
+The variables in the @code{car} positions are bound to the values in the @code{cdr}
+during the execution of some debug commands. When evaluating arbitrary
+expressions in the debugger, the normal values of the printer control
+variables are in effect.
+
+Initially empty, @code{*debug-print-variable-alist*} is typically used to
+provide bindings for printer control variables.
+@end deffn
+@node stack frames
@section Stack Frames
-@cindex Stack frames
-
-A @dfn{stack frame} is the run-time representation of a call to a
-function; the frame stores the state that a function needs to remember
-what it is doing. Frames have:
-
-@itemize
-
-@item
-@dfn{variables} (@pxref{Variable Access}), which are the values being operated
-on.
-
-@item
-@dfn{arguments} to the call (which are really just particularly
-interesting variables).
-
-@item
-a current source location (@pxref{Source Location Printing}), which is
-the place in the program where the function was running when it
-stopped to call another function, or because of an interrupt or error.
-
-@end itemize
@menu
-* Stack Motion::
-* How Arguments are Printed::
-* Function Names::
-* Debug Tail Recursion::
-* Unknown Locations and Interrupts::
+* Stack Motion: stack motion.
+* How Arguments are Printed: how arguments are printed.
+* Function Names: function names.
+* Debug Tail Recursion: debug tail recursion.
+* Unknown Locations and Interrupts: unknown locations and interrupts.
@end menu
-@node Stack Motion
-@comment node-name, next, previous, up
+A @emph{stack frame} is the run-time representation of a call to a
+function; the frame stores the state that a function needs to
+remember what it is doing. Frames have:
+
+@itemize
+@item @emph{Variables} (see @ref{variable access}), which are the values being
+ operated on.
+
+@item @emph{Arguments} to the call (which are really just particularly
+ interesting variables).
+
+@item A current source location (@ref{source location printing}), which is
+ the place in the program where the function was running when it
+ stopped to call another function, or because of an interrupt or
+ error.
+@end itemize
+
+@node stack motion
@subsection Stack Motion
These commands move to a new stack frame and print the name of the
function and the values of its arguments in the style of a Lisp
function call:
-@deffn {Debugger Command} @nopkg{up}
-Move up to the next higher frame. More recent function calls are
-considered to be higher on the stack.
-@end deffn
+@itemize
+@item @code{up}: Move up to the next higher frame. More recent function calls
+ are considered to be higher on the stack.
-@deffn {Debugger Command} @nopkg{down}
-Move down to the next lower frame.
-@end deffn
+@item @code{down}: Move down to the next lower frame.
-@deffn {Debugger Command} @nopkg{top}
-Move to the highest frame, that is, the frame where the debugger was
-entered.
-@end deffn
+@item @code{top}: Move to the highest frame, that is, the frame where the
+ debugger was entered.
-@deffn {Debugger Command} @nopkg{bottom}
-Move to the lowest frame.
-@end deffn
+@item @code{bottom}: Move to the lowest frame.
-@deffn {Debugger Command} @nopkg{frame} [@var{n}]
-Move to the frame with the specified number. Prompts for the number if not
-supplied. The frame with number 0 is the frame where the debugger
-was entered.
-@end deffn
+@item @code{frame [<n>]}: Move to the frame with the specified number.
+ Prompts for the number if not supplied. The frame with number 0 is
+ the frame where the debugger was entered.
+@end itemize
-
-@node How Arguments are Printed
-@comment node-name, next, previous, up
+@node how arguments are printed
@subsection How Arguments are Printed
A frame is printed to look like a function call, but with the actual
argument values in the argument positions. So the frame for this call
in the source:
-@lisp
+@example
(myfun (+ 3 4) 'a)
-@end lisp
+@end example
would look like this:
@@ -217,9 +216,9 @@ All keyword and optional arguments are displayed with their actual
values; if the corresponding argument was not supplied, the value will
be the default. So this call:
-@lisp
+@example
(subseq "foo" 1)
-@end lisp
+@end example
would look like this:
@@ -229,9 +228,9 @@ would look like this:
And this call:
-@lisp
+@example
(string-upcase "test case")
-@end lisp
+@end example
would look like this:
@@ -240,17 +239,17 @@ would look like this:
@end example
The arguments to a function call are displayed by accessing the
-argument variables. Although those variables are initialized to the
+argument variables. Although those variables are initialized to the
actual argument values, they can be set inside the function; in this
case the new value will be displayed.
-@code{&rest} arguments are handled somewhat differently. The value of
-the rest argument variable is displayed as the spread-out arguments to
+@code{&rest} arguments are handled somewhat differently. The value of the
+rest argument variable is displayed as the spread-out arguments to
the call, so:
-@lisp
+@example
(format t "~A is a ~A." "This" 'test)
-@end lisp
+@end example
would look like this:
@@ -259,70 +258,55 @@ would look like this:
@end example
Rest arguments cause an exception to the normal display of keyword
-arguments in functions that have both @code{&rest} and @code{&key}
-arguments. In this case, the keyword argument variables are not
-displayed at all; the rest arg is displayed instead. So for these
-functions, only the keywords actually supplied will be shown, and the
-values displayed will be the argument values, not values of the
+arguments in functions that have both @code{&rest} and @code{&key} arguments. In
+this case, the keyword argument variables are not displayed at all;
+the rest arg is displayed instead. So for these functions, only the
+keywords actually supplied will be shown, and the values displayed
+will be the argument values, not values of the
(possibly modified) variables.
If the variable for an argument is never referenced by the function,
-it will be deleted. The variable value is then unavailable, so the
-debugger prints @samp{#<unused-arg>} instead of the value. Similarly,
-if for any of a number of reasons the value of the variable is
-unavailable or not known to be available (@pxref{Variable Access}),
-then @samp{#<unavailable-arg>} will be printed instead of the argument
-value.
+it will be deleted. The variable value is then unavailable, so the
+debugger prints @code{#<unused-arg>} instead of the value. Similarly, if
+for any of a number of reasons the value of the variable is
+unavailable or not known to be available (@ref{variable access}), then
+@code{#<unavailable-arg>} will be printed instead of the argument value.
- Note that inline expansion and open-coding affect what frames
-are present in the debugger, see @ref{Debugger Policy Control}.
-@comment FIXME: link here to section about open coding once it exists.
-@c @ref{open-coding}
+Note that inline expansion and open-coding affect what frames are
+present in the debugger, see @ref{debugger policy control}.
-
-@node Function Names
-@comment node-name, next, previous, up
+@node function names
@subsection Function Names
+@menu
+* Entry Point Details: entry point details.
+@end menu
+
If a function is defined by @code{defun} it will appear in backtrace
-by that name. Functions defined by @code{labels} and @code{flet} will
-appear as @code{(FLET @var{name})} and @code{(LABELS @var{name})} respectively.
-Anonymous lambdas will appear as @code{(LAMBDA @var{lambda-list})}.
+by that name. Functions defined by @code{labels} and @code{flet} will appear as
+@code{(flet <name>)} and @code{(labels <name>)} respectively. Anonymous
+lambdas will appear as @code{(lambda <lambda-list>)}.
-@menu
-* Entry Point Details::
-@end menu
-
-@node Entry Point Details
-@comment node-name, next, previous, up
+@node entry point details
@subsubsection Entry Point Details
-@cindex External entry points
-@cindex Entry points, external
-@cindex Block compilation, debugger implications
-@cindex External, stack frame kind
-@cindex Optional, stack frame kind
-@cindex Cleanup, stack frame kind
Sometimes the compiler introduces new functions that are used to
implement a user function, but are not directly specified in the
source. This is mostly done for argument type and count checking.
-With recursive or block compiled functions, an additional
-@code{external} frame may appear before the frame representing the first
-call to the recursive function or entry to the compiled block. This is a
+With recursive or block compiled functions, an additional @code{external}
+frame may appear before the frame representing the first call to the
+recursive function or entry to the compiled block. This is a
consequence of the way the compiler works: there is nothing odd with
-your program. You may also see @code{cleanup} frames during the
-execution of @code{unwind-protect} cleanup code, and @code{optional} for
-variable argument entry points.
+your program. You may also see @code{cleanup} frames during the execution
+of @code{unwind-protect} cleanup code, and @code{optional} for variable argument
+entry points.
-@node Debug Tail Recursion
-@comment node-name, next, previous, up
+@node debug tail recursion
@subsection Debug Tail Recursion
-@cindex Tail recursion
-@cindex Recursion, tail
-The compiler is ``properly tail recursive.'' If a function call is in
-a tail-recursive position, the stack frame will be deallocated
+The compiler is @emph{properly tail recursive}. If a function call is
+in a tail-recursive position, the stack frame will be deallocated
@emph{at the time of the call}, rather than after the call returns.
Consider this backtrace:
@@ -331,12 +315,12 @@ Consider this backtrace:
(FOO ...)
@end example
-Because of tail recursion, it is not necessarily the case that
-@code{FOO} directly called @code{BAR}. It may be that @code{FOO}
-called some other function @code{FOO2} which then called @code{BAR}
-tail-recursively, as in this example:
+Because of tail recursion, it is not necessarily the case that @code{foo}
+directly called @code{bar}. It may be that @code{foo} called some other
+function @code{foo2}, which then called @code{bar} tail-recursively, as in
+this example:
-@lisp
+@example
(defun foo ()
...
(foo2 ...)
@@ -348,282 +332,268 @@ tail-recursively, as in this example:
(defun bar (...)
...)
-@end lisp
+@end example
-Usually the elimination of tail-recursive frames makes debugging more
-pleasant, since these frames are mostly uninformative. If there is any
-doubt about how one function called another, it can usually be
-eliminated by finding the source location in the calling frame.
-@xref{Source Location Printing}.
+Usually the elimination of tail-recursive frames makes debugging
+more pleasant, since these frames are mostly uninformative. If there
+is any doubt about how one function called another, it can usually
+be eliminated by finding the source location in the calling frame.
+See @ref{source location printing}.
-The elimination of tail-recursive frames can be prevented by disabling
-tail-recursion optimization, which happens when the @code{debug}
-optimization quality is greater than @code{2}.
-@xref{Debugger Policy Control}.
+The elimination of tail-recursive frames can be prevented by
+disabling tail-recursion optimization, which happens when the @code{debug}
+optimization quality is greater than 2. See
+@ref{debugger policy control}.
-@comment FIXME: reinstate this link once the chapter is in the manual.
-@c For a more thorough discussion of tail recursion, @ref{tail-recursion}.
-
-@node Unknown Locations and Interrupts
-@comment node-name, next, previous, up
+@node unknown locations and interrupts
@subsection Unknown Locations and Interrupts
-@cindex Unknown code locations
-@cindex Locations, unknown
-@cindex Interrupts
-@cindex Errors, run-time
The debugger operates using special debugging information attached to
-the compiled code. This debug information tells the debugger what it
+the compiled code. This debug information tells the debugger what it
needs to know about the locations in the code where the debugger can
-be invoked. If the debugger somehow encounters a location not
-described in the debug information, then it is said to be
-@dfn{unknown}. If the code location for a frame is unknown, then some
-variables may be inaccessible, and the source location cannot be
-precisely displayed.
+be invoked. If the debugger somehow encounters a location not
+described in the debug information, then it is said to be @emph{unknown}.
+If the code location for a frame is unknown, then some variables may
+be inaccessible, and the source location cannot be precisely
+displayed.
There are three reasons why a code location could be unknown:
@itemize
+@item There is inadequate debug information due to the value of the
+ @code{debug} optimization quality. See @ref{debugger policy control}.
-@item
-There is inadequate debug information due to the value of the @code{debug}
-optimization quality. @xref{Debugger Policy Control}.
-
-@item
-The debugger was entered because of an interrupt such as @key{C-c}.
-
-@item
-A hardware error such as ``@samp{bus error}'' occurred in code that was
-compiled unsafely due to the value of the @code{safety} optimization
-quality.
-@comment FIXME: reinstate link when section on optimize qualities exists.
-@c @xref{optimize-declaration}.
+@item The debugger was entered because of an interrupt such as @code{C-c}.
+@item A hardware error such as a bus error occurred in code that was
+ compiled unsafely due to the value of the @code{safety}
+ optimization quality.
@end itemize
In the last two cases, the values of argument variables are
-accessible, but may be incorrect. For more details on when variable
-values are accessible, see @ref{Variable Value Availability}.
+accessible, but may be incorrect. For more details on when variable
+values are accessible, see @ref{variable value availability}.
It is possible for an interrupt to happen when a function call or
-return is in progress. The debugger may then flame out with some
-obscure error or insist that the bottom of the stack has been reached,
-when the real problem is that the current stack frame can't be
-located. If this happens, return from the interrupt and try again.
+return is in progress. The debugger may then flame out with some
+obscure error or insist that the bottom of the stack has been
+reached, when the real problem is that the current stack frame can't
+be located. If this happens, return from the interrupt and try
+again.
-
-@node Variable Access
-@comment node-name, next, previous, up
+@node variable access
@section Variable Access
-@cindex Debug variables
-@cindex Variables, debugger access
+
+@menu
+* Variable Value Availability: variable value availability.
+* Note On Lexical Variable Access: note on lexical variable access.
+@end menu
There are two ways to access the current frame's local variables in
-the debugger: @command{list-locals} and @code{sb-debug:var}.
+the debugger: @code{list-locals} and @code{sb-debug:var}.
The debugger doesn't really understand lexical scoping; it has just
-one namespace for all the variables in the current stack frame. If a
+one namespace for all the variables in the current stack frame. If a
symbol is the name of multiple variables in the same function, then
-the reference appears ambiguous, even though lexical scoping specifies
-which value is visible at any given source location. If the scopes of
-the two variables are not nested, then the debugger can resolve the
-ambiguity by observing that only one variable is accessible.
+the reference appears ambiguous, even though lexical scoping
+specifies which value is visible at any given source location. If
+the scopes of the two variables are not nested, then the debugger
+can resolve the ambiguity by observing that only one variable is
+accessible.
When there are ambiguous variables, the evaluator assigns each one a
-small integer identifier. The @code{sb-debug:var} function uses this
-identifier to distinguish between ambiguous variables. The
-@command{list-locals} command prints the identifier. In the
-following example, there are two variables named @code{X}. The first
-one has identifier 0 (which is not printed), the second one has
-identifier 1.
+small integer identifier. The @code{sb-debug:var} function uses this
+identifier to distinguish between ambiguous variables. The
+@code{list-locals} command prints the identifier. In the following
+example, there are two variables named @code{x}. The first one has
+identifier 0 (which is not printed), the second one has identifier
+1.
@example
X = 1
X#1 = 2
@end example
-@deffn {Debugger Command} @nopkg{list-locals} [@var{prefix}]
-This command prints the name and value of all variables in the current
-frame whose name has the specified @var{prefix}. @var{prefix} may be
-a string or a symbol. If no @var{prefix} is given, then all available
-variables are printed. If a variable has a potentially ambiguous
-name, then the name is printed with a ``@code{#@var{identifier}}''
-suffix, where @var{identifier} is the small integer used to make the
-name unique.
+@itemize
+@item @code{list-locals [<prefix>]}: This command prints the name and value
+ of all variables in the current frame whose name has the specified
+ @code{<prefix>}, which may be a string or a symbol. If no @code{<prefix>} is
+ given, then all available variables are printed. If a variable has
+ a potentially ambiguous name, then the name is printed with a
+ @code{#<identifier>} suffix, where @code{<identifier>} is the small integer
+ used to make the name unique.
+@end itemize
+
+@anchor{Function sb-debug var}
+@ffindex @sortas{var sb-debug} var [sb-debug]
+@deffn{Function} sb-debug:var name &optional id
+Return a variable's value if possible. @code{name} is a simple-string or symbol.
+If it is a simple-string, it is an initial substring of the
+variable's name. If name is a symbol, it has the same name and
+package as the variable whose value this function returns. If the
+symbol is uninterned, then the variable has the same name as the
+symbol, but it has no package.
+
+If name is the initial substring of variables with different names,
+then this returns no values after displaying the ambiguous names.
+If name determines multiple variables with the same name, then you
+must use the optional @code{id} argument to specify which one you want. If
+you left @code{id} unspecified, then this returns no values after
+displaying the distinguishing id values.
+
+The result of this function is limited to the availability of
+variable information. This is @code{setf}able.
@end deffn
-
-@defun @sbdebug{var} @var{name} &optional @var{identifier}
-This function returns the value of the variable in the current frame
-with the specified @var{name}. If supplied, @var{identifier}
-determines which value to return when there are ambiguous variables.
-
-When @var{name} is a symbol, it is interpreted as the symbol name of
-the variable, i.e. the package is significant. If @var{name} is an
-uninterned symbol (gensym), then return the value of the uninterned
-variable with the same name. If @var{name} is a string,
-@code{sb-debug:var} interprets it as the prefix of a variable name
-that must unambiguously complete to the name of a valid variable.
-
-@var{identifier} is used to disambiguate the variable name; use
-@command{list-locals} to find out the identifiers.
-@end defun
-
-
-@menu
-* Variable Value Availability::
-* Note On Lexical Variable Access::
-@end menu
-
-@node Variable Value Availability
-@comment node-name, next, previous, up
+@node variable value availability
@subsection Variable Value Availability
-@cindex Availability of debug variables
-@cindex Validity of debug variables
-@cindex Debug optimization quality
The value of a variable may be unavailable to the debugger in portions
-of the program where Lisp says that the variable is defined. If a
-variable value is not available, the debugger will not let you read or
-write that variable. With one exception, the debugger will never
-display an incorrect value for a variable. Rather than displaying
+of the program where Lisp says that the variable is defined. If a
+variable value is not available, the debugger will not let you read
+or write that variable. With one exception, the debugger will never
+display an incorrect value for a variable. Rather than displaying
incorrect values, the debugger tells you the value is unavailable.
-The one exception is this: if you interrupt (e.g., with @key{C-c}) or
-if there is an unexpected hardware error such as ``@samp{bus error}''
-(which should only happen in unsafe code), then the values displayed
-for arguments to the interrupted frame might be
-incorrect.@footnote{Since the location of an interrupt or hardware
-error will always be an unknown location, non-argument variable values
-will never be available in the interrupted frame. @xref{Unknown
-Locations and Interrupts}.} This exception applies only to the
-interrupted frame: any frame farther down the stack will be fine.
+The one exception is this: if you interrupt (e.g. with @code{C-c}) or if
+there is an unexpected hardware error such as a bus error (which
+should only happen in unsafe code), then the values displayed for
+arguments to the interrupted frame might be incorrect. This
+exception applies only to the interrupted frame: any frame farther
+down the stack will be fine.
+
+@quotation
+@emph{Note}: Since the location of an interrupt or hardware error will
+always be an unknown location, non-argument variable values will
+never be available in the interrupted frame. See
+@ref{unknown locations and interrupts}.)
+@end quotation
The value of a variable may be unavailable for these reasons:
@itemize
+@item The value of the @code{debug} optimization quality may have omitted debug
+ information needed to determine whether the variable is available.
+ Unless a variable is an argument, its value will only be available
+ when @code{debug} is at least 2.
-@item
-The value of the @code{debug} optimization quality may have omitted debug
-information needed to determine whether the variable is available.
-Unless a variable is an argument, its value will only be available when
-@code{debug} is at least @code{2}.
+@item The compiler did lifetime analysis and determined that the value
+ was no longer needed, even though its scope had not been exited.
+ Lifetime analysis is inhibited when the @code{debug} optimization
+ quality is 3.
-@item
-The compiler did lifetime analysis and determined that the value was no longer
-needed, even though its scope had not been exited. Lifetime analysis is
-inhibited when the @code{debug} optimization quality is @code{3}.
+@item The variable's name is an uninterned symbol (gensym). To save
+ space, the compiler only dumps debug information about uninterned
+ variables when the @code{debug} optimization quality is 3.
-@item
-The variable's name is an uninterned symbol (gensym). To save space, the
-compiler only dumps debug information about uninterned variables when the
-@code{debug} optimization quality is @code{3}.
+@item The frame's location is unknown (see
+ @ref{unknown locations and interrupts}) because the debugger was
+ entered due to an interrupt or unexpected hardware error. Under
+ these conditions the values of arguments will be available, but
+ might be incorrect. This is the exception mentioned above.
-@item
-The frame's location is unknown (@pxref{Unknown Locations and
-Interrupts}) because the debugger was entered due to an interrupt or
-unexpected hardware error. Under these conditions the values of
-arguments will be available, but might be incorrect. This is the
-exception mentioned above.
+@item The variable (or the code referencing it) was optimized out of
+ existence. Variables with no reads are always optimized away. The
+ degree to which the compiler deletes variables will depend on the
+ value of the @code{compilation-speed} optimization quality, but most
+ source-level optimizations are done under all compilation
+ policies.
-@item
-The variable (or the code referencing it) was optimized out
-of existence. Variables with no reads are always optimized away. The
-degree to which the compiler deletes variables will depend on the
-value of the @code{compilation-speed} optimization quality, but most
-source-level optimizations are done under all compilation policies.
+@item The variable is never set and its definition looks like
-@item
-The variable is never set and its definition looks like
-@lisp
+@example
(LET ((var1 var2))
...)
-@end lisp
+@end example
+
In this case, @code{var1} is substituted with @code{var2}.
-@item
-The variable is never set and is referenced exactly once. In this
-case, the reference is substituted with the variable initial value.
-
+@item The variable is never set and is referenced exactly once. In this
+ case, the reference is substituted with the variable initial
+ value.
@end itemize
Since it is especially useful to be able to get the arguments to a
-function, argument variables are treated specially when the
-@code{speed} optimization quality is less than @code{3} and the
-@code{debug} quality is at least @code{1}. With this compilation
-policy, the values of argument variables are almost always available
-everywhere in the function, even at unknown locations. For
-non-argument variables, @code{debug} must be at least @code{2} for
-values to be available, and even then, values are only available at
-known locations.
+function, argument variables are treated specially when the @code{speed}
+optimization quality is less than 3 and the @code{debug} quality is at
+least 1. With this compilation policy, the values of argument
+variables are almost always available everywhere in the function,
+even at unknown locations. For non-argument variables, @code{debug} must be
+at least 2 for values to be available, and even then, values are
+only available at known locations.
-
-@node Note On Lexical Variable Access
-@comment node-name, next, previous, up
+@node note on lexical variable access
@subsection Note On Lexical Variable Access
When the debugger command loop establishes variable bindings for
available variables, these variable bindings have lexical scope and
-dynamic extent.@footnote{The variable bindings are actually created
-using the Lisp @code{symbol-macrolet} special form.} You can close
-over them, but such closures can't be used as upward function arguments.
+dynamic extent. You can close over them, but such closures can't be
+used as upward function arguments.
-You can also set local variables using @code{setq}, but if the
-variable was closed over in the original source and never set, then
-setting the variable in the debugger may not change the value in all
-the functions the variable is defined in. Another risk of setting
+@quotation
+@emph{Note}: The variable bindings are actually created using the Lisp
+@code{symbol-macrolet} special form.
+@end quotation
+
+You can also set local variables using @code{setq}, but if the variable was
+closed over in the original source and never set, then setting the
+variable in the debugger may not change the value in all the
+functions the variable is defined in. Another risk of setting
variables is that you may assign a value of a type that the compiler
-proved the variable could never take on. This may result in bad
+proved the variable could never take on. This may result in bad
things happening.
-
-@node Source Location Printing
-@comment node-name, next, previous, up
+@node source location printing
@section Source Location Printing
-@cindex Source location printing, debugger
+
+@menu
+* How the Source is Found: how the source is found.
+* Source Location Availability: source location availability.
+@end menu
One of the debugger's capabilities is source level debugging of
compiled code. These commands display the source location for the
current frame:
-@deffn {Debugger Command} @nopkg{source} [@var{context}]
-This command displays the file that the current frame's function was
-defined from (if it was defined from a file), and then the source form
-responsible for generating the code that the current frame was
-executing. If @var{context} is specified, then it is an integer
-specifying the number of enclosing levels of list structure to print.
-@end deffn
+@itemize
+@item @code{source [<context>]}: This command displays the file that the
+ current frame's function was defined from (if it was defined from
+ a file), and then the source form responsible for generating the
+ code that the current frame was executing. If @code{<context>} is
+ specified, then it is an integer specifying the number of
+ enclosing levels of list structure to print.
+@end itemize
-The source form for a location in the code is the innermost list present
-in the original source that encloses the form responsible for generating
-that code. If the actual source form is not a list, then some enclosing
-list will be printed. For example, if the source form was a reference
-to the variable @code{*some-random-special*}, then the innermost
-enclosing evaluated form will be printed. Here are some possible
-enclosing forms:
+The source form for a location in the code is the innermost list
+present in the original source that encloses the form responsible
+for generating that code. If the actual source form is not a list,
+then some enclosing list will be printed. For example, if the source
+form was a reference to the variable @code{*some-random-special*}, then
+the innermost enclosing evaluated form will be printed. Here are
+some possible enclosing forms:
-@lisp
+@example
(let ((a *some-random-special*))
...)
(+ *some-random-special* ...)
-@end lisp
+@end example
-If the code at a location was generated from the expansion of a macro
-or a source-level compiler optimization, then the form in the original
-source that expanded into that code will be printed. Suppose the file
-@file{/usr/me/mystuff.lisp} looked like this:
+If the code at a location was generated from the expansion of a
+macro or a source-level compiler optimization, then the form in the
+original source that expanded into that code will be printed.
+Suppose the file @code{/usr/me/mystuff.lisp} looked like this:
-@lisp
+@example
(defmacro mymac ()
'(myfun))
(defun foo ()
(mymac)
...)
-@end lisp
+@end example
-If @code{foo} has called @code{myfun}, and is waiting for it to
-return, then the @command{source} command would print:
+If @code{foo} has called @code{myfun}, and is waiting for it to return, then
+the @code{source} command would print:
@example
; File: /usr/me/mystuff.lisp
@@ -634,11 +604,10 @@ return, then the @command{source} command would print:
Note that the macro use was printed, not the actual function call form,
@code{(myfun)}.
-If enclosing source is printed by giving an argument to
-@command{source} or @command{vsource}, then the actual source form is
-marked by wrapping it in a list whose first element is
-@samp{#:***HERE***}. In the previous example, @code{source 1} would
-print:
+If enclosing source is printed by giving an argument to @code{source} or
+@code{vsource}, then the actual source form is marked by wrapping it in a
+list whose first element is @code{#:***here***}. In the previous example,
+@code{source 1} would print:
@example
; File: /usr/me/mystuff.lisp
@@ -649,369 +618,303 @@ print:
...)
@end example
-
-@menu
-* How the Source is Found::
-* Source Location Availability::
-@end menu
-
-@node How the Source is Found
-@comment node-name, next, previous, up
+@node how the source is found
@subsection How the Source is Found
-If the code was defined from Lisp by @code{compile} or
-@code{eval}, then the source can always be reliably located. If the
-code was defined from a @file{fasl} file created by
-@code{compile-file}, then the debugger gets the source forms it
-prints by reading them from the original source file. This is a
-potential problem, since the source file might have moved or changed
-since the time it was compiled.
+If the code was defined from Lisp by @code{compile} or @code{eval}, then the source
+can always be reliably located. If the code was defined from a FASL
+file created by @code{compile-file}, then the debugger gets the source
+forms it prints by reading them from the original source file. This
+is a potential problem, since the source file might have moved or
+changed since the time it was compiled.
The source file is opened using the @code{truename} of the source file
-pathname originally given to the compiler. This is an absolute pathname
-with all logical names and symbolic links expanded. If the file can't
-be located using this name, then the debugger gives up and signals an
-error.
+pathname originally given to the compiler. This is an absolute
+pathname with all logical names and symbolic links expanded. If the
+file can't be located using this name, then the debugger gives up
+and signals an error.
If the source file can be found, but has been modified since the time it was
compiled, the debugger prints this warning:
@example
; File has been modified since compilation:
-; @var{filename}
+; <filename>
; Using form offset instead of character position.
@end example
-where @var{filename} is the name of the source file. It then proceeds
+where @code{<filename>} is the name of the source file. It then proceeds
using a robust but not foolproof heuristic for locating the source.
This heuristic works if:
@itemize
+@item No top-level forms before the top-level form containing the source
+ have been added or deleted, and
-@item
-No top-level forms before the top-level form containing the source
-have been added or deleted, and
-
-@item
-The top-level form containing the source has not been modified much.
-(More precisely, none of the list forms beginning before the source
-form have been added or deleted.)
-
+@item the top-level form containing the source has not been modified
+ much. (More precisely, none of the list forms beginning before the
+ source form have been added or deleted.)
@end itemize
-If the heuristic doesn't work, the displayed source will be wrong, but will
-probably be near the actual source. If the ``shape'' of the top-level form in
-the source file is too different from the original form, then an error will be
-signaled. When the heuristic is used, the source location commands are
-noticeably slowed.
+If the heuristic doesn't work, the displayed source will be wrong,
+but will probably be near the actual source. If the "shape" of the
+top-level form in the source file is too different from the original
+form, then an error will be signaled. When the heuristic is used,
+the source location commands are noticeably slowed.
-Source location printing can also be confused if (after the source was
-compiled) a read-macro you used in the code was redefined to expand
-into something different, or if a read-macro ever returns the same
-@code{eq} list twice. If you don't define read macros and don't use
+Source location printing can also be confused if (after the source
+was compiled) a read-macro you used in the code was redefined to
+expand into something different, or if a read-macro ever returns the
+same @code{eq} list twice. If you don't define read macros and don't use
@code{##} in perverted ways, you don't need to worry about this.
-
-@node Source Location Availability
-@comment node-name, next, previous, up
+@node source location availability
@subsection Source Location Availability
-@cindex Debug optimization quality
-@cindex Block, basic
-@cindex Block, start location
Source location information is only available when the @code{debug}
-optimization quality is at least @code{2}. If source location
-information is unavailable, the source commands will give an error
-message.
+optimization quality is at least 2. If source location information
+is unavailable, the source commands will give an error message.
If source location information is available, but the source location
is unknown because of an interrupt or unexpected hardware error
-(@pxref{Unknown Locations and Interrupts}), then the command will
-print:
+(see @ref{unknown locations and interrupts}), then the command will
+print
@example
Unknown location: using block start.
@end example
and then proceed to print the source location for the start of the
-@emph{basic block} enclosing the code location. It's a bit
-complicated to explain exactly what a basic block is, but here are
-some properties of the block start location:
+@emph{basic block} enclosing the code location. It's a bit complicated to
+explain exactly what a basic block is, but here are some properties
+of the block start location:
@itemize
-
@item The block start location may be the same as the true location.
-@item The block start location will never be later in the
-program's flow of control than the true location.
+@item The block start location will never be later in the program's flow
+ of control than the true location.
-@item No conditional control structures (such as @code{if},
-@code{cond}, @code{or}) will intervene between the block start and the
-true location (but note that some conditionals present in the original
-source could be optimized away.) Function calls @emph{do not} end
-basic blocks.
+@item No conditional control structures (such as @code{if}, @code{cond}, @code{or}) will
+ intervene between the block start and the true location (but note
+ that some conditionals present in the original source could be
+ optimized away.) Function calls @emph{do not} end basic blocks.
@item The head of a loop will be the start of a block.
-@item The programming language concept of ``block structure'' and the
-Lisp @code{block} special form are totally unrelated to the compiler's
-basic block.
-
+@item The programming language concept of block structure and the Lisp
+ @code{block} special form are totally unrelated to the compiler's basic
+ block.
@end itemize
-In other words, the true location lies between the printed location and the
-next conditional (but watch out because the compiler may have changed the
-program on you.)
+In other words, the true location lies between the printed location
+and the next conditional (but watch out because the compiler may
+have changed the program on you.)
-
-@node Debugger Policy Control
-@comment node-name, next, previous, up
+@node debugger policy control
@section Debugger Policy Control
-@cindex Policy, debugger
-@cindex Debug optimization quality
-@cindex Optimize declaration
-@cindex Inline expansion
-@cindex Semi-inline expansion
The compilation policy specified by @code{optimize} declarations
-affects the behavior seen in the debugger. The @code{debug} quality
+affects the behavior seen in the debugger. The @code{debug} quality
directly affects the debugger by controlling the amount of debugger
-information dumped. Other optimization qualities have indirect but
+information dumped. Other optimization qualities have indirect but
observable effects due to changes in the way compilation is done.
-Unlike the other optimization qualities (which are compared in relative value
-to evaluate tradeoffs), the @code{debug} optimization quality is directly
-translated to a level of debug information. This absolute interpretation
-allows the user to count on a particular amount of debug information being
-available even when the values of the other qualities are changed during
-compilation. These are the levels of debug information that correspond to the
-values of the @code{debug} quality:
+Unlike the other optimization qualities (which are compared in
+relative value to evaluate tradeoffs), the @code{debug} optimization
+quality is directly translated to a level of debug information. This
+absolute interpretation allows the user to count on a particular
+amount of debug information being available even when the values of
+the other qualities are changed during compilation. These are the
+levels of debug information that correspond to the values of the
+@code{debug} quality:
-@table @code
+@itemize
+@item @code{0}: Only the function name and enough information to allow the
+ stack to be parsed.
-@item 0
-Only the function name and enough information to allow the stack to
-be parsed.
+@item @code{> 0}: Any level greater than 0 gives level 0 plus all argument
+ variables. Values will only be accessible if the argument variable
+ is never set and @code{speed} is not 3. SBCL allows any real value for
+ optimization qualities. It may be useful to specify 0.5 to get
+ backtrace argument display without argument documentation.
-@item > 0
-Any level greater than @code{0} gives level @code{0} plus all argument
-variables. Values will only be accessible if the argument variable is
-never set and @code{speed} is not @code{3}. SBCL allows any real
-value for optimization qualities. It may be useful to specify
-@code{0.5} to get backtrace argument display without argument
-documentation.
+@item @code{1}: Level 1 provides argument documentation (printed argument
+ lists) and derived argument/result type information. This makes
+ @code{describe} more informative, and allows the compiler to do
+ compile-time argument count and type checking for any calls
+ compiled at run-time. This is the default.
-@item 1
-Level @code{1} provides argument documentation (printed argument lists) and
-derived argument/result type information. This makes @code{describe}
-more informative, and allows the compiler to do compile-time argument
-count and type checking for any calls compiled at run-time. This is
-the default.
+@item @code{2}: Level 1 plus all interned local variables, source location
+ information, and lifetime information that tells the debugger when
+ arguments are available (even when @code{speed} is 3 or the argument is
+ set).
-@item 2
-Level @code{1} plus all interned local variables, source location
-information, and lifetime information that tells the debugger when
-arguments are available (even when @code{speed} is @code{3} or the
-argument is set).
+@item @code{> 2}: Any level greater than 2 gives level 2 and in addition
+ disables tail-call optimization, so that the backtrace will
+ contain frames for all invoked functions, even those in tail
+ positions.
-@item > 2
-Any level greater than @code{2} gives level @code{2} and in addition
-disables tail-call optimization, so that the backtrace will contain
-frames for all invoked functions, even those in tail positions.
+@item @code{3}: Level 2 plus all uninterned variables. In addition, lifetime
+ analysis is disabled (even when @code{speed} is 3), ensuring that all
+ variable values are available at any known location within the
+ scope of the binding. This has a speed penalty in addition to the
+ obvious space penalty.
+@end itemize
-@item 3
-Level @code{2} plus all uninterned variables. In addition, lifetime
-analysis is disabled (even when @code{speed} is @code{3}), ensuring
-that all variable values are available at any known location within
-the scope of the binding. This has a speed penalty in addition to the
-obvious space penalty.
+Inlining of local functions is inhibited so that they may be @code{trace}d.
-Inlining of local functions is inhibited so that they may be
-@code{trace}d.
+@itemize
+@item @code{> (max speed space)}: If @code{debug} is greater than both @code{speed} and
+ @code{space}, the command @code{return} can be used to continue execution by
+ returning a value from the current stack frame.
-@item > (max speed space)
-If @code{debug} is greater than both @code{speed} and @code{space},
-the command @command{return} can be used to continue execution by
-returning a value from the current stack frame.
+@item @code{> (max speed space compilation-speed)}: If @code{debug} is greater than
+ all of @code{speed}, @code{space} and @code{compilation-speed} the code will be
+ steppable (see @ref{single stepping}).
+@end itemize
-@item > (max speed space compilation-speed)
-If @code{debug} is greater than all of @code{speed}, @code{space} and
-@code{compilation-speed} the code will be steppable (@pxref{Single Stepping}).
+As you can see, if the @code{speed} quality is 3, debugger performance is
+degraded. This effect comes from the elimination of argument
+variable special-casing (see @ref{variable value availability}). Some
+degree of speed/debuggability tradeoff is unavoidable, but the
+effect is not too drastic when @code{debug} is at least 2.
-@end table
+In addition to @code{inline} and @code{notinline} declarations, the relative
+values of the @code{speed} and @code{space} qualities also change whether
+functions are inline expanded. If a function is inline expanded,
+then there will be no frame to represent the call, and the arguments
+will be treated like any other local variable. Functions may also be
+@emph{semi-inline}, in which case there is a frame to represent the call,
+but the call is to an optimized local version of the function, not
+to the original function.
-As you can see, if the @code{speed} quality is @code{3}, debugger performance is
-degraded. This effect comes from the elimination of argument variable
-special-casing (@pxref{Variable Value Availability}). Some degree of
-speed/debuggability tradeoff is unavoidable, but the effect is not too drastic
-when @code{debug} is at least @code{2}.
-
-In addition to @code{inline} and @code{notinline} declarations, the
-relative values of the @code{speed} and @code{space} qualities also
-change whether functions are inline expanded.
-@comment FIXME: link to section about inline expansion when it exists
-@c (\pxlref{inline-expansion}.)
-If a function is inline expanded, then
-there will be no frame to represent the call, and the arguments will
-be treated like any other local variable. Functions may also be
-``semi-inline'', in which case there is a frame to represent the call,
-but the call is to an optimized local version of the function, not to
-the original function.
-
-
-@node Exiting Commands
-@comment node-name, next, previous, up
+@node exiting commands
@section Exiting Commands
These commands get you out of the debugger.
-@deffn {Debugger Command} @nopkg{toplevel}
-Throw to top level.
-@end deffn
+@itemize
+@item @code{toplevel}: Throw to top level.
-@deffn {Debugger Command} @nopkg{restart} [@var{n}]
-Invokes the @var{n}th restart case as displayed by the @code{error}
-command. If @var{n} is not specified, the available restart cases are
-reported.
-@end deffn
+@item @code{restart [<n>]}: Invoke the @code{<n>}th restart case as displayed by
+ the @code{error} command. If @code{<n>} is not specified, the available
+ restart cases are reported.
-@deffn {Debugger Command} @nopkg{continue}
-Calls @code{continue} on the condition given to @code{debug}. If there is no
-restart case named @var{continue}, then an error is signaled.
-@end deffn
+@item @code{continue}: Call @code{continue} on the condition given to @code{debug}. If
+ there is no restart case named @code{continue}, then an error is
+ signaled.
-@deffn {Debugger Command} @nopkg{abort}
-Calls @code{abort} on the condition given to @code{debug}. This is
-useful for popping debug command loop levels or aborting to top level,
-as the case may be.
-@end deffn
+@item @code{abort}: Call @code{abort} on the condition given to @code{debug}. This is
+ useful for popping debug command loop levels or aborting to top
+ level, as the case may be.
-@deffn {Debugger Command} @nopkg{return} @var{value}
-Returns @var{value} from the current stack frame. This command is
-available when the @code{debug} optimization quality is greater than
-both @code{speed} and @code{space}. Care must be taken that the value
-is of the same type as SBCL expects the stack frame to return.
-@end deffn
+@item @code{return <value>}: Return @code{value} from the current stack frame.
+ This command is available when the @code{debug} optimization quality is
+ greater than both @code{speed} and @code{space}. Care must be taken that the
+ value is of the same type as SBCL expects the stack frame to
+ return.
-@deffn {Debugger Command} @nopkg{restart-frame}
-Restarts execution of the current stack frame. This command is
-available when the @code{debug} optimization quality is greater than
-both @code{speed} and @code{space} and when the frame is for a global
-function. If the function is redefined in the debugger before the frame
-is restarted, the new function will be used.
-@end deffn
+@item @code{restart-frame}: Restart execution of the current stack frame.
+ This command is available when the @code{debug} optimization quality is
+ greater than both @code{speed} and @code{space} and when the frame is for a
+ global function. If the function is redefined in the debugger
+ before the frame is restarted, the new function will be used.
+@end itemize
-@node Information Commands
-@comment node-name, next, previous, up
+@node information commands
@section Information Commands
Most of these commands print information about the current frame or
function, but a few show general information.
-@deffn {Debugger Command} @nopkg{help}
-@deffnx {Debugger Command} @nopkg{?}
-Displays a synopsis of debugger commands.
-@end deffn
+@itemize
+@item @code{help} or @code{?}: Display a synopsis of debugger commands.
-@deffn {Debugger Command} @nopkg{describe}
-Calls @code{describe} on the current function and displays the number of
-local variables.
-@end deffn
+@item @code{describe}: Call @code{describe} on the current function and displays the
+ number of local variables.
-@deffn {Debugger Command} @nopkg{print}
-Displays the current function call as it would be displayed by moving to
-this frame.
-@end deffn
+@item @code{print}: Display the current function call as it would be
+ displayed by moving to this frame.
-@deffn {Debugger Command} @nopkg{error}
-Prints the condition given to @code{invoke-debugger} and the active
-proceed cases.
-@end deffn
+@item @code{error}: Print the condition given to @code{invoke-debugger} and the
+ active proceed cases.
-@deffn {Debugger Command} @nopkg{backtrace} [@var{n}]
-Displays all the frames from the current to the bottom. Only shows
-@var{n} frames if specified. The printing is controlled by
-@code{*debug-print-variable-alist*}.
-@end deffn
+@item @code{backtrace [<n>]}: Display all the frames from the current to the
+ bottom. Only shows @code{<n>} frames if specified. The printing is
+ controlled by @code{sb-debug:*debug-print-variable-alist*}.
+@end itemize
-@node Breakpoint Commands, , Information Commands, Debugger
-@comment node-name, next, previous, up
+@node breakpoint commands
@section Breakpoint Commands
-@cindex Breakpoints
+
+@menu
+* Breakpoint Example: breakpoint example.
+@end menu
SBCL supports setting of breakpoints inside compiled functions and
-stepping of compiled code. Breakpoints can only be set at known
-locations (@pxref{Unknown Locations and Interrupts}), so these
-commands are largely useless unless the @code{debug} optimize quality
-is at least @code{2} (@pxref{Debugger Policy Control}). These
-commands manipulate breakpoints:
+stepping of compiled code. Breakpoints can only be set at known
+locations (see @ref{unknown locations and interrupts}), so these commands
+are largely useless unless the @code{debug} optimize quality is at least
+2 (see @ref{debugger policy control}). These commands manipulate
+breakpoints:
-@deffn {Debugger Command} breakpoint @var{location} [@var{option} @var{value}]*
-Set a breakpoint in some function. @var{location} may be an integer
-code location number (as displayed by @command{list-locations}) or a
-keyword. The keyword can be used to indicate setting a breakpoint at
-the function start (@code{:start}, @code{:s}) or function end
-(@code{:end}, @code{:e}). The @command{breakpoint} command has
-@code{:condition}, @code{:break}, @code{:print} and @code{:function}
-options which work similarly to the @code{trace} options.
-@end deffn
+@itemize
+@item @code{breakpoint <location> [<option> <value>]*}: Set a breakpoint in
+ some function. @code{<location>} may be an integer code location
+ number (as displayed by @code{list-locations}) or a keyword. The
+ keyword can be used to indicate setting a breakpoint at the
+ function start (@code{:start}, @code{:s}) or function end (@code{:end}, @code{:e}). The
+ @code{breakpoint} command has @code{:condition}, @code{:break}, @code{:print} and @code{:function}
+ options which work similarly to the @code{trace} options.
-@deffn {Debugger Command} list-locations [@var{function}]
-@deffnx {Debugger Command} ll [@var{function}]
-List all the code locations in the current frame's function, or in
-@var{function} if it is supplied. The display format is the code
-location number, a colon and then the source form for that location:
+@item @code{list-locations [<function>]} or @code{ll [<function>]}: List all the
+ code locations in the current frame's function, or in @code{<function>}
+ if it is supplied. The display format is the code location number,
+ a colon and then the source form for that location:
@example
3: (1- N)
@end example
-If consecutive locations have the same source, then a numeric range
-like @code{3-5:} will be printed. For example, a default function
-call has a known location both immediately before and after the call,
-which would result in two code locations with the same source. The
-listed function becomes the new default function for breakpoint
-setting (via the @command{breakpoint}) command.
-@end deffn
+If consecutive locations have the same source, then a numeric
+range like @code{3-5:} will be printed. For example, a default
+function call has a known location both immediately before and
+after the call, which would result in two code locations with
+the same source. The listed function becomes the new default
+function for breakpoint setting (via the @code{breakpoint}) command.
-@deffn {Debugger Command} list-breakpoints
-@deffnx {Debugger Command} lb
-List all currently active breakpoints with their breakpoint number.
-@end deffn
+@item @code{list-breakpoints} or @code{lb}: List all currently active breakpoints
+ with their breakpoint number.
-@deffn {Debugger Command} delete-breakpoint [@var{number}]
-@deffnx {Debugger Command} db [@var{number}]
-Delete a breakpoint specified by its breakpoint number. If no number
-is specified, delete all breakpoints.
-@end deffn
+@item @code{delete-breakpoint [<number>]} or @code{db [<number>]}: Delete a
+ breakpoint specified by its breakpoint number. If no number is
+ specified, delete all breakpoints.
-@deffn {Debugger Command} step*
-Step to the next possible breakpoint location in the current function.
-This always steps over function calls, instead of stepping into them
-@end deffn
+@item @code{step*}: Step to the next possible breakpoint location in the
+ current function. This always steps over function calls, instead
+ of stepping into them.
+@end itemize
-@menu
-* Breakpoint Example::
-@end menu
-
-@node Breakpoint Example, , Breakpoint Commands, Breakpoint Commands
-@comment node-name, next, previous, up
+@node breakpoint example
@subsection Breakpoint Example
Consider this definition of the factorial function:
-@lisp
+@example
(defun ! (n)
(if (zerop n)
1
(* n (! (1- n)))))
-@end lisp
+@end example
This debugger session demonstrates the use of breakpoints:
-@example
-* (break) ; invoke debugger
+@itemize
+@item (break) ; invoke debugger
+@end itemize
+@example
debugger invoked on a SIMPLE-CONDITION in thread 11184: break
restarts (invokable by number or by possibly-abbreviated name):
@@ -1069,18 +972,17 @@ Source: (* N (! (1- N)))
3]
@end example
-Note: The @command{step*} command differs from the single stepping
-commands in that it also functions in compiled code which has not been
-compiled with stepping instrumentation. It simply steps to the next
-compiled code location. In the future, this form of stepping may be
-improved enough to subsume the instrumentation based stepping commands,
-which have much higher overhead.
+@quotation
+@emph{Note}: The @code{step*} command differs from the single stepping
+commands in that it also functions in compiled code which has not
+been compiled with stepping instrumentation. It simply steps to
+the next compiled code location. In the future, this form of
+stepping may be improved enough to subsume the instrumentation
+based stepping commands, which have much higher overhead.
+@end quotation
-@node Function Tracing
-@comment node-name, next, previous, up
+@node function tracing
@section Function Tracing
-@cindex Tracing
-@cindex Function, tracing
The tracer causes selected functions to print their arguments and
their results whenever they are called. Options allow conditional
@@ -1088,92 +990,219 @@ printing of the trace information and conditional breakpoints on
function entry or exit.
In SBCL, tracing can be done either by temporarily redefining the
-function name (encapsulation), or using breakpoints. When breakpoints
-are used, the function object itself is destructively modified to cause
-the tracing action. The advantage of using breakpoints is that tracing
-works even when the function is anonymously called via @code{funcall},
-that function object identity is preserved, and that anonymous and local
-functions can also be traced.
-
-@include macro-common-lisp-trace.texinfo
-
- In the case of functions where the known return convention is used
- to optimize, encapsulation may be necessary in order to make
- tracing work at all. The symptom of this occurring is an error
- stating
+function name (encapsulation), or using breakpoints. When
+breakpoints are used, the function object itself is destructively
+modified to cause the tracing action. The advantage of using
+breakpoints is that tracing works even when the function is
+anonymously called via @code{funcall}, that function object identity is
+preserved, and that anonymous and local functions can also be
+traced.
+
+@anchor{Macro common-lisp trace}
+@ffindex @sortas{trace common-lisp} trace [common-lisp]
+@deffn{Macro} trace &rest specs
+@code{trace} @code{@{Option Global-Value@}* @{Name @{Option Value@}*@}*}
+
+@code{trace} is a debugging tool that provides information when specified
+functions are called. In its simplest form:
+
@example
- Error in function @var{foo}: :FUNCTION-END breakpoints are
- currently unsupported for the known return convention.
+(TRACE NAME-1 NAME-2 ...)
@end example
- in such cases we recommend using @code{(trace @var{foo} :encapsulate
- t)}
-@include macro-common-lisp-untrace.texinfo
+The @code{name}s are not evaluated. Each may be one of the following:
+
+@itemize
+@item @code{symbol}, denoting a function or macro.
+@item @code{fname}, a valid function name, denoting a function.
+@item @code{(method fname qualifiers* (specializers*))} denoting a method.
+@item @code{(compiler-macro symbol)} denoting a compiler macro.
+@item @code{(labels fname :in outer-name)} or @code{(flet fname :in outer-name)}
+ denoting a local function where @code{outer-name} may be any of the
+ previous names for functions, macros, methods or compiler macros.
+ Tracing local functions may require @code{debug} policy 3 to inhibit
+ inlining.
+@item @code{string} denoting all functions fbound to symbols whose home package
+ is the package with the given name.
+@end itemize
+
+Options allow modification of the default behavior. Each option is a
+pair of an option keyword and a value form. Global options are
+specified before the first name, and affect all functions traced by a
+given use of @code{trace}. Options may also be interspersed with function
+names, in which case they act as local options, only affecting tracing
+of the immediately preceding function name. Local options override
+global options.
+
+By default, @code{trace} causes a printout on @code{*trace-output*} each time that
+one of the named functions is entered or returns. (This is the basic,
+ANSI Common Lisp behavior of @code{trace}.)
+
+The following options are defined:
+
+@itemize
+@item @code{:report} @code{<report-type>}
+
+If @code{report-type} is @code{trace} (the default) then information is
+reported by printing immediately. If @code{report-type} is @code{nil}, then
+the only effect of the trace is to execute other options (e.g.
+@code{print} or @code{break}). Otherwise, @code{report-type} is treated as a function
+designator and, for each trace event, funcalled with 5 arguments:
+trace depth (a non-negative integer), a function name or a
+function object, a keyword (@code{:enter}, @code{:exit} or @code{:non-local-exit}), a
+stack frame, and a list of values (arguments or return values).
+
+@item @code{:condition} @code{<form>}
+@item @code{:condition-after} @code{<form>}
+@item @code{:condition-all} @code{<form>}
+
+If @code{:condition} is specified, then @code{trace} does nothing unless @code{form}
+evaluates to true at the time of the call. @code{:condition-after} is
+similar, but suppresses the initial printout, and is tested when
+the function returns. @code{:condition-all} tries both before and after.
+
+@item @code{:break} @code{<form>}
+@item @code{:break-after} @code{<form>}
+@item @code{:break-all} @code{<form>}
-@include var-sb-debug-star-trace-indentation-step-star.texinfo
+If specified, and @code{form} evaluates to true, then the debugger is
+invoked at the start of the function, at the end of the function,
+or both, according to the respective option.
-@include var-sb-debug-star-max-trace-indentation-star.texinfo
+@item @code{:print} @code{<form>}
+@item @code{:print-after} @code{<form>}
+@item @code{:print-all} @code{<form>}
-@include var-sb-debug-star-trace-encapsulate-default-star.texinfo
+In addition to the usual printout, the result of evaluating @code{form}
+is printed at the start of the function, at the end of the
+function, or both, according to the respective option. Multiple
+print options cause multiple values to be printed.
+
+@item @code{:wherein} @code{<names>}
+
+If specified, @code{names} is a function name or list of names. @code{trace}
+does nothing unless a call to one of those functions encloses the
+call to this function (i.e. it would appear in a backtrace.)
+Anonymous functions have string names like "DEFUN FOO".
+
+@item @code{:encapsulate} @{@code{:default} | @code{t} | @code{nil}@}
+
+If @code{t}, the default, tracing is done via encapsulation (redefining
+the function name) rather than by modifying the function. @code{:default}
+is not the default but means to use encapsulation for interpreted
+functions and funcallable instances, breakpoints otherwise. When
+encapsulation is used, forms are *not* evaluated in the function's
+lexical environment, but @code{sb-debug:arg} can still be used.
+
+@item @code{:methods} @{@code{t} | @code{nil}@}
+
+If @code{t}, any function argument naming a generic function will have
+its methods traced in addition to the generic function itself.
+
+@item @code{:function} @code{<function-form>}
+
+This is a not really an option but rather another way of
+specifying what function to trace. The @code{function-form} is
+evaluated immediately, and the resulting function is traced.
+@end itemize
+
+@code{:condition}, @code{:break} and @code{:print} forms are evaluated in a context which
+mocks up the lexical environment of the called function, so that
+@code{sb-debug:var} and @code{sb-debug:arg} can be used.
+The @code{*-after} and @code{*-all} forms can use also use @code{sb-debug:arg}. In forms
+which are evaluated after the function call, @code{(sb-debug:arg n)} returns
+the @code{n}th value returned by the function.
+@end deffn
+In the case of functions where the known return convention is used
+to optimize, encapsulation may be necessary in order to make tracing
+work at all. The symptom of this occurring is an error stating
+
+@example
+Error in function FOO: :FUNCTION-END breakpoints are
+currently unsupported for the known return convention.
+@end example
-@include var-sb-debug-star-trace-report-default-star.texinfo
+in such cases we recommend using @code{(TRACE FOO :ENCAPSULATE t)}.
-@node Single Stepping
-@comment node-name, next, previous, up
+@anchor{Macro common-lisp untrace}
+@ffindex @sortas{untrace common-lisp} untrace [common-lisp]
+@deffn{Macro} untrace &rest specs
+Remove tracing from the specified functions. Untraces all
+functions when called with no arguments.
+@end deffn
+@anchor{Variable sb-debug *trace-indentation-step*}
+@vvindex @sortas{trace-indentation-step* sb-debug} *trace-indentation-step* [sb-debug]
+@deffn{Variable} sb-debug:*trace-indentation-step*
+The increase in trace indentation at each call level.
+@end deffn
+@anchor{Variable sb-debug *max-trace-indentation*}
+@vvindex @sortas{max-trace-indentation* sb-debug} *max-trace-indentation* [sb-debug]
+@deffn{Variable} sb-debug:*max-trace-indentation*
+If the trace indentation exceeds this value, then indentation restarts
+at 0.
+@end deffn
+@anchor{Variable sb-debug *trace-encapsulate-default*}
+@vvindex @sortas{trace-encapsulate-default* sb-debug} *trace-encapsulate-default* [sb-debug]
+@deffn{Variable} sb-debug:*trace-encapsulate-default*
+The default value for the @code{:encapsulate} option to @code{trace}.
+@end deffn
+@anchor{Variable sb-debug *trace-report-default*}
+@vvindex @sortas{trace-report-default* sb-debug} *trace-report-default* [sb-debug]
+@deffn{Variable} sb-debug:*trace-report-default*
+The default value for the @code{:report} option to @code{trace}.
+@end deffn
+@node single stepping
@section Single Stepping
-@cindex Stepper
-@cindex Single Stepping
SBCL includes an instrumentation based single-stepper for compiled
-code, that can be invoked via the @code{step} macro, or from within
-the debugger. @xref{Debugger Policy Control}, for details on enabling
+code, that can be invoked via the @code{step} macro, or from within the
+debugger. See @ref{debugger policy control}, for details on enabling
stepping for compiled code.
The following debugger commands are used for controlling single stepping.
-@deffn {Debugger Command} @nopkg{start}
-Selects the @code{continue} restart if one exists and starts single stepping.
-None of the other single stepping commands can be used before stepping has
-been started either by using @code{start} or by using the standard
-@code{step} macro.
-@end deffn
+@itemize
+@item @code{start}: Select the @code{continue} restart if one exists and starts
+ single stepping. None of the other single stepping commands can be
+ used before stepping has been started either by using @code{start} or
+ by using the standard @code{step} macro.
-@deffn {Debugger Command} @nopkg{step}
-Steps into the current form. Stepping will be resumed when the next
-form that has been compiled with stepper instrumentation is evaluated.
-@end deffn
+@item @code{step}: Step into the current form. Stepping will be resumed when
+ the next form that has been compiled with stepper instrumentation
+ is evaluated.
-@deffn {Debugger Command} @nopkg{next}
-Steps over the current form. Stepping will be disabled until evaluation of
-the form is complete.
-@end deffn
+@item @code{next}: Step over the current form. Stepping will be disabled
+ until evaluation of the form is complete.
-@deffn {Debugger Command} @nopkg{out}
-Steps out of the current frame. Stepping will be disabled until the
-topmost stack frame that had been stepped into returns.
-@end deffn
+@item @code{out}: Step out of the current frame. Stepping will be disabled
+ until the topmost stack frame that had been stepped into returns.
-@deffn {Debugger Command} @nopkg{stop}
-Stops the single stepper and resumes normal execution.
-@end deffn
-
-@include macro-common-lisp-step.texinfo
+@item @code{stop}: Stop the single stepper and resumes normal execution.
+@end itemize
-@node Enabling and Disabling the Debugger
-@comment node-name, next, previous, up
+@anchor{Macro common-lisp step}
+@ffindex @sortas{step common-lisp} step [common-lisp]
+@deffn{Macro} step form
+The form is evaluated with single stepping enabled. Function calls
+outside the lexical scope of the form can be stepped into only if the
+functions in question have been compiled with sufficient @code{debug} policy
+to be at least partially steppable.
+@end deffn
+@node enabling and disabling the debugger
@section Enabling and Disabling the Debugger
-@cindex debugger, enabling
-@cindex debugger, disabling
-@cindex disabling debugger
-@cindex ldb, enabling
-@cindex ldb, disabling
-@cindex disabling ldb
-
-In certain contexts (e.g., non-interactive applications), it may be
+In certain contexts (e.g. non-interactive applications), it may be
desirable to turn off the SBCL debugger (and possibly re-enable it).
The functions here control the debugger.
-@include fun-sb-ext-disable-debugger.texinfo
-
-@include fun-sb-ext-enable-debugger.texinfo
+@anchor{Function sb-ext disable-debugger}
+@ffindex @sortas{disable-debugger sb-ext} disable-debugger [sb-ext]
+@deffn{Function} sb-ext:disable-debugger
+When invoked, this function will turn off both the SBCL debugger
+and @code{ldb} (the low-level debugger). See also @code{enable-debugger}.
+@end deffn
+@anchor{Function sb-ext enable-debugger}
+@ffindex @sortas{enable-debugger sb-ext} enable-debugger [sb-ext]
+@deffn{Function} sb-ext:enable-debugger
+Restore the debugger if it has been turned off by @code{disable-debugger}.
+@end deffn
diff --git a/doc/manual/deprecation.texinfo b/doc/manual/deprecation.texinfo
index 173e52e99..ee7cae580 100644
--- a/doc/manual/deprecation.texinfo
+++ b/doc/manual/deprecation.texinfo
@@ -1,279 +1,272 @@
-@node Deprecation
-@comment node-name, next, previous, up
+@c Generated by the sb-manual contrib. Do not edit.
+
+@node deprecation
@chapter Deprecation
+@menu
+* Why Deprecate?: why deprecate?.
+* The Deprecation Pipeline: the deprecation pipeline.
+* Deprecation Conditions: deprecation conditions.
+* Introspecting Deprecation Information: introspecting deprecation information.
+* Deprecation Declaration: deprecation declaration.
+* Deprecation Examples: deprecation examples.
+* Deprecated Interfaces in SBCL: deprecated interfaces in sbcl.
+@end menu
+
In order to support evolution of interfaces in SBCL as well as in user
code, SBCL allows declaring functions, variables and types as
-deprecated. Users of deprecated things are notified by means of warnings
-while the deprecated thing in question is still available.
+deprecated. Users of deprecated things are notified by means of
+warnings while the deprecated thing in question is still available.
This chapter documents the interfaces for being notified when using
deprecated thing and declaring things as deprecated, the deprecation
-process used for SBCL interfaces, and lists legacy interfaces in various
-stages of deprecation.
+process used for SBCL interfaces, and lists legacy interfaces in
+various stages of deprecation.
-@dfn{Deprecation} in this context should not be confused with those
-things the ANSI Common Lisp standard calls @dfn{deprecated}: the
-entirety of ANSI CL is supported by SBCL, and none of those interfaces
-are subject to censure.
+@emph{Deprecation} in this context should not be confused with those
+things the ANSI Common Lisp standard calls @emph{deprecated}: the
+entirety of ANSI CL is supported by SBCL, and none of those
+interfaces are subject to censure.
-@menu
-* Why Deprecate?::
-* The Deprecation Pipeline::
-* Deprecation Conditions::
-* Introspecting Deprecation Information::
-* Deprecation Declaration::
-* Deprecation Examples::
-* Deprecated Interfaces in SBCL::
-@end menu
-
-@node Why Deprecate?
-@comment node-name, next, previous, up
+@node why deprecate?
@section Why Deprecate?
-@cindex Why Deprecate?
While generally speaking we try to keep SBCL changes as backwards
compatible as feasible, there are situations when existing interfaces
are deprecated:
@itemize
-
@item @strong{Broken Interfaces}
-Sometimes it turns out that an interface is sufficiently misdesigned
-that fixing it would be worse than deprecating it and replacing it
-with another.
+Sometimes it turns out that an interface is sufficiently
+misdesigned that fixing it would be worse than deprecating it
+and replacing it with another.
-This is typically the case when fixing the interface would change its
-semantics in ways that could break user code subtly: in such cases we
-may end up considering the obvious breakage caused by deprecation to
-be preferable.
+This is typically the case when fixing the interface would
+change its semantics in ways that could break user code subtly:
+in such cases we may end up considering the obvious breakage
+caused by deprecation to be preferable.
-Another example are functions or macros whose current signature makes
-them hard or impossible to extend in the future: backwards compatible
-extensions would either make the interface intolerably hairy, or are
-sometimes outright impossible.
+Another example are functions or macros whose current signature
+makes them hard or impossible to extend in the future: backwards
+compatible extensions would either make the interface
+intolerably hairy, or are sometimes outright impossible.
@item @strong{Internal Interfaces}
-SBCL has several internal interfaces that were never meant to be used
-in user code -- or at least never meant to be used in user code
-unwilling to track changes to SBCL internals.
+SBCL has several internal interfaces that were never meant to be
+used in user code -- or at least never meant to be used in user
+code unwilling to track changes to SBCL internals.
-Ideally we'd like to be free to refactor our own internals as we
-please, without even going through the hassle of deprecating things.
-Sometimes, however, it turns out that our internal interfaces have
-several external users who aren't using them advisedly, but due to
-misunderstandings regarding their status or stability.
+Ideally, we'd like to be free to refactor our own internals as
+we please, without even going through the hassle of deprecating
+things. Sometimes, however, it turns out that our internal
+interfaces have several external users who aren't using them
+advisedly, but due to misunderstandings regarding their status
+or stability.
Consider a deprecated internal interface a reminder for SBCL
-maintainers not to delete the thing just yet, even though it is seems
-unused -- because it has external users.
+maintainers not to delete the thing just yet, even though it is
+seems unused -- because it has external users.
-When internal interfaces are deprecated we try our best to provide
-supported alternatives.
+When internal interfaces are deprecated we try our best to
+provide supported alternatives.
@item @strong{Aesthetics & Ease of Maintenance}
-Sometimes an interface isn't broken or internal, but just inconsistent
-somehow.
+Sometimes an interface isn't broken or internal but just
+inconsistent somehow.
-This mostly happens only with historical interfaces inherited from
-CMUCL which often haven't been officially supported in SBCL before, or
-with new extensions to SBCL that haven't been around for very long in
-the first place.
+This mostly happens only with historical interfaces inherited
+from CMUCL which often haven't been officially supported in SBCL
+before, or with new extensions to SBCL that haven't been around
+for very long in the first place.
The alternative would be to keep the suboptimal version around
-forever, possibly alongside an improved version. Sometimes we may do
-just that, but because every line of code comes with a maintenance
-cost, sometimes we opt to deprecate the suboptimal version instead:
-SBCL doesn't have infinite developer resources.
-
-We also believe that sometimes cleaning out legacy interfaces helps
-keep the whole system more comprehensible to users, and makes
-introspective tools such as
-@findex @cl{apropos}
-@code{apropos} more useful.
+forever, possibly alongside an improved version. Sometimes we
+may do just that, but because every line of code comes with a
+maintenance cost, sometimes we opt to deprecate the suboptimal
+version instead: SBCL doesn't have infinite developer resources.
+We also believe that sometimes cleaning out legacy interfaces
+helps keep the whole system more comprehensible to users, and
+makes introspective tools such as @code{apropos} more useful.
@end itemize
-@node The Deprecation Pipeline
-@comment node-name, next, previous, up
+@node the deprecation pipeline
@section The Deprecation Pipeline
-@cindex The Deprecation Pipeline
-SBCL uses a @dfn{deprecation pipeline} with multiple stages: as time
-goes by, deprecated things move from earlier stages of deprecation to
-later stages before finally being removed. The intention is making users
-aware of necessary changes early but allowing a migration to new
-interfaces at a reasonable pace.
+SBCL uses a @emph{deprecation pipeline} with multiplestages: as
+time time goes by, deprecated things move from earlier stages of
+deprecation to later stages before finally being removed. The
+intention is making users aware of necessary changes early but
+allowing a migration to new interfaces at a reasonable pace.
Deprecation proceeds in three stages, each lasting approximately a
year. In some cases it might move slower or faster, but one year per
stage is what we aim at in general. During each stage warnings (and
errors) of increasing severity are signaled, which note that the
-interface is deprecated, and point users towards any replacements when
-applicable.
-
-@enumerate
+interface is deprecated, and point users towards any replacements
+when applicable.
+@itemize
@item @strong{Early Deprecation}
During early deprecation the interface is kept in working
-condition. However, when a thing in this deprecation stage is used, an
-@tindex @sbext{early-deprecation-warning}
-@code{sb-ext:early-deprecation-warning}, which is a
-@tindex @cl{style-warning}
-@code{style-warning}, is signaled at
-compile-time.
+condition. However, when a thing in this deprecation stage is
+used, an @code{sb-ext:early-deprecation-warning}, which is a
+@code{style-warning}, is signaled at compile-time.
-The internals may change at this stage: typically because the interface
-is re-implemented on top of its successor. While we try to keep things
-as backwards-compatible as feasible (taking maintenance costs into account),
-sometimes semantics change slightly.
+The internals may change at this stage: typically because the
+interface is re-implemented on top of its successor. While we
+try to keep things as backwards-compatible as feasible (taking
+maintenance costs into account), sometimes semantics change
+slightly.
-For example, when the spinlock API was deprecated, spinlock objects ceased
-to exist, and the whole spinlock API became a synonym for the mutex
-API -- so code using the spinlock API continued working, but silently
-switched to mutexes instead. However, if someone relied on
+For example, when the spinlock API was deprecated, spinlock
+objects ceased to exist, and the whole spinlock API became a
+synonym for the mutex API -- so code using the spinlock API
+continued working but silently switched to mutexes instead.
+However, if someone relied on
- @code{(typep lock 'spinlock)}
+@example
+(typep lock 'spinlock)
+@end example
-returning @code{NIL} for a mutexes, trouble could ensue.
+returning @code{nil} for a mutexes, trouble could ensue.
@item @strong{Late Deprecation}
-During late deprecation the interface remains as it was during early
-deprecation, but the compile-time warning is upgraded: when a thing in
-this deprecation stage is used, a
-@tindex @sbext{late-deprecation-warning}
-@code{sb-ext:late-deprecation-warning},
-which is a full
-@tindex @cl{warning}
-@code{warning}, is signaled at compile-time.
+During late deprecation the interface remains as it was during
+early deprecation, but the compile-time warning is upgraded:
+when a thing in this deprecation stage is used, a
+@code{sb-ext:late-deprecation-warning}, which is a full @code{warning}, is
+signaled at compile-time.
@item @strong{Final Deprecation}
-During final deprecation the symbols still exist. However, when a thing
-in this deprecation stage is used, a
-@tindex @sbext{final-deprecation-warning}
-@code{sb-ext:final-deprecation-warning},
-which is a full
-@tindex @cl{warning}
-@code{warning}, is signaled at compile-time and an
-@tindex @cl{error}
-@code{error} is signaled at run-time.
+During final deprecation the symbols still exist. However, when
+a thing in this deprecation stage is used, a
+@code{sb-ext:final-deprecation-warning}, which is a full @code{warning}, is
+signaled at compile-time and an @code{error} is signaled at run-time.
@item @strong{After Final Deprecation}
The interface is deleted entirely.
+@end itemize
-@end enumerate
-
-@node Deprecation Conditions
-@comment node-name, next, previous, up
+@node deprecation conditions
@section Deprecation Conditions
-@cindex Deprecation Conditions
-@tindex @sbext{deprecation-condition}
@code{sb-ext:deprecation-condition} is the superclass of all
deprecation-related warning and error conditions. All common slots and
readers are defined in this condition class.
-@include condition-sb-ext-deprecation-condition.texinfo
-
-@include condition-sb-ext-early-deprecation-warning.texinfo
-
-@include condition-sb-ext-late-deprecation-warning.texinfo
-
-@include condition-sb-ext-final-deprecation-warning.texinfo
-
-@include condition-sb-ext-deprecation-error.texinfo
-
-@node Introspecting Deprecation Information
-@comment node-name, next, previous, up
+@anchor{Condition sb-ext deprecation-condition}
+@ttindex @sortas{deprecation-condition sb-ext} deprecation-condition [sb-ext]
+@deffn{Condition} sb-ext:deprecation-condition
+Superclass for deprecation-related error and warning
+conditions.
+@end deffn
+@anchor{Condition sb-ext early-deprecation-warning}
+@ttindex @sortas{early-deprecation-warning sb-ext} early-deprecation-warning [sb-ext]
+@deffn{Condition} sb-ext:early-deprecation-warning
+This warning is signaled when the use of a variable,
+function, type, etc. in @code{:early} deprecation is detected at
+compile-time. The use will work at run-time with no warning or
+error.
+@end deffn
+@anchor{Condition sb-ext late-deprecation-warning}
+@ttindex @sortas{late-deprecation-warning sb-ext} late-deprecation-warning [sb-ext]
+@deffn{Condition} sb-ext:late-deprecation-warning
+This warning is signaled when the use of a variable,
+function, type, etc. in @code{:late} deprecation is detected at
+compile-time. The use will work at run-time with no warning or
+error.
+@end deffn
+@anchor{Condition sb-ext final-deprecation-warning}
+@ttindex @sortas{final-deprecation-warning sb-ext} final-deprecation-warning [sb-ext]
+@deffn{Condition} sb-ext:final-deprecation-warning
+This warning is signaled when the use of a variable,
+function, type, etc. in @code{:final} deprecation is detected at
+compile-time. An error will be signaled at run-time.
+@end deffn
+@anchor{Condition sb-ext deprecation-error}
+@ttindex @sortas{deprecation-error sb-ext} deprecation-error [sb-ext]
+@deffn{Condition} sb-ext:deprecation-error
+This error is signaled at run-time when an attempt is made to use
+a thing that is in @code{:final} deprecation, i.e. call a function or access
+a variable.
+@end deffn
+@node introspecting deprecation information
@section Introspecting Deprecation Information
-@cindex Introspecting Deprecation Information
-@comment TODO @findex @sbcltl{function-information}
-@comment TODO @findex @sbcltl{variable-information}
The deprecation status of functions and variables can be inspected
using the @code{sb-cltl2:function-information} and
-@code{sb-cltl2:variable-information} functions provided by the
-@code{sb-cltl2} contributed module.
+@code{sb-cltl2:variable-information} functions provided by the @code{sb-cltl2}
+contributed module.
-@node Deprecation Declaration
-@comment node-name, next, previous, up
+@node deprecation declaration
@section Deprecation Declaration
-@cindex Deprecation Declaration
-@findex @sbext{deprecated}
The @code{sb-ext:deprecated} declaration can be used to declare objects
-in various namespaces@footnote{See ``namespace'' entry in the glossary
-of the Common Lisp Hyperspec.} as deprecated.
+in various namespaces as deprecated.
-@deffn {Declaration} @sbext{deprecated}
+@quotation
+@emph{Note}: See the @code{namespace} @code{clhs} glossary entry in the glossary of
+the Common Lisp Hyperspec.)
+@end quotation
-Syntax:
-@example
-@code{sb-ext:deprecated} stage since @{object-clause@}*
+@itemize
+@item [@strong{declaration}] @code{sb-ext:deprecated}
-stage ::= @{:early | :late | :final@}
+Syntax: @code{(sb-ext:deprecated stage since &rest object-clauses)}
-since ::= @{@var{version} | (@var{software} @var{version})@}
+stage ::= @{@code{:early} | @code{:late} | @code{:final}@}
-object-clause ::= (namespace @var{name} [:replacement @var{replacement}])
+since ::= @{@code{<version>} | (@code{<software>} @code{<version>})@}
-namespace ::= @{cl:variable | cl:function | cl:type@}
-@end example
+object-clause ::= (namespace @code{<name>} [@code{:replacement} @code{<replacement>}])
-@noindent were @var{name} is the name of the deprecated thing,
-@var{version} and @var{software} are strings describing the version in
-which the thing has been deprecated and @var{replacement} is a name or a
-list of names designating things that should be used instead of the
-deprecated thing.
+namespace ::= @{@code{cl:variable} | @code{cl:function} | @code{cl:type}@}
+
+where the terminal @code{<name>} is the name of the deprecated thing,
+@code{<version>} and @code{<software>} are strings describing the version
+in which the thing has been deprecated and @code{<replacement>} is a
+name or a list of names designating things that should be used
+instead of the deprecated thing.
Currently the following namespaces are supported:
-@table @code
+@itemize
+@item @code{cl:function}: Declare functions, compiler-macros or macros as
+ deprecated.
-@item cl:function
-Declare functions, compiler-macros or macros as deprecated.
-
-@quotation note
When declaring a function to be in @code{:final} deprecation, there
-should be no actual definition of the function as the declaration emits
-a stub function that signals a
-@tindex @sbext{deprecation-error}
+should be no actual definition of the function as the
+declaration emits a stub function that signals a
@code{sb-ext:deprecation-error} at run-time when called.
-@end quotation
-@item cl:variable
-Declare special and global variables, constants and symbol-macros as
-deprecated.
+@item @code{cl:variable}: Declare special and global variables, constants
+ and symbol-macros as deprecated.
-@quotation note
When declaring a variable to be in @code{:final} deprecation, there
-should be no actual definition of the variable as the declaration emits
-a symbol-macro that signals a
-@tindex @sbext{deprecation-error}
+should be no actual definition of the variable as the
+declaration emits a symbol-macro that signals a
@code{sb-ext:deprecation-error} at run-time when accessed.
-@end quotation
-@item cl:type
-Declare named types (i.e. defined via @code{deftype}), standard classes,
-structure classes and condition classes as deprecated.
+@item @code{cl:type}: Declare named types (i.e. defined via @code{deftype}),
+ standard classes, structure classes and condition classes as
+ deprecated.
+@end itemize
+@end itemize
-@end table
-@end deffn
-
-@node Deprecation Examples
-@comment node-name, next, previous, up
+@node deprecation examples
@section Deprecation Examples
-@cindex Deprecation Examples
Marking functions as deprecated:
-@lisp
+
+@example
(defun foo ())
(defun bar ())
(declaim (deprecated :early ("my-system" "1.2.3")
@@ -283,10 +276,11 @@ Marking functions as deprecated:
;; :final deprecation:
(declaim (deprecated :final ("my-system" "1.2.3")
(function fez :replacement whoop)))
-@end lisp
+@end example
-@noindent Attempting to use the deprecated functions:
-@lisp
+Attempting to use the deprecated functions:
+
+@example
(defun baz ()
(foo))
| STYLE-WARNING: The function CL-USER::FOO has been deprecated...
@@ -300,69 +294,75 @@ Marking functions as deprecated:
=> DANGER
(danger)
|- ERROR: The function CL-USER::FEZ has been deprecated...
-@end lisp
+@end example
-@node Deprecated Interfaces in SBCL
-@comment node-name, next, previous, up
+@node deprecated interfaces in sbcl
@section Deprecated Interfaces in SBCL
+@menu
+* List of Deprecated Interfaces: list of deprecated interfaces.
+* Historical Interfaces: historical interfaces.
+@end menu
+
This sections lists legacy interfaces in various stages of deprecation.
+@node list of deprecated interfaces
@subsection List of Deprecated Interfaces
+@menu
+* Early Deprecation: early deprecation.
+* Late Deprecation: late deprecation.
+* Final Deprecation: final deprecation.
+@end menu
+
+@node early deprecation
@subsubsection Early Deprecation
-@tindex @sbext{early-deprecation-warning}
-
@itemize
-
-@item @strong{SOCKINT::WIN32-*}
+@item @code{sockint::win32-*}
Deprecated in favor of the corresponding prefix-less functions
(e.g. @code{sockint::bind} replaces @code{sockint::win32-bind}) as of
-1.2.10 in March 2015. Expected to move into late deprecation in August
-2015.
+1.2.10 in March 2015. Expected to move into late deprecation in
+August 2015.
-@sp 1
-@item @strong{SB-UNIX:UNIX-EXIT}
+@item @code{sb-unix:unix-exit}
-Deprecated as of 1.0.56.55 in May 2012. Expected to move into late
-deprecation in May 2013.
+Deprecated as of 1.0.56.55 in May 2012. Expected to move into
+late deprecation in May 2013.
-When the SBCL process termination was refactored as part of changes that
-led to @code{sb-ext:quit} being deprecated, @code{sb-unix:unix-exit}
-ceased to be used internally. Since @code{SB-UNIX} is an internal package
-not intended for user code to use, and since we're slowly in the process
-of refactoring things to be less Unix-oriented, @code{sb-unix:unix-exit}
-was initially deleted as it was no longer used. Unfortunately it became
-apparent that it was used by several external users, so it was re-instated
-in deprecated form.
+When the SBCL process termination was refactored,
+@code{sb-unix:unix-exit} ceased to be used internally. Since @code{sb-unix}
+is an internal package not intended for user code to use, and
+since we're slowly in the process of refactoring things to be
+less Unix-oriented, @code{sb-unix:unix-exit} was initially deleted as
+it was no longer used. Unfortunately it became apparent that it
+was used by several external users, so it was re-instated in
+deprecated form.
While the cost of keeping @code{sb-unix:unix-exit} indefinitely is
-trivial, the ability to refactor our internals is important, so its
-deprecation was taken as an opportunity to highlight that
-@code{SB-UNIX} is an internal package and @code{SB-POSIX} should be
-used by user-programs instead -- or alternatively calling the foreign
-function directly if the desired interface doesn't for some reason
-exist in @code{SB-POSIX}.
+trivial, the ability to refactor our internals is important, so
+its deprecation was taken as an opportunity to highlight that
+@code{sb-unix} is an internal package and @code{sb-posix} should be used
+by user-programs instead -- or alternatively calling the foreign
+function directly if the desired interface doesn't for some
+reason exist in @code{sb-posix}.
@strong{Remedy}
-For code needing to work with legacy SBCLs, use e.g. @code{system-exit}
-as show above in remedies for @code{sb-ext:quit}. In modern SBCLs
-simply call either @code{sb-posix:exit} or @code{sb-ext:exit} with
-appropriate arguments.
+For code needing to work with legacy SBCLs, use e.g.
+@code{system-exit}. In modern SBCLs, simply call either @code{sb-posix:exit}
+or @code{sb-ext:exit} with appropriate arguments.
-@sp 1
-@item @strong{SB-C::MERGE-TAIL-CALLS Compiler Policy}
+@item @code{sb-c::merge-tail-calls} compiler policy
-Deprecated as of 1.0.53.74 in November 2011. Expected to move into
-late deprecation in November 2012.
+Deprecated as of 1.0.53.74 in November 2011. Expected to move
+into late deprecation in November 2012.
-This compiler policy was never functional: SBCL has always merged tail
-calls when it could, regardless of this policy setting. (It was also
-never officially supported, but several code-bases have historically
-used it.)
+This compiler policy was never functional: SBCL has always
+merged tail calls when it could, regardless of this policy
+setting. (It was also never officially supported, but several
+code-bases have historically used it.)
@strong{Remedy}
@@ -370,52 +370,49 @@ Simply remove the policy declarations. They were never necessary: SBCL
always merged tail-calls when possible. To disable tail merging,
structure the code to avoid the tail position instead.
-@sp 1
-@item @strong{Spinlock API}
+@item The Spinlock API
-Deprecated as of 1.0.53.11 in August 2011. Expected to move into late
-deprecation in August 2012.
+Deprecated as of 1.0.53.11 in August 2011. Expected to move into
+late deprecation in August 2012.
-Spinlocks were an internal interface, but had a number of external users
-and were hence deprecated instead of being simply deleted.
+Spinlocks were an internal interface but had a number of
+external users and were hence deprecated instead of being simply
+deleted.
-Affected symbols: @code{sb-thread::spinlock},
-@code{sb-thread::make-spinlock}, @code{sb-thread::with-spinlock},
-@code{sb-thread::with-recursive-spinlock},
+Affected symbols: @code{sb-thread::spinlock}, @code{sb-thread::make-spinlock},
+@code{sb-thread::with-spinlock}, @code{sb-thread::with-recursive-spinlock},
@code{sb-thread::get-spinlock}, @code{sb-thread::release-spinlock},
@code{sb-thread::spinlock-value}, and @code{sb-thread::spinlock-name}.
@strong{Remedy}
-Use the mutex API instead, or implement spinlocks suiting your needs
-on top of @code{sb-ext:compare-and-swap},
-@code{sb-ext:spin-loop-hint}, etc.
+Use the mutex API instead, or implement spinlocks suiting your
+needs on top of @code{sb-ext:compare-and-swap}, @code{sb-ext:spin-loop-hint},
+etc.
-@item @strong{SOCKINT::HANDLE->FD}, @strong{SOCKINT::FD->HANDLE}
-
-Internally deprecated in 2012. Declared deprecated as of 1.2.10 in March
-2015. Expected to move into final deprecation in August 2015.
+@item @code{sockint::handle->fd}, @code{sockint::fd->handle}
+Internally deprecated in 2012. Declared deprecated as of 1.2.10
+in March 2015. Expected to move into final deprecation in August
+2015.
@end itemize
+@node late deprecation
@subsubsection Late Deprecation
-@tindex @sbext{late-deprecation-warning}
-
@itemize
-
-@item @strong{SB-THREAD:JOIN-THREAD-ERROR-THREAD and SB-THREAD:INTERRUPT-THREAD-ERROR-THREAD}
+@item @code{sb-thread:join-thread-error-thread} and
+ @code{sb-thread:interrupt-thread-error-thread}
Deprecated in favor of @code{sb-thread:thread-error-thread} as of
-1.0.29.17 in June 2009. Expected to move into final deprecation in
-June 2012.
+1.0.29.17 in June 2009. Expected to move into final deprecation
+in June 2012.
@strong{Remedy}
For code that needs to support legacy SBCLs, use e.g.:
-@sp 1
-@lisp
+@example
(defun get-thread-error-thread (condition)
#+#.(cl:if (cl:find-symbol "THREAD-ERROR-THREAD" :sb-thread)
'(and) '(or))
@@ -427,25 +424,22 @@ For code that needs to support legacy SBCLs, use e.g.:
(sb-thread:join-thread-error-thread condition))
(sb-thread:interrupt-thread-error
(sb-thread:interrupt-thread-error-thread condition))))
-@end lisp
-@sp 1
+@end example
-@sp 1
-@item @strong{SB-INTROSPECT:FUNCTION-ARGLIST}
+@item @code{sb-introspect:function-arglist}
Deprecated in favor of @code{sb-introspect:function-lambda-list} as of
-1.0.24.5 in January 2009. Expected to move into final deprecation in
-January 2012.
+1.0.24.5 in January 2009. Expected to move into final
+deprecation in January 2012.
-Renamed for consistency and aesthetics. Functions have lambda-lists,
-not arglists.
+Renamed for consistency and aesthetics. Functions have
+lambda-lists, not arglists.
@strong{Remedy}
+@example
For code that needs to support legacy SBCLs, use e.g.:
-@sp 1
-@lisp
(defun get-function-lambda-list (function)
#+#.(cl:if (cl:find-symbol "FUNCTION-LAMBDA-LIST" :sb-introspect)
'(and) '(or))
@@ -453,43 +447,38 @@ For code that needs to support legacy SBCLs, use e.g.:
#-#.(cl:if (cl:find-symbol "FUNCTION-LAMBDA-LIST" :sb-introspect)
'(and) '(or))
(sb-introspect:function-arglist function))
-@end lisp
-@sp 1
+@end example
-@sp 1
-@item @strong{Stack Allocation Policies}
+@item Stack Allocation Policies
-Deprecated in favor of @code{sb-ext:*stack-allocate-dynamic-extent*}
-as of 1.0.19.7 in August 2008, and are expected to be removed in
+Deprecated in favor of @code{sb-ext:*stack-allocate-dynamic-extent*} as
+of 1.0.19.7 in August 2008, and are expected to be removed in
August 2012.
Affected symbols: @code{sb-c::stack-allocate-dynamic-extent},
@code{sb-c::stack-allocate-vector}, and
@code{sb-c::stack-allocate-value-cells}.
-These compiler policies were never officially supported, and turned
-out the be a flawed design.
+These compiler policies were never officially supported, and
+turned out the be a flawed design.
@strong{Remedy}
-For code that needs stack-allocation in legacy SBCLs, conditionalize
-using:
+For code that needs stack-allocation in legacy SBCLs,
+conditionalize using:
-@sp 1
-@lisp
+@example
#-#.(cl:if (cl:find-symbol "*STACK-ALLOCATE-DYNAMIC-EXTENT*" :sb-ext)
'(and) '(or))
(declare (optimize sb-c::stack-allocate-dynamic-extent))
-@end lisp
-@sp 1
+@end example
-However, unless stack allocation is essential, we recommend simply
-removing these declarations. Refer to documentation on
-@code{sb-ext:*stack-allocate-dynamic*} for details on stack allocation
-control in modern SBCLs.
+However, unless stack allocation is essential, we recommend
+simply removing these declarations. Refer to documentation on
+@code{sb-ext:*stack-allocate-dynamic*} for details on stack
+allocation control in modern SBCLs.
-@sp 1
-@item @strong{SB-SYS:OUTPUT-RAW-BYTES}
+@item @code{sb-sys:output-raw-bytes}
Deprecated as of 1.0.8.16 in June 2007. Expected to move into final
deprecation in June 2012.
@@ -500,39 +489,36 @@ bivalent streams.
@strong{Remedy}
-Use streams with element-type @code{(unsigned-byte 8)}
-or @code{:default} -- the latter allowing both binary and
-character IO -- in conjunction with @code{write-sequence}.
-
+Use streams with element-type (@code{unsigned-byte} 8) or
+@code{:default} -- the latter allowing both binary and character IO --
+in conjunction with @code{write-sequence}.
@end itemize
+@node final deprecation
@subsubsection Final Deprecation
-@tindex @sbext{final-deprecation-warning}
-
No interfaces are currently in final deprecation.
+@node historical interfaces
@subsection Historical Interfaces
The following is a partial list of interfaces present in historical
versions of SBCL, which have since then been deleted.
@itemize
+@item @code{sb-kernel:instance-lambda}
-@item @strong{SB-KERNEL:INSTANCE-LAMBDA}
+Historically needed for CLOS code. Deprecated as of 0.9.3.32 in
+August 2005. Deleted as of 1.0.47.8 in April 2011. Plain @code{lambda}
+can be used where SB-KERNEL:INSTANCE-LAMBDA used to be needed.
-Historically needed for CLOS code. Deprecated as of 0.9.3.32 in August
-2005. Deleted as of 1.0.47.8 in April 2011. Plain @code{lambda} can be
-used where @code{sb-kernel:instance-lambda} used to be needed.
-
-@sp 1
-@item @strong{SB-ALIEN:DEF-ALIEN-ROUTINE, SB-ALIEN:DEF-ALIEN-VARIABLE, SB-ALIEN:DEF-ALIEN-TYPE}
-
-Inherited from CMUCL, naming convention not consistent with preferred
-SBCL style. Deprecated as of 0.pre7.90 in December 2001. Deleted as of
-1.0.9.17 in September 2007. Replaced by
-@code{sb-alien:define-alien-routine},
-@code{sb-alien:define-alien-variable}, and
-@code{sb-alien:define-alien-type}.
+@item @code{sb-alien:def-alien-routine}, @code{sb-alien:def-alien-variable},
+ @code{sb-alien:def-alien-type}
+Inherited from CMUCL, naming convention not consistent with
+preferred SBCL style. Deprecated as of 0.pre7.90 in December
+2001. Deleted as of 1.0.9.17 in September 2007. Replaced by
+@code{sb-alien:define-alien-routine}, @code{sb-alien:define-alien-variable},
+and @code{sb-alien:define-alien-type}.
@end itemize
+
diff --git a/doc/manual/efficiency.texinfo b/doc/manual/efficiency.texinfo
index b13198598..915aaaed8 100644
--- a/doc/manual/efficiency.texinfo
+++ b/doc/manual/efficiency.texinfo
@@ -1,46 +1,52 @@
-@node Efficiency
-@comment node-name, next, previous, up
+@c Generated by the sb-manual contrib. Do not edit.
+
+@node efficiency
@chapter Efficiency
-@cindex Efficiency
@menu
-* Slot access::
-* Stack allocation::
-* Modular arithmetic::
-* Recognized idioms::
-* Global and Always-Bound variables::
-* Miscellaneous Efficiency Issues::
+* Slot Access: slot access.
+* Stack Allocation: stack allocation.
+* Modular Arithmetic: modular arithmetic.
+* Recognized Idioms: recognized idioms.
+* Global and Always-bound Variables: global and always bound variables.
+* Miscellaneous Efficiency Issues: miscellaneous efficiency issues.
@end menu
-@node Slot access
-@comment node-name, next, previous, up
-@section Slot access
-@cindex Slot access
+@node slot access
+@section Slot Access
-@subsection Structure object slot access
+@menu
+* Structure Object Slot Access: structure object slot access.
+* Standard Object Slot Access: standard object slot access.
+@end menu
+
+@node structure object slot access
+@subsection Structure Object Slot Access
-Structure slot accessors are efficient only if the compiler is able to
-open code them: compiling a call to a structure slot accessor before
-the structure is defined, declaring one @code{notinline}, or passing
-it as a functional argument to another function causes severe
-performance degradation.
+Structure slot accessors are efficient only if the compiler is
+able to open code them: compiling a call to a structure slot
+accessor before the structure is defined, declaring one @code{notinline},
+or passing it as a functional argument to another function causes
+severe performance degradation.
-@subsection Standard object slot access
+@node standard object slot access
+@subsection Standard Object Slot Access
The most efficient way to access a slot of a @code{standard-object} is
by using @code{slot-value} with a constant slot name argument inside a
@code{defmethod} body, where the variable holding the instance is a
-specializer parameter of the method and is never assigned to. The cost
-is roughly 1.6 times that of an open coded structure slot accessor.
+specializer parameter of the method and is never assigned to. The
+cost is roughly 1.6 times that of an open coded structure slot
+accessor.
Second most efficient way is to use a CLOS slot accessor, or
-@code{slot-value} with a constant slot name argument, but in
-circumstances other than specified above. This may be up to 3 times as
-slow as the method described above.
+@code{slot-value} with a constant slot name argument, but in circumstances
+other than specified above. This may be up to 3 times as slow as the
+method described above.
Example:
-@lisp
+@example
(defclass foo () ((bar)))
;; Fast: specializer and never assigned to
@@ -62,96 +68,81 @@ Example:
(setf (slot-value foo 'bar) new)
(setf foo new)
old))
-@end lisp
+@end example
Note that when profiling code such as this, the first few calls to the
generic function are not representative, as the dispatch mechanism is
lazily set up during those calls.
-@node Stack allocation
-@comment node-name, next, previous, up
-@section Stack allocation
-@cindex @code{dynamic-extent} declaration
-@cindex declaration, @code{dynamic-extent}
+@node stack allocation
+@section Stack Allocation
SBCL has fairly extensive support for performing allocations on the
stack when a variable or function is declared @code{dynamic-extent}. The
-@code{dynamic-extent} declarations are not verified, but are simply
-trusted as long as @code{sb-ext:*stack-allocate-dynamic-extent*} is
-true.
+@code{dynamic-extent} declarations are not verified but are simply trusted
+as long as @code{sb-ext:*stack-allocate-dynamic-extent*} is true.
-@include var-sb-ext-star-stack-allocate-dynamic-extent-star.texinfo
+@anchor{Variable sb-ext *stack-allocate-dynamic-extent*}
+@vvindex @sortas{stack-allocate-dynamic-extent* sb-ext} *stack-allocate-dynamic-extent* [sb-ext]
+@deffn{Variable} sb-ext:*stack-allocate-dynamic-extent*
+If true (the default), the compiler believes @code{dynamic-extent} declarations
+and stack allocates otherwise inaccessible parts of the object whenever
+possible.
+@end deffn
+SBCL recognizes any value which a variable declared @code{dynamic-extent}
+can take on as having dynamic extent. This means that, in addition
+to the value a variable is bound to initially, a value assigned to a
+variable by @code{setq} is also recognized as having dynamic extent when
+the variable is declared @code{dynamic-extent}. Users can thus build
+complex structures on the stack using iteration and @code{setq}.
-SBCL recognizes any value which a variable declared
-@code{dynamic-extent} can take on as having dynamic extent. This means
-that, in addition to the value a variable is bound to initially, a value
-assigned to a variable by @code{setq} is also recognized as having
-dynamic extent when the variable is declared
-@code{dynamic-extent}. Users can thus build complex structures on the
-stack using iteration and @code{setq}.
-
-At present, SBCL implements stack allocation for the following kinds of
-values when they are recognized as having dynamic extent:
+At present, SBCL implements stack allocation for the following kinds
+of values when they are recognized as having dynamic extent:
@itemize
-
-@item
-@code{&rest} lists
-
-@item
-@findex @cl{cons}
-@findex @cl{list}
-@findex @cl{list*}
-@findex @cl{vector}
-the results of @code{cons}, @code{list}, @code{list*}, and @code{vector}
-
-@item
-@findex @cl{make-array}
-the result of simple forms of @code{make-array}: stack allocation is
-possible only if the resulting array is known to be both simple and
-one-dimensional, and has a constant @code{:element-type}.
-
-@cindex Safety optimization quality
-@strong{Note}: stack space is limited, so allocation of a large vector
-may cause stack overflow. Stack overflow checks are done except in zero
-@code{safety} policies.
-
-@item
-@findex @cl{flet}
-@findex @cl{labels}
-@cindex @code{safety} optimization quality
-@cindex optimization quality, @code{safety}
-closures defined with @code{flet} or @code{labels} with a bound
-@code{dynamic-extent} declaration.
-
-@item
-anonymous closures defined with @code{lambda}
-
-@item
-user-defined structures when the structure constructor defined using
-@code{defstruct} has been declared @code{inline}
-
-@strong{Note}: structures with ``raw'' slots can currently be
-stack-allocated only on x86 and x86-64. A ``raw'' slot is one whose
-declared type is a subtype of exactly one of: @code{double-float},
-@code{single-float}, @code{(complex double-float)}, @code{(complex single-float)},
-or @code{sb-ext:word}; but as an exception to the preceding, any subtype
-of @code{fixnum} is not stored as raw despite also being a subtype
-of @code{sb-ext:word}.
-
-@item
-otherwise-inaccessible parts of objects recognized to be dynamic
-extent. The support for detecting when this applies is very
-sophisticated. The compiler can do this detection when any value form
-for a variable contains conditional allocations, function calls, inlined
-functions, anonymous closures, or even other variables. This allows
-stack allocation of complex structures.
-
+@item @code{&rest} lists;
+
+@item the results of @code{cons}, @code{list}, @code{list*}, and @code{vector};
+
+@item the result of simple forms of @code{make-array}: stack allocation is
+ possible only if the resulting array is known to be both simple
+ and one-dimensional, and has a constant @code{:element-type};
+
+@quotation
+@strong{Warning}: Stack space is limited, so allocation of a large
+vector may cause stack overflow. Stack overflow checks are
+done except in zero @code{safety} policies.
+@end quotation
+
+@item closures defined with @code{flet} or @code{labels} with a bound @code{dynamic-extent}
+ declaration;
+
+@item anonymous closures defined with @code{lambda};
+
+@item user-defined structures when the structure constructor defined using
+ @code{defstruct} has been declared @code{inline};
+
+@quotation
+@emph{Note}: Structures with @emph{raw} slots can currently be
+stack-allocated only on x86 and x86-64. A raw slot is one
+whose declared type is a subtype of exactly one of:
+@code{double-float}, @code{single-float}, @code{(complex
+double-float)}, @code{(complex single-float)}, or @code{sb-ext:word}; but
+as an exception to the preceding, any subtype of @code{fixnum} is not
+stored as raw despite also being a subtype of @code{sb-ext:word}.
+@end quotation
+
+@item otherwise-inaccessible parts of objects recognized to be dynamic
+ extent. The support for detecting when this applies is very
+ sophisticated. The compiler can do this detection when any value
+ form for a variable contains conditional allocations, function
+ calls, inlined functions, anonymous closures, or even other
+ variables. This allows stack allocation of complex structures.
@end itemize
Examples:
-@lisp
+@example
;;; Declaiming a structure constructor inline before definition makes
;;; stack allocation possible.
(declaim (inline make-thing))
@@ -190,38 +181,40 @@ Examples:
(defun foo (&rest args)
(declare (dynamic-extent args))
...)
-@end lisp
+@end example
-As a notable exception to recognizing otherwise inaccessible parts of
-other recognized dynamic extent values, SBCL does not as of 1.0.48.21
-propagate dynamic-extentness through @code{&rest} arguments -- but
-another conforming implementation might, so portable code should not
-rely on this.
+As a notable exception to recognizing otherwise inaccessible parts
+of other recognized dynamic extent values, SBCL does not as of
+1.0.48.21 propagate dynamic-extentness through @code{&rest} arguments --
+but another conforming implementation might, so portable code should
+not rely on this.
-@lisp
+@example
(declaim (inline foo))
(defun foo (fun &rest arguments)
(declare (dynamic-extent arguments))
(apply fun arguments))
(defun bar (a)
- ;; SBCL will heap allocate the result of (LIST A), and stack allocate
- ;; only the spine of the &rest list -- so this is safe, but unportable.
+ ;; SBCL will heap allocate the result of (LIST A), and stack
+ ;; allocate only the spine of the &rest list -- so this is
+ ;; safe but unportable.
;;
- ;; Another implementation, including earlier versions of SBCL might consider
- ;; (LIST A) to be otherwise inaccessible and stack-allocate it as well!
+ ;; Another implementation, including earlier versions of SBCL
+ ;; might consider (LIST A) to be otherwise inaccessible and
+ ;; stack-allocate it as well!
(foo #'car (list a)))
-@end lisp
+@end example
If dynamic extent constraints specified in the Common Lisp standard
are violated, the best that can happen is for the program to have
-garbage in variables and return values; more commonly, the system will
-crash.
+garbage in variables and return values; more commonly, the system
+will crash.
In particular, it is important to realize that this can interact in
suprising ways with the otherwise inaccessible parts criterion:
-@lisp
+@example
(let* ((a (list 1 2 3))
(b (cons a a)))
(declare (dynamic-extent b))
@@ -231,18 +224,18 @@ suprising ways with the otherwise inaccessible parts criterion:
;;
;; Hence returning (CAR B) here is unsafe.
...)
-@end lisp
+@end example
SBCL also performs sophisticated escape analysis to enable automatic
stack allocation of local functions without any bound dynamic extent
declarations in many situations where the compiler can prove that no
-uses escape (traditional Lisp terminology names this situation ``all
-uses are downward funargs''). For example, in the following function,
-the local function @code{#'predicatep} is stack allocated, because the
-compiler understands that the built-in function @code{#'position-if}
-only uses its first argument as a downward funarg:
+uses escape (traditional Lisp terminology names this situation "all
+uses are downward funargs"). For example, in the following
+function, the local function @code{#'predicatep} is stack allocated,
+because the compiler understands that the built-in function
+@code{position-if} only uses its first argument as a downward funarg:
-@lisp
+@example
(let ((acc 0))
(flet ((predicatep (num) (plusp (+ num off))))
(dotimes (i 10)
@@ -251,139 +244,150 @@ only uses its first argument as a downward funarg:
(incf acc (if (positivep acc) 10 3))
(incf acc (position-if #'predicatep array))))
acc)
-@end lisp
+@end example
-Users can also declare that their own functions take downward funargs by
-adding bound dynamic extent declarations on the function arguments.
+Users can also declare that their own functions take downward
+funargs by adding bound dynamic extent declarations on the function
+arguments.
-@lisp
+@example
(defun trivial-hof (fun arg)
(declare (dynamic-extent fun))
(funcall fun 3 arg))
-@end lisp
+@end example
-Currently, such dynamic extent declarations only cause stack allocation
-of downward funargs at call sites on sufficiently unsafe policy. This is
-partly because the compiler is currently not able to detect incorrect
-usage of dynamic extent declarations.
+Currently, such dynamic extent declarations only cause stack
+allocation of downward funargs at call sites on sufficiently unsafe
+policy. This is partly because the compiler is currently not able to
+detect incorrect usage of dynamic extent declarations.
-@lisp
+@example
(defun autodxclosure1 (&optional (x 4))
;; Calling a higher-order function will only implicitly
- ;; stack-allocate a funarg if the callee is trusted (a CL: function)
- ;; or the caller is unsafe.
+ ;; stack-allocate a funarg if the callee is trusted (a CL:
+ ;; function) or the caller is unsafe.
(declare (optimize speed (safety 0) (debug 0)))
(trivial-hof (lambda (a b) (+ a b x)) 92))
-@end lisp
+@end example
-@node Modular arithmetic
-@comment node-name, next, previous, up
-@section Modular arithmetic
-@cindex Modular arithmetic
-@cindex Arithmetic, modular
-@cindex Arithmetic, hardware
-@findex @cl{logand}
-Some numeric functions have a property: @var{N} lower bits of the
-result depend only on @var{N} lower bits of (all or some)
-arguments. If the compiler sees an expression of form @code{(logand
-@var{exp} @var{mask})}, where @var{exp} is a tree of such ``good''
-functions and @var{mask} is known to be of type @code{(unsigned-byte
-@var{w})}, where @var{w} is a ``good'' width, all intermediate results
-will be cut to @var{w} bits (but it is not done for variables and
-constants!). This often results in an ability to use simple machine
-instructions for the functions.
+@node modular arithmetic
+@section Modular Arithmetic
-Consider an example.
+@menu
+* Signed Modular Arithmetic: signed modular arithmetic.
+@end menu
-@lisp
+Some numeric functions have a property: n lower bits of the
+result depend only on n lower bits of (all or some) arguments. If
+the compiler sees an expression of form @code{(logand <expr> <mask>)},
+where @code{<expr>} is a tree of such @emph{good} functions and @code{<mask>} is
+known to be of type @code{(unsigned-byte <w>)}, where @code{<w>} is a @emph{good}
+width, all intermediate results will be cut to @code{<w>} bits (but it is
+not done for variables and constants!). This often results in an
+ability to use simple machine instructions for the functions.
+
+Consider this example:
+
+@example
(defun i (x y)
(declare (type (unsigned-byte 32) x y))
(ldb (byte 32 0) (logxor x (lognot y))))
-@end lisp
+@end example
The result of @code{(lognot y)} will be negative and of type
-@code{(signed-byte 33)}, so a naive implementation on a 32-bit
-platform is unable to use 32-bit arithmetic here. But modular
-arithmetic optimizer is able to do it: because the result is cut down
-to 32 bits, the compiler will replace @code{logxor} and @code{lognot}
-with versions cutting results to 32 bits, and because terminals
-(here---expressions @code{x} and @code{y}) are also of type
-@code{(unsigned-byte 32)}, 32-bit machine arithmetic can be used.
+@code{(signed-byte 33)}, so a naive implementation on a 32-bit platform
+is unable to use 32-bit arithmetic here. But modular arithmetic
+optimizer is able to do it: because the result is cut down to 32
+bits, the compiler will replace @code{logxor} and @code{lognot} with versions
+cutting results to 32 bits, and because terminals (here, expressions
+@code{x} and @code{y}) are also of type @code{(unsigned-byte 32)}, 32-bit machine
+arithmetic can be used.
-As of SBCL 0.8.5 ``good'' functions are @code{+}, @code{-};
-@code{logand}, @code{logior}, @code{logxor}, @code{lognot} and their
-combinations; and @code{ash} with the positive second
-argument. ``Good'' widths are 32 on 32-bit CPUs and 64 on 64-bit CPUs.
-While it is possible to support smaller widths as well,
+As of SBCL 0.8.5 good functions are @code{+}, @code{-}, @code{logand}, @code{logior},
+@code{logxor}, @code{lognot} and their combinations; and @code{ash} with the positive
+second argument. Good widths are 32 on 32-bit CPUs and 64 on 64-bit
+CPUs. While it is possible to support smaller widths as well,
currently this is not implemented.
-@subsection Signed modular arithmetic
+@node signed modular arithmetic
+@subsection Signed Modular Arithmetic
-Sign-extending the result in the following way will be translated into
-signed modular arithmetic:
+Sign-extending the result in the following way will be
+translated into signed modular arithmetic:
-@lisp
+@example
(defun add (a b)
(declare (type (signed-byte 64) a b))
(let ((u (ldb (byte 64 0) (+ a b))))
(logior u (- (mask-field (byte 1 63) u)))))
-@end lisp
+@end example
+@node recognized idioms
+@section Recognized Idioms
-@node Recognized idioms
-@comment node-name, next, previous, up
-@section Recognized idioms
-@cindex Arithmetic, modular
-@cindex Arithmetic, hardware
+@menu
+* Count Trailing Zeros: count trailing zeros.
+@end menu
-Common Lisp doesn't directly expose all features present in modern
-hardware. Some code patterns are recognized and turned into more
-efficient hardware instructions without requiring the use of internal
-features.
+Common Lisp doesn't directly expose all features present in
+modern hardware. Some code patterns are recognized and turned into
+more efficient hardware instructions without requiring the use of
+internal features.
-@subsection Count trailing zeros
+@node count trailing zeros
+@subsection Count Trailing Zeros
-@lisp
+@example
(defun ctz (n)
(declare (type (unsigned-byte 64) n))
(integer-length (ldb (byte 64 0) (lognor n (- n)))))
-@end lisp
-is turned into hardware instructions on arm64 and x86-64. It returns 64 when @code{n} is 0.
-@code{n} can also be @code{(signed-byte 64)} or @code{fixnum}.
+@end example
-@node Global and Always-Bound variables
-@comment node-name, next, previous, up
-@section Global and Always-Bound variables
+is turned into hardware instructions on arm64 and x86-64. It returns
+64 when @code{n} is 0. @code{n} can also be @code{(signed-byte 64)} or @code{fixnum}.
-@include macro-sb-ext-defglobal.texinfo
+@node global and always bound variables
+@section Global and Always-bound Variables
-@deffn {Declaration} @sbext{global}
+@anchor{Macro sb-ext defglobal}
+@ffindex @sortas{defglobal sb-ext} defglobal [sb-ext]
+@deffn{Macro} sb-ext:defglobal name value &optional doc
+Defines @code{name} as a global variable that is always bound. @code{value} is evaluated
+and assigned to @code{name} both at compile- and load-time, but only if @code{name} is not
+already bound.
-Syntax: @code{(sb-ext:global symbol*)}
+Global variables share their values between all threads, and cannot be
+locally bound, declared special, defined as constants, and neither bound
+nor defined as symbol macros.
+
+See also the declarations @code{sb-ext:global} and @code{sb-ext:always-bound}.
+@end deffn
+@itemize
+@item [@strong{declaration}] @code{sb-ext:global}
+
+Syntax: @code{(sb-ext:global &rest symbols)}
Only valid as a global proclamation.
Specifies that the named symbols cannot be proclaimed or locally
declared @code{special}. Proclaiming an already special or constant
-variable name as @code{global} signal an error. Allows more efficient
-value lookup in threaded environments in addition to expressing
-programmer intention.
-@end deffn
+variable name as @code{sb-ext:global} signal an error. Allows more
+efficient value lookup in threaded environments in addition to
+expressing programmer intention.
-@deffn {Declaration} @sbext{always-bound}
+@item [@strong{declaration}] @code{sb-ext:always-bound}
-Syntax: @code{(sb-ext:always-bound symbol*)}
+Syntax: @code{(sb-ext:always-bound &rest symbols)}
Only valid as a global proclamation.
Specifies that the named symbols are always bound. Inhibits
@code{makunbound} of the named symbols. Proclaiming an unbound symbol
-as @code{always-bound} signals an error. Allows the compiler to elide
-boundness checks from value lookups.
-@end deffn
+as @code{sb-ext:always-bound} signals an error. Allows the compiler to
+elide boundness checks from value lookups.
+@end itemize
-@node Miscellaneous Efficiency Issues
-@comment node-name, next, previous, up
+@node miscellaneous efficiency issues
@section Miscellaneous Efficiency Issues
FIXME: The material in the CMUCL manual about getting good
@@ -413,84 +417,60 @@ Besides this information from the CMUCL manual, there are a few other
points to keep in mind.
@itemize
+@item The CMUCL manual doesn't seem to state it explicitly, but Python
+ has a mental block about type inference when assignment is
+ involved. Python is very aggressive and clever about inferring the
+ types of values bound with @code{let}, @code{let*}, inline function call, and so
+ forth. However, it's much more passive and dumb about inferring
+ the types of values assigned with @code{setq}, @code{setf}, and friends. It
+ would be nice to fix this, but in the meantime don't expect that
+ just because it's very smart about types in most respects it will
+ be smart about types involved in assignments. (This doesn't affect
+ its ability to benefit from explicit type declarations involving
+ the assigned variables, only its ability to get by without
+ explicit type declarations.)
+@end itemize
-@item
-@findex @cl{let}
-@findex @cl{let*}
-@findex @cl{setq}
-@findex @cl{setf}
-The CMUCL manual doesn't seem to state it explicitly, but Python has a
-mental block about type inference when assignment is involved. Python
-is very aggressive and clever about inferring the types of values
-bound with @code{let}, @code{let*}, inline function call, and so
-forth. However, it's much more passive and dumb about inferring the
-types of values assigned with @code{setq}, @code{setf}, and
-friends. It would be nice to fix this, but in the meantime don't
-expect that just because it's very smart about types in most respects
-it will be smart about types involved in assignments. (This doesn't
-affect its ability to benefit from explicit type declarations
-involving the assigned variables, only its ability to get by without
-explicit type declarations.)
-
-@c <!-- FIXME: Python dislikes assignments, but not in type
-@c inference. The real problems are loop induction, closed over
-@c variables and aliases. -->
-
-@item
-Since the time the CMUCL manual was written, CMUCL (and thus SBCL) has
-gotten a generational garbage collector. This means that there are
-some efficiency implications of various patterns of memory usage which
-aren't discussed in the CMUCL manual. (Some new material should be
-written about this.)
-
-@item
-SBCL has some important known efficiency problems. Perhaps the most
-important are
-
-@itemize @minus
+@itemize
+@item Since the time the CMUCL manual was written, CMUCL (and thus SBCL)
+ has gotten a generational garbage collector. This means that there
+ are some efficiency implications of various patterns of memory
+ usage which aren't discussed in the CMUCL manual. (Some new
+ material should be written about this.)
-@item
-The garbage collector is not particularly efficient, at least on
-platforms without the generational collector (as of SBCL 0.8.9, all
-except x86).
+@item SBCL has some important known efficiency problems. Perhaps the
+ most important are
-@item
-Various aspects of the PCL implementation of CLOS are more inefficient
-than necessary.
+@itemize
+@item The garbage collector is not particularly efficient, at least
+ on platforms without the generational collector (as of SBCL
+ 0.8.9, all except x86).
+@item Various aspects of the PCL implementation of CLOS are more
+ inefficient than necessary.
@end itemize
-
@end itemize
-Finally, note that Common Lisp defines many constructs which, in
-the infamous phrase, ``could be compiled efficiently by a
-sufficiently smart compiler''. The phrase is infamous because
-making a compiler which actually is sufficiently smart to find all
-these optimizations systematically is well beyond the state of the art
-of current compiler technology. Instead, they're optimized on a
-case-by-case basis by hand-written code, or not optimized at all if
-the appropriate case hasn't been hand-coded. Some cases where no such
+Finally, note that Common Lisp defines many constructs which, in the
+infamous phrase, "could be compiled efficiently by a sufficiently
+smart compiler". The phrase is infamous because making a compiler
+which actually is sufficiently smart to find all these optimizations
+systematically is well beyond the state of the art of current
+compiler technology. Instead, they're optimized on a case-by-case
+basis by hand-written code, or not optimized at all if the
+appropriate case hasn't been hand-coded. Some cases where no such
hand-coding has been done as of SBCL version 0.6.3 include
@itemize
+@item @code{(reduce #'f x)} where the type of @code{x} is known at compile time,
-@item
-@code{(reduce #'f x)} where the type of @code{x} is known at compile
-time
+@item various bit vector operations, e.g. @code{(position 0 some-bit-vector)},
-@item
-various bit vector operations, e.g. @code{(position 0
-some-bit-vector)}
-
-@item
-specialized sequence idioms, e.g. @code{(remove item list :count 1)}
-
-@item
-cases where local compilation policy does not require excessive type
-checking, e.g. @code{(locally (declare (safety 1)) (assoc item
-list))} (which currently performs safe @code{endp} checking internal
-to assoc).
+@item specialized sequence idioms, e.g. @code{(remove item list :count 1)},
+@item cases where local compilation policy does not require excessive
+ type checking, e.g. @code{(locally (declare (safety 1)) (assoc item list))}
+ (which currently performs safe @code{endp} checking internal to @code{assoc}).
@end itemize
If your system's performance is suffering because of some construct
@@ -498,5 +478,6 @@ which could in principle be compiled efficiently, but which the SBCL
compiler can't in practice compile efficiently, consider writing a
patch to the compiler and submitting it for inclusion in the main
sources. Such code is often reasonably straightforward to write;
-search the sources for the string ``@code{deftransform}'' to find many
+search the sources for the string @code{deftransform} to find many
examples (some straightforward, some less so).
+
diff --git a/doc/manual/external-formats.texinfo b/doc/manual/external-formats.texinfo
index 429af8ecf..3112bbf74 100644
--- a/doc/manual/external-formats.texinfo
+++ b/doc/manual/external-formats.texinfo
@@ -1,173 +1,239 @@
-@node External Formats
-@comment node-name, next, previous, up
+@c Generated by the sb-manual contrib. Do not edit.
+
+@node external formats
@chapter External Formats
-External formats determine the coding of characters from/to sequences of
-octets when exchanging data with the outside world. Examples of such
-exchanges are:
-
-@enumerate
-
-@item
-Character streams associated with files, sockets and process
-input/output (See @ref{Stream External Formats} and @ref{Running
-external programs})
-
-@item
-Names of files
-
-@item
-Foreign strings (See @ref{Foreign Types and Lisp Types})
-
-@item
-Posix interface (See @ref{sb-posix})
-
-@item
-Hostname- and protocol-related functions of the BSD-socket interface
-(See @ref{Networking})
-
-@end enumerate
-
-Technically, external formats in SBCL are named objects describing
-coding of characters as well as policies in case de- or encoding is not
-possible. Each external format has a canonical name and zero or more
-aliases. User code mostly interacts with external formats by supplying
-external format designators to functions that use external formats
-internally.
-
@menu
-* The Default External Format::
-* External Format Designators::
-* Character Coding Conditions::
-* Converting between Strings and Octet Vectors::
-* Supported External Formats::
+* The Default External Format: default external format.
+* External Format Designators: external format designators.
+* Character Coding Conditions: character coding conditions.
+* Converting between Strings and Octet Vectors: converting between strings and octet vectors.
+* Supported External Formats: supported external formats.
@end menu
-@node The Default External Format
+External formats determine the coding of characters from/to sequences
+of octets when exchanging data with the outside world. Examples of
+such exchanges are:
+
+@itemize
+@item Character streams associated with files, sockets and process
+ input/output (see @ref{stream external formats} and
+ @ref{running external programs})
+
+@item Names of files
+
+@item Foreign strings (see @ref{foreign types and lisp types})
+
+@item Posix interface (see @ref{sb posix})
+
+@item Hostname- and protocol-related functions of the BSD-socket interface
+ (see @ref{networking})
+@end itemize
+
+Technically, external formats in SBCL are named objects describing
+coding of characters as well as policies in case de- or encoding is
+not possible. Each external format has a canonical name and zero or
+more aliases. User code mostly interacts with external formats by
+supplying external format designators to functions that use external
+formats internally.
+
+@node default external format
@section The Default External Format
-@cindex The Default External Format
-Most functions interacting with external formats use a default external
-format if none is explicitly specified. In some cases, the default
-external format is used unconditionally.
-
-The default external format is UTF-8. It can be changed via
-
-@var{sb-ext:*default-external-format*}
-and
-@var{sb-ext:*default-c-string-external-format*}
-
-@node External Format Designators
+@anchor{Variable sb-ext *default-external-format*}
+@vvindex @sortas{default-external-format* sb-ext} *default-external-format* [sb-ext]
+@deffn{Variable} sb-ext:*default-external-format*
+Most functions interacting with external formats (@code{open}, notably)
+use this default.
+@end deffn
+@anchor{Variable sb-ext *default-source-external-format*}
+@vvindex @sortas{default-source-external-format* sb-ext} *default-source-external-format* [sb-ext]
+@deffn{Variable} sb-ext:*default-source-external-format*
+@end deffn
+@anchor{Variable sb-ext *default-c-string-external-format*}
+@vvindex @sortas{default-c-string-external-format* sb-ext} *default-c-string-external-format* [sb-ext]
+@deffn{Variable} sb-ext:*default-c-string-external-format*
+@end deffn
+@node external format designators
@section External Format Designators
-@cindex External Format Designators
-@findex @cl{open}
-@findex @cl{with-open-file}
In situations where an external format designator is required, such as
-the @code{:external-format} argument in calls to @code{open} or
-@code{with-open-file}, users may supply the name of an encoding to
-denote the external format which is applying that encoding to Lisp
-characters.
+the @code{:external-format} argument in calls to @code{open} or @code{with-open-file},
+users may supply the name of an encoding to denote the external
+format which is applying that encoding to Lisp characters.
In addition to the basic encoding for an external format, options
-controlling various special cases may be passed, by using a list (whose
-first element must be an encoding name and whose rest is a plist) as an
-external file format designator.
+controlling various special cases may be passed, by using a list
+(whose first element must be an encoding name and whose rest is a
+plist) as an external file format designator.
-More specifically, external format designators can take the following
-forms:
+More specifically, external format designators can take the
+following forms:
-@table @code
+@itemize
+@item @code{:default}: Designates the current default external format (see
+ @ref{default external format}).
-@item :default
-Designates the current default external format (See @ref{The Default
-External Format}).
+@item @code{<keyword>}: Designates the supported external format that has
+ @code{<keyword>} as one of its names (see @ref{supported external formats}).
-@item @var{keyword}
-Designates the supported external format that has @var{keyword} as one
-of its names. (See @ref{Supported External Formats}).
+@item @code{(<keyword> . <options-plist>)}: Designates an external format
+ that is like the one designated by @code{<keyword>} with options as
+ specified in @code{<options-plist>}.
+@end itemize
-@item (@var{keyword} . @var{options-plist})
-Designates an external format that is like the one designated by
-@var{keyword} with options as specified in @var{options-plist}.
+Valid options for @code{<options-plist>} are:
-@end table
-
-Valid options for @var{options-plist} are:
-
-@table @code
-
-@item :newline @var{newline}
+@itemize
+@item @code{:NEWLINE <newline>}
An external format with an explicit @code{:newline} option is like its
-@var{keyword} parent, but recognizes certain characters or character
-sequences as newlines. For @code{:lf} (the default), the
+@code{<keyword>} parent but recognizes certain characters or
+character sequences as newlines. For @code{:lf} (the default), the
@code{#\Linefeed} character is treated as @code{#\Newline} for both
-input and output. For @code{:cr}, @code{#\Return} is treated as
+input and output. For @code{:cr}, @code{#\Return} is treated as
@code{#\Newline}, while for @code{:crlf} the two-character sequence
-@code{#\Return #\Linefeed} is translated to and from @code{#\Newline}.
+@code{#\Return #\Linefeed} is translated to and from
+@code{#\Newline}.
-@item :replacement @var{replacement}
+@item @code{:REPLACEMENT <replacement>}
An external format with an explicit @code{:replacement} option is like
-its @var{keyword} parent, but does not signal an error in case a
-character or octet sequence cannot be en- or decoded. Instead, it
-inserts @var{replacement} at the position in
-question. @var{replacement} has to be a string designator, that is a
-character or string.
+its @code{<keyword>} parent but does not signal an error in case a
+character or octet sequence cannot be en- or decoded. Instead,
+it inserts @code{<replacement>} at the position in question.
+@code{<replacement>} must be a string designator; that is, a
+character or a string.
+@end itemize
For example:
-@lisp
+
+@example
(with-open-file (stream pathname :external-format '(:utf-8 :replacement #\?))
(read-line stream))
-@end lisp
-will read the first line of @var{pathname}, replacing any octet sequence
-that is not valid in the UTF-8 external format with a question mark
-character.
+@end example
-@end table
+will read the first line of @code{pathname}, replacing any octet
+sequence that is not valid in the UTF-8 external format with a
+question mark character.
-@node Character Coding Conditions
+@node character coding conditions
@section Character Coding Conditions
-@cindex Character Coding Conditions
De- or encoding characters using a given external format is not always
possible:
@itemize
+@item Decoding an octet vector using a given external format can fail if
+ it contains an octet or sequence of octets that does not have an
+ interpretation as a character according to the external format.
-@item
-Decoding an octet vector using a given external format can fail if it
-contains an octet or sequence of octets that does not have an
-interpretation as a character according to the external format.
-
-@item
-Conversely, a string may contain characters that a given external format
-cannot encode. For example, the ASCII external format cannot encode the
-character @code{#\ö}.
-
+@item Conversely, a string may contain characters that a given external
+ format cannot encode. For example, the ASCII external format
+ cannot encode the character @code{#\ö}.
@end itemize
Unless the external format governing the coding uses the
-@code{:replacement} keyword, SBCL will signal (continuable) errors under
-the above circumstances. The types of the condition signaled are not
-currently exported or documented but will be in future SBCL versions.
+@code{:replacement} option, SBCL will signal (continuable) errors under the
+above circumstances. The types of the condition signaled are not
+currently exported or documented but will be in future SBCL
+versions.
-@node Converting between Strings and Octet Vectors
+@node converting between strings and octet vectors
@section Converting between Strings and Octet Vectors
-@cindex Converting between Strings and Octet Vectors
-To encode Lisp strings as octet vectors and decode octet vectors as Lisp
-strings, the following SBCL-specific functions can be used:
+To encode Lisp strings as octet vectors and decode octet vectors as
+Lisp strings, the following SBCL-specific functions can be used:
-@include fun-sb-ext-string-to-octets.texinfo
-@include fun-sb-ext-octets-to-string.texinfo
+@anchor{Function sb-ext string-to-octets}
+@ffindex @sortas{string-to-octets sb-ext} string-to-octets [sb-ext]
+@deffn{Function} sb-ext:string-to-octets string &key external-format start end null-terminate
+Return an octet vector that is @code{string} encoded according to @code{external-format}.
-@node Supported External Formats
+If @code{external-format} is given, it must designate an external format.
+
+If given, @code{start} and @code{end} must be bounding index designators and
+designate a subsequence of @code{string} that should be encoded.
+
+If @code{null-terminate} is true, the returned octet vector ends with an
+additional 0 element that does not correspond to any part of @code{string}.
+
+If some of the characters of @code{string} (or the subsequence bounded by
+@code{start} and @code{end}) cannot be encoded by @code{external-format} an error of a
+subtype of @code{sb-int:character-encoding-error} is signaled.
+
+Note that for some values of @code{external-format} and @code{null-terminate} the
+length of the returned vector may be different from the length of
+@code{string} (or the subsequence bounded by @code{start} and @code{end}).
+@end deffn
+@anchor{Function sb-ext octets-to-string}
+@ffindex @sortas{octets-to-string sb-ext} octets-to-string [sb-ext]
+@deffn{Function} sb-ext:octets-to-string vector &key external-format start end
+Return a string obtained by decoding @code{vector} according to @code{external-format}.
+
+If @code{external-format} is given, it must designate an external format.
+
+If given, @code{start} and @code{end} must be bounding index designators and
+designate a subsequence of @code{vector} that should be decoded.
+
+If some of the octets of @code{vector} (or the subsequence bounded by @code{start}
+and @code{end}) cannot be decoded by @code{external-format} an error of a subtype of
+@code{sb-int:character-decoding-error} is signaled.
+
+Note that for some values of @code{external-format} the length of the
+returned string may be different from the length of @code{vector} (or the
+subsequence bounded by @code{start} and @code{end}).
+@end deffn
+@node supported external formats
@section Supported External Formats
-@cindex Supported External Formats
-The following table lists the external formats supported by SBCL in the
-form of the respective canonical name followed by the list of aliases:
+The following lists the external formats supported by SBCL in
+the form of the respective canonical name followed by the list of aliases:
+
+@itemize
+@item @code{:euc-jp}
+
+@code{:eucjp}, @code{:|eucJP|}
+
+@item @code{:gbk}
+
+@code{:cp936}
+
+@item @code{:shift_jis}
+
+@code{:sjis}, @code{:|Shift_JIS|}, @code{:cp932}
+
+@item @code{:ucs-2be}
+
+@code{:ucs2be}
+
+@item @code{:ucs-2le}
+
+@code{:ucs2le}
+
+@item @code{:ucs-4be}
+
+@code{:ucs4be}
+
+@item @code{:ucs-4le}
+
+@code{:ucs4le}
+
+@item @code{:utf-16be}
+
+@code{:utf16be}
+
+@item @code{:utf-16le}
+
+@code{:utf16le}
+
+@item @code{:utf-32be}
+
+@code{:utf32be}
+
+@item @code{:utf-32le}
+
+@code{:utf32le}
+@end itemize
+
-@include encodings.texi-temp
diff --git a/doc/manual/ffi.texinfo b/doc/manual/ffi.texinfo
index 4d835b71a..8481d260a 100644
--- a/doc/manual/ffi.texinfo
+++ b/doc/manual/ffi.texinfo
@@ -1,88 +1,90 @@
-@node Foreign Function Interface
-@comment node-name, next, previous, up
+@c Generated by the sb-manual contrib. Do not edit.
+
+@node foreign function interface
@chapter Foreign Function Interface
+@menu
+* Introduction to the Foreign Function Interface: introduction to the foreign function interface.
+* Foreign Types: foreign types.
+* Operations On Foreign Values: operations on foreign values.
+* Foreign Variables: foreign variables.
+* Foreign Data Structure Examples: foreign data structure examples.
+* Loading Shared Object Files: loading shared object files.
+* Foreign Function Calls: foreign function calls.
+* Calling Lisp From C: calling lisp from c.
+* Step-By-Step Example of the Foreign Function Interface: step by step example of the foreign function interface.
+@end menu
+
This chapter describes SBCL's interface to C programs and
-libraries (and, since C interfaces are a sort of @emph{lingua
-franca} of the Unix world, to other programs and libraries in
-general.)
+libraries (and, since C interfaces are a sort of @emph{lingua franca}
+of the Unix world, to other programs and libraries in general).
@quotation
-Note: In the modern Lisp world, the usual term for this functionality
-is Foreign Function Interface, or @acronym{FFI}, where despite the
-mention of ``function'' in this term, @acronym{FFI} also
-refers to direct manipulation of C data structures as well as
-functions. The traditional CMUCL terminology is Alien Interface, and
-while that older terminology is no longer used much in the system
+@emph{Note}: In the modern Lisp world, the usual term for this
+functionality is Foreign Function Interface, or FFI, where despite
+the mention of @emph{function} in this term, FFI also refers to direct
+manipulation of C data structures as well as functions. The
+traditional CMUCL terminology is Alien Interface, and while that
+older terminology is no longer used much in the system
documentation, it still reflected in names in the implementation,
-notably in the name of the @code{SB-ALIEN} package.
+notably in the name of the @code{sb-alien} package.
@end quotation
-@menu
-* Introduction to the Foreign Function Interface::
-* Foreign Types::
-* Operations On Foreign Values::
-* Foreign Variables::
-* Foreign Data Structure Examples::
-* Loading Shared Object Files::
-* Foreign Function Calls::
-* Calling Lisp From C::
-* Step-By-Step Example of the Foreign Function Interface::
-@end menu
-
-@node Introduction to the Foreign Function Interface
-@comment node-name, next, previous, up
+@node introduction to the foreign function interface
@section Introduction to the Foreign Function Interface
-@c AKA "Introduction to Aliens" in the CMU CL manual
Because of Lisp's emphasis on dynamic memory allocation and garbage
-collection, Lisp implementations use non-C-like memory representations
-for objects. This representation mismatch creates friction when a Lisp
-program must share objects with programs which expect C data. There
-are three common approaches to establishing communication:
+collection, Lisp implementations use non-C-like memory
+representations for objects. This representation mismatch creates
+friction when a Lisp program must share objects with programs which
+expect C data. There are three common approaches to establishing
+communication:
@itemize
-@item
-The burden can be placed on the foreign program (and programmer) by
-requiring the knowledge and use of the representations used internally
-by the Lisp implementation. This can require a considerable amount of
-``glue'' code on the C side, and that code tends to be sensitively
-dependent on the internal implementation details of the Lisp system.
+@item The burden can be placed on the foreign program (and programmer)
+ by requiring the knowledge and use of the representations used
+ internally by the Lisp implementation. This can require a
+ considerable amount of "glue" code on the C side, and that code
+ tends to be sensitively dependent on the internal implementation
+ details of the Lisp system.
-@item
-The Lisp system can automatically convert objects back and forth between
-the Lisp and foreign representations. This is convenient, but
-translation becomes prohibitively slow when large or complex data
-structures must be shared. This approach is supported by the SBCL
-@acronym{FFI}, and used automatically when passing integers and strings.
-
-@item
-The Lisp program can directly manipulate foreign objects through the
-use of extensions to the Lisp language.
+@item The Lisp system can automatically convert objects back and forth
+ between the Lisp and foreign representations. This is convenient,
+ but translation becomes prohibitively slow when large or complex
+ data structures must be shared. This approach is supported by the
+ SBCL FFI, and used automatically when passing integers and
+ strings.
+@item The Lisp program can directly manipulate foreign objects through
+ the use of extensions to the Lisp language.
@end itemize
SBCL, like CMUCL before it, relies primarily on the automatic
-conversion and direct manipulation approaches. The @code{SB-ALIEN}
+conversion and direct manipulation approaches. The @code{sb-alien}
package provides a facility wherein foreign values of simple scalar
types are automatically converted and complex types are directly
-manipulated in their foreign representation. Additionally the
-lower-level System Area Pointers (or @acronym{SAP}s) can be used where
+manipulated in their foreign representation. Additionally the
+lower-level System Area Pointers (or SAPs) can be used where
necessary to provide untyped access to foreign memory.
Any foreign objects that can't automatically be converted into Lisp
-values are represented by objects of type @code{alien-value}. Since
-Lisp is a dynamically typed language, even foreign objects must have a
-run-time type; this type information is provided by encapsulating the
-raw pointer to the foreign data within an @code{alien-value} object.
+values are represented by objects of type
+@code{sb-alien-internals:alien-value} Since Lisp is a dynamically typed
+language, even foreign objects must have a run-time type; this type
+information is provided by encapsulating the raw pointer to the
+foreign data within an @code{sb-alien-internals:alien-value} object.
-The type language and operations on foreign types are
-intentionally similar to those of the C language.
+The type language and operations on foreign types are intentionally
+similar to those of the C language.
-@node Foreign Types
-@comment node-name, next, previous, up
+@node foreign types
@section Foreign Types
-@c AKA "Alien Types" in the CMU CL manual
+
+@menu
+* Defining Foreign Types: defining foreign types.
+* Foreign Types and Lisp Types: foreign types and lisp types.
+* Foreign Type Specifiers: foreign type specifiers.
+@end menu
Alien types have a description language based on nested list
structure. For example the C type
@@ -94,238 +96,208 @@ struct foo @{
@};
@end example
-has the corresponding SBCL @acronym{FFI} type
+has the corresponding SBCL FFI type
-@lisp
+@example
(struct foo
(a int)
(b (array (* (struct foo)) 100)))
-@end lisp
+@end example
-
-@menu
-* Defining Foreign Types::
-* Foreign Types and Lisp Types::
-* Foreign Type Specifiers::
-@end menu
-
-@node Defining Foreign Types
-@comment node-name, next, previous, up
+@node defining foreign types
@subsection Defining Foreign Types
-Types may be either named or anonymous. With structure and union
+Types may be either named or anonymous. With structure and union
types, the name is part of the type specifier, allowing recursively
defined types such as:
-@lisp
+@example
(struct foo (a (* (struct foo))))
-@end lisp
+@end example
An anonymous structure or union type is specified by using the name
-@code{nil}. The @code{with-alien} macro defines a local scope which
-``captures'' any named type definitions. Other types are not
-inherently named, but can be given named abbreviations using the
-@code{define-alien-type} macro.
+@code{nil}. The @code{with-alien} macro defines a local scope which @emph{captures} any
+named type definitions. Other types are not inherently named, but
+can be given named abbreviations using the @code{define-alien-type} macro.
-@node Foreign Types and Lisp Types
-@comment node-name, next, previous, up
+@node foreign types and lisp types
@subsection Foreign Types and Lisp Types
-The foreign types form a subsystem of the SBCL type system. An
+The foreign types form a subsystem of the SBCL type system. An
@code{alien} type specifier provides a way to use any foreign type as a
-Lisp type specifier. For example,
+Lisp type specifier. For example,
-@lisp
-(typep @var{foo} '(alien (* int)))
-@end lisp
+@example
+(typep foo '(alien (* int)))
+@end example
-can be used to determine whether @var{foo} is a pointer to a foreign
-@code{int}. @code{alien} type specifiers can be used in the same ways
-as ordinary Lisp type specifiers (like @code{string}.) Alien type
-declarations are subject to the same precise type checking as any
-other declaration. @xref{Precise Type Checking}.
+can be used to determine whether @code{foo} is a pointer to a foreign
+@code{int}. @code{alien} type specifiers can be used in the same ways as
+ordinary Lisp type specifiers (like @code{string}.) Alien type declarations
+are subject to the same precise type checking as any other
+declaration. See @ref{precise type checking}.
-Note that the type identifiers used in the foreign type system overlap
-with native Lisp type specifiers in some cases. For example, the type
-specifier @code{(alien single-float)} is identical to
-@code{single-float}, since foreign floats are automatically converted
-to Lisp floats. When @code{type-of} is called on an alien value that
-is not automatically converted to a Lisp value, then it will return an
+Note that the type identifiers used in the foreign type system
+overlap with native Lisp type specifiers in some cases. For example,
+the type specifier @code{(alien single-float)} is identical to
+@code{single-float}, since foreign floats are automatically converted to
+Lisp floats. When @code{type-of} is called on an alien value that is not
+automatically converted to a Lisp value, then it will return an
@code{alien} type specifier.
-@node Foreign Type Specifiers
-@comment node-name, next, previous, up
+@node foreign type specifiers
@subsection Foreign Type Specifiers
-Note: All foreign type names are exported from the @code{sb-alien}
-package. Some foreign type names are also symbols in
-the @code{common-lisp} package, in which case they are
-reexported from the @code{sb-alien} package, so that
-e.g. it is legal to refer to @code{sb-alien:single-float}.
+@quotation
+@emph{Note}: All foreign type names are exported from the @code{sb-alien}
+package. Some foreign type names are also symbols in the
+@code{common-lisp} package, in which case they are reexported from the
+@code{sb-alien} package, so that e.g. it is legal to refer to
+@code{single-float}.
+@end quotation
These are the basic foreign type specifiers:
@itemize
-@item
-The foreign type specifier @code{(* @var{foo})} describes a pointer to
-an object of type @var{foo}. A pointed-to type @var{foo} of @code{t}
-indicates a pointer to anything, similar to @code{void *} in
-ANSI C. A null alien pointer can be detected with the
-@code{sb-alien:null-alien} function.
+@item The foreign type specifier @code{(* <foo>)} describes a pointer to an
+ object of type @code{<foo>}. A pointed-to type @code{<foo>} of @code{t} indicates a
+ pointer to anything, similar to @code{void *} in ANSI C. A null alien
+ pointer can be detected with the @code{null-alien} function.
-@item
-The foreign type specifier @code{(array @var{foo} &rest
-dimensions)} describes array of the specified @code{dimensions},
-holding elements of type @var{foo}. Note that (unlike in C) @code{(*
-@var{foo})} and @code{(array @var{foo})} are considered to be
-different types when type checking is done. If equivalence of pointer
-and array types is desired, it may be explicitly coerced using
-@code{sb-alien:cast}.
+@item The foreign type specifier @code{(array <foo> &rest <dimensions>)}
+ describes array of the specified @code{<dimensions>}, holding elements
+ of type @code{<foo>}. Note that (unlike in C) @code{(* <foo>)} and
+ @code{(array <foo>)} are considered to be different types when
+ type checking is done. If equivalence of pointer and array types
+ is desired, it may be explicitly coerced using @code{cast}.
+@end itemize
-Arrays are accessed using @code{sb-alien:deref}, passing the indices
-as additional arguments. Elements are stored in column-major order
+Arrays are accessed using @code{deref}, passing the indices
+as additional arguments. Elements are stored in row-major order
(as in C), so the first dimension determines only the size of the
-memory block, and not the layout of the higher dimensions. An array
-whose first dimension is variable may be specified by using @code{nil}
-as the first dimension. Fixed-size arrays can be allocated as array
-elements, structure slots or @code{sb-alien:with-alien}
-variables. Dynamic arrays can only be allocated using
-@code{sb-alien:make-alien}.
+memory block, and not the layout of the higher dimensions. An array
+whose first dimension is variable may be specified by using @code{nil} as
+the first dimension. Fixed-size arrays can be allocated as array
+elements, structure slots or @code{with-alien} variables. Dynamic arrays
+can only be allocated using @code{make-alien}.
-@item
-The foreign type specifier @code{(sb-alien:struct @var{name} &rest
-@var{fields})} describes a structure type with the specified
-@var{name} and @var{fields}. Fields are allocated at the same offsets
-used by the implementation's C compiler, as guessed by the SBCL
-internals. An optional @code{:alignment} keyword argument can be
-specified for each field to explicitly control the alignment of a
-field. If @var{name} is @code{nil} then the structure is anonymous.
+@itemize
+@item The foreign type specifier @code{(struct <name> &rest <fields>)}
+ describes a structure type with the specified @code{<name>} and
+ @code{<fields>}. Fields are allocated at the same offsets used by the
+ implementation's C compiler, as guessed by the SBCL internals.
+ An optional @code{:alignment} keyword argument can be specified for each
+ field to explicitly control the alignment of a field. If @code{<name>}
+ is @code{nil} then the structure is anonymous.
If a named foreign @code{struct} specifier is passed to
@code{define-alien-type} or @code{with-alien}, then this defines,
-respectively, a new global or local foreign structure type. If no
-@var{fields} are specified, then the fields are taken
-from the current (local or global) alien structure type definition of
-@var{name}.
+respectively, a new global or local foreign structure type. If
+no @code{<fields>} are specified, then the fields are taken from the
+current (local or global) alien structure type definition of
+@code{<name>}.
-@item
-The foreign type specifier @code{(sb-alien:union @var{name} &rest
-@var{fields})} is similar to @code{sb-alien:struct}, but describes a
-union type. All fields are allocated at the same offset, and the size
-of the union is the size of the largest field. The programmer must
-determine which field is active from context.
+@item The foreign type specifier @code{(union <name> &rest <fields>)} is
+ similar to @code{struct} but describes a union type. All fields are
+ allocated at the same offset, and the size of the union is the
+ size of the largest field. The programmer must determine which
+ field is active from context.
-@item
-The foreign type specifier @code{(sb-alien:enum @var{name} &rest
-@var{specs})} describes an enumeration type that maps between integer
-values and symbols. If @var{name} is @code{nil}, then the type is
-anonymous. Each element of the @var{specs} list is either a Lisp
-symbol, or a list @code{(@var{symbol} @var{value})}. @var{value} is
-an integer. If @var{value} is not supplied, then it defaults to one
-greater than the value for the preceding spec (or to zero if it is the
-first spec).
+@item The foreign type specifier @code{(enum <name> &rest <specs>)} describes
+ an enumeration type that maps between integer values and symbols.
+ If @code{<name>} is @code{nil}, then the type is anonymous. Each element of
+ the @code{<specs>} list is either a Lisp symbol, or a list
+ @code{(<symbol> <value>)}. @code{<value>} is an integer. If @code{<value>} is not
+ supplied, then it defaults to one greater than the value for the
+ preceding spec (or to zero if it is the first spec).
-@item
-The foreign type specifier @code{(sb-alien:signed &optional
-@var{bits})} specifies a signed integer with the specified number of
-@var{bits} precision. The upper limit on integer
-precision is determined by the machine's word size. If
-@var{bits} is not specified, the maximum size will be
-used.
+@item The foreign type specifier @code{(signed &optional <bits>)} specifies a
+ signed integer with the specified number of @code{<bits>} precision.
+ The upper limit on integer precision is determined by the
+ machine's word size. If @code{<bits>} is not specified, the maximum
+ size will be used.
-@item
-The foreign type specifier @code{(integer &optional @var{bits})}
-is equivalent to the corresponding type specifier using
-@code{sb-alien:signed} instead of @code{integer}.
+@item The foreign type specifier @code{(integer &optional <bits>)} is
+ equivalent to the corresponding type specifier using @code{signed}
+ instead of @code{integer}.
-@item
-The foreign type specifier @code{(sb-alien:unsigned &optional
-@var{bits})} is like corresponding type specifier using
-@code{sb-alien:signed} except that the variable is treated as an
-unsigned integer.
+@item The foreign type specifier @code{(unsigned &optional <bits>)} is like
+ corresponding type specifier using @code{signed} except that the variable
+ is treated as an unsigned integer.
-@item
-The foreign type specifier @code{(boolean &optional @var{bits})} is
-similar to an enumeration type, but maps from Lisp @code{nil} and
-@code{t} to C @code{0} and @code{1} respectively. @var{bits}
-determines the amount of storage allocated to hold the truth value.
+@item The foreign type specifier @code{(boolean &optional <bits>)} is similar
+ to an enumeration type but maps from Lisp @code{nil} and @code{t} to C 0 and 1
+ respectively. @code{<bits>} determines the amount of storage allocated
+ to hold the truth value.
-@item
-The foreign type specifier @code{single-float} describes a
-floating-point number in IEEE single-precision format.
+@item The foreign type specifier @code{single-float} describes a
+ floating-point number in IEEE single-precision format.
-@item
-The foreign type specifier @code{double-float} describes a
-floating-point number in IEEE double-precision format.
+@item The foreign type specifier @code{double-float} describes a
+ floating-point number in IEEE double-precision format.
-@item
-The foreign type specifier @code{(function @var{result-type} &rest
-@var{arg-types})} describes a foreign function that takes arguments of
-the specified @var{arg-types} and returns a result of type
-@var{result-type}. Note that the only context where a foreign
-@code{function} type is directly specified is in the argument to
-@code{sb-alien:alien-funcall}. In all other contexts, foreign
-functions are represented by foreign function pointer types: @code{(*
-(function @dots{}))}.
+@item The foreign type specifier @code{(function <result-type> &rest
+ <arg-types>)} describes a foreign function that takes arguments of
+ the specified @code{<arg-types>} and returns a result of type
+ @code{<result-type>}. Note that the only context where a foreign
+ @code{function} type is directly specified is in the argument to
+ @code{alien-funcall}. In all other contexts, foreign functions are
+ represented by foreign function pointer types: @code{(* (function
+ ...))}.
-@item
-The foreign type specifier @code{sb-alien:system-area-pointer}
-describes a pointer which is represented in Lisp as a
-@code{system-area-pointer} object. SBCL exports this type from
-@code{sb-alien} because CMUCL did, but tentatively (as of the first
-draft of this section of the manual, SBCL 0.7.6) it is deprecated,
-since it doesn't seem to be required by user code.
+@item The foreign type specifier @code{system-area-pointer} describes a
+ pointer which is represented in Lisp as a @code{system-area-pointer}
+ object. SBCL exports this type from @code{sb-alien} because CMUCL did,
+ but tentatively (as of the first draft of this section of the
+ manual, SBCL 0.7.6) it is deprecated, since it doesn't seem to be
+ required by user code.
-@item
-The foreign type specifier @code{sb-alien:void} is used in function
-types to declare that no useful value is returned. Using
-@code{alien-funcall} to call a @code{void} foreign function will
-return zero values.
+@item The foreign type specifier @code{void} is used in function types to
+ declare that no useful value is returned. Using @code{alien-funcall} to
+ call a @code{void} foreign function will return zero values.
-@item
-@cindex External formats
-The foreign type specifier @code{(sb-alien:c-string &key
-external-format element-type not-null)} is similar to
-@code{(* char)}, but is interpreted as a null-terminated string, and
-is automatically converted into a Lisp string when accessed; or if the
-pointer is C @code{NULL} or @code{0}, then accessing it gives Lisp
-@code{nil} unless @code{not-null} is true, in which case a type-error
-is signalled.
+@item The foreign type specifier @code{(C-STRING &KEY <external-format>
+ <element-type> <not-null>)} is similar to @code{(* char)} but is
+ interpreted as a null-terminated string, and is automatically
+ converted into a Lisp string when accessed; or if the pointer is C
+ @code{null} or 0, then accessing it gives Lisp @code{nil} unless
+ @code{<not-null>} is true, in which case a @code{type-error} is signalled.
-External format conversion is automatically done when Lisp strings are
-passed to foreign code, or when foreign strings are passed to Lisp code.
-If the type specifier has an explicit @code{external-format}, that
-external format will be used. Otherwise a default external format that
-has been determined at SBCL startup time based on the current locale
-settings will be used. For example, when the following alien routine is
-called, the Lisp string given as argument is converted to an
-@code{ebcdic} octet representation.
+External format conversion is automatically done when Lisp
+strings are passed to foreign code, or when foreign strings are
+passed to Lisp code. If the type specifier has an explicit
+@code{<external-format>}, that external format will be used.
+Otherwise @code{sb-ext:*default-c-string-external-format*} will be
+used. For example, when the following alien routine is called,
+the Lisp string given as argument is converted to an EBCDIC
+octet representation.
-@lisp
+@example
(define-alien-routine test int (str (c-string :external-format :ebcdic-us)))
-@end lisp
+@end example
-Lisp strings of type @code{base-string} are stored with a trailing NUL
-termination, so no copying (either by the user or the implementation) is
-necessary when passing them to foreign code, assuming that the
-@code{external-format} and @code{element-type} of the @code{c-string}
-type are compatible with the internal representation of the string. For
-an SBCL built with Unicode support that means an @code{external-format}
-of @code{:ascii} and an @code{element-type} of @code{base-char}. Without
-Unicode support the @code{external-format} can also be
-@code{:iso-8859-1}, and the @code{element-type} can also be
-@code{character}. If the @code{external-format} or @code{element-type}
-is not compatible, or the string is a @code{(simple-array character
-(*))}, this data is copied by the implementation as required.
+Lisp strings of type @code{base-string} are stored with a trailing
+@code{NUL} termination, so no copying (either by the user or the
+implementation) is necessary when passing them to foreign code,
+assuming that the @code{<external-format>} and @code{<element-type>} of
+the @code{c-string} type are compatible with the internal
+representation of the string. For an SBCL built with Unicode
+support that means an @code{<external-format>} of @code{:ascii} and an
+@code{<element-type>} of @code{base-char}. Without Unicode support the
+@code{<external-format>} can also be @code{:iso-8859-1}, and the
+@code{<element-type>} can also be @code{character}. If
+@code{<external-format>} and @code{<element-type>} are not compatible, or
+the string is a @code{(simple-array character (*))}, this data is
+copied by the implementation as required.
Assigning a Lisp string to a @code{c-string} structure field or
variable stores the contents of the string to the memory already
-pointed to by that variable. When a foreign object of type @code{(*
-char)} is assigned to a @code{c-string}, then the
-@code{c-string} pointer is assigned to. This allows
-@code{c-string} pointers to be initialized. For example:
+pointed to by that variable. When a foreign object of type
+@code{(* char)} is assigned to a @code{c-string}, then the @code{c-string} pointer
+is assigned to. This allows @code{c-string} pointers to be initialized.
+For example:
-@lisp
+@example
(cl:in-package "CL-USER") ; which USEs package "SB-ALIEN"
(define-alien-type nil (struct foo (str c-string)))
@@ -335,224 +307,250 @@ char)} is assigned to a @code{c-string}, then the
(setf (slot my-foo 'str) (make-alien char (length str))
(slot my-foo 'str) str)
my-foo))
-@end lisp
+@end example
-Storing Lisp @code{NIL} in a @code{c-string} writes C @code{NULL} to
-the variable.
+Storing Lisp @code{nil} in a @code{c-string} writes C @code{NULL} to the
+variable.
+@end itemize
-@item
-@code{sb-alien} also exports translations of these C type
+@itemize
+@item @code{sb-alien} also exports translations of these C type
+@end itemize
specifiers as foreign type specifiers:
-@code{char},
-@code{short},
-@code{int},
-@code{long},
-@code{unsigned-char},
-@code{unsigned-short},
-@code{unsigned-int},
-@code{unsigned-long},
-@code{float}, @code{double},
-@code{size-t}, and @code{off-t}.
-@end itemize
+ @code{char}, @code{short}, @code{int}, @code{long}, @code{unsigned-char}, @code{unsigned-short},
+ @code{unsigned-int}, @code{unsigned-long}, @code{float}, @code{double}, @code{size-t}, @code{off-t}
-@node Operations On Foreign Values
-@comment node-name, next, previous, up
+@node operations on foreign values
@section Operations On Foreign Values
-@c AKA "Alien Operations" in the CMU CL manual
-
-This section describes how to read foreign values as Lisp values, how
-to coerce foreign values to different kinds of foreign values, and how
-to dynamically allocate and free foreign variables.
@menu
-* Accessing Foreign Values::
-* Coercing Foreign Values::
-* Foreign Dynamic Allocation::
+* Accessing Foreign Values: accessing foreign values.
+* Coercing Foreign Values: coercing foreign values.
+* Foreign Dynamic Allocation: foreign dynamic allocation.
@end menu
-@node Accessing Foreign Values
-@comment node-name, next, previous, up
+This section describes how to read foreign values as Lisp values,
+how to coerce foreign values to different kinds of foreign values,
+and how to dynamically allocate and free foreign variables.
+
+@node accessing foreign values
@subsection Accessing Foreign Values
-@defun @sbalien{deref} @var{pointer-or-array} &rest @var{indices}
-
-The @code{sb-alien:deref} function returns the value pointed to by a
-foreign pointer, or the value of a foreign array element. When
-dereferencing a pointer, an optional single index can be specified to
-give the equivalent of C pointer arithmetic; this index is scaled by
-the size of the type pointed to. When dereferencing an array, the
-number of indices must be the same as the number of dimensions in the
-array type. @code{deref} can be set with @code{setf} to assign a new
-value.
-@end defun
-
-@defun @sbalien{slot} @var{struct-or-union} @var{slot-name}
-
-The @code{sb-alien:slot} function extracts the value of the slot named
-@var{slot-name} from a foreign @code{struct} or @code{union}. If
-@var{struct-or-union} is a pointer to a structure or union, then it is
-automatically dereferenced. @code{sb-alien:slot} can be set with
-@code{setf} to assign a new value. Note that @var{slot-name} is
-evaluated, and need not be a compile-time constant (but only constant
-slot accesses are efficiently compiled).
-@end defun
+@menu
+* Untyped memory: untyped memory.
+@end menu
+@anchor{Function sb-alien deref}
+@ffindex @sortas{deref sb-alien} deref [sb-alien]
+@deffn{Function} sb-alien:deref alien &rest indices
+Dereference an @code{alien} pointer or array. When dereferencing a pointer,
+an optional single index can be specified to give the equivalent of
+C pointer arithmetic; this index is scaled by the size of the type
+pointed to. When dereferencing an array, the number of indices must
+be the same as the number of dimensions in the array type. @code{setf}able.
+@end deffn
+@anchor{Function sb-alien slot}
+@ffindex @sortas{slot sb-alien} slot [sb-alien]
+@deffn{Function} sb-alien:slot alien slot
+Extract the value of the slot named @code{slot} from a foreign @code{struct} or
+@code{union} @code{alien}. If @code{alien} is a pointer to a structure or union, then it
+is automatically dereferenced. @code{setf}able.
+Note that @code{slot} is evaluated, and need not be a compile-time
+constant (but only constant slot accesses are efficiently compiled).
+@end deffn
+@node untyped memory
@subsubsection Untyped memory
As noted at the beginning of the chapter, the System Area Pointer
-facilities allow untyped access to foreign memory. @acronym{SAP}s can
-be converted to and from the usual typed foreign values using
-@code{sap-alien} and @code{alien-sap} (described elsewhere), and also
-to and from integers - raw machine addresses. They should thus be
-used with caution; corrupting the Lisp heap or other memory with
-@acronym{SAP}s is trivial.
-
-@defun @sbsys{int-sap} @var{machine-address}
-
-Creates a @acronym{SAP} pointing at the virtual address
-@var{machine-address}.
-@end defun
-
-@defun @sbsys{sap-ref-32} @var{sap} @var{offset}
-
-Access the value of the memory location at @var{offset} bytes from
-@var{sap}. This form may also be used with @code{setf} to alter the
-memory at that location.
-@end defun
-
-@defun @sbsys{sap=} @var{sap1} @var{sap2}
-
-Compare @var{sap1} and @var{sap2} for equality.
-@end defun
+facilities allow untyped access to foreign memory. SAPs can be
+converted to and from the usual typed foreign values using @code{sap-alien}
+and @code{alien-sap}, and also to and from integers (raw machine
+addresses). They should thus be used with caution; corrupting the
+Lisp heap or other memory with SAPs is trivial.
+@anchor{Function sb-sys int-sap}
+@ffindex @sortas{int-sap sb-sys} int-sap [sb-sys]
+@deffn{Function} sb-sys:int-sap x
+Creates a @code{sap} pointing at the virtual address @code{x}.
+@end deffn
+@anchor{Function sb-sys sap-ref-32}
+@ffindex @sortas{sap-ref-32 sb-sys} sap-ref-32 [sb-sys]
+@deffn{Function} sb-sys:sap-ref-32 sap offset
+Access the value of the memory location at @code{offset} bytes from @code{sap}. @code{setf}able.
+@end deffn
+@anchor{Function sb-sys sap=}
+@ffindex @sortas{sap= sb-sys} sap= [sb-sys]
+@deffn{Function} sb-sys:sap= x y
+Compare the @code{sap}s @code{x} and @code{y} for equality.
+@end deffn
Similarly named functions exist for accessing other sizes of word,
-other comparisons, and other conversions. The reader is invited to
-use @code{apropos} and @code{describe} for more details
+other comparisons, and other conversions. The reader is invited to
+use @code{apropos} and @code{describe} for more details:
-@lisp
+@example
(apropos "sap" :sb-sys)
-@end lisp
+@end example
-
-@node Coercing Foreign Values
-@comment node-name, next, previous, up
+@node coercing foreign values
@subsection Coercing Foreign Values
-@defmac @sbalien{addr} @var{alien-expr}
-
-The @code{sb-alien:addr} macro returns a pointer to the location
-specified by @var{alien-expr}, which must be either a foreign
-variable, a use of @code{sb-alien:deref}, a use of
-@code{sb-alien:slot}, or a use of @code{sb-alien:extern-alien}.
-@end defmac
-
-@defmac @sbalien{cast} @var{foreign-value} @var{new-type}
-
-The @code{sb-alien:cast} macro converts @var{foreign-value} to a new
-foreign value with the specified @var{new-type}. Both types, old and
-new, must be foreign pointer, array or function types. Note that the
-resulting Lisp foreign variable object is not @code{eq} to the
-argument, but it does refer to the same foreign data bits.
-@end defmac
-
-@defmac @sbalien{sap-alien} @var{sap} @var{type}
-
-The @code{sb-alien:sap-alien} macro converts @var{sap} (a system
-area pointer) to a foreign value with the specified
-@var{type}. @var{type} is not evaluated.
-
-The @var{type} must be some foreign pointer, array, or record type.
-@end defmac
-
-@defun @sbalien{alien-sap} @var{foreign-value}
-
-The @code{sb-alien:alien-sap} function returns the @acronym{SAP} which
-points to @var{alien-value}'s data.
-
-The @var{foreign-value} must be of some foreign pointer, array, or
-record type.
-@end defun
-
-
-@node Foreign Dynamic Allocation
-@comment node-name, next, previous, up
+@anchor{Macro sb-alien addr}
+@ffindex @sortas{addr sb-alien} addr [sb-alien]
+@deffn{Macro} sb-alien:addr expr
+Return an Alien pointer to the data addressed by @code{expr},
+which must be a foreign variable, a call to @code{deref} or @code{slot}, or a use
+of @code{extern-alien}.
+@end deffn
+@anchor{Macro sb-alien cast}
+@ffindex @sortas{cast sb-alien} cast [sb-alien]
+@deffn{Macro} sb-alien:cast alien type
+Convert @code{alien} to an Alien of the specified @code{type} (not evaluated).
+Both types must be Alien array, pointer or function types.
+
+Note that the resulting Lisp foreign variable object is not @code{eq} to
+the argument, but it points to the same foreign memory address.
+@end deffn
+@anchor{Macro sb-alien sap-alien}
+@ffindex @sortas{sap-alien sb-alien} sap-alien [sb-alien]
+@deffn{Macro} sb-alien:sap-alien sap type
+Convert the @code{system-area-pointer} @code{sap} to an @code{alien} of the specified
+@code{type} (not evaluated). @code{type} must be pointer-like (foreign pointer,
+array, or record type).
+@end deffn
+@anchor{Function sb-alien alien-sap}
+@ffindex @sortas{alien-sap sb-alien} alien-sap [sb-alien]
+@deffn{Function} sb-alien:alien-sap alien
+Return a @code{system-area-pointer} pointing to @code{alien}'s data.
+@code{alien} must be of some foreign pointer, array, or record type.
+@end deffn
+@node foreign dynamic allocation
@subsection Foreign Dynamic Allocation
-Lisp code can call the C standard library functions @code{malloc} and
-@code{free} to dynamically allocate and deallocate foreign variables.
-The Lisp code shares the same allocator with foreign C code, so it's
-OK for foreign code to call @code{free} on the result of Lisp
-@code{sb-alien:make-alien}, or for Lisp code to call
-@code{sb-alien:free-alien} on foreign objects allocated by C code.
-
-@include macro-sb-alien-make-alien.texinfo
-@include fun-sb-alien-make-alien-string.texinfo
-@include fun-sb-alien-free-alien.texinfo
-
-@node Foreign Variables
-@comment node-name, next, previous, up
+Lisp code can call the C standard library functions @code{malloc}
+and @code{free} to dynamically allocate and deallocate foreign variables.
+The Lisp code uses the same allocator as foreign C code, so it's
+OK for foreign code to call @code{free} on the result of Lisp @code{make-alien},
+or for Lisp code to call @code{free-alien} on foreign objects allocated by
+C code.
+
+@anchor{Macro sb-alien make-alien}
+@ffindex @sortas{make-alien sb-alien} make-alien [sb-alien]
+@deffn{Macro} sb-alien:make-alien type &optional size
+Allocate an alien of type @code{type} in foreign heap, and return an alien
+pointer to it. The allocated memory is not initialized, and may
+contain garbage. The memory is allocated using @code{malloc(3)}, so it can
+be passed to foreign functions which use @code{free(3)}, or released using
+@code{free-alien}.
+
+For alien stack allocation, see macro @code{with-alien}.
+
+The @code{type} argument is not evaluated. If @code{size} is supplied, how it is
+interpreted depends on @code{type}:
+
+@itemize
+@item When @code{type} is a foreign array type, an array of that type is
+ allocated, and a pointer to it is returned. Note that you must use
+ @code{deref} to first access the array through the pointer.
+
+If supplied, @code{size} is used as the first dimension for the array.
+
+@item When @code{type} is any other foreign type, then an object for that type is
+ allocated, and a pointer to it is returned. So
+ (@code{make-alien} @code{int}) returns a (* @code{int}).
+
+If @code{size} is specified, then a block of that many objects is
+allocated, with the result pointing to the first one.
+@end itemize
+
+Examples:
+
+@example
+(defvar *foo* (make-alien (array char 10)))
+(type-of *foo*) ; => (alien (* (array (signed 8) 10)))
+(setf (deref (deref *foo*) 0) 10) ; => 10
+
+(make-alien char 12) ; => (alien (* (signed 8)))
+@end example
+@end deffn
+@anchor{Function sb-alien make-alien-string}
+@ffindex @sortas{make-alien-string sb-alien} make-alien-string [sb-alien]
+@deffn{Function} sb-alien:make-alien-string string &rest rest &key start end external-format null-terminate
+Copy part of @code{string} delimited by @code{start} and @code{end} into freshly
+allocated foreign memory, freeable using @code{free(3)} or @code{free-alien}.
+Returns the allocated string as a (* @code{char}) alien, and the number of
+bytes allocated as secondary value.
+
+The string is encoded using @code{external-format}. If @code{null-terminate} is
+true (the default), the alien string is terminated by an additional
+null byte.
+@end deffn
+@anchor{Function sb-alien free-alien}
+@ffindex @sortas{free-alien sb-alien} free-alien [sb-alien]
+@deffn{Function} sb-alien:free-alien alien
+Dispose of the storage pointed to by @code{alien}. The @code{alien} must have been
+allocated by @code{make-alien}, @code{make-alien-string} or @code{malloc(3)}.
+@end deffn
+@node foreign variables
@section Foreign Variables
-@c AKA "Alien Variables" in the CMU CL manual
-
-Both local (stack allocated) and external (C global) foreign variables
-are supported.
@menu
-* Local Foreign Variables::
-* External Foreign Variables::
+* Local Foreign Variables: local foreign variables.
+* External Foreign Variables: external foreign variables.
@end menu
-@node Local Foreign Variables
-@comment node-name, next, previous, up
+Both local (stack allocated) and external (C global) foreign
+variables are supported.
+
+@node local foreign variables
@subsection Local Foreign Variables
-@defmac @sbalien{with-alien} @var{var-definitions} &body @var{body}
+@anchor{Macro sb-alien with-alien}
+@ffindex @sortas{with-alien sb-alien} with-alien [sb-alien]
+@deffn{Macro} sb-alien:with-alien bindings &body body
+Establish some local alien variables of dynamic extent.
+Each of @code{bindings} is of the form:
-The @code{with-alien} macro establishes local foreign variables with
-the specified alien types and names. This form is analogous to
-defining a local variable in C: additional storage is allocated, and
-the initial value is copied. This form is less analogous to
-@code{LET}-allocated Lisp variables, since the variables can't be
-captured in closures: they live only for the dynamic extent of the
-body, and referring to them outside is a gruesome error.
+@example
+ VAR TYPE [ ALLOCATION ] [ INITIAL-VALUE | EXTERNAL-NAME ]
+@end example
-The @var{var-definitions} argument is a list of
-variable definitions, each of the form
-@lisp
-(@var{name} @var{type} &optional @var{initial-value})
-@end lisp
+ @code{allocation} should be one of:
-The names of the variables are established as symbol-macros; the
-bindings have lexical scope, and may be assigned with @code{setq} or
-@code{setf}.
+@itemize
+@item @code{:local} (the default): The alien is allocated on the stack, and
+ has dynamic extent.
+
+@item @code{:extern}: No alien is allocated, but @code{var} is established as a
+ local name for the external alien given by @code{external-name}.
+@end itemize
+
+@code{var}s are established as symbol-macros; the bindings have lexical
+scope, and may be assigned with @code{setq} or @code{setf}.
The @code{with-alien} macro also establishes a new scope for named
-structures and unions. Any @var{type} specified for a variable may
-contain named structure or union types with the slots specified.
-Within the lexical scope of the binding specifiers and body, a locally
-defined foreign structure type @var{foo} can be referenced by its name
-using @code{(struct @var{foo})}.
+structures and unions. Any @code{type} specified for a variable may contain
+named structure or union types with the slots specified. Within the
+lexical scope of the binding specifiers and body, a locally defined
+foreign structure type @code{foo} can be referenced by its name using
+@code{(struct foo)}.
When a foreign function returns a structure by value, using
-@code{alien-funcall} as the @var{initial-value} allows the returned
-struct to be stack-allocated directly into the local variable's
-storage, avoiding heap allocation:
+@code{alien-funcall} as the @code{initial-value} allows the returned struct to
+be stack-allocated directly into the local variable's storage,
+avoiding heap allocation:
-@lisp
+@example
(with-alien ((result (struct point)
(alien-funcall
(extern-alien "make_point"
(function (struct point) double double))
1.0d0 2.0d0)))
(values (slot result 'x) (slot result 'y)))
-@end lisp
-
-@end defmac
-
-@node External Foreign Variables
-@comment node-name, next, previous, up
+@end example
+@end deffn
+@node external foreign variables
@subsection External Foreign Variables
External foreign names are strings, and Lisp names are symbols. When
@@ -562,76 +560,74 @@ macros @code{extern-alien}, @code{define-alien-variable} and
@code{define-alien-routine} use this conversion heuristic:
@itemize
+@item Alien names are converted to Lisp names by uppercasing and
+ replacing underscores with hyphens.
-@item
-Alien names are converted to Lisp names by uppercasing and replacing
-underscores with hyphens.
+@item Conversely, Lisp names are converted to alien names by lowercasing
+ and replacing hyphens with underscores.
-@item
-Conversely, Lisp names are converted to alien names by lowercasing and
-replacing hyphens with underscores.
-
-@item
-Both the Lisp symbol and alien string names may be separately
-specified by using a list of the form
-
-@lisp
-(alien-string lisp-symbol)
-@end lisp
+@item Both the Lisp symbol and alien string names may be separately
+ specified by using a list of the form
+@example
+(<alien-string> <lisp-symbol>)
+@end example
@end itemize
-@defmac @sbalien{define-alien-variable} @var{name} @var{type}
+@anchor{Macro sb-alien define-alien-variable}
+@ffindex @sortas{define-alien-variable sb-alien} define-alien-variable [sb-alien]
+@deffn{Macro} sb-alien:define-alien-variable name type
+Define @code{name} as an external alien variable of type @code{type}.
+Neither is evaluated.
-The @code{define-alien-variable} macro defines @var{name} as an
-external foreign variable of the specified foreign @code{type}.
-@var{name} and @code{type} are not evaluated. The Lisp name of the
-variable (see above) becomes a global alien variable. Global alien
-variables are effectively ``global symbol macros''; a reference to the
-variable fetches the contents of the external variable. Similarly,
-setting the variable stores new contents -- the new contents must be
-of the declared @code{type}. Someday, they may well be implemented
-using the @acronym{ANSI} @code{define-symbol-macro} mechanism, but as
-of SBCL 0.7.5, they are still implemented using an older more-or-less
+In its full form, @code{name} is @code{(<alien-name-string>
+<lisp-name-symbol>)}. If @code{name} is just a symbol or string, then the
+other name is guessed from the one supplied as described
+@ref{external foreign variables}.
+
+The Lisp name of the variable becomes a global alien variable.
+Global alien variables are effectively "global symbol macros"; a
+reference to the variable fetches the contents of the external
+variable. Similarly, setting the variable stores new contents -- the
+new contents must be of the declared @code{type}. Someday, they may well be
+implemented using the ANSI @code{define-symbol-macro} mechanism, but as of
+SBCL 0.7.5, they are still implemented using an older more-or-less
parallel mechanism inherited from CMUCL.
-For example, to access a C-level counter @var{foo}, one could write
+For example, to access a C-level counter @code{foo}, one could write
-@lisp
+@example
(define-alien-variable "foo" int)
;; Now it is possible to get the value of the C variable foo simply by
;; referencing that Lisp variable:
(print foo)
(setf foo 14)
(incf foo)
-@end lisp
-@end defmac
+@end example
+@end deffn
+@anchor{Function sb-alien get-errno}
+@ffindex @sortas{get-errno sb-alien} get-errno [sb-alien]
+@deffn{Function} sb-alien:get-errno
+Return the value of the C library pseudo-variable named @code{errno}.
-@defun @sbalien{get-errno}
-
-Since in modern C libraries, the @code{errno} ``variable'' is typically
-no longer a variable, but some bizarre artificial construct
-which behaves superficially like a variable within a given thread,
-it can no longer reliably be accessed through the ordinary
-@code{define-alien-variable} mechanism. Instead, SBCL provides
-the operator @code{sb-alien:get-errno} to allow Lisp code to read it.
-@end defun
-
-@defmac @sbalien{extern-alien} @var{name} @var{type}
-
-The @code{extern-alien} macro returns an alien with the specified
-@var{type} which points to an externally defined value. @var{name} is
-not evaluated, and may be either a string or a symbol. @var{type} is
-an unevaluated alien type specifier.
-@end defmac
-
-@node Foreign Data Structure Examples
-@comment node-name, next, previous, up
+Since in modern C libraries, @code{errno} is typically no longer a
+variable, but some bizarre artificial construct which behaves
+superficially like a variable within a given thread, it can no longer
+reliably be accessed through the ordinary @code{define-alien-variable}
+mechanism.
+@end deffn
+@anchor{Macro sb-alien extern-alien}
+@ffindex @sortas{extern-alien sb-alien} extern-alien [sb-alien]
+@deffn{Macro} sb-alien:extern-alien name type
+Return an alien of @code{type} which points to an externally defined value of @code{name}.
+@code{name} is not evaluated and may be either a string or a symbol. @code{type}
+is an unevaluated alien type specifier. @code{setf}able.
+@end deffn
+@node foreign data structure examples
@section Foreign Data Structure Examples
-@c AKA "Alien Data Structure Example" in the CMU CL manual
Now that we have alien types, operations and variables, we can
-manipulate foreign data structures. This C declaration
+manipulate foreign data structures. This C declaration
@example
struct foo @{
@@ -642,12 +638,12 @@ struct foo @{
can be translated into the following alien type:
-@lisp
+@example
(define-alien-type nil
(struct foo
(a int)
(b (array (* (struct foo)) 100))))
-@end lisp
+@end example
Once the @code{foo} alien type has been defined as above, the C
expression
@@ -659,13 +655,13 @@ f.b[7].a;
can be translated in this way:
-@lisp
+@example
(with-alien ((f (struct foo)))
(slot (deref (slot f 'b) 7) 'a)
;;
;; Do something with f...
)
-@end lisp
+@end example
Or consider this example of an external C variable and some accesses:
@@ -684,7 +680,7 @@ my_struct = my_struct->n;
which can be manipulated in Lisp like this:
-@lisp
+@example
(define-alien-type nil
(struct c-struct
(x short)
@@ -697,76 +693,95 @@ which can be manipulated in Lisp like this:
(incf (slot my-struct 'x))
(setf (slot my-struct 'a) 5)
(setq my-struct (slot my-struct 'n))
-@end lisp
+@end example
-@node Loading Shared Object Files
-@comment node-name, next, previous, up
+@node loading shared object files
@section Loading Shared Object Files
Foreign object files can be loaded into the running Lisp process by
calling @code{load-shared-object}.
-@include fun-sb-alien-load-shared-object.texinfo
+@anchor{Function sb-alien load-shared-object}
+@ffindex @sortas{load-shared-object sb-alien} load-shared-object [sb-alien]
+@deffn{Function} sb-alien:load-shared-object pathname &key dont-save
+Load a shared library / dynamic shared object file / similar foreign
+container specified by designated @code{pathname}, such as a .so on an ELF platform.
-@include fun-sb-alien-unload-shared-object.texinfo
+Locating the shared object follows standard rules of the platform, consult the
+manual page for @code{dlopen(3)} for details. Typically paths specified by
+environment variables such as LD@emph{LIBRARY}PATH are searched if the @code{pathname} has
+no directory, but on some systems (eg. Mac OS X) search may happen even if
+@code{pathname} is absolute. (On Windows LoadLibrary is used instead of @code{dlopen(3)}.)
-@node Foreign Function Calls
-@comment node-name, next, previous, up
+On non-Windows platforms calling @code{load-shared-object} again with a @code{pathname}
+@code{equal} to the designated pathname of a previous call will replace the old
+definitions; if a symbol was previously referenced through the object and
+is not present in the reloaded version an error will be signalled. Reloading
+may not work as expected if user or library-code has called @code{dlopen(3)} on the
+same shared object or running on a system where @code{dlclose(3)} is a noop.
+
+@code{load-shared-object} interacts with @code{sb-ext:save-lisp-and-die}:
+
+1. If @code{dont-save} is true (default is @code{nil}), the shared object will be dropped
+when @code{save-lisp-and-die} is called -- otherwise shared objects are reloaded
+automatically when a saved core starts up. Specifying @code{dont-save} can be useful
+when the location of the shared object on startup is uncertain.
+
+2. On most platforms references in compiled code to foreign symbols in shared
+objects (such as those generated by @code{define-alien-routine}) remain valid across
+@code{save-lisp-and-die}. On those platforms where this is not supported, a @code{warning}
+will be signalled when the core is saved -- this is orthogonal from @code{dont-save}.
+@end deffn
+@anchor{Function sb-alien unload-shared-object}
+@ffindex @sortas{unload-shared-object sb-alien} unload-shared-object [sb-alien]
+@deffn{Function} sb-alien:unload-shared-object pathname
+Unloads the shared object loaded earlier using the designated @code{pathname} with
+@code{load-shared-object}, to the degree supported on the platform.
+
+Experimental.
+@end deffn
+@node foreign function calls
@section Foreign Function Calls
The foreign function call interface allows a Lisp program to call
many functions written in languages that use the C calling convention.
Lisp sets up various signal handling routines and other environment
-information when it first starts up, and expects these to be in place
-at all times. The C functions called by Lisp should not change the
-environment, especially the signal handlers: the signal handlers
-installed by Lisp typically have interesting flags set (e.g to request
-machine context information, or for signal delivery on an alternate
-stack) which the Lisp runtime relies on for correct operation.
-Precise details of how this works may change without notice between
-versions; the source, or the brain of a friendly SBCL developer, is
-the only documentation. Users of a Lisp built with the
+information when it first starts up, and expects these to be in
+place at all times. The C functions called by Lisp should not change
+the environment, especially the signal handlers: the signal handlers
+installed by Lisp typically have interesting flags set (e.g to
+request machine context information, or for signal delivery on an
+alternate stack) which the Lisp runtime relies on for correct
+operation. Precise details of how this works may change without
+notice between versions; the source, or the brain of a friendly SBCL
+developer, is the only documentation. Users of a Lisp built with the
@code{:sb-thread} feature should also read the section about threads,
-@ref{Threading}.
+@ref{threading}.
-@menu
-* The alien-funcall Primitive::
-* The alien-funcall-into Primitive::
-* The define-alien-routine Macro::
-* define-alien-routine Example::
-@end menu
+@anchor{Function sb-alien alien-funcall}
+@ffindex @sortas{alien-funcall sb-alien} alien-funcall [sb-alien]
+@deffn{Function} sb-alien:alien-funcall alien &rest args
+Call the foreign function @code{alien} with @code{args} and return its C return value
+as a Lisp value. @code{alien}'s foreign type specifies the argument and
+result types. @code{alien} is typically an @code{extern-alien} or a value defined
+with @code{define-alien-routine}.
-@node The alien-funcall Primitive
-@comment node-name, next, previous, up
-@subsection The @code{alien-funcall} Primitive
+The type of @code{alien} must be @code{(alien (function ...))} or @code{(alien
+(* (function ...)))}. The function type is used to determine how to
+call the function (as though it was declared with a prototype). The
+type need not be known at compile time, but only known-type calls
+are efficiently compiled.
-@defun @sbalien{alien-funcall} @var{alien-function} &rest @var{arguments}
-
-The @code{alien-funcall} function is the foreign function call
-primitive: @var{alien-function} is called with the supplied
-@var{arguments} and its C return value is returned as a Lisp value.
-The @var{alien-function} is an arbitrary run-time expression; to refer
-to a constant function, use @code{extern-alien} or a value defined by
-@code{define-alien-routine}.
-
-The type of @code{alien-function} must be @code{(alien (function
-...))} or @code{(alien (* (function ...)))}. The function type is
-used to determine how to call the function (as though it was declared
-with a prototype.) The type need not be known at compile time, but
-only known-type calls are efficiently compiled.
-
-On unix-like x86-64 and ARM64 systems, structures may be passed and
-returned by value. The implementation follows the System V AMD64 ABI
+On Unix-like x86-64 and ARM64 systems, structures may be passed and
+returned by value. The implementation follows the System V AMD64 ABI
and AAPCS64 specifications respectively.
-@end defun
-
-Here is an example which allocates a @code{(struct foo)}, calls a
-foreign function to initialize it, then returns a Lisp vector of all
+Here is an example which allocates a @code{(struct foo)}, calls a foreign
+function to initialize it, then returns a Lisp vector of all
the @code{(* (struct foo))} objects filled in by the foreign call:
-@lisp
+@example
;; Allocate a foo on the stack.
(with-alien ((f (struct foo)))
;; Call some C function to fill in foo fields.
@@ -782,34 +797,21 @@ the @code{(* (struct foo))} objects filled in by the foreign call:
(setf (svref result i) (deref (deref a) i)))
;; Voila.
result)))
-@end lisp
+@end example
+@end deffn
+@anchor{Function sb-alien alien-funcall-into}
+@ffindex @sortas{alien-funcall-into sb-alien} alien-funcall-into [sb-alien]
+@deffn{Function} sb-alien:alien-funcall-into alien result-buffer &rest args
+Call the foreign function @code{alien}, writing the struct result to @code{result-buffer}.
+Returns no values.
-@node The alien-funcall-into Primitive
-@comment node-name, next, previous, up
-@subsection The @code{alien-funcall-into} Primitive
+@code{result-buffer} should be a @code{system-area-pointer} to appropriately sized memory.
+Only supported on x86-64 and ARM64.
-@defun @sbalien{alien-funcall-into} @var{alien-function} @var{result-buffer} &rest @var{arguments}
+Here is an example that calls a C function returning a struct, writing
+the result to a stack-allocated buffer:
-The @code{alien-funcall-into} function calls a foreign function that
-returns a structure by value, writing the result directly into a
-caller-provided buffer rather than heap-allocating.
-
-@var{alien-function} is the foreign function to call.
-@var{result-buffer} is a @code{system-area-pointer} pointing to memory
-where the struct result will be written. The buffer is typically
-stack-allocated using @code{with-alien}.
-
-The function returns no values. The caller accesses the result
-through the buffer.
-
-This function is only available on x86-64 and ARM64.
-
-@end defun
-
-Here is an example that calls a C function returning a struct,
-writing the result to a stack-allocated buffer:
-
-@lisp
+@example
(define-alien-type nil (struct point (x double) (y double)))
(with-alien ((result (struct point)))
@@ -819,90 +821,69 @@ writing the result to a stack-allocated buffer:
(alien-sap (addr result))
1.0d0 2.0d0)
(values (slot result 'x) (slot result 'y)))
-@end lisp
+@end example
+@end deffn
+@anchor{Macro sb-alien define-alien-routine}
+@ffindex @sortas{define-alien-routine sb-alien} define-alien-routine [sb-alien]
+@deffn{Macro} sb-alien:define-alien-routine name result-type &rest args
+Define a foreign interface function for the routine with the specified @code{name}.
+Also automatically @code{declaim} the @code{ftype} of the defined function. The
+semantics of the actual call are the same as for @code{alien-funcall}.
-@node The define-alien-routine Macro
-@comment node-name, next, previous, up
-@subsection The @code{define-alien-routine} Macro
+This macro is a convenience for automatically generating Lisp
+interfaces to simple foreign functions. The primary feature is the
+parameter style specification, which translates the C
+pass-by-reference idiom into additional return values.
-@defmac @sbalien{define-alien-routine} @var{name} @var{result-type} &rest @var{arg-specifiers}
+@code{name} may be either a string, a symbol, or a list of the
+form @code{(<foreign-name-string> <lisp-name-symbol>)}.
-The @code{define-alien-routine} macro is a convenience for
-automatically generating Lisp interfaces to simple foreign functions.
-The primary feature is the parameter style specification, which
-translates the C pass-by-reference idiom into additional return
-values.
+@code{result-type} is the alien type for the function return value. @code{void} may be
+used to specify a function with no result.
-@var{name} is usually a string external symbol, but may also be a
-symbol Lisp name or a list of the foreign name and the Lisp name. If
-only one name is specified, the other is automatically derived as for
-@code{extern-alien}. @var{result-type} is the alien type of the
-return value.
+@code{args} is a list of @code{(arg-name arg-type &optional style)} elements.
+@code{arg-name} is a symbol that names the argument, primarily for
+documentation. @code{arg-type} is the C type of the argument.
-Each element of the @var{arg-specifiers} list
-specifies an argument to the foreign function, and is
-of the form
-@lisp
-(aname atype &optional style)
-@end lisp
-
-@var{aname} is the symbol name of the argument to the constructed
-function (for documentation). @var{atype} is the alien type of
-corresponding foreign argument. The semantics of the actual call are
-the same as for @code{alien-funcall}. @var{style} specifies how this
-argument should be handled at call and return time, and should be one
-of the following:
+@code{style} specifies the way that the argument is passed:
@itemize
+@item @code{:in}: An @code{:in} argument is simply passed by value. The value to be
+ passed is obtained from argument(s) to the interface function. No
+ values are returned for @code{:in} arguments. This is the default mode.
-@item
-@code{:in} specifies that the argument is passed by value. This is the
-default. @code{:in} arguments have no corresponding return value from
-the Lisp function.
+@item @code{:out}: A pass-by-reference output value. The specified argument type
+ must be a pointer to a fixed sized object. An object of the correct
+ size is allocated on the stack, and its address is passed to the
+ foreign function. When the function returns, the contents of this
+ location are returned as one of the values of the Lisp function (and
+ the location is automatically deallocated). @code{:out} and @code{:in-out} cannot
+ be used with pointers to arrays, records or functions.
-@item
-@code{:copy} is similar to @code{:in}, but the argument is copied to a
-pre-allocated object and a pointer to this object is passed to the
-foreign routine.
-
-@item
-@code{:out} specifies a pass-by-reference output value. The type of
-the argument must be a pointer to a fixed-sized object (such as an
-integer or pointer). @code{:out} and @code{:in-out} style cannot be
-used with pointers to arrays, records or functions. An object of the
-correct size is allocated on the stack, and its address is passed to
-the foreign function. When the function returns, the contents of this
-location are returned as one of the values of the Lisp function (and
-the location is automatically deallocated).
-
-@item
-@code{:in-out} is a combination of @code{:copy} and @code{:out}. The
-argument is copied to a pre-allocated object and a pointer to this
-object is passed to the foreign routine. On return, the contents of
-this location is returned as an additional value.
+@item @code{:copy}: This is similar to @code{:in}, except that the argument values are
+ stored on the stack, and a pointer to the object is passed instead
+ of the value itself.
+@item @code{:in-out}: This is a combination of @code{:out} and @code{:copy}. A pointer to the
+ argument is passed, with the object being initialized from the
+ supplied argument and the return value being determined by accessing
+ the object on return.
@end itemize
@quotation
-Note: Any efficiency-critical foreign interface function should be inline
-expanded, which can be done by preceding the
+@emph{Note}: Any efficiency-critical foreign interface function should be
+inline expanded, which can be done by preceding the
@code{define-alien-routine} call with:
-@lisp
+@example
(declaim (inline lisp-name))
-@end lisp
+@end example
In addition to avoiding the Lisp call overhead, this allows
pointers, word-integers and floats to be passed using non-descriptor
-representations, avoiding consing.)
+representations, avoiding consing.
@end quotation
-@end defmac
-
-@node define-alien-routine Example
-@comment node-name, next, previous, up
-@subsection @code{define-alien-routine} Example
-
Consider the C function @code{cfoo} with the following calling
convention:
@@ -917,164 +898,25 @@ cfoo (str, a, i)
@}
@end example
-This can be described by the following call to
-@code{define-alien-routine}:
+This can be described by the following call to @code{define-alien-routine}:
-@lisp
+@example
(define-alien-routine "cfoo" void
(str c-string)
(a char :in-out)
(i int :out))
-@end lisp
+@end example
-The Lisp function @code{cfoo} will have two arguments (@var{str} and
-@var{a}) and two return values (@var{a} and @var{i}).
-
-@c <!-- FIXME: This is a "changebar" section from the CMU CL manual.
-@c I (WHN 2002-07-14) am not very familiar with this content, so
-@c I'm not immediately prepared to try to update it for SBCL, and
-@c I'm not feeling masochistic enough to work to encourage this
-@c kind of low-level hack anyway. However, I acknowledge that callbacks
-@c are sometimes really really necessary, so I include the original
-@c text in case someone is hard-core enough to benefit from it. If
-@c anyone brings the information up to date for SBCL, it belong
-@c either in the main manual or on a CLiki SBCL Internals page.
-@c LaTeX \subsection{Accessing Lisp Arrays}
-@c LaTeX
-@c LaTeX Due to the way \cmucl{} manages memory, the amount of memory that can
-@c LaTeX be dynamically allocated by \code{malloc} or \funref{make-alien} is
-@c LaTeX limited\footnote{\cmucl{} mmaps a large piece of memory for it's own
-@c LaTeX use and this memory is typically about 8 MB above the start of the C
-@c LaTeX heap. Thus, only about 8 MB of memory can be dynamically
-@c LaTeX allocated.}.
-
-@c Empirically determined to be considerably >8Mb on this x86 linux
-@c machine, but I don't know what the actual values are - dan 2003.09.01
-
-@c Note that this technique is used in SB-GROVEL in the SBCL contrib
-
-@c LaTeX
-@c LaTeX To overcome this limitation, it is possible to access the content of
-@c LaTeX Lisp arrays which are limited only by the amount of physical memory
-@c LaTeX and swap space available. However, this technique is only useful if
-@c LaTeX the foreign function takes pointers to memory instead of allocating
-@c LaTeX memory for itself. In latter case, you will have to modify the
-@c LaTeX foreign functions.
-@c LaTeX
-@c LaTeX This technique takes advantage of the fact that \cmucl{} has
-@c LaTeX specialized array types (\pxlref{specialized-array-types}) that match
-@c LaTeX a typical C array. For example, a \code{(simple-array double-float
-@c LaTeX (100))} is stored in memory in essentially the same way as the C
-@c LaTeX array \code{double x[100]} would be. The following function allows us
-@c LaTeX to get the physical address of such a Lisp array:
-@c LaTeX \begin{example}
-@c LaTeX (defun array-data-address (array)
-@c LaTeX "Return the physical address of where the actual data of an array is
-@c LaTeX stored.
-@c LaTeX
-@c LaTeX ARRAY must be a specialized array type in CMU Lisp. This means ARRAY
-@c LaTeX must be an array of one of the following types:
-@c LaTeX
-@c LaTeX double-float
-@c LaTeX single-float
-@c LaTeX (unsigned-byte 32)
-@c LaTeX (unsigned-byte 16)
-@c LaTeX (unsigned-byte 8)
-@c LaTeX (signed-byte 32)
-@c LaTeX (signed-byte 16)
-@c LaTeX (signed-byte 8)
-@c LaTeX "
-@c LaTeX (declare (type (or #+signed-array (array (signed-byte 8))
-@c LaTeX #+signed-array (array (signed-byte 16))
-@c LaTeX #+signed-array (array (signed-byte 32))
-@c LaTeX (array (unsigned-byte 8))
-@c LaTeX (array (unsigned-byte 16))
-@c LaTeX (array (unsigned-byte 32))
-@c LaTeX (array single-float)
-@c LaTeX (array double-float))
-@c LaTeX array)
-@c LaTeX (optimize (speed 3) (safety 0))
-@c LaTeX (ext:optimize-interface (safety 3)))
-@c LaTeX ;; with-array-data will get us to the actual data. However, because
-@c LaTeX ;; the array could have been displaced, we need to know where the
-@c LaTeX ;; data starts.
-@c LaTeX (lisp::with-array-data ((data array)
-@c LaTeX (start)
-@c LaTeX (end))
-@c LaTeX (declare (ignore end))
-@c LaTeX ;; DATA is a specialized simple-array. Memory is laid out like this:
-@c LaTeX ;;
-@c LaTeX ;; byte offset Value
-@c LaTeX ;; 0 type code (should be 70 for double-float vector)
-@c LaTeX ;; 4 4 * number of elements in vector
-@c LaTeX ;; 8 1st element of vector
-@c LaTeX ;; ... ...
-@c LaTeX ;;
-@c LaTeX (let ((addr (+ 8 (logandc1 7 (kernel:get-lisp-obj-address data))))
-@c LaTeX (type-size (let ((type (array-element-type data)))
-@c LaTeX (cond ((or (equal type '(signed-byte 8))
-@c LaTeX (equal type '(unsigned-byte 8)))
-@c LaTeX 1)
-@c LaTeX ((or (equal type '(signed-byte 16))
-@c LaTeX (equal type '(unsigned-byte 16)))
-@c LaTeX 2)
-@c LaTeX ((or (equal type '(signed-byte 32))
-@c LaTeX (equal type '(unsigned-byte 32)))
-@c LaTeX 4)
-@c LaTeX ((equal type 'single-float)
-@c LaTeX 4)
-@c LaTeX ((equal type 'double-float)
-@c LaTeX 8)
-@c LaTeX (t
-@c LaTeX (error "Unknown specialized array element type"))))))
-@c LaTeX (declare (type (unsigned-byte 32) addr)
-@c LaTeX (optimize (speed 3) (safety 0) (ext:inhibit-warnings 3)))
-@c LaTeX (system:int-sap (the (unsigned-byte 32)
-@c LaTeX (+ addr (* type-size start)))))))
-@c LaTeX \end{example}
-@c LaTeX
-@c LaTeX Assume we have the C function below that we wish to use:
-@c LaTeX \begin{example}
-@c LaTeX double dotprod(double* x, double* y, int n)
-@c LaTeX \{
-@c LaTeX int k;
-@c LaTeX double sum = 0;
-@c LaTeX
-@c LaTeX for (k = 0; k < n; ++k) \{
-@c LaTeX sum += x[k] * y[k];
-@c LaTeX \}
-@c LaTeX \}
-@c LaTeX \end{example}
-@c LaTeX The following example generates two large arrays in Lisp, and calls the C
-@c LaTeX function to do the desired computation. This would not have been
-@c LaTeX possible using \code{malloc} or \code{make-alien} since we need about
-@c LaTeX 16 MB of memory to hold the two arrays.
-@c LaTeX \begin{example}
-@c LaTeX (define-alien-routine "dotprod" double
-@c LaTeX (x (* double-float) :in)
-@c LaTeX (y (* double-float) :in)
-@c LaTeX (n int :in))
-@c LaTeX
-@c LaTeX (let ((x (make-array 1000000 :element-type 'double-float))
-@c LaTeX (y (make-array 1000000 :element-type 'double-float)))
-@c LaTeX ;; Initialize X and Y somehow
-@c LaTeX (let ((x-addr (system:int-sap (array-data-address x)))
-@c LaTeX (y-addr (system:int-sap (array-data-address y))))
-@c LaTeX (dotprod x-addr y-addr 1000000)))
-@c LaTeX \end{example}
-@c LaTeX In this example, it may be useful to wrap the inner \code{let}
-@c LaTeX expression in an \code{unwind-protect} that first turns off garbage
-@c LaTeX collection and then turns garbage collection on afterwards. This will
-@c LaTeX prevent garbage collection from moving \code{x} and \code{y} after we
-@c LaTeX have obtained the (now erroneous) addresses but before the call to
-@c LaTeX \code{dotprod} is made.
-@c LaTeX
-@c -->
-
-@node Calling Lisp From C
-@comment node-name, next, previous, up
+The Lisp function @code{cfoo} will have two arguments (@code{str} and @code{a}) and
+two return values (@code{a} and @code{i}).
+@end deffn
+@node calling lisp from c
@section Calling Lisp From C
+@menu
+* Lisp as a Shared Library: lisp as a shared library.
+@end menu
+
SBCL supports the calling of Lisp functions using the C calling
convention. This is useful for both defining callbacks and for creating
an interface for calling into Lisp as a shared library directly from C.
@@ -1084,74 +926,98 @@ foreign function which can be called with the C calling convention.
On x86-64 and ARM64, callbacks may receive and return structures by
value.
-@include macro-sb-alien-define-alien-callable.texinfo
+@anchor{Macro sb-alien define-alien-callable}
+@ffindex @sortas{define-alien-callable sb-alien} define-alien-callable [sb-alien]
+@deffn{Macro} sb-alien:define-alien-callable name result-type typed-lambda-list &body body
+Define an alien function which can be called by alien code. The alien
+function returned by (@code{alien-callable-function} @code{name}) expects alien
+arguments of the specified @code{arg-type}s and returns an alien of type
+@code{result-type}.
+@code{typed-lambda-list} is a list of @code{(arg-name arg-type)} elements, and
+@code{body} is @code{@{doc-string@} @{decl@}* @{form@}*}.
+
+If (@code{alien-callable-function} @code{name}) already exists, its value is not
+changed (though it is arranged that an updated version of the Lisp
+callable function will be called, provided that the new type and the
+existing type are compatible). This feature allows for incremental
+redefinition of callable functions.
+@end deffn
The @code{alien-callable-function} function returns the foreign callable
-value associated with any name defined by @code{define-alien-callable},
-so that we can, for example, pass the callable value to C as a callback.
-
-@include fun-sb-alien-alien-callable-function.texinfo
+value associated with any name defined by @code{define-alien-callable}, so
+that we can, for example, pass the callable value to C as a
+callback.
+@anchor{Function sb-alien alien-callable-function}
+@ffindex @sortas{alien-callable-function sb-alien} alien-callable-function [sb-alien]
+@deffn{Function} sb-alien:alien-callable-function name
+Return the alien callable function associated with @code{name}.
+@end deffn
The @code{with-alien-callable} macro wraps Lisp code and establishes
local C foreign functions which can be called with the C calling
convention. This macro is handy for passing callbacks which close over
Lisp values into C.
-@include macro-sb-alien-with-alien-callable.texinfo
+@anchor{Macro sb-alien with-alien-callable}
+@ffindex @sortas{with-alien-callable sb-alien} with-alien-callable [sb-alien]
+@deffn{Macro} sb-alien:with-alien-callable definitions &body body
+Establish some local alien functions.
+Each element of @code{definitions} is of the form:
+@example
+NAME RESULT-TYPE @{(ARG-NAME ARG-TYPE)@}* @{DOC-STRING@} @{DECL@}* @{FORM@}*
+@end example
+
+The resulting alien callable value has dynamic extent.
+@end deffn
Note that the garbage collector moves objects, and won't be able to fix
-up any references in C variables. There are three mechanisms for coping
-with this:
+up any references in C variables. There are three mechanisms for
+coping with this:
-@enumerate
-@item
-The @code{sb-ext:purify} moves all live Lisp data into static or
-read-only areas such that it will never be moved (or freed) again in the
-life of the Lisp session
+@itemize
+@item @code{sb-ext:purify} moves all live Lisp data into static or read-only
+ areas such that it will never be moved (or freed) again in the
+ life of the Lisp session
-@item
-@code{sb-sys:with-pinned-objects} is a macro which arranges for some set
-of objects to be pinned in memory for the dynamic extent of its body
-forms. On ports which use the generational garbage collector (most, as
-of this writing) this affects exactly the specified objects. On other
-ports it is implemented by turning off GC for the duration (so could be
-said to have a whole-world granularity).
+@item @code{sb-sys:with-pinned-objects} is a macro which arranges for some set
+ of objects to be pinned in memory for the dynamic extent of its
+ body forms. On ports which use the generational garbage
+ collector (most, as of this writing) this affects exactly the
+ specified objects. On other ports it is implemented by turning off
+ GC for the duration (so could be said to have a whole-world
+ granularity).
-@item
-Disable GC, using the @code{without-gcing} macro.
-@end enumerate
+@item Disable GC, using the SB-EXT:WITHOUT-GCING macro.
+@end itemize
-@menu
-* Lisp as a Shared Library::
-@end menu
-
-@node Lisp as a Shared Library
-@comment node-name, next, previous, up
+@node lisp as a shared library
@subsection Lisp as a Shared Library
-SBCL supports the use of Lisp as a shared library that can be used by C
-programs using the @code{define-alien-callable} interface. See the
-@code{:callable-exports} keyword to @code{save-lisp-and-die} for how to
-save the Lisp image in a way that allows a C program to initialize the
-Lisp runtime and the exported symbols. When SBCL is built as a library,
-it exposes the symbol @code{initialize_lisp} which can be used in
-conjunction with a core initializing global symbols to foreign callables
-as function pointers and with object code allocating those symbols to
-initialize the runtime properly. The arguments to @code{initialize_lisp}
-are the same as the arguments to the main @code{sbcl}
+
+SBCL supports the use of Lisp as a shared library that can be used by
+C programs using the @code{define-alien-callable} interface. See the
+@code{:callable-exports} argument of @code{sb-ext:save-lisp-and-die} for how to
+save the Lisp image in a way that allows a C program to initialize
+the Lisp runtime and the exported symbols. When SBCL is built as a
+library, it exposes the symbol @code{initialize_lisp} which can be used
+in conjunction with a core initializing global symbols to foreign
+callables as function pointers and with object code allocating those
+symbols to initialize the runtime properly. The arguments to
+@code{initialize_lisp} are the same as the arguments to the main @code{sbcl}
program.
-Note: There is currently no way to run exit hooks or otherwise undo
-Lisp initialization gracefully from C.
+@quotation
+@emph{Note}: There is currently no way to run exit hooks or otherwise
+undo Lisp initialization gracefully from C.
+@end quotation
-@node Step-By-Step Example of the Foreign Function Interface
-@comment node-name, next, previous, up
+@node step by step example of the foreign function interface
@section Step-By-Step Example of the Foreign Function Interface
This section presents a complete example of an interface to a somewhat
complicated C function.
-Suppose you have the following C function which you want to be able to
-call from Lisp in the file @file{test.c}
+Suppose you have the following C function which you want to be able
+to call from Lisp in the file @code{test.c}:
@example
struct c_struct
@@ -1169,11 +1035,11 @@ struct c_struct *c_function (i, s, r, a)
int j;
struct c_struct *r2;
- printf("i = %d\n", i);
- printf("s = %s\n", s);
- printf("r->x = %d\n", r->x);
- printf("r->s = %s\n", r->s);
- for (j = 0; j < 10; j++) printf("a[%d] = %d.\n", j, a[j]);
+ printf("i = %dn", i);
+ printf("s = %sn", s);
+ printf("r->x = %dn", r->x);
+ printf("r->s = %sn", r->s);
+ for (j = 0; j < 10; j++) printf("a[%d] = %d.n", j, a[j]);
r2 = (struct c_struct *) malloc (sizeof(struct c_struct));
r2->x = i + 5;
r2->s = "a C string";
@@ -1182,9 +1048,9 @@ struct c_struct *c_function (i, s, r, a)
@end example
It is possible to call this C function from Lisp using the file
-@file{test.lisp} containing
+@code{test.lisp} containing
-@lisp
+@example
(cl:defpackage "TEST-C-CALL" (:use "CL" "SB-ALIEN" "SB-C-CALL"))
(cl:in-package "TEST-C-CALL")
@@ -1221,7 +1087,7 @@ It is possible to call this C function from Lisp using the file
(with-alien ((res (* (struct c-struct))
(c-function 5 "another Lisp string" (addr c-struct) ar)))
- (format t "~&back from C function~%")
+ (format t "~&back from C function~%")
(multiple-value-prog1
(values (slot res 'x)
(slot res 's))
@@ -1229,29 +1095,44 @@ It is possible to call this C function from Lisp using the file
;; Deallocate result. (after we are done referring to it:
;; "Pillage, *then* burn.")
(free-alien res)))))
-@end lisp
+@end example
To execute the above example, it is necessary to compile the C
-routine, e.g.: @samp{cc -c test.c && ld -shared -o test.so test.o} (In
-order to enable incremental loading with some linkers, you may need to
-say @samp{cc -G 0 -c test.c})
+routine, e.g. with @code{cc -c test.c && ld -shared -o test.so test.o}.
+In order to enable incremental loading with some linkers, you may
+need to say @code{cc -G 0 -c test.c}.
-Once the C code has been compiled, you can start up Lisp and load it in:
-@samp{sbcl}. Lisp should start up with its normal prompt.
+Once the C code has been compiled, you can start up Lisp and load it
+in: @code{sbcl}. Lisp should start up with its normal prompt.
-Within Lisp, compile the Lisp file. (This step can be done
-separately. You don't have to recompile every time.)
-@samp{(compile-file "test.lisp")}
+Within Lisp, compile the Lisp file:
+
+@example
+(compile-file "test.lisp")
+@end example
+
+This step can be done separately. You don't have to recompile every
+time.
Within Lisp, load the foreign object file to define the necessary
-symbols: @samp{(load-shared-object "test.so")}.
-
-Now you can load the compiled Lisp (``fasl'') file into Lisp:
-@samp{(load "test.fasl")}
-And once the Lisp file is loaded, you can call the
-Lisp routine that sets up the parameters and calls the C
-function:
-@samp{(test-c-call::call-cfun)}
+symbols:
+
+@example
+(load-shared-object "test.so")
+@end example
+
+Now you can load the compiled Lisp (fasl) file into Lisp:
+
+@example
+(load "test.fasl")
+@end example
+
+And once the Lisp file is loaded, you can call the Lisp routine
+that sets up the parameters and calls the C function:
+
+@example
+(test-c-call::call-cfun)
+@end example
The C routine should print the following information to standard output:
@@ -1287,3 +1168,4 @@ Lisp read-eval-print loop should print the following return values:
10
"a C string"
@end example
+
diff --git a/doc/manual/gray-streams-examples.texinfo b/doc/manual/gray-streams-examples.texinfo
deleted file mode 100644
index 8418bf0c7..000000000
--- a/doc/manual/gray-streams-examples.texinfo
+++ /dev/null
@@ -1,223 +0,0 @@
-@node Gray Streams examples
-@subsection Gray Streams examples
-
-@macro codew{stuff}
-@code{@w{\stuff\}}
-@end macro
-
-Below are two classes of stream that can be conveniently defined as
-wrappers for Common Lisp streams. These are meant to serve as
-examples of minimal implementations of the protocols that must be
-followed when defining Gray streams. Realistic uses of the Gray
-Streams API would implement the various methods that can do I/O in
-batches, such as @codew{stream-read-line}, @codew{stream-write-string},
-@codew{stream-read-sequence}, and @codew{stream-write-sequence}.
-
-
-@menu
-* Character counting input stream::
-* Output prefixing character stream::
-@end menu
-
-@node Character counting input stream
-@subsubsection Character counting input stream
-
-It is occasionally handy for programs that process input files to
-count the number of characters and lines seen so far, and the number
-of characters seen on the current line, so that useful messages may be
-reported in case of parsing errors, etc. Here is a character input
-stream class that keeps track of these counts. Note that all
-character input streams must implement @codew{stream-read-char} and
-@codew{stream-unread-char}.
-
-@lisp
-@group
-(defclass wrapped-stream (fundamental-stream)
- ((stream :initarg :stream :reader stream-of)))
-@end group
-@group
-(defmethod stream-element-type ((stream wrapped-stream))
- (stream-element-type (stream-of stream)))
-@end group
-@group
-(defmethod close ((stream wrapped-stream) &key abort)
- (close (stream-of stream) :abort abort))
-@end group
-@group
-(defclass wrapped-character-input-stream
- (wrapped-stream fundamental-character-input-stream)
- ())
-@end group
-@group
-(defmethod stream-read-char ((stream wrapped-character-input-stream))
- (read-char (stream-of stream) nil :eof))
-@end group
-@group
-(defmethod stream-unread-char ((stream wrapped-character-input-stream)
- char)
- (unread-char char (stream-of stream)))
-@end group
-@group
-(defclass counting-character-input-stream
- (wrapped-character-input-stream)
- ((char-count :initform 1 :accessor char-count-of)
- (line-count :initform 1 :accessor line-count-of)
- (col-count :initform 1 :accessor col-count-of)
- (prev-col-count :initform 1 :accessor prev-col-count-of)))
-@end group
-@group
-(defmethod stream-read-char ((stream counting-character-input-stream))
- (with-accessors ((inner-stream stream-of) (chars char-count-of)
- (lines line-count-of) (cols col-count-of)
- (prev prev-col-count-of)) stream
- (let ((char (call-next-method)))
- (cond ((eql char :eof)
- :eof)
- ((char= char #\Newline)
- (incf lines)
- (incf chars)
- (setf prev cols)
- (setf cols 1)
- char)
- (t
- (incf chars)
- (incf cols)
- char)))))
-@end group
-@group
-(defmethod stream-unread-char ((stream counting-character-input-stream)
- char)
- (with-accessors ((inner-stream stream-of) (chars char-count-of)
- (lines line-count-of) (cols col-count-of)
- (prev prev-col-count-of)) stream
- (cond ((char= char #\Newline)
- (decf lines)
- (decf chars)
- (setf cols prev))
- (t
- (decf chars)
- (decf cols)
- char))
- (call-next-method)))
-@end group
-@end lisp
-
-The default methods for @codew{stream-read-char-no-hang},
-@codew{stream-peek-char}, @codew{stream-listen},
-@codew{stream-clear-input}, @codew{stream-read-line}, and
-@codew{stream-read-sequence} should be sufficient (though the last two
-will probably be slower than methods that forwarded directly).
-
-Here's a sample use of this class:
-
-@lisp
-@group
-(with-input-from-string (input "1 2
- 3 :foo ")
- (let ((counted-stream (make-instance 'counting-character-input-stream
- :stream input)))
- (loop for thing = (read counted-stream) while thing
- unless (numberp thing) do
- (error "Non-number ~S (line ~D, column ~D)" thing
- (line-count-of counted-stream)
- (- (col-count-of counted-stream)
- (length (format nil "~S" thing))))
- end
- do (print thing))))
-@end group
-@verbatim
-1
-2
-3
-Non-number :FOO (line 2, column 5)
- [Condition of type SIMPLE-ERROR]
-@end verbatim
-@end lisp
-
-@node Output prefixing character stream
-@subsubsection Output prefixing character stream
-
-One use for a wrapped output stream might be to prefix each line of
-text with a timestamp, e.g., for a logging stream. Here's a simple
-stream that does this, though without any fancy line-wrapping. Note
-that all character output stream classes must implement
-@codew{stream-write-char} and @codew{stream-line-column}.
-
-@lisp
-@group
-(defclass wrapped-stream (fundamental-stream)
- ((stream :initarg :stream :reader stream-of)))
-@end group
-@group
-(defmethod stream-element-type ((stream wrapped-stream))
- (stream-element-type (stream-of stream)))
-@end group
-@group
-(defmethod close ((stream wrapped-stream) &key abort)
- (close (stream-of stream) :abort abort))
-@end group
-@group
-(defclass wrapped-character-output-stream
- (wrapped-stream fundamental-character-output-stream)
- ((col-index :initform 0 :accessor col-index-of)))
-@end group
-@group
-(defmethod stream-line-column ((stream wrapped-character-output-stream))
- (col-index-of stream))
-@end group
-@group
-(defmethod stream-write-char ((stream wrapped-character-output-stream)
- char)
- (with-accessors ((inner-stream stream-of) (cols col-index-of)) stream
- (write-char char inner-stream)
- (if (char= char #\Newline)
- (setf cols 0)
- (incf cols))))
-@end group
-@group
-(defclass prefixed-character-output-stream
- (wrapped-character-output-stream)
- ((prefix :initarg :prefix :reader prefix-of)))
-@end group
-@group
-(defgeneric write-prefix (prefix stream)
- (:method ((prefix string) stream) (write-string prefix stream))
- (:method ((prefix function) stream) (funcall prefix stream)))
-@end group
-@group
-(defmethod stream-write-char ((stream prefixed-character-output-stream)
- char)
- (with-accessors ((inner-stream stream-of) (cols col-index-of)
- (prefix prefix-of)) stream
- (when (zerop cols)
- (write-prefix prefix inner-stream))
- (call-next-method)))
-@end group
-@end lisp
-
-As with the example input stream, this implements only the minimal
-protocol. A production implementation should also provide methods for
-at least @codew{stream-write-line}, @codew{stream-write-sequence}.
-
-And here's a sample use of this class:
-
-@lisp
-@group
-(flet ((format-timestamp (stream)
- (apply #'format stream "[~2@@*~2,' D:~1@@*~2,'0D:~0@@*~2,'0D] "
- (multiple-value-list (get-decoded-time)))))
- (let ((output (make-instance 'prefixed-character-output-stream
- :stream *standard-output*
- :prefix #'format-timestamp)))
- (loop for string in '("abc" "def" "ghi") do
- (write-line string output)
- (sleep 1))))
-@end group
-@verbatim
-[ 0:30:05] abc
-[ 0:30:06] def
-[ 0:30:07] ghi
-NIL
-@end verbatim
-@end lisp
-@unmacro codew
diff --git a/doc/manual/intro.texinfo b/doc/manual/intro.texinfo
index df985e16a..576318783 100644
--- a/doc/manual/intro.texinfo
+++ b/doc/manual/intro.texinfo
@@ -1,210 +1,172 @@
-@node Introduction
-@comment node-name, next, previous, up
+@c Generated by the sb-manual contrib. Do not edit.
+
+@node introduction
@chapter Introduction
+@menu
+* ANSI Conformance: ansi conformance.
+* Extensions: extensions.
+* Idiosyncrasies: idiosyncrasies.
+* Development Tools: development tools.
+* More SBCL Information: more sbcl information.
+* More Common Lisp Information: more common lisp information.
+* History and Implementation of SBCL: history and implementation of sbcl.
+@end menu
+
SBCL is a mostly-conforming implementation of the ANSI Common Lisp
standard. This manual focuses on behavior which is specific to SBCL,
not on behavior which is common to all implementations of ANSI Common
Lisp.
-@menu
-* ANSI Conformance::
-* Extensions::
-* Idiosyncrasies::
-* Development Tools::
-* More SBCL Information::
-* More Common Lisp Information::
-* History and Implementation of SBCL::
-@end menu
-
-
-
-@node ANSI Conformance
-@comment node-name, next, previous, up
+@node ansi conformance
@section ANSI Conformance
Essentially every type of non-conformance is considered a bug. (The
-exceptions involve internal inconsistencies in the standard.)
-@xref{Reporting Bugs}.
-
-@subsection Exceptions
+exceptions involve internal inconsistencies in the standard.) See
+@ref{reporting bugs}.
@itemize
-
-@item
-@findex @cl{prog2}
-@code{prog2} returns the primary value of its second form, as
-specified in the @strong{Arguments and Values} section of the
-specification for that operator, not that of its first form, as
-specified in the @strong{Description}.
-
-@item
-@tindex @cl{string}
-@tindex @cl{character}
-@tindex @cl{nil}
-The @code{string} type is considered to be the union of all types
-@code{(array @emph{c} (@emph{size}))} for all non-@code{nil} subtypes @code{@emph{c}} of
-@code{character}, excluding arrays specialized to the empty type.
-
-@item
-@findex @cl{define-method-combination}
-@vindex @cl{nil}
-The @code{:order} long form option in @code{define-method-combination}
-method group specifiers accepts the value @code{nil} as well as
-@code{:most-specific-first} and @code{:most-specific-last}, in order
-to allow programmers to declare that the order of methods playing that
-role in the method combination does not matter.
-
+@item @code{prog2} returns the primary value of its second form, as
+ specified in the @emph{Arguments and Values} section of the
+ specification for that operator, not that of its first form, as
+ specified in the @emph{Description}.
+
+@item The @code{string} type is considered to be the union of all types
+ @code{(array c (size))} for all non-@code{nil} subtypes @code{c} of @code{character},
+ excluding arrays specialized to the empty type.
+
+@item The @code{:order} long form option in @code{define-method-combination} method
+ group specifiers accepts the value @code{nil} as well as
+ @code{:most-specific-first} and @code{:most-specific-last}, in order to allow
+ programmers to declare that the order of methods playing that role
+ in the method combination does not matter.
@end itemize
-@node Extensions
-@comment node-name, next, previous, up
+@node extensions
@section Extensions
SBCL comes with numerous extensions, some in core and some in modules
-loadable with @code{require}. Unfortunately, not all of these
-extensions have proper documentation yet.
-
-@c FIXME: Once bits and pieces referred to here get real documentation
-@c add xrefs there.
-
-@table @strong
-
-@item System Definition Tool
-@code{asdf} is a flexible and popular protocol-oriented system
-definition tool by Daniel Barlow. @xref{Top, , , asdf} for more
-information.
+loadable with @code{require}. Unfortunately, not all of these extensions
+have proper documentation yet.
-@item Foreign Function Interface
-@code{sb-alien} package allows interfacing with C-code, loading shared
-object files, etc. @xref{Foreign Function Interface}.
+@itemize
+@item @strong{System Definition Tool:} ASDF is a flexible and popular
+ protocol-oriented system definition tool by Daniel Barlow.
-@code{sb-grovel} can be used to partially automate generation of
-foreign function interface definitions. @xref{sb-grovel}.
+@item @strong{Foreign Function Interface:} The @code{sb-alien} package allows
+ interfacing with C-code, loading shared object files, etc. See
+ @ref{foreign function interface}.
-@item Recursive Event Loop
-SBCL provides a recursive event loop (@code{serve-event}) for doing
-non-blocking IO on multiple streams without using threads.
+@ref{sb grovel} can be used to partially automate generation of
+foreign function interface definitions.
-@item Timeouts and Deadlines
-SBCL allows restricting the execution time of individual operations or
-parts of a computation using @code{:timeout} arguments to certain
-blocking operations, synchronous timeouts and asynchronous timeouts. The
-latter two affect operations without explicit timeout support (such as
-standard functions and macros). @xref{Timeouts and Deadlines}.
+@item @strong{Recursive Event Loop:} SBCL provides a recursive event
+ loop (@code{serve-event}) for doing non-blocking IO on multiple streams
+ without using threads.
-@item Metaobject Protocol
-@code{sb-mop} package provides a metaobject protocol for the Common
-Lisp Object System as described in @cite{Art of Metaobject Protocol}.
+@item @strong{Timeouts and Deadlines:} SBCL allows restricting the execution
+ time of individual operations or parts of a computation using
+ @code{:timeout} arguments to certain blocking operations, synchronous
+ timeouts and asynchronous timeouts. The latter two affect operations
+ without explicit timeout support (such as standard functions and
+ macros). See @ref{timeouts and deadlines}.
-@item Extensible Sequences
-SBCL allows users to define subclasses of the @code{sequence}
-class. @xref{Extensible Sequences}.
+@item @strong{Metaobject Protocol:} The @code{sb-mop} package provides an
+ implementation of the metaobject protocol for the Common Lisp
+ Object System as described in @emph{The Art of the Metaobject Protocol}
+ by Kiczales et al.
-@item Native Threads
-SBCL has native threads on x86/Linux, capable of taking advantage
-of SMP on multiprocessor machines. @xref{Threading}.
+@item @strong{Extensible Sequences:} SBCL allows users to define subclasses
+ of the @code{sequence} class. See @ref{extensible sequences}.
-@item Network Interface
-@code{sb-bsd-sockets} is a low-level networking interface, providing
-both TCP and UDP sockets. @xref{Networking}.
+@item @strong{Native Threads:} SBCL has native threads on numerous platforms,
+ capable of taking advantage of SMP on multiprocessor machines. See
+ @ref{threading}.
-@item Introspective Facilities
-@code{sb-introspect} module offers numerous introspective extensions,
-including access to function lambda-lists and a cross referencing
-facility.
+@item @strong{Network Interface:} The @code{sb-bsd-sockets} module is a low-level
+ networking interface, providing both TCP and UDP sockets. See
+ @ref{networking}.
-@item Operating System Interface
-@code{sb-ext} contains a number of functions for running external
-processes, accessing environment variables, etc.
+@item @strong{Introspective Facilities:} The @ref{sb introspect} module offers
+ numerous introspective extensions, including access to function
+ lambda-lists and a cross referencing facility.
-@code{sb-posix} module provides a lispy interface to standard POSIX
-facilities.
+@item @strong{Operating System Interface:} The @code{sb-ext} package contains a
+ number of functions for running external processes, accessing
+ environment variables, etc.
-@item Extensible Streams
-@code{sb-gray} is an implementation of @emph{Gray Streams}. @xref{Gray
-Streams}.
+The @ref{sb posix} module provides a lispy interface to standard
+POSIX facilities.
-@code{sb-simple-streams} is an implementation of the @emph{simple
-streams} API proposed by Franz Inc. @xref{Simple Streams}.
+@item @strong{Extensible Streams:} The package @code{sb-gray} provides an
+ implementation of @ref{gray streams}.
-@item Profiling
-@code{sb-profile} is a exact per-function profiler. @xref{Deterministic
-Profiler}.
+The @ref{sb simple streams} module is an implementation of the Simple
+Streams API proposed by Franz Inc.
-@code{sb-sprof} is a statistical profiler, capable of call-graph
-generation and instruction level profiling, which also supports
-allocation profiling. @xref{Statistical Profiler}.
+@item @strong{Profiling:} The @code{sb-profile} package provides an exact,
+ per-function @ref{deterministic profiler}.
-@item Customization Hooks
-SBCL contains a number of extra-standard customization hooks that
-can be used to tweak the behaviour of the system. @xref{Customization
-Hooks for Users}.
+The @code{sb-sprof} module is SBCL's @ref{statistical profiler}, capable
+of call-graph generation and instruction level profiling, which
+also supports allocation profiling.
-@code{sb-aclrepl} provides an Allegro CL -style toplevel for SBCL,
-as an alternative to the classic CMUCL-style one. @xref{sb-aclrepl}.
+@item @strong{Customization Hooks:} SBCL contains a number of extra-standard
+ customization hooks that can be used to tweak the behaviour of the
+ system. See @ref{customization hooks for users}.
-@item CLTL2 Compatibility Layer
-@code{sb-cltl2} module provides @code{compiler-let} and environment
-access functionality described in @cite{Common Lisp The Language, 2nd
-Edition} which were removed from the language during the ANSI
-standardization process.
+@item @strong{sb-aclrepl:} The @ref{sb aclrepl} module provides an Allegro-style
+ toplevel for SBCL, as an alternative to the classic CMUCL-style
+ one.
-@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
-runtime.
+@item @strong{CLTL2 Compatibility Layer:} The SB-CLTL2 module provides
+ @code{sb-cltl2:compiler-let} and environment access functionality
+ described in @emph{Common Lisp The Language, 2nd Edition} which were
+ removed from the language during the ANSI standardization process.
-@item Bitwise Rotation
-@code{sb-rotate-byte} provides an efficient primitive for bitwise
-rotation of integers, an operation required by e.g. numerous
-cryptographic algorithms, but not available as a primitive in ANSI
-Common Lisp. @xref{sb-rotate-byte}.
+@item @strong{Executable Delivery:} The @code{:executable} argument to
+ @code{sb-ext:save-lisp-and-die} can produce a "standalone" executable
+ containing both an image of the current Lisp session and an SBCL
+ runtime.
-@item Test Harness
-@code{sb-rt} module is a simple yet attractive regression and
-unit-test framework.
+@item @strong{Bitwise Rotation:} The @ref{sb rotate byte} module provides an
+ efficient primitive for bitwise rotation of integers, an operation
+ required by e.g. numerous cryptographic algorithms but not
+ available as a primitive in ANSI Common Lisp.
-@item MD5 Sums
-@code{sb-md5} is an implementation of the MD5 message digest algorithm
-for Common Lisp, using the modular arithmetic optimizations provided
-by SBCL. @xref{sb-md5}.
+@item @strong{Test Harness:} The @code{sb-rt} module is a simple yet attractive
+ regression and unit-test framework.
-@end table
+@item @strong{MD5 Sums:} The @ref{sb md5} module provides an implementation of the
+ MD5 message digest algorithm for Common Lisp, using the modular
+ arithmetic optimizations provided by SBCL.
+@end itemize
-
-
-
-@node Idiosyncrasies
-@comment node-name, next, previous, up
+@node idiosyncrasies
@section Idiosyncrasies
+@menu
+* Declarations: declarations.
+* FASL format: fasl format.
+* Compiler-only Implementation: compiler only implementation.
+* Defining Constants: defining constants.
+* Style Warnings: style warnings.
+@end menu
+
The information in this section describes some of the ways that SBCL
deals with choices that the ANSI standard leaves to the
implementation.
-@menu
-* Declarations::
-* FASL Format::
-* Compiler-only Implementation::
-* Defining Constants::
-* Style Warnings::
-@end menu
-
-@node Declarations
-@comment node-name, next, previous, up
+@node declarations
@subsection Declarations
Declarations are generally treated as assertions. This general
principle, and its implications, and the bugs which still keep the
compiler from quite satisfying this principle, are discussed in
-@ref{Declarations as Assertions}.
+@ref{declarations as assertions}.
-
-@node FASL Format
-@comment node-name, next, previous, up
-@subsection FASL Format
+@node fasl format
+@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
@@ -213,10 +175,10 @@ 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}.)
+ASDF-based systems, and makes a good candidate for inclusion in the
+user or system initialization file (see @ref{initialization files}).
-@lisp
+@example
(require :asdf)
;;; If a fasl was stale, try to recompile and load (once).
@@ -227,328 +189,302 @@ the user or system initialization file (@pxref{Initialization Files}.)
(sb-ext:invalid-fasl ()
(asdf:perform (make-instance 'asdf:compile-op) c)
(call-next-method))))
-@end lisp
+@end example
-
-@node Compiler-only Implementation
-@comment node-name, next, previous, up
+@node compiler only implementation
@subsection Compiler-only Implementation
SBCL is essentially a compiler-only implementation of Common Lisp.
That is, for all but a few special cases, @code{eval} creates a lambda
expression, calls @code{compile} on the lambda expression to create a
-compiled function, and then calls @code{funcall} on the resulting
-function object. A more traditional interpreter is also available on
-default builds; it is usually only called internally. This is
-explicitly allowed by the ANSI standard, but leads to some oddities;
-e.g. at default settings, @code{functionp} and
-@code{compiled-function-p} are equivalent, and they collapse into the
-same function when SBCL is built without the interpreter.
+compiled function, and then calls @code{funcall} on the resulting function
+object. A more traditional interpreter is also available on default
+builds; it is usually only called internally. This is explicitly
+allowed by the ANSI standard but leads to some oddities; e.g. at
+default settings, @code{functionp} and @code{compiled-function-p} are equivalent,
+and they collapse into the same function when SBCL is built without
+the interpreter.
-@node Defining Constants
-@comment node-name, next, previous, up
+@node defining constants
@subsection Defining Constants
-@findex @cl{defconstant}
SBCL is quite strict about ANSI's definition of @code{defconstant}.
-ANSI says that doing @code{defconstant} of the same symbol more than
-once is undefined unless the new value is @code{eql} to the old value.
-Conforming to this specification is a nuisance when the ``constant''
-value is only constant under some weaker test like @code{string=} or
-@code{equal}.
+ANSI says that doing @code{defconstant} of the same symbol more than once
+is undefined unless the new value is @code{eql} to the old value.
+Conforming to this specification is a nuisance when the "constant"
+value is only constant under some weaker test like @code{string=} or @code{equal}.
-It's especially annoying because, in SBCL, @code{defconstant} takes
-effect not only at load time but also at compile time, so that just
+It's especially annoying because, in SBCL, @code{defconstant} takes effect
+not only at load time but also at compile time, so that just
compiling and loading reasonable code like
-@lisp
+
+@example
(defconstant +foobyte+ '(1 4))
-@end lisp
-runs into this undefined behavior. Many implementations of Common Lisp
-try to help the programmer around this annoyance by silently accepting
-the undefined code and trying to do what the programmer probably
-meant.
+@end example
+
+runs into this undefined behavior. Many implementations of Common
+Lisp try to help the programmer around this annoyance by silently
+accepting the undefined code and trying to do what the programmer
+probably meant.
SBCL instead treats the undefined behavior as an error. Often such
code can be rewritten in portable ANSI Common Lisp which has the
-desired behavior. E.g., the code above can be given an exactly defined
-meaning by replacing @code{defconstant} either with
-@code{defparameter} or with a customized macro which does the right
-thing, e.g.
-@lisp
+desired behavior. E.g., the code above can be given an exactly
+defined meaning by replacing @code{defconstant} either with @code{defparameter} or
+with a customized macro which does the right thing, e.g.
+
+@example
(defmacro define-constant (name value &optional doc)
`(defconstant ,name (if (boundp ',name) (symbol-value ',name) ,value)
,@@(when doc (list doc))))
-@end lisp
-or possibly along the lines of the @code{defconstant-eqx} macro used
+@end example
+
+or possibly along the lines of the @code{sb-int:defconstant-eqx} macro used
internally in the implementation of SBCL itself. In circumstances
-where this is not appropriate, the programmer can handle the condition
-type @code{sb-ext:defconstant-uneql}, and choose either the
-@command{continue} or @command{abort} restart as appropriate.
+where this is not appropriate, the programmer can handle the
+condition type @code{sb-ext:defconstant-uneql} and choose either the
+@code{continue} restart or @code{abort} restart as appropriate.
-@node Style Warnings
-@comment node-name, next, previous, up
+@node style warnings
@subsection Style Warnings
SBCL gives style warnings about various kinds of perfectly legal code,
e.g.
@itemize
+@item multiple @code{defun}s of the same symbol in different units;
-@item
-multiple @code{defun}s of the same symbol in different units;
-
-@item
-special variables not named in the conventional @code{*foo*} style,
-and lexical variables unconventionally named in the @code{*foo*} style
-
+@item special variables not named in the conventional @code{*foo*} style, and
+ lexical variables unconventionally named in the @code{*foo*} style.
@end itemize
This causes friction with people who point out that other ways of
-organizing code (especially avoiding the use of @code{defgeneric}) are
-just as aesthetically stylish. However, these warnings should be read
-not as ``warning, bad aesthetics detected, you have no style'' but
-``warning, this style keeps the compiler from understanding the code
-as well as you might like.'' That is, unless the compiler warns about
+organizing code (especially avoiding the use of @code{defgeneric}) are just
+as aesthetically stylish. However, these warnings should be read not
+as @emph{warning, bad aesthetics detected, you have no style} but as
+@emph{warning, this style keeps the compiler from understanding the code
+as well as you might like}. That is, unless the compiler warns about
such conditions, there's no way for the compiler to warn about some
-programming errors which would otherwise be easy to overlook. (Related
-bug: The warning about multiple @code{defun}s is pointlessly annoying
-when you compile and then load a function containing @code{defun}
-wrapped in @code{eval-when}, and ideally should be suppressed in that
-case, but still isn't as of SBCL 0.7.6.)
+programming errors which would otherwise be easy to
+overlook. (Related bug: The warning about multiple @code{defun}s is
+pointlessly annoying when you compile and then load a function
+containing @code{defun} wrapped in @code{eval-when}, and ideally should be
+suppressed in that case, but still isn't as of SBCL 0.7.6.)
-
-
-
-@node Development Tools
-@comment node-name, next, previous, up
+@node development tools
@section Development Tools
@menu
-* Editor Integration::
-* Language Reference::
-* Generating Executables::
+* Editor Integration: editor integration.
+* Language Reference: language reference.
+* Generating Executables: generating executables.
@end menu
-@node Editor Integration
-@comment node-name, next, previous, up
+@node editor integration
@subsection Editor Integration
-Though SBCL can be used running ``bare'', the recommended mode of
+Though SBCL can be used running "bare", the recommended mode of
development is with an editor connected to SBCL, supporting not
only basic lisp editing (paren-matching, etc), but providing among
other features an integrated debugger, interactive compilation, and
automated documentation lookup.
-Currently @dfn{SLIME}@footnote{Historically, the ILISP package at
-@uref{http://ilisp.cons.org/} provided similar functionality, but it
-does not support modern SBCL versions.} (Superior Lisp Interaction
-Mode for Emacs) together with Emacs is recommended for use with
-SBCL, though other options exist as well.
+Currently @emph{SLIME} (Superior Lisp Interaction Mode for Emacs)
+together with Emacs is recommended for use with SBCL, though other
+options exist as well. Historically, the ILISP package at
+@url{http://ilisp.cons.org/} provided similar functionality, but it does
+not support modern SBCL versions.
-SLIME can be downloaded from
-@uref{https://slime.common-lisp.dev/}.
+SLIME can be downloaded from @url{https://slime.common-lisp.dev/}.
-@node Language Reference
-@comment node-name, next, previous, up
+@node language reference
@subsection Language Reference
-@dfn{CLHS} (Common Lisp Hyperspec) is a hypertext version of the ANSI
-standard, made freely available by @emph{LispWorks} -- an invaluable
+@emph{CLHS} (Common Lisp Hyperspec) is a hypertext version of the ANSI
+standard, made freely available by LispWorks -- an invaluable
reference.
-See: @uref{https://www.lispworks.com/documentation/HyperSpec/Front/index.htm}
+See @url{https://www.lispworks.com/documentation/HyperSpec/Front/index.htm}.
-@node Generating Executables
-@comment node-name, next, previous, up
+@node generating executables
@subsection Generating Executables
-SBCL can generate stand-alone executables. The generated executables
+SBCL can generate stand-alone executables. The generated executables
include the SBCL runtime itself, so no restrictions are placed on
-program functionality. For example, a deployed program can call
-@code{compile} and @code{load}, which requires the compiler to be present
-in the executable. For further information, @xref{Function
-sb-ext save-lisp-and-die}.
+program functionality. For example, a deployed program can call
+@code{compile} and @code{load}, which requires the compiler to be present in the
+executable. For further information, @code{sb-ext:save-lisp-and-die}.
-
-@node More SBCL Information
-@comment node-name, next, previous, up
+@node more sbcl information
@section More SBCL Information
@menu
-* SBCL Homepage::
-* Online Documentation::
-* Additional Documentation Files::
-* Internals Documentation::
+* SBCL Homepage: sbcl homepage.
+* Online Documentation: online documentation.
+* Additional Documentation Files: additional documentation files.
+* Internals Documentation: internals documentation.
@end menu
-@node SBCL Homepage
-@comment node-name, next, previous, up
+@node sbcl homepage
@subsection SBCL Homepage
-The SBCL website at @uref{http://www.sbcl.org/} has some general
+The SBCL website at @url{http://www.sbcl.org/} has some general
information, plus links to mailing lists devoted to SBCL, and to
archives of these mailing lists. Subscribing to the mailing lists
-@cite{sbcl-help} and @cite{sbcl-announce} is recommended: both are
-fairly low-volume, and help you keep abreast with SBCL development.
+@code{sbcl-help} and @code{sbcl-announce} is recommended: both are fairly
+low-volume, and help you keep abreast with SBCL development.
-@node Online Documentation
-@comment node-name, next, previous, up
+@node online documentation
@subsection Online Documentation
Documentation for non-ANSI extensions for various commands is
-available online from the SBCL executable itself. The extensions
-for functions which have their own command prompts (e.g. the debugger,
-and @code{inspect}) are documented in text available by typing
-@command{help} at their command prompts. The extensions for functions
-which don't have their own command prompt (such as @code{trace}) are
-described in their documentation strings, unless your SBCL was
-compiled with an option not to include documentation strings, in which
-case the documentation strings are only readable in the source code.
+available online from the SBCL executable itself. The extensions for
+functions which have their own command prompts (e.g. the debugger,
+and @code{inspect}) are documented in text available by typing @code{help} at
+their command prompts. The extensions for functions which don't have
+their own command prompt (such as @code{trace}) are described in their
+documentation strings, unless your SBCL was compiled with an option
+not to include documentation strings, in which case the
+documentation strings are only readable in the source code.
-@node Additional Documentation Files
-@comment node-name, next, previous, up
+@node additional documentation files
@subsection Additional Documentation Files
Besides this user manual both SBCL source and binary distributions
-include some other SBCL-specific documentation files, which should be
-installed along with this manual on your system, e.g. in
-@file{/usr/local/share/doc/sbcl/}.
+include some other SBCL-specific documentation files, which should
+be installed along with this manual on your system, e.g. in
+@code{/usr/local/share/doc/sbcl/}.
-@table @file
+@itemize
+@item @code{copying}: Licence and copyright summary.
-@item COPYING
-Licence and copyright summary.
+@item @code{credits}: Authorship information on various parts of SBCL.
-@item CREDITS
-Authorship information on various parts of SBCL.
+@item @code{install}: Covers installing SBCL from both source and binary
+ distributions on your system, and also has some installation
+ related troubleshooting information.
-@item INSTALL
-Covers installing SBCL from both source and binary distributions on
-your system, and also has some installation related troubleshooting
-information.
+@item @code{news}: Summarizes changes between various SBCL versions.
+@end itemize
-@item NEWS
-Summarizes changes between various SBCL versions.
-
-@end table
-
-@node Internals Documentation
-@comment node-name, next, previous, up
+@node internals documentation
@subsection Internals Documentation
If you're interested in the development of the SBCL system itself,
-then subscribing to @cite{sbcl-devel} is a good idea.
-
-@c FIXME: Copy historical info from the Web Archive to ... somewhere?
+then subscribing to @code{sbcl-devel} is a good idea.
SBCL internals documentation -- besides comments in the source -- is
-available
-@uref{https://web.archive.org/web/20120814000933/http://sbcl-internals.cliki.net/index,in
-the Web Archive}.
+available in the Web Archive:
+
+@url{https://web.archive.org/web/20120814000933/http://sbcl-internals.cliki.net/index}.
Some low-level information describing the programming details of the
conversion from CMUCL to SBCL is available in the
-@file{doc/FOR-CMUCL-DEVELOPERS} file in the SBCL distribution and
-@uref{https://sourceforge.net/p/sbcl/sbcl/ci/master/tree/doc/FOR-CMUCL-DEVELOPERS,on
-SourceForge}.
+@code{doc/FOR-CMUCL-DEVELOPERS} file.
-@node More Common Lisp Information
-@comment node-name, next, previous, up
+@node more common lisp information
@section More Common Lisp Information
@menu
-* Internet Community::
-* Third-party Libraries::
-* Common Lisp Books::
+* Internet Community: internet community.
+* Third-party Libraries: third party libraries.
+* Common Lisp Books: common lisp books.
@end menu
-@node Internet Community
-@comment node-name, next, previous, up
+@node internet community
@subsection Internet Community
-@c FIXME: Say something smart here
+IRC channels on @url{https://libera.chat/}:
-The Common Lisp internet community is fairly diverse:
-@uref{https://groups.google.com/g/comp.lang.lisp} is fairly high volume newsgroup, but has
-a rather poor signal/noise ratio. Various special interest mailing
-lists and IRC tend to provide more content and less flames.
-@uref{https://www.lisp.org} and @uref{https://cliki.net} contain
+@itemize
+@item @code{#common-lisp}: "Common Lisp, the #1=(programmable . #1#)
+ programming language"
+
+@item @code{#lispcafe}: "The Lisp Café; sit down, have a drink, chat about
+ anything, and enjoy your stay. | @url{https://www.cliki.net/lispcafe} |
+ Be insuperable to each other".
+
+@item @code{#sbcl}: "Steel Bank Common Lisp Dev Hangout"
+@end itemize
+
+You can use @url{https://web.libera.chat} or a normal IRC client.
+
+Also, see @url{https://www.reddit.com/r/Common_Lisp/}, as well as
+@url{https://www.lisp.org} and @url{https://cliki.net}, which contain
numerous pointers places in the net where lispers talks shop.
-@node Third-party Libraries
-@comment node-name, next, previous, up
+@node third party libraries
@subsection Third-party Libraries
For a wealth of information about free Common Lisp libraries and tools
-we recommend checking out @emph{CLiki}: @uref{https://cliki.net/}.
+we recommend checking out @emph{CLiki}: @url{https://cliki.net/}.
-@node Common Lisp Books
-@comment node-name, next, previous, up
+The most popular library manager is Quicklisp:
+@url{https://www.quicklisp.org/beta/}.
+
+@node common lisp books
@subsection Common Lisp Books
If you're not a programmer and you're trying to learn, many
introductory Lisp books are available. However, we don't have any
-standout favorites. If you can't decide, try checking the Usenet
-@uref{https://groups.google.com/g/comp.lang.lisp} FAQ for recent
-recommendations.
-
-@c FIXME: This non-stance is silly. Maybe we could recommend SICP,
-@c Touretzky, or something at least.
+standout favorites.
If you are an experienced programmer in other languages but need to
learn about Common Lisp, some books stand out:
-@table @cite
-
+@itemize
@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{https://gigamonkeys.com/book/}.
+
+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:
+@url{https://gigamonkeys.com/book/}.
@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.
+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
-Lisp book, since it is slightly pre-ANSI so you need to be on your
-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{https://www.paulgraham.com/onlisp.html}.
+
+An in-depth treatment of macros, but not recommended as a first
+Common Lisp book, since it is slightly pre-ANSI so you need to
+be on your 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
+@url{https://www.paulgraham.com/onlisp.html}.
@item Object-Oriented Programming In Common Lisp, by Sonya Keene
-With the exception of @cite{Practical Common Lisp} most introductory
+
+With the exception of @emph{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.
+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 the prime source of information on the Common Lisp Metaobject
-Protocol, which is supported by SBCL. Section 2 (Chapters 5 and 6) are
-freely available at @uref{http://mop.lisp.se/www.alu.org/mop/}.
-@end table
+Currently the prime source of information on the Common Lisp
+Metaobject Protocol, which is supported by SBCL. Section
+2 (Chapters 5 and 6) are freely available at
+@url{http://mop.lisp.se/www.alu.org/mop/}.
+@end itemize
-
-
-
-@node History and Implementation of SBCL
-@comment node-name, next, previous, up
+@node history and implementation of sbcl
@section History and Implementation of SBCL
-You can work productively with SBCL without knowing or
-understanding anything about where it came from, how it is
-implemented, or how it extends the ANSI Common Lisp standard. However,
-a little knowledge can be helpful in order to understand error
-messages, to troubleshoot problems, to understand why some parts of
-the system are better debugged than others, and to anticipate which
-known bugs, known performance problems, and missing extensions are
-likely to be fixed, tuned, or added.
+You can work productively with SBCL without knowing or understanding
+anything about where it came from, how it is implemented, or how it
+extends the ANSI Common Lisp standard. However, a little knowledge
+can be helpful in order to understand error messages, to
+troubleshoot problems, to understand why some parts of the system
+are better debugged than others, and to anticipate which known bugs,
+known performance problems, and missing extensions are likely to be
+fixed, tuned, or added.
SBCL is descended from CMUCL, which is itself descended from Spice
Lisp, including early implementations for the Mach operating system on
@@ -556,47 +492,40 @@ the IBM RT, back in the 1980s. Some design decisions from that time are
still reflected in the current implementation:
@itemize
+@item The system expects to be loaded into a fixed-at-compile-time
+ location in virtual memory, and also expects the location of all
+ of its heap storage to be specified at compile time.
-@item
-The system expects to be loaded into a fixed-at-compile-time location
-in virtual memory, and also expects the location of all of its heap
-storage to be specified at compile time.
-
-@item
-The system overcommits memory, allocating large amounts of address
-space from the system (often more than the amount of virtual memory
-available) and then failing if it ends up using too much of the
-allocated storage.
-
-@item
-The system is implemented as a C program which is responsible for
-supplying low-level services and loading a Lisp @file{.core}
-file.
+@item The system overcommits memory, allocating large amounts of address
+ space from the system (often more than the amount of virtual
+ memory available) and then failing if it ends up using too much of
+ the allocated storage.
+@item The system is implemented as a C program which is responsible for
+ supplying low-level services and loading a Lisp @code{.core} file.
@end itemize
-@cindex Garbage Collection, generational
-SBCL also inherited some newer architectural features from CMUCL. The
-most important is that on some architectures it has a generational
-garbage collector (``GC''), which has various implications (mostly
-good) for performance. These are discussed in another chapter,
-@ref{Efficiency}.
+SBCL also inherited some newer architectural features from CMUCL.
+The most important is that on some architectures it has a
+generational garbage collector (GC), which has various
+implications (mostly good) for performance. These are discussed in
+another chapter, @ref{efficiency}.
SBCL has diverged from CMUCL in that SBCL is now essentially a
-``compiler-only implementation'' of Common Lisp. This is a change in
-implementation strategy, taking advantage of the freedom ``any of these
-facilities might share the same execution strategy'' guaranteed in the
-ANSI specification section 3.1 (``Evaluation''). It does not mean SBCL
-can't be used interactively, and in fact the change is largely invisible
+compiler-only implementation of Common Lisp. This is a change in
+implementation strategy, taking advantage of the freedom "any of
+these facilities might share the same execution strategy"
+guaranteed in @code{clhs} @code{3.1} (Evaluation). It does not mean SBCL can't
+be used interactively, and in fact the change is largely invisible
to the casual user, since SBCL still can and does execute code
-interactively by compiling it on the fly. (It is visible if you know how
-to look, like using @code{compiled-function-p}; and it is visible in the
-way that SBCL doesn't have many bugs which behave differently in
-interpreted code than in compiled code.) What it means is that in SBCL,
-the @code{eval} function only truly ``interprets'' a few easy kinds of
-forms, such as symbols which are @code{boundp}. More complicated forms
-are evaluated by calling @code{compile} and then calling @code{funcall}
-on the returned result.
+interactively by compiling it on the fly. (It is visible if you know
+how to look, like using @code{compiled-function-p}; and it is visible in
+the way that SBCL doesn't have many bugs which behave differently in
+interpreted code than in compiled code.) What it means is that in
+SBCL, the @code{eval} function only truly "interprets" a few easy kinds
+of forms, such as symbols which are @code{boundp}. More complicated forms
+are evaluated by calling @code{compile} and then calling @code{funcall} on the
+returned result.
The direct ancestor of SBCL is the x86 port of CMUCL. This port was in
some ways the most cobbled-together of all the CMUCL ports, since a
@@ -605,7 +534,6 @@ x86 architecture. Some things (like tracing and debugging) do not work
particularly well there. SBCL should be able to improve in these areas
(and has already improved in some other areas), but it takes a while.
-@cindex Garbage Collection, conservative
On the x86 SBCL -- like the x86 port of CMUCL -- uses a
@emph{conservative} GC. This means that it doesn't maintain a strict
separation between tagged and untagged data, instead treating some
@@ -613,39 +541,36 @@ untagged data (e.g. raw floating point numbers) as possibly-tagged
data and so not collecting any Lisp objects that they point to. This
has some negative consequences for average time efficiency (though
possibly no worse than the negative consequences of trying to
-implement an exact GC on a processor architecture as register-poor as
-the X86) and also has potentially unlimited consequences for
+implement an exact GC on a processor architecture as register-poor
+as the X86) and also has potentially unlimited consequences for
worst-case memory efficiency. In practice, conservative garbage
collectors work reasonably well, not getting anywhere near the worst
case. But they can occasionally cause odd patterns of memory usage.
The fork from CMUCL was based on a major rewrite of the system
bootstrap process. CMUCL has for many years tolerated a very unusual
-``build'' procedure which doesn't actually build the complete system
-from scratch, but instead progressively overwrites parts of a running
-system with new versions. This quasi-build procedure can cause various
-bizarre bootstrapping hangups, especially when a major change is made
-to the system. It also makes the connection between the current source
-code and the current executable more tenuous than in other software
-systems -- it's easy to accidentally ``build'' a CMUCL system
-containing characteristics not reflected in the current version of the
-source code.
+"build" procedure which doesn't actually build the complete system
+from scratch, but instead progressively overwrites parts of a
+running system with new versions. This quasi-build procedure can
+cause various bizarre bootstrapping hangups, especially when a major
+change is made to the system. It also makes the connection between
+the current source code and the current executable more tenuous than
+in other software systems -- it's easy to accidentally build a CMUCL
+system containing characteristics not reflected in the current
+version of the source code.
-Other major changes since the fork from CMUCL include
+Other major changes since the fork from CMUCL include:
@itemize
+@item SBCL has removed many CMUCL extensions, (e.g. IP networking,
+ remote procedure call, Unix system interface, and X11 interface)
+ from the core system. Most of these are available as contributed
+ modules (distributed with SBCL) or third-party modules instead.
-@item
-SBCL has removed many CMUCL extensions, (e.g. IP networking,
-remote procedure call, Unix system interface, and X11 interface) from
-the core system. Most of these are available as contributed modules
-(distributed with SBCL) or third-party modules instead.
-
-@item
-SBCL has deleted or deprecated some nonstandard features and code
-complexity which helped efficiency at the price of
-maintainability. For example, the SBCL compiler no longer implements
-memory pooling internally (and so is simpler and more maintainable,
-but generates more garbage and runs more slowly).
-
+@item SBCL has deleted or deprecated some nonstandard features and code
+ complexity which helped efficiency at the price of
+ maintainability. For example, the SBCL compiler no longer
+ implements memory pooling internally (and so is simpler and more
+ maintainable, but generates more garbage and runs more slowly).
@end itemize
+
diff --git a/doc/manual/package-locks.texinfo b/doc/manual/package-locks.texinfo
index a0a7cca8f..813ce7274 100644
--- a/doc/manual/package-locks.texinfo
+++ b/doc/manual/package-locks.texinfo
@@ -1,58 +1,49 @@
-@node Package Locks
-@comment node-name, next, previous, up
+@c Generated by the sb-manual contrib. Do not edit.
+
+@node package locks
@chapter Package Locks
-@cindex Packages, locked
+
+@menu
+* Package Lock Concepts: package lock concepts.
+* Package Lock Dictionary: package lock dictionary.
+@end menu
None of the following sections apply to SBCL built without package
locking support.
-@quotation warning
-The interface described here is experimental: incompatible changes in
-future SBCL releases are possible, even expected: the concept of
-``implementation packages'' and the associated operators may be renamed;
-more operations (such as naming restarts or catch tags) may be added to
-the list of operations violating package locks.
-@end quotation
+The interface described here is experimental: incompatible changes
+in future SBCL releases are possible, even expected: the concept of
+@emph{implementation packages} and the associated operators may be
+renamed; more operations (such as naming restarts or catch tags) may
+be added to the list of operations violating package locks.
-@menu
-* Package Lock Concepts::
-* Package Lock Dictionary::
-@end menu
-
-@node Package Lock Concepts
+@node package lock concepts
@section Package Lock Concepts
@menu
-* Package Lock Overview::
-* Implementation Packages::
-* Package Lock Violations::
-* Package Locks in Compiled Code::
-* Operations Violating Package Locks::
+* Implementation Packages: implementation packages.
+* Package Lock Violations: package lock violations.
+* Package Locks in Compiled Code: package locks in compiled code.
+* Operations Violating Package Locks: operations violating package locks.
@end menu
-@node Package Lock Overview
-@comment node-name, next, previous, up
-@subsection Package Locking Overview
-
Package locks protect against unintentional modifications of a package:
they provide similar protection to user packages as is mandated to
@code{common-lisp} package by the ANSI specification. They are not, and
should not be used as, a security measure.
-Newly created packages are by default unlocked (see the @code{:lock}
-option to @code{defpackage}).
+Newly created packages are by default unlocked (see the @code{:lock} option
+to @code{defpackage}).
-The package @code{common-lisp} and SBCL internal implementation
-packages are locked by default, including @code{sb-ext}.
+The package @code{common-lisp} and SBCL internal implementation packages
+are locked by default, including @code{sb-ext}.
-It may be beneficial to lock @code{common-lisp-user} as well, to
-ensure that various libraries don't pollute it without asking,
-but this is not currently done by default.
+It may be beneficial to lock @code{common-lisp-user} as well, to ensure
+that various libraries don't pollute it without asking, but this is
+not currently done by default.
-@node Implementation Packages
+@node implementation packages
@subsection Implementation Packages
-@vindex @cl{@earmuffs{package}}
-@findex @cl{defpackage}
Each package has a list of associated implementation packages. A
locked package, and the symbols whose home package it is, can be
@@ -64,40 +55,32 @@ Unless explicitly altered by @code{defpackage},
@code{sb-ext:remove-implementation-package} each package is its own
(only) implementation package.
-@node Package Lock Violations
+@node package lock violations
@subsection Package Lock Violations
-@tindex @sbext{package-lock-violation}
-@tindex @sbext{package-locked-error}
-@tindex @sbext{symbol-package-locked-error}
-@tindex @cl{package-error}
+@menu
+* Lexical Bindings and Declarations: lexical bindings and declarations.
+* Other Operations: other operations.
+@end menu
+
+@node lexical bindings and declarations
@subsubsection Lexical Bindings and Declarations
-@findex @cl{let}
-@findex @cl{let*}
-@findex @cl{flet}
-@findex @cl{labels}
-@findex @cl{macrolet}
-@findex @cl{symbol-macrolet}
-@findex @cl{declare}
-@cindex Declarations
-@findex @sbext{disable-package-locks}
-@findex @sbext{enable-package-locks}
Lexical bindings or declarations that violate package locks cause a
-compile-time warning, and a runtime @code{program-error} when the form
-that violates package locks would be executed.
+compile-time warning, and a runtime @code{program-error} when the form that
+violates package locks would be executed.
-A complete listing of operators affect by this is: @code{let},
-@code{let*}, @code{flet}, @code{labels}, @code{macrolet}, and
-@code{symbol-macrolet}, @code{declare}.
+A complete listing of operators affect by this is: @code{let}, @code{let*}, @code{flet},
+@code{labels}, @code{macrolet}, and @code{symbol-macrolet}, @code{declare}.
-Package locks affecting both lexical bindings and declarations can be
-disabled locally with @code{sb-ext:disable-package-locks} declaration,
-and re-enabled with @code{sb-ext:enable-package-locks} declaration.
+Package locks affecting both lexical bindings and declarations can
+be disabled locally with the @code{sb-ext:disable-package-locks}
+declaration, and re-enabled with the @code{sb-ext:enable-package-locks}
+declaration.
Example:
-@lisp
+@example
(in-package :locked)
(defun foo () ...)
@@ -107,8 +90,9 @@ Example:
(flet ((foo () ...))
(declare (enable-package-locks locked:foo)) ; re-enable for body
,@@body)))
-@end lisp
+@end example
+@node other operations
@subsubsection Other Operations
If an non-lexical operation violates a package lock, a continuable
@@ -119,87 +103,79 @@ attempted.
Additional restarts may be established for continuable package lock
violations for interactive use.
-The actual type of the error depends on circumstances that caused the
-violation: operations on packages signal errors of type
-@code{sb-ext:package-locked-error}, and operations on symbols signal
-errors of type @code{sb-ext:symbol-package-locked-error}.
+The actual type of the error depends on circumstances that caused
+the violation: operations on packages signal errors of type
+@code{sb-ext:package-locked-error}, and operations on symbols signal errors
+of type @code{sb-ext:symbol-package-locked-error}.
-
-@node Package Locks in Compiled Code
+@node package locks in compiled code
@subsection Package Locks in Compiled Code
-@subsubsection Interned Symbols
-
-If file-compiled code contains interned symbols, then loading that code
-into an image without the said symbols will not cause a package lock
-violation, even if the packages in question are locked.
-
-@subsubsection Other Limitations on Compiled Code
+If file-compiled code contains interned symbols, then loading that
+code into an image without the said symbols will not cause a package
+lock violation, even if the packages in question are locked.
With the exception of interned symbols, behaviour is unspecified if
-package locks affecting compiled code are not the same during loading
-of the code or execution.
+package locks affecting compiled code are not the same during
+loading of the code or execution.
-Specifically, code compiled with packages unlocked may or may not fail
-to signal package-lock-violations even if the packages are locked at
-runtime, and code compiled with packages locked may or may not signal
-spurious package-lock-violations at runtime even if the packages are
-unlocked.
+Specifically, code compiled with packages unlocked may or may not
+fail to signal package-lock-violations even if the packages are
+locked at runtime, and code compiled with packages locked may or may
+not signal spurious package-lock-violations at runtime even if the
+packages are unlocked.
In practice all this means that package-locks have a negligible
-performance penalty in compiled code as long as they are not violated.
+performance penalty in compiled code as long as they are not
+violated.
-@node Operations Violating Package Locks
+@node operations violating package locks
@subsection Operations Violating Package Locks
+@menu
+* Operations on Packages: operations on packages.
+* Operations on Symbols: operations on symbols.
+@end menu
+
+@node operations on packages
@subsubsection Operations on Packages
The following actions cause a package lock violation if the package
operated on is locked, and @code{*package*} is not an implementation
package of that package, and the action would cause a change in the
state of the package (so e.g. exporting already external symbols is
-never a violation). Package lock violations caused by these operations
-signal errors of type @code{sb-ext:package-locked-error}.
+never a violation). Package lock violations caused by these
+operations signal errors of type @code{sb-ext:package-locked-error}.
-@enumerate
-@item
-Shadowing a symbol in a package.
+@itemize
+@item Shadowing a symbol in a package.
-@item
-Importing a symbol to a package.
+@item Importing a symbol to a package.
-@item
-Uninterning a symbol from a package.
+@item Uninterning a symbol from a package.
-@item
-Exporting a symbol from a package.
+@item Exporting a symbol from a package.
-@item
-Unexporting a symbol from a package.
+@item Unexporting a symbol from a package.
-@item
-Changing the packages used by a package.
+@item Changing the packages used by a package.
-@item
-Renaming a package.
+@item Renaming a package.
-@item
-Deleting a package.
+@item Deleting a package.
-@item
-Adding a new package local nickname to a package.
+@item Adding a new package local nickname to a package.
-@item
-Removing an existing package local nickname to a package.
-
-@end enumerate
+@item Removing an existing package local nickname to a package.
+@end itemize
+@node operations on symbols
@subsubsection Operations on Symbols
Following actions cause a package lock violation if the home package
of the symbol operated on is locked, and @code{*package*} is not an
-implementation package of that package. Package lock violations caused
-by these action signal errors of type
+implementation package of that package. Package lock violations
+caused by these action signal errors of type
@code{sb-ext:symbol-package-locked-error}.
These actions cause only one package lock violation per lexically
@@ -207,7 +183,8 @@ apparent violated package.
Example:
-@lisp
+
+@example
;;; Packages FOO and BAR are locked.
;;;
;;; Two lexically apparent violated packages: exactly two
@@ -216,155 +193,194 @@ Example:
(defclass foo:point ()
((x :accessor bar:x)
(y :accessor bar:y)))
-@end lisp
+@end example
-@enumerate
-@item
-Binding or altering its value lexically or dynamically, or
-establishing it as a symbol-macro.
+@itemize
+@item Binding or altering its value lexically or dynamically, or
+ establishing it as a symbol-macro.
Exceptions:
-@itemize @minus
-@item
-If the symbol is not defined as a constant, global symbol-macro or a
-global dynamic variable, it may be lexically bound or established as a
-local symbol macro.
-
-@item
-If the symbol is defined as a global dynamic variable, it may be
-assigned or bound.
+@itemize
+@item If the symbol is not defined as a constant, global
+ symbol-macro or a global dynamic variable, it may be lexically
+ bound or established as a local symbol macro.
+@item If the symbol is defined as a global dynamic variable, it may
+ be assigned or bound.
@end itemize
-@item
-Defining, undefining, or binding it, or its setf name as a function.
+@item Defining, undefining, or binding it, or its setf name as a
+ function.
Exceptions:
-@itemize @minus
-@item
-If the symbol is not defined as a function, macro, or special operator
-it and its setf name may be lexically bound as a function.
-
+@itemize
+@item If the symbol is not defined as a function, macro, or special
+ operator it and its setf name may be lexically bound as a
+ function.
@end itemize
-@item
-Defining, undefining, or binding it as a macro or compiler macro.
+@item Defining, undefining, or binding it as a macro or compiler macro.
Exceptions:
-@itemize @minus
-@item
-If the symbol is not defined as a function, macro, or special operator
-it may be lexically bound as a macro.
-
+@itemize
+@item If the symbol is not defined as a function, macro, or special
+ operator it may be lexically bound as a macro.
@end itemize
-@item
-Defining it as a type specifier or structure.
+@item Defining it as a type specifier or structure.
-@item
-Defining it as a declaration with a declaration proclamation.
+@item Defining it as a declaration with a declaration proclamation.
-@item
-Declaring or proclaiming it special.
+@item Declaring or proclaiming it special.
-@item
-Declaring or proclaiming its type or ftype.
+@item Declaring or proclaiming its type or ftype.
Exceptions:
-@itemize @minus
-@item
-If the symbol may be lexically bound, the type of that binding may be
-declared.
-
-@item
-If the symbol may be lexically bound as a function, the ftype of that
-binding may be declared.
+@itemize
+@item If the symbol may be lexically bound, the type of that binding
+ may be declared.
+@item If the symbol may be lexically bound as a function, the ftype
+ of that binding may be declared.
@end itemize
-@item
-Defining a setf expander for it.
-
-@item
-Defining it as a method combination type.
+@item Defining a setf expander for it.
-@item
-Using it as the class-name argument to setf of find-class.
+@item Defining it as a method combination type.
-@item
-Defining it as a hash table test using @code{sb-ext:define-hash-table-test}.
+@item Using it as the @code{class-name} argument to (@code{setf} @code{find-class}).
-@end enumerate
+@item Defining it as a hash table test using @code{sb-ext:define-hash-table-test}.
+@end itemize
-@node Package Lock Dictionary
+@node package lock dictionary
@section Package Lock Dictionary
-@deffn {Declaration} @sbext{disable-package-locks}
+@itemize
+@item [@strong{declaration}] @code{sb-ext:disable-package-locks}
-Syntax: @code{(sb-ext:disable-package-locks symbol*)}
+Syntax: @code{(sb-ext:disable-package-locks &rest symbols)}
-Disables package locks affecting the named symbols during compilation
-in the lexical scope of the declaration. Disabling locks on symbols
-whose home package is unlocked, or disabling an already disabled lock,
-has no effect.
-@end deffn
-
-@deffn {Declaration} @sbext{enable-package-locks}
+Disables package locks affecting the named symbols during
+compilation in the lexical scope of the declaration. Disabling
+locks on symbols whose home package is unlocked, or disabling an
+already disabled lock, has no effect.
-Syntax: @code{(sb-ext:enable-package-locks symbol*)}
-
-Re-enables package locks affecting the named symbols during compilation
-in the lexical scope of the declaration. Enabling locks that were not
-first disabled with @code{sb-ext:disable-package-locks} declaration, or
-enabling locks that are already enabled has no effect.
-@end deffn
+@item [@strong{declaration}] @code{sb-ext:enable-package-locks}
-@include condition-sb-ext-package-lock-violation.texinfo
-@include condition-sb-ext-package-locked-error.texinfo
-@include condition-sb-ext-symbol-package-locked-error.texinfo
+Syntax: @code{(sb-ext:enable-package-locks &rest symbols)}
-@defun @sbext{package-locked-error-symbol} symbol-package-locked-error
+Re-enables package locks affecting the named symbols during
+compilation in the lexical scope of the declaration. Enabling
+locks that were not first disabled with
+@code{sb-ext:disable-package-locks} declaration, or enabling locks that
+are already enabled has no effect.
+@end itemize
-Returns the symbol that caused the @code{symbol-package-locked-error}
+@anchor{Condition sb-ext package-lock-violation}
+@ttindex @sortas{package-lock-violation sb-ext} package-lock-violation [sb-ext]
+@deffn{Condition} sb-ext:package-lock-violation
+Subtype of @code{cl:package-error}. A subtype of this error is signalled
+when a package-lock is violated.
+@end deffn
+@anchor{Condition sb-ext package-locked-error}
+@ttindex @sortas{package-locked-error sb-ext} package-locked-error [sb-ext]
+@deffn{Condition} sb-ext:package-locked-error
+Subtype of @code{sb-ext:package-lock-violation}. An error of this type is
+signalled when an operation on a package violates a package lock.
+@end deffn
+@anchor{Condition sb-ext symbol-package-locked-error}
+@ttindex @sortas{symbol-package-locked-error sb-ext} symbol-package-locked-error [sb-ext]
+@deffn{Condition} sb-ext:symbol-package-locked-error
+Subtype of @code{sb-ext:package-lock-violation}. An error of this type is
+signalled when an operation on a symbol violates a package lock. The
+symbol that caused the violation is accessed by the function
+@code{sb-ext:package-locked-error-symbol}.
+@end deffn
+@anchor{Function sb-ext package-locked-error-symbol}
+@ffindex @sortas{package-locked-error-symbol sb-ext} package-locked-error-symbol [sb-ext]
+@deffn{Function} sb-ext:package-locked-error-symbol condition
+Return the symbol that caused the @code{symbol-package-locked-error}
condition.
-@end defun
-
-@include fun-sb-ext-package-locked-p.texinfo
-@include fun-sb-ext-lock-package.texinfo
-@include fun-sb-ext-unlock-package.texinfo
-@include fun-sb-ext-package-implemented-by-list.texinfo
-@include fun-sb-ext-package-implements-list.texinfo
-@include fun-sb-ext-add-implementation-package.texinfo
-@include fun-sb-ext-remove-implementation-package.texinfo
-@include macro-sb-ext-without-package-locks.texinfo
-@include macro-sb-ext-with-unlocked-packages.texinfo
-
-@defmac @cl{defpackage} name [[option]]* @result{} package
-
-Options are extended to include the following:
+@end deffn
+@anchor{Function sb-ext package-locked-p}
+@ffindex @sortas{package-locked-p sb-ext} package-locked-p [sb-ext]
+@deffn{Function} sb-ext:package-locked-p package
+Returns @code{t} when @code{package} is locked, @code{nil} otherwise. Signals an error
+if @code{package} doesn't designate a valid package.
+@end deffn
+@anchor{Function sb-ext lock-package}
+@ffindex @sortas{lock-package sb-ext} lock-package [sb-ext]
+@deffn{Function} sb-ext:lock-package package
+Locks @code{package} and returns @code{t}. Has no effect if @code{package} was already
+locked. Signals an error if @code{package} is not a valid package designator
+@end deffn
+@anchor{Function sb-ext unlock-package}
+@ffindex @sortas{unlock-package sb-ext} unlock-package [sb-ext]
+@deffn{Function} sb-ext:unlock-package package
+Unlocks @code{package} and returns @code{t}. Has no effect if @code{package} was already
+unlocked. Signals an error if @code{package} is not a valid package designator.
+@end deffn
+@anchor{Function sb-ext package-implemented-by-list}
+@ffindex @sortas{package-implemented-by-list sb-ext} package-implemented-by-list [sb-ext]
+@deffn{Function} sb-ext:package-implemented-by-list package
+Returns a list containing the implementation packages of
+@code{package}. Signals an error if @code{package} is not a valid package designator.
+@end deffn
+@anchor{Function sb-ext package-implements-list}
+@ffindex @sortas{package-implements-list sb-ext} package-implements-list [sb-ext]
+@deffn{Function} sb-ext:package-implements-list package
+Returns the packages that @code{package} is an implementation package
+of. Signals an error if @code{package} is not a valid package designator.
+@end deffn
+@anchor{Function sb-ext add-implementation-package}
+@ffindex @sortas{add-implementation-package sb-ext} add-implementation-package [sb-ext]
+@deffn{Function} sb-ext:add-implementation-package packages-to-add &optional package
+Adds @code{packages-to-add} as implementation packages of @code{package}. Signals
+an error if @code{package} or any of the @code{packages-to-add} is not a valid
+package designator.
+@end deffn
+@anchor{Function sb-ext remove-implementation-package}
+@ffindex @sortas{remove-implementation-package sb-ext} remove-implementation-package [sb-ext]
+@deffn{Function} sb-ext:remove-implementation-package packages-to-remove &optional package
+Removes @code{packages-to-remove} from the implementation packages of
+@code{package}. Signals an error if @code{package} or any of the @code{packages-to-remove}
+is not a valid package designator.
+@end deffn
+@anchor{Macro sb-ext without-package-locks}
+@ffindex @sortas{without-package-locks sb-ext} without-package-locks [sb-ext]
+@deffn{Macro} sb-ext:without-package-locks &body body
+Ignores all runtime package lock violations during the execution of
+body. Body can begin with declarations.
+@end deffn
+@anchor{Macro sb-ext with-unlocked-packages}
+@ffindex @sortas{with-unlocked-packages sb-ext} with-unlocked-packages [sb-ext]
+@deffn{Macro} sb-ext:with-unlocked-packages (&rest packages) &body forms
+Unlocks @code{packages} for the dynamic scope of the body. Signals an
+error if any of @code{packages} is not a valid package designator.
+@end deffn
+The @code{defpackage} options are extended to include the following:
@itemize
-@item
-@code{:lock} @var{boolean}
+@item @code{:lock} @code{<boolean>} (defaults to @code{nil})
-If the argument to @code{:lock} is @code{t}, the package is initially
-locked. If @code{:lock} is not provided it defaults to @code{nil}.
+If the argument to @code{:lock} is @code{t}, the package is locked, else it is
+unlocked. Existing package are also affected.
-@item
-@code{:implement} @var{package-designator}*
+@item @code{:implement} @code{<package-designator>*}
-The package is added as an implementation package to the packages
-named. If @code{:implement} is not provided, it defaults to the
-package itself.
+The package is added as an implementation package to the
+packages named. If @code{:implement} is not provided, it defaults to
+the package itself.
@end itemize
Example:
-@lisp
+@example
(defpackage "FOO" (:export "BAR") (:lock t) (:implement))
(defpackage "FOO-INT" (:use "FOO") (:implement "FOO" "FOO-INT"))
@@ -373,7 +389,8 @@ Example:
(defpackage "FOO") (:export "BAR"))
(lock-package "FOO")
(remove-implementation-package "FOO" "FOO")
+
(defpackage "FOO-INT" (:use "BAR"))
(add-implementation-package "FOO-INT" "FOO")
-@end lisp
-@end defmac
+@end example
+
diff --git a/doc/manual/pathnames.texinfo b/doc/manual/pathnames.texinfo
index bdd03cc13..3821d7b27 100644
--- a/doc/manual/pathnames.texinfo
+++ b/doc/manual/pathnames.texinfo
@@ -1,174 +1,146 @@
-@node Pathnames
-@comment node-name, next, previous, up
+@c Generated by the sb-manual contrib. Do not edit.
+
+@node pathnames
@chapter Pathnames
-@cindex Pathnames
-
@menu
-* Lisp Pathnames::
-* Native Filenames::
+* Lisp Pathnames: lisp pathnames.
+* Native Filenames: native filenames.
@end menu
-@node Lisp Pathnames
-@comment node-name, next, previous, up
+@node lisp pathnames
@section Lisp Pathnames
-There are many aspects of ANSI Common Lisp's pathname support which are
-implementation-defined and so need documentation.
+@menu
+* Home Directory Specifiers: home directory specifiers.
+* The SYS Logical Pathname Host: the sys logical pathname host.
+@end menu
-@c FIXME: as a matter of ANSI conformance, we are required to document
-@c implementation-defined stuff, which for pathnames (chapter 19 of CLtS)
-@c includes:
-@c
-@c * Otherwise, the parsing of thing is implementation-defined.
-@c (PARSE-NAMESTRING)
-@c
-@c * If thing contains an explicit host name and no explicit device name,
-@c then it is implementation-defined whether parse-namestring will supply
-@c the standard default device for that host as the device component of
-@c the resulting pathname. (PARSE-NAMESTRING)
-@c
-@c * The specific nature of the search is implementation-defined.
-@c (LOAD-LOGICAL-PATHNAME-TRANSLATIONS)
-@c
-@c * Any additional elements are implementation-defined.
-@c (LOGICAL-PATHNAME-TRANSLATIONS)
-@c
-@c * The matching rules are implementation-defined but should be consistent
-@c with directory. (PATHNAME-MATCH-P)
-@c
-@c * Any such additional translations are implementation-defined.
-@c (TRANSLATE-LOGICAL-PATHNAMES)
-@c
-@c * ...or an implementation-defined portion of a component...
-@c (TRANSLATE-PATHNAME)
-@c
-@c * The portion of source that is copied into the resulting pathname is
-@c implementation-defined. (TRANSLATE-PATHNAME)
-@c
-@c * During the copying of a portion of source into the resulting
-@c pathname, additional implementation-defined translations of case or
-@c file naming conventions might occur. (TRANSLATE-PATHNAME)
-@c
-@c * In general, the syntax of namestrings involves the use of
-@c implementation-defined conventions. (19.1.1)
-@c
-@c * The nature of the mapping between structure imposed by pathnames and
-@c the structure, if any, that is used by the underlying file system is
-@c implementation-defined. (19.1.2)
-@c
-@c * The mapping of the pathname components into the concepts peculiar to
-@c each file system is implementation-defined. (19.1.2)
-@c
-@c * Whether separator characters are permitted as part of a string in a
-@c pathname component is implementation-defined; (19.2.2.1.1)
-@c
-@c * Whether a value of :unspecific is permitted for any component on any
-@c given file system accessible to the implementation is
-@c implementation-defined. (19.2.2.2.3)
-@c
-@c * Other symbols and integers have implementation-defined meaning.
-@c (19.2.2.4.6)
+There are many aspects of ANSI Common Lisp's pathname support
+which are implementation-defined and so need documentation.
+@node home directory specifiers
@subsection Home Directory Specifiers
SBCL accepts the keyword @code{:home} and a list of the form
-@code{(:home "username")} as a directory component immediately
+@code{(:home} @code{"username")} as a directory component immediately
following @code{:absolute}.
-@code{:home} is represented in namestrings by @code{~/} and
-@code{(:home "username"} by @code{~username/} at the start of the
-namestring. Tilde-characters elsewhere in namestrings represent
-themselves.
+@code{:home} is represented in namestrings by @code{~/} and @code{(:home}
+@code{"username")} by @code{~username/} at the start of the namestring.
+Tilde-characters elsewhere in namestrings represent themselves.
Home directory specifiers are resolved to home directory of the
-current or specified user by @code{native-namestring}, which is used
-by the implementation to translate pathnames before passing them on to
-operating system specific routines.
+current or specified user by @code{sb-ext:native-namestring}, which is used
+by the implementation to translate pathnames before passing them on
+to operating system specific routines.
-Using @code{(:home "user")} form on Windows signals an error.
+Using @code{(:home} @code{"user")} form on Windows signals an error.
+@node the sys logical pathname host
@subsection The SYS Logical Pathname Host
-@cindex Logical pathnames
-@cindex Pathnames, logical
-@findex @cl{logical-pathname-translations}
-@findex @setf{@cl{logical-pathname-translations}}
-
-@c * The existence and meaning of SYS: logical pathnames is
-@c implementation-defined. (19.3.1.1.1)
-
-The logical pathname host named by @code{"SYS"} exists in SBCL. Its
-@code{logical-pathname-translations} may be set by the site or the user
+The logical pathname host named by @code{"SYS"} exists in SBCL.
+Its @code{logical-pathname-translations} may be set by the site or the user
applicable to point to the locations of the system's sources; in
-particular, the core system's source files match the logical pathname
-@code{"SYS:SRC;**;*.*.*"}, and the contributed modules' source files
-match @code{"SYS:CONTRIB;**;*.*.*"}.
+particular, the core system's source files match the logical
+pathname @code{"SYS:SRC;**;*.*.*"}, and the contributed modules' source
+files match @code{"SYS:CONTRIB;**;*.*.*"}.
-@include fun-sb-ext-set-sbcl-source-location.texinfo
-
-@node Native Filenames
-@comment node-name, next, previous, up
+@anchor{Function sb-ext set-sbcl-source-location}
+@ffindex @sortas{set-sbcl-source-location sb-ext} set-sbcl-source-location [sb-ext]
+@deffn{Function} sb-ext:set-sbcl-source-location pathname
+Initialize the @code{SYS} logical host based on @code{pathname}, which should
+be the top-level directory of the SBCL sources. This will replace any
+existing translations for @code{"SYS:SRC;"}, @code{"SYS:CONTRIB;"}, and
+@code{"SYS:OUTPUT;"}. Other @code{"SYS:"} translations are preserved.
+@end deffn
+@node native filenames
@section Native Filenames
In some circumstances, what is wanted is a Lisp pathname object which
-corresponds to a string produced by the Operating System. In this case,
-some of the default parsing rules are inappropriate: most filesystems do
-not have a native understanding of wild pathnames; such functionality is
-often provided by shells above the OS, often in mutually-incompatible
-ways.
+corresponds to a string produced by the Operating System. In this
+case, some of the default parsing rules are inappropriate: most
+filesystems do not have a native understanding of wild pathnames;
+such functionality is often provided by shells above the OS, often
+in mutually-incompatible ways.
To allow the user to deal with this, the following functions are
-provided: @code{parse-native-namestring} and @code{native-pathname}
+provided: @code{sb-ext:parse-native-namestring} and @code{sb-ext:native-pathname}
return the closest equivalent Lisp pathname to a given string
-(appropriate for the Operating System), while @code{native-namestring}
-converts a non-wild pathname designator to the equivalent native
-namestring, if possible. Some Lisp pathname concepts (such as the
-@code{:back} directory component) have no direct equivalents in most
-Operating Systems; the behaviour of @code{native-namestring} is
-unspecified if an inappropriate pathname designator is passed to it.
-Additionally, note that conversion from pathname to native filename
-and back to pathname should not be expected to preserve equivalence
-under @code{equal}.
-
-@include fun-sb-ext-parse-native-namestring.texinfo
-@include fun-sb-ext-native-pathname.texinfo
-@include fun-sb-ext-native-namestring.texinfo
+(appropriate for the Operating System), while
+@code{sb-ext:native-namestring} converts a non-wild pathname designator to
+the equivalent native namestring, if possible. Some Lisp pathname
+concepts (such as the @code{:back} directory component) have no direct
+equivalents in most Operating Systems; the behaviour of
+@code{sb-ext:native-namestring} is unspecified if an inappropriate pathname
+designator is passed to it. Additionally, note that conversion from
+pathname to native filename and back to pathname should not be
+expected to preserve equivalence under @code{equal}.
+@anchor{Function sb-ext parse-native-namestring}
+@ffindex @sortas{parse-native-namestring sb-ext} parse-native-namestring [sb-ext]
+@deffn{Function} sb-ext:parse-native-namestring thing &optional host defaults &key start end junk-allowed as-directory
+Convert @code{thing} into a pathname, using the native conventions
+appropriate for the pathname host @code{host}, or if not specified the
+host of @code{defaults}. If @code{thing} is a string, the parse is bounded by
+@code{start} and @code{end}, and error behaviour is controlled by @code{junk-allowed},
+as with @code{parse-namestring}. For file systems whose native
+conventions allow directories to be indicated as files, if
+@code{as-directory} is true, return a pathname denoting @code{thing} as a
+directory.
+@end deffn
+@anchor{Function sb-ext native-pathname}
+@ffindex @sortas{native-pathname sb-ext} native-pathname [sb-ext]
+@deffn{Function} sb-ext:native-pathname pathspec
+Convert @code{pathspec} (a pathname designator) into a pathname, assuming
+the operating system native pathname conventions.
+@end deffn
+@anchor{Function sb-ext native-namestring}
+@ffindex @sortas{native-namestring sb-ext} native-namestring [sb-ext]
+@deffn{Function} sb-ext:native-namestring pathname &key as-file
+Construct the full native (name)string form of @code{pathname}. For
+file systems whose native conventions allow directories to be
+indicated as files, if @code{as-file} is true and the name, type, and
+version components of @code{pathname} are all @code{nil} or @code{:unspecific},
+construct a string that names the directory according to the file
+system's syntax for files.
+@end deffn
Because some file systems permit the names of directories to be
expressed in multiple ways, it is occasionally necessary to parse a
-native file name ``as a directory name'' or to produce a native file
-name that names a directory ``as a file''. For these cases,
-@code{parse-native-namestring} accepts the keyword argument
-@code{as-directory} to force a filename to parse as a directory, and
-@code{native-namestring} accepts the keyword argument @code{as-file}
-to force a pathname to unparse as a file. For example,
+native file name as a directory name or to produce a native file
+name that names a directory as a file. For these cases,
+PARSE-NATIVE-NAMESTRING accepts the keyword argument
+@code{:as-directory} to force a filename to parse as a directory, and
+@code{sb-ext:native-namestring} accepts the keyword argument @code{:as-file}
+to force a pathname to unparse as a file. For example,
-@lisp
+@example
; On Unix, the directory "/tmp/" can be denoted by "/tmp/" or "/tmp".
; Under the default rules for native filenames, these parse and
; unparse differently.
(defvar *p*)
-(setf *p* (parse-native-namestring "/tmp/")) @result{} #P"/tmp/"
-(pathname-name *p*) @result{} NIL
-(pathname-directory *p*) @result{} (:ABSOLUTE "tmp")
-(native-namestring *p*) @result{} "/tmp/"
+(setf *p* (parse-native-namestring "/tmp/")) => #P"/tmp/"
+(pathname-name *p*) => NIL
+(pathname-directory *p*) => (:ABSOLUTE "tmp")
+(native-namestring *p*) => "/tmp/"
-(setf *p* (parse-native-namestring "/tmp")) @result{} #P"/tmp"
-(pathname-name *p*) @result{} "tmp"
-(pathname-directory *p*) @result{} (:ABSOLUTE)
-(native-namestring *p*) @result{} "/tmp"
+(setf *p* (parse-native-namestring "/tmp")) => #P"/tmp"
+(pathname-name *p*) => "tmp"
+(pathname-directory *p*) => (:ABSOLUTE)
+(native-namestring *p*) => "/tmp"
; A non-NIL AS-DIRECTORY argument to PARSE-NATIVE-NAMESTRING forces
; both the second string to parse the way the first does.
(setf *p* (parse-native-namestring "/tmp"
nil *default-pathname-defaults*
- :as-directory t)) @result{} #P"/tmp/"
-(pathname-name *p*) @result{} NIL
-(pathname-directory *p*) @result{} (:ABSOLUTE "tmp")
+ :as-directory t)) => #P"/tmp/"
+(pathname-name *p*) => NIL
+(pathname-directory *p*) => (:ABSOLUTE "tmp")
; A non-NIL AS-FILE argument to NATIVE-NAMESTRING forces the pathname
; parsed from the first string to unparse as the second string.
-(setf *p* (parse-native-namestring "/tmp/")) @result{} #P"/tmp/"
-(native-namestring *p* :as-file t) @result{} "/tmp"
-@end lisp
+(setf *p* (parse-native-namestring "/tmp/")) => #P"/tmp/"
+(native-namestring *p* :as-file t) => "/tmp"
+@end example
+
diff --git a/doc/manual/profiling.texinfo b/doc/manual/profiling.texinfo
index cedb93b13..1d9a9d568 100644
--- a/doc/manual/profiling.texinfo
+++ b/doc/manual/profiling.texinfo
@@ -1,37 +1,67 @@
-@node Profiling
-@comment node-name, next, previous, up
+@c Generated by the sb-manual contrib. Do not edit.
+
+@node profiling
@chapter Profiling
-@cindex Profiling
-
-SBCL includes both a deterministic profiler, that can collect statistics
-on individual functions, and a more ``modern'' statistical profiler.
-
-Inlined functions do not appear in the results reported by either.
@menu
-* Deterministic Profiler::
-* Statistical Profiler::
+* Deterministic Profiler: deterministic profiler.
+* Statistical Profiler: statistical profiler.
@end menu
-@node Deterministic Profiler
-@comment node-name, next, previous, up
+SBCL includes both a deterministic profiler, that can collect
+statistics on individual functions, and a more "modern",
+statistical profiler.
+
+Inlined functions do not appear in the results reported by either.
+
+@node deterministic profiler
@section Deterministic Profiler
-@cindex Profiling, deterministic
The package @code{sb-profile} provides a classic, per-function-call
profiler.
-@quotation note
-When profiling code executed by multiple threads in parallel, the
-consing attributed to each function is inaccurate.
+@quotation
+@strong{Warning}: When profiling code executed by multiple threads in
+parallel, the consing attributed to each function is inaccurate.
@end quotation
-@include macro-sb-profile-profile.texinfo
-@include macro-sb-profile-unprofile.texinfo
-@include fun-sb-profile-report.texinfo
-@include fun-sb-profile-reset.texinfo
+@anchor{Macro sb-profile profile}
+@ffindex @sortas{profile sb-profile} profile [sb-profile]
+@deffn{Macro} sb-profile:profile &rest names
+If no names are supplied, return the list of profiled functions.
-@node Statistical Profiler
-@comment node-name, next, previous, up
-@section Statistical Profiler
-@include sb-sprof/sb-sprof.texinfo
+If names are supplied, wrap profiling code around the named functions.
+As in @code{trace}, the names are not evaluated. A symbol names a function.
+A string names all the functions named by symbols in the named
+package. If a function is already profiled, then unprofile and
+reprofile (useful to notice function redefinition.) If a name is
+undefined, then we give a warning and ignore it. See also
+@code{unprofile}, @code{report} and @code{reset}.
+@end deffn
+@anchor{Macro sb-profile unprofile}
+@ffindex @sortas{unprofile sb-profile} unprofile [sb-profile]
+@deffn{Macro} sb-profile:unprofile &rest names
+Unwrap any profiling code around the named functions, or if no names
+are given, unprofile all profiled functions. A symbol names
+a function. A string names all the functions named by symbols in the
+named package. @code{names} defaults to the list of names of all currently
+profiled functions.
+@end deffn
+@anchor{Function sb-profile report}
+@ffindex @sortas{report sb-profile} report [sb-profile]
+@deffn{Function} sb-profile:report &key limit print-no-call-list
+Report results from profiling. The results are approximately
+adjusted for profiling overhead. The compensation may be rather
+inaccurate when bignums are involved in runtime calculation, as in a
+very-long-running Lisp process.
+
+If @code{limit} is set to an integer, only the top @code{limit} results are
+reported. If @code{print-no-call-list} is @code{t} (the default) then a list of
+uncalled profiled functions are listed.
+@end deffn
+@anchor{Function sb-profile reset}
+@ffindex @sortas{reset sb-profile} reset [sb-profile]
+@deffn{Function} sb-profile:reset
+Reset the counters for all profiled functions.
+@end deffn
+@include ../../contrib/sb-sprof/sb-sprof.texinfo
diff --git a/doc/manual/start-stop.texinfo b/doc/manual/start-stop.texinfo
index fdae41717..374a029a5 100644
--- a/doc/manual/start-stop.texinfo
+++ b/doc/manual/start-stop.texinfo
@@ -1,35 +1,34 @@
-@node Starting and Stopping
-@comment node-name, next, previous, up
+@c Generated by the sb-manual contrib. Do not edit.
+
+@node starting and stopping
@chapter Starting and Stopping
@menu
-* Starting SBCL::
-* Stopping SBCL::
-* Command Line Options::
-* Initialization Files::
-* Initialization and Exit Hooks::
+* Starting SBCL: starting sbcl.
+* Stopping SBCL: stopping sbcl.
+* Command Line Options: command line options.
+* Initialization Files: initialization files.
+* Initialization and Exit Hooks: initialization and exit hooks.
@end menu
-@node Starting SBCL
-@comment node-name, next, previous, up
+@node starting sbcl
@section Starting SBCL
@menu
-* Running from Shell::
-* Running from Emacs::
-* Shebang Scripts::
+* Running from Shell: running from shell.
+* Running from Emacs: running from emacs.
+* Shebang Scripts: shebang scripts.
@end menu
-@node Running from Shell
-@comment node-name, next, previous, up
-@subsection From Shell to Lisp
+@node running from shell
+@subsection Running from Shell
-To run SBCL, type @command{sbcl} at the command line.
+To run SBCL, type @code{sbcl} at the command line.
-You should end up in the toplevel @dfn{REPL} (read-eval-print loop),
+You should end up in the toplevel @emph{REPL} (read-eval-print loop),
where you can interact with SBCL by typing expressions.
-@smallexample
+@example
$ sbcl
This is SBCL 0.8.13.60, an implementation of ANSI Common Lisp.
More information about SBCL is available at <http://www.sbcl.org/>.
@@ -42,125 +41,310 @@ distribution for more information.
4
* (exit)
$
-@end smallexample
+@end example
-See also @ref{Command Line Options} and @ref{Stopping SBCL}.
+Also see @ref{command line options} and @ref{stopping sbcl}.
-@node Running from Emacs
-@comment node-name, next, previous, up
+@node running from emacs
@subsection Running from Emacs
-To run SBCL as an @code{inferior-lisp} from Emacs, in your
-@file{.emacs} do something like:
+To run SBCL as an @code{inferior-lisp} from Emacs, in your @code{.emacs} do
+something like:
-@lisp
+@example
;;; The SBCL binary and command-line arguments
(setq inferior-lisp-program "/usr/local/bin/sbcl --noinform")
-@end lisp
+@end example
-For more information on using SBCL with Emacs, see @ref{Editor
-Integration}.
+For more information on using SBCL with Emacs, see
+@ref{editor integration}.
-
-@node Shebang Scripts
-@comment node-name, next, previous, up
+@node shebang scripts
@subsection Shebang Scripts
-@vindex @sbext{@earmuffs{posix-argv}}
Standard Unix tools that are interpreters follow a common command line
-protocol that is necessary to work with ``shebang scripts''. SBCL supports
-this via the @code{--script} command line option @pxref{Command Line Options}.
+protocol that is necessary to work with "shebang scripts". SBCL
+supports this via the @code{--script} command line option (see
+@ref{command line options}).
-Example file (@file{hello.lisp}):
+Example file (@code{hello.lisp}):
-@lisp
+@example
#!/usr/local/bin/sbcl --script
(write-line "Hello, World!")
-@end lisp
+@end example
Usage from the command line:
-@smallexample
+@example
$ ./hello.lisp
Hello, World!
-@end smallexample
+@end example
Note that SBCL skips the shebang line when it reads the file:
-@smallexample
+@example
$ sbcl --script hello.lisp
Hello, World!
-@end smallexample
+@end example
-@node Stopping SBCL
-@comment node-name, next, previous, up
+@node stopping sbcl
@section Stopping SBCL
@menu
-* Exit::
-* End of File::
-* Saving a Core Image::
-* Exit on Errors::
+* Exit: exit.
+* End of File: end of file.
+* Saving a Core Image: saving a core image.
+* Exit on Errors: exit on errors.
@end menu
-@node Exit
-@comment node-name, next, previous, up
+@node exit
@subsection Exit
SBCL can be stopped at any time by calling @code{sb-ext:exit},
-optionally returning a specified numeric value to the calling process.
-See @ref{Threading} for information about terminating individual threads.
+optionally returning a specified numeric value to the calling
+process. See @ref{threading} for information about terminating individual
+threads.
-@include fun-sb-ext-exit.texinfo
+@anchor{Function sb-ext exit}
+@ffindex @sortas{exit sb-ext} exit [sb-ext]
+@deffn{Function} sb-ext:exit &key code abort timeout
+Terminates the process, causing SBCL to exit with @code{code}. @code{code}
+defaults to 0 when @code{abort} is false, and 1 when it is true.
-@node End of File
-@comment node-name, next, previous, up
+When @code{abort} is false (the default), current thread is first unwound,
+@code{*exit-hooks*} are run, other threads are terminated, and standard
+output streams are flushed before SBCL calls @code{exit(3)} -- at which point
+@code{atexit(3)} functions will run. If multiple threads call @code{exit} with @code{abort}
+being false, the first one to call it will complete the protocol.
+
+When @code{abort} is true, SBCL exits immediately by calling @code{_exit(2)}
+without unwinding stack, or calling exit hooks. Note that @code{_exit(2)}
+does not call @code{atexit(3)} functions unlike @code{exit(3)}.
+
+Recursive calls to @code{exit} cause @code{exit} to behave as if @code{abort} was true.
+
+@code{timeout} controls waiting for other threads to terminate when @code{abort} is
+@code{nil}. Once current thread has been unwound and @code{*exit-hooks*} have been
+run, spawning new threads is prevented and all other threads are
+terminated by calling @code{sb-thread:terminate-thread} on them. The system
+then waits for them to finish using @code{sb-thread:join-thread}, waiting at
+most a total @code{timeout} seconds for all threads to join. Those threads
+that do not finish in time are simply ignored while the exit protocol
+continues. @code{timeout} defaults to @code{*exit-timeout*}, which in turn defaults
+to 60. @code{timeout} @code{nil} means to wait indefinitely.
+
+Note that @code{timeout} applies only to @code{sb-thread:join-thread}, not
+@code{*exit-hooks*}. Since @code{sb-thread:terminate-thread} is asynchronous,
+getting multithreaded application termination with complex cleanups
+right using it can be tricky. To perform an orderly synchronous
+shutdown use an exit hook instead of relying on implicit thread
+termination.
+
+Consequences are unspecified if serious conditions occur during @code{exit}
+excepting errors from @code{*exit-hooks*}, which cause warnings and stop
+execution of the hook that signaled, but otherwise allow the exit
+process to continue normally.
+@end deffn
+@node end of file
@subsection End of File
By default SBCL also exits on end of input, caused either by user
-pressing @kbd{Control-D} on an attached terminal, or end of input when
+pressing @code{Control-D} on an attached terminal, or end of input when
using SBCL as part of a shell pipeline.
-@node Saving a Core Image
-@comment node-name, next, previous, up
+@node saving a core image
@subsection Saving a Core Image
SBCL has the ability to save its state as a file for later
execution. This functionality is important for its bootstrapping
process, and is also provided as an extension to the user.
-@include fun-sb-ext-save-lisp-and-die.texinfo
-@include var-sb-ext-star-save-hooks-star.texinfo
+@anchor{Function sb-ext save-lisp-and-die}
+@ffindex @sortas{save-lisp-and-die sb-ext} save-lisp-and-die [sb-ext]
+@deffn{Function} sb-ext:save-lisp-and-die core-file-name &key toplevel executable save-runtime-options callable-exports purify root-structures environment-name compression
+Save a "core image", i.e. enough information to restart a Lisp
+process later in the same state, in the file of the specified name.
+Only global state is preserved: the stack is unwound in the process.
+The following @code{&key} arguments are defined:
+
+@itemize
+@item @code{:toplevel}
+
+The function to run when the created core file is resumed. The
+default function handles command line toplevel option
+processing (see @ref{toplevel options}) and runs the top
+level read-eval-print loop. This function returning is equivalent
+to (@code{sb-ext:exit} @code{:code} 0) being called.
+
+@code{toplevel} functions should always provide an @code{abort} restart:
+otherwise code they call will run without one.
+
+@item @code{:executable}
+
+If true, arrange to combine the SBCL runtime and the core image to
+create a standalone executable. If false (the default), the core
+image will not be executable on its own. Executable images always
+behave as if they were passed the @code{--noinform} runtime option.
+ If @code{:executable} is @code{:elf-object}, then the resulting core will be
+ wrapped in a .o which requires further linking. (EXPERIMENTAL)
+
+@item @code{:save-runtime-options}
+
+If true, values of runtime options @code{--dynamic-space-size} and
+@code{--control-stack-size} that were used to start SBCL are stored in
+the standalone executable, and restored when the executable is
+run. This also inhibits normal runtime option processing, causing
+all command line arguments to be passed to the toplevel. If
+@code{:accept-runtime-options} then @code{--dynamic-space-size} and
+@code{--control-stack-size} are still processed by the runtime.
+Meaningless if @code{:executable} is @code{nil}.
+
+@item @code{:callable-exports}
+
+This should be a list of symbols to be initialized to the
+appropriate alien callables on startup. All exported symbols
+should be present as global symbols in the symbol table of the
+runtime before the saved core is loaded. When this list is
+non-empty, the @code{:toplevel} argument cannot be supplied.
+
+@item @code{:purify}
+
+If true (the default), then some objects in the restarted core
+will be memory-mapped as read-only. Among those objects are
+numeric vectors that were determined to be compile-time constants,
+and any immutable values according to the language specification
+such as symbol names.
+
+@item @code{:root-structures}
+
+This should be a list of the main entry points in any newly loaded
+systems. This need not be supplied, but locality and/or @code{gc}
+performance may be better if they are. This has two different but
+related meanings: If @code{:purify} is true - and only for cheneygc - the
+root structures are those which anchor the set of objects moved
+into static space. On gencgc - and only on platforms supporting
+immobile code - these are the functions and/or function-names
+which commence a depth-first scan of code when reordering based on
+the statically observable call chain. The complete set of
+reachable objects is not affected per se. This argument is
+meaningless if neither enabling precondition holds.
+
+@item @code{:environment-name}
+
+This has no purpose; it is accepted only for legacy compatibility.
+
+@item @code{:compression}
+
+This is only meaningful if the runtime was built with the
+@code{:sb-core-compression} feature enabled. If @code{nil} (the default),
+saves to uncompressed core files. If @code{:sb-core-compression} was
+enabled at build-time, the argument may also be an integer from -7
+to 22, corresponding to zstd compression levels, or @code{t} (which is
+equivalent to the default compression level, 9).
+
+@item @code{:application-type}
+
+Present only on Windows and is meaningful only with @code{:executable} @code{t}.
+Specifies the subsystem of the executable, @code{:console} or @code{:gui}.
+The notable difference is that @code{:gui} doesn't automatically create
+a console window. The default is @code{:console}.
+@end itemize
+
+The save/load process changes the values of some global variables:
+
+@itemize
+@item @code{*standard-output*}, @code{*debug-io*}, etc
+
+Everything related to open streams is necessarily changed, since
+the OS won't let us preserve a stream across save and load.
+
+@item @code{*default-pathname-defaults*}
+
+This is reinitialized to reflect the working directory where the
+saved core is loaded.
+@end itemize
+
+@code{save-lisp-and-die} interacts with @code{sb-alien:load-shared-object}: see its
+documentation for details.
+
+On threaded platforms only a single thread may remain running after
+@code{sb-ext:*save-hooks*} have run. Applications using multiple threads can
+be @code{save-lisp-and-die} friendly by registering a save-hook that quits
+any additional threads, and an init-hook that restarts them.
+
+This implementation is not as polished and painless as you might like:
+
+@itemize
+@item It corrupts the current Lisp image enough that the current process
+ needs to be killed afterwards. This can be worked around by forking
+ another process that saves the core.
+
+@item There is absolutely no binary compatibility of core images between
+ different runtime support programs. Even runtimes built from the
+ same sources at different times are treated as incompatible for this
+ purpose.
+@end itemize
+
+This isn't because we like it this way, but just because there don't
+seem to be good quick fixes for either limitation and no one has been
+sufficiently motivated to do lengthy fixes.
+@end deffn
+@anchor{Variable sb-ext *save-hooks*}
+@vvindex @sortas{save-hooks* sb-ext} *save-hooks* [sb-ext]
+@deffn{Variable} sb-ext:*save-hooks*
+A list of function designators which are called in an unspecified
+order before creating a saved core image.
+
+Unused by SBCL itself: reserved for user and applications.
+@end deffn
In cases where the standard initialization files have already been loaded
-into the saved core, and alternative ones should be used (or none at all),
-SBCL allows customizing the initfile pathname computation.
-
-@include var-sb-ext-star-sysinit-pathname-function-star.texinfo
-@include var-sb-ext-star-userinit-pathname-function-star.texinfo
+into the saved core, and alternative ones should be used (or none at
+all), SBCL allows customizing the initfile pathname computation.
+@anchor{Variable sb-ext *sysinit-pathname-function*}
+@vvindex @sortas{sysinit-pathname-function* sb-ext} *sysinit-pathname-function* [sb-ext]
+@deffn{Variable} sb-ext:*sysinit-pathname-function*
+Designator for a function of zero arguments called to obtain a
+pathname designator for the default sysinit file, or @code{nil}. If the
+function returns @code{nil}, no sysinit file is used unless one has been
+specified on the command-line.
+@end deffn
+@anchor{Variable sb-ext *userinit-pathname-function*}
+@vvindex @sortas{userinit-pathname-function* sb-ext} *userinit-pathname-function* [sb-ext]
+@deffn{Variable} sb-ext:*userinit-pathname-function*
+Designator for a function of zero arguments called to obtain a
+pathname designator or a stream for the default userinit file, or @code{nil}.
+If the function returns @code{nil}, no userinit file is used unless one has
+been specified on the command-line.
+@end deffn
To facilitate distribution of SBCL applications using external
-resources, the filesystem location of the SBCL core file being used is
-available from Lisp.
+resources, the filesystem location of the SBCL core file being used
+is available from Lisp.
-@include var-sb-ext-star-core-pathname-star.texinfo
-
-@node Exit on Errors
-@comment node-name, next, previous, up
+@anchor{Variable sb-ext *core-pathname*}
+@vvindex @sortas{core-pathname* sb-ext} *core-pathname* [sb-ext]
+@deffn{Variable} sb-ext:*core-pathname*
+The absolute pathname of the running SBCL core.
+@end deffn
+@node exit on errors
@subsection Exit on Errors
SBCL can also be configured to exit if an unhandled error occurs,
which is mainly useful for acting as part of a shell pipeline; doing
-so under most other circumstances would mean giving up large parts of
-the flexibility and robustness of Common Lisp. See @ref{Debugger Entry}.
+so under most other circumstances would mean giving up large parts
+of the flexibility and robustness of Common Lisp. See
+@ref{debugger entry} and the command line option @code{--disable-debugger} in
+@ref{runtime options}.
-@node Command Line Options
-@comment node-name, next, previous, up
+@node command line options
@section Command Line Options
-@c FIXME: This is essentially cut-and-paste from the manpage
-@c What should probably be done is generate both this and the
-@c man-page from ``sbcl --help'' output.
+@menu
+* Runtime Options: runtime options.
+* Toplevel Options: toplevel options.
+@end menu
Command line options can be considered an advanced topic; for ordinary
interactive use, no command line arguments should be necessary.
@@ -170,13 +354,19 @@ is helpful to understand that the SBCL system is implemented as two
components, a low-level runtime environment written in C and a
higher-level system written in Common Lisp itself. Some command line
arguments are processed during the initialization of the low-level
-runtime environment, some command line arguments are processed during
-the initialization of the Common Lisp system, and any remaining
-command line arguments are passed on to user code.
+runtime environment, some command line arguments are processed
+during the initialization of the Common Lisp system, and any
+remaining command line arguments are made available to user code via
+@code{sb-ext:*posix-argv*}.
-The full, unambiguous syntax for invoking SBCL at the command line is:
+The full, unambiguous syntax for invoking SBCL at the command line
+is:
-@command{sbcl} @var{runtime-option}* @code{--end-runtime-options} @var{toplevel-option}* @code{--end-toplevel-options} @var{user-option}*
+@example
+sbcl <runtime-option>* --end-runtime-options \
+ <toplevel-option>* --end-toplevel-options \
+ <user-option>*
+@end example
For convenience, @code{--end-runtime-options} and
@code{--end-toplevel-options} can be omitted, which can be convenient
@@ -185,210 +375,236 @@ no ambiguities are possible with the option values you are using.
Omitting these elements is probably a bad idea for any batch file
where any of the options are under user control, since it makes it
impossible for SBCL to detect erroneous command line input, so that
-erroneous command line arguments will be passed on to the user program
-even if they was intended for the runtime system or the Lisp system.
+erroneous command line arguments will be passed on to the user
+program even if they was intended for the runtime system or the Lisp
+system.
-@menu
-* Runtime Options::
-* Toplevel Options::
-@end menu
-
-@node Runtime Options
-@comment node-name, next, previous, up
+@node runtime options
@subsection Runtime Options
-@table @code
-
-@item --core @var{corefilename}
-Run the specified Lisp core file instead of the default. Note that if
-the Lisp core file is a user-created core file, it may run a
-nonstandard toplevel which does not recognize the standard toplevel
-options.
-
-@item --dynamic-space-size @var{megabytes}
-Size of the dynamic space reserved on startup in megabytes. Default
-value is platform dependent.
-
-@item --control-stack-size @var{megabytes}
-Size of control stack reserved for each thread in megabytes. Default
-value is 2.
-
-@item --tls-limit @var{positive integer}
-Maximum number of thread-local symbols in threaded builds. Default
-value is 4096.
-
-@item --noinform
-Suppress the printing of any banner or other informational message at
-startup. This makes it easier to write Lisp programs which work
-cleanly in Unix pipelines. See also the @code{--noprint} and
-@code{--disable-debugger} options.
-
-@item --disable-ldb
-@cindex ldb
-@cindex ldb, disabling
-@cindex disabling ldb
-Disable the low-level debugger. Only effective if SBCL is compiled
-with LDB.
-
-@item --lose-on-corruption
-@cindex ldb
-There are some dangerous low-level errors (for instance, control stack
-exhausted, memory fault) that (or whose handlers) can corrupt the
-image. By default, SBCL prints a warning, then tries to continue and
-handle the error in Lisp, but this will not always work, and SBCL may
-malfunction or even hang. With this option, upon encountering such an
-error, SBCL will exit instead of invoking LDB (if present and
-enabled).
-
-
-@item --script @var{filename}
+@itemize
+@item @code{--core <corefilename>}
+
+Run the specified Lisp core file instead of the default. Note
+that if the Lisp core file is a user-created core file, it may
+run a nonstandard toplevel which does not recognize the standard
+toplevel options.
+
+@item @code{--dynamic-space-size <megabytes>}
+
+Size of the dynamic space reserved on startup in megabytes.
+Default value is platform dependent.
+
+@item @code{--control-stack-size <megabytes>}
+
+Size of control stack reserved for each thread in megabytes.
+Default value is 2.
+
+@item @code{--tls-limit <positive integer>}
+
+Maximum number of thread-local symbols in threaded builds.
+Default value is 4096.
+
+@item @code{--noinform}
+
+Suppress the printing of any banner or other informational
+message at startup. This makes it easier to write Lisp programs
+which work cleanly in Unix pipelines. See also the @code{--noprint}
+and @code{--disable-debugger} options.
+
+@item @code{--disable-ldb}
+
+Disable the low-level debugger. Only effective if SBCL is
+compiled with @code{ldb}.
+
+@item @code{--lose-on-corruption}
+
+There are some dangerous low-level errors (for instance, control
+stack exhausted, memory fault) that (or whose handlers) can
+corrupt the image. By default, SBCL prints a warning, then tries
+to continue and handle the error in Lisp, but this will not
+always work, and SBCL may malfunction or even hang. With this
+option, upon encountering such an error, SBCL will exit instead
+of invoking @code{ldb} (if present and enabled).
+
+@item @code{--script <filename>}
+
As a @emph{runtime} option, this is equivalent to @code{--noinform}
@code{--disable-ldb} @code{--lose-on-corruption}
-@code{--end-runtime-options} @code{--script} @var{filename}. See the
-description of @code{--script} as a @emph{toplevel} option below. If
-there are no other command line arguments following @code{--script},
-the filename argument can be omitted.
+@code{--end-runtime-options} @code{--script} @code{<filename>}. See
+the description of @code{--script} as a @emph{toplevel} option below.
+If there are no other command line arguments following
+@code{--script}, the filename argument can be omitted.
+@item @code{--merge-core-pages}
-@item --merge-core-pages
-When platform support is present, provide hints to the operating system
-that identical pages may be shared between processes until they are
-written to. This can be useful to reduce the memory usage on systems
-with multiple SBCL processes started from similar but differently-named
-core files, or from compressed cores. Without platform support, do
-nothing. By default only compressed cores trigger hinting.
+When platform support is present, provide hints to the operating
+system that identical pages may be shared between processes
+until they are written to. This can be useful to reduce the
+memory usage on systems with multiple SBCL processes started
+from similar but differently-named core files, or from
+compressed cores. Without platform support, do nothing. By
+default only compressed cores trigger hinting.
-@item --no-merge-core-pages
-Ensures that no sharing hint is provided to the operating system.
+@item @code{--no-merge-core-pages}
+
+Ensures that no sharing hint is provided to the operating
+system.
+
+@item @code{--help}
-@item --help
Print some basic information about SBCL, then exit.
-@item --version
+@item @code{--version}
+
Print SBCL's version information, then exit.
+@end itemize
-@end table
+In the future, runtime options may be added to control behaviour
+such as lazy allocation of memory.
-In the future, runtime options may be added to control behaviour such
-as lazy allocation of memory.
+Runtime options, including any @code{--end-runtime-options} option, are
+stripped out of the command line before the Lisp toplevel logic gets
+a chance to see it.
-Runtime options, including any @code{--end-runtime-options} option,
-are stripped out of the command line before the Lisp toplevel logic
-gets a chance to see it.
-
-@node Toplevel Options
-@comment node-name, next, previous, up
+@node toplevel options
@subsection Toplevel Options
-@table @code
+The following options are processed and removed by the default
+toplevel (see @code{sb-ext:save-lisp-and-die}).
-@item --sysinit @var{filename}
-Load filename instead of the default system initialization file
-(@pxref{Initialization Files}.)
+@itemize
+@item @code{--sysinit <filename>}
-@item --no-sysinit
-Don't load a system-wide initialization file. If this option is given,
-the @code{--sysinit} option is ignored.
+Load @code{filename} instead of the default system initialization
+file (see @ref{initialization files}).
-@item --userinit @var{filename}
-Load filename instead of the default user initialization file
-(@pxref{Initialization Files}.)
+@item @code{--no-sysinit}
-@item --no-userinit
-Don't load a user initialization file. If this option is given,
+Don't load a system-wide initialization file. If this option is
+given, the @code{--sysinit} option is ignored.
+
+@item @code{--userinit <filename>}
+
+Load @code{filename} instead of the default user initialization file
+(see @ref{initialization files}.)
+
+@item @code{--no-userinit}
+
+Don't load a user initialization file. If this option is given,
the @code{--userinit} option is ignored.
-@item --eval @var{command}
+@item @code{--eval <command>}
+
After executing any initialization file, but before starting the
-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.
+read-eval-print loop on standard input, read and evaluate
+@code{command}. 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
-special syntax is intended to reduce quoting headaches when invoking
-SBCL from shell scripts.
+@item @code{--load <filename>}
-@item --noprint
-When ordinarily the toplevel "read-eval-print loop" would be executed,
-execute a "read-eval loop" instead, i.e. don't print a prompt and
-don't echo results. Combined with the @code{--noinform} runtime
-option, this makes it easier to write Lisp "scripts" which work
-cleanly in Unix pipelines.
+This is equivalent to @code{--eval '(load "<filename>")'}. The
+special syntax is intended to reduce quoting headaches when
+invoking SBCL from shell scripts.
+
+@item @code{--noprint}
+
+When ordinarily the toplevel "read-eval-print loop" would be
+executed, execute a "read-eval loop" instead, i.e. don't print
+a prompt and don't echo results. Combined with the @code{--noinform}
+runtime option, this makes it easier to write Lisp "scripts"
+which work cleanly in Unix pipelines.
+
+@item @code{--disable-debugger}
-@item --disable-debugger
By default when SBCL encounters an error, it enters the builtin
-debugger, allowing interactive diagnosis and possible intercession.
-This option disables the debugger, causing errors to print a backtrace
-and exit with status 1 instead. When given, this option takes effect
-before loading of initialization files or processing @code{--eval} and
-@code{--load} options. See @code{sb-ext:disable-debugger} for details.
-@xref{Debugger Entry}.
+debugger, allowing interactive diagnosis and possible
+intercession. This option disables the debugger, causing errors
+to print a backtrace and exit with status 1 instead. When given,
+this option takes effect before loading of initialization files
+or processing @code{--eval} and @code{--load} options. See
+@code{sb-ext:disable-debugger} and @ref{debugger entry}.
-@item --script @var{filename}
-Implies @code{--no-userinit} @code{--no-sysinit}
-@code{--disable-debugger} @code{--end-toplevel-options}.
+@item @code{--script <filename>}
-Causes the system to load the specified file instead of entering the
-read-eval-print-loop, and exit afterwards. If the file begins with a
-shebang line, it is ignored.
+Implies @code{--no-userinit} @code{--no-sysinit} @code{--disable-debugger}
+@code{--end-toplevel-options}.
-If there are no other command line arguments following, the filename
-can be omitted: this causes the script to be loaded from standard
-input instead. Shebang lines in standard input script are currently
-@emph{not} ignored.
+Causes the system to load the specified file instead of entering
+the read-eval-print-loop, and exit afterwards. If the file
+begins with a shebang line, it is ignored.
-In either case, if there is an unhandled error (e.g. end of file, or a
-broken pipe) on either standard input, standard output, or standard
-error, the script silently exits with code 0. This allows e.g. safely
-piping output from SBCL to @code{head -n1} or similar.
+If there are no other command line arguments following, the
+filename can be omitted: this causes the script to be loaded
+from standard input instead. Shebang lines in standard input
+script are currently @emph{not} ignored.
+
+In either case, if there is an unhandled error (e.g. end of
+file, or a broken pipe) on either standard input, standard
+output, or standard error, the script silently exits with code
+0. This allows e.g. safely piping output from SBCL to @code{head -n1}
+or similar.
Additionally, the option sets @code{*compile-verbose*} and
@code{*load-verbose*} to @code{nil} while loading the file to avoid
potentially verbose diagnostic messages printed on the standard
output.
+@end itemize
-@end table
-
-@node Initialization Files
-@comment node-name, next, previous, up
+@node initialization files
@section Initialization Files
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.
+@code{*package*} and @code{*readtable*}, and for proclaiming a global optimization
+policy.
-@table @strong
+@itemize
+@item @strong{System Initialization File:} Defaults to @code{$SBCL_HOME/sbclrc},
+ or if that doesn't exist to @code{/etc/sbclrc}. Can be overridden with
+ the command line option @code{--sysinit} or @code{--no-sysinit} (see
+ @ref{toplevel options}).
-@item System Initialization File
-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} (@pxref{Toplevel Options}).
+The system initialization file is intended for system
+administrators and software packagers to configure locations of
+installed third party modules, etc.
-The system initialization file is intended for system administrators
-and software packagers to configure locations of installed third party
-modules, etc.
+@item @strong{User Initialization File:} Defaults to @code{$HOME/.sbclrc}. Can be
+ overridden with the command line option @code{--userinit} or
+ @code{--no-userinit} (see @ref{toplevel options}).
-@item User Initialization File
-Defaults to @file{@env{$HOME}/.sbclrc}. Can be overridden with the
-command line option @code{--userinit} or @code{--no-userinit}
-(@pxref{Toplevel Options}).
-
-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 table
+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 (see @ref{fasl format}), etc.
+@end itemize
Neither initialization file is required.
-@node Initialization and Exit Hooks
-@comment node-name, next, previous, up
+@node initialization and exit hooks
@section Initialization and Exit Hooks
SBCL provides hooks into the system initialization and exit.
-@include var-sb-ext-star-init-hooks-star.texinfo
-@include var-sb-ext-star-exit-hooks-star.texinfo
+@anchor{Variable sb-ext *init-hooks*}
+@vvindex @sortas{init-hooks* sb-ext} *init-hooks* [sb-ext]
+@deffn{Variable} sb-ext:*init-hooks*
+A list of function designators which are called in an unspecified
+order when a saved core image starts up, after the system itself has
+been initialized, but before non-user threads such as the finalizer
+thread have been started.
+
+Unused by SBCL itself: reserved for user and applications.
+@end deffn
+@anchor{Variable sb-ext *exit-hooks*}
+@vvindex @sortas{exit-hooks* sb-ext} *exit-hooks* [sb-ext]
+@deffn{Variable} sb-ext:*exit-hooks*
+A list of function designators which are called in an unspecified
+order when SBCL process exits.
+
+Unused by SBCL itself: reserved for user and applications.
+
+Using (@code{sb-ext:exit} @code{:abort} @code{t}), or calling @code{exit(3)} directly circumvents
+these hooks.
+@end deffn
diff --git a/doc/manual/streams.texinfo b/doc/manual/streams.texinfo
index 3cc4f4dd8..e9ee58d10 100644
--- a/doc/manual/streams.texinfo
+++ b/doc/manual/streams.texinfo
@@ -1,202 +1,576 @@
-@node Streams
-@comment node-name, next, previous, up
+@c Generated by the sb-manual contrib. Do not edit.
+
+@node streams
@chapter Streams
+@menu
+* Stream External Formats: stream external formats.
+* Bivalent Streams: bivalent streams.
+* Gray Streams: gray streams.
+* Simple Streams: sb simple streams.
+@end menu
+
Streams which read or write Lisp character data from or to the outside
world -- files, sockets or other external entities -- require the
-specification of a conversion between the external, binary data and the
-Lisp characters. In ANSI Common Lisp, this is done by specifying the
-@code{:external-format} argument when the stream is created. The major
-information required is an @emph{encoding}, specified by a keyword
-naming that encoding; however, it is also possible to specify
-refinements to that encoding as additional options to the external
-format designator.
+specification of a conversion between the external, binary data and
+the Lisp characters. In ANSI Common Lisp, this is done by specifying
+the @code{:external-format} argument when the stream is created. The major
+information required is an @emph{encoding}, specified by a keyword naming
+that encoding; however, it is also possible to specify refinements
+to that encoding as additional options to the external format
+designator.
In addition, SBCL supports various extensions of ANSI Common Lisp
streams:
-@table @strong
-@item Bivalent Streams
-A type of stream that can read and write both @code{character} and
-@code{(unsigned-byte 8)} values.
+@itemize
+@item @emph{Bivalent Streams}: A type of stream that can read and write both
+ @code{character} and @code{(unsigned-byte 8)} values.
-@item Gray Streams
-User-overloadable CLOS classes whose instances can be used as Lisp
-streams (e.g. passed as the first argument to @code{format}).
+@item @emph{Gray Streams}: User-overloadable CLOS classes whose instances can
+ be used as Lisp streams (e.g. passed as the first argument to
+ @code{format}).
-@item Simple Streams
-The bundled contrib module @dfn{sb-simple-streams} implements a subset
-of the Franz Allegro simple-streams proposal.
+@item @emph{Simple Streams}: The bundled contrib module @code{sb-simple-streams}
+ implements a subset of the Franz Allegro simple-streams proposal.
+@end itemize
-@end table
-
-@menu
-* Stream External Formats::
-* Bivalent Streams::
-* Gray Streams::
-* Simple Streams::
-@end menu
-
-@node Stream External Formats
+@node stream external formats
@section Stream External Formats
-@cindex Stream External formats
-@findex @cl{stream-external-format}
The function @code{stream-external-format} returns the canonical name of
-the external format (See @ref{External Formats}) used by the stream for
+the external format (See @ref{external formats}) used by the stream for
character-based input and/or output.
-@findex @cl{open}
-@findex @cl{with-open-file}
When constructing file streams, for example using @code{open} or
@code{with-open-file}, the external format to use is specified via the
@code{:external-format} argument which accepts an external format
-designator (See @ref{External Format Designators}).
+designator (see @ref{external format designators}).
-@node Bivalent Streams
+@node bivalent streams
@section Bivalent Streams
-A @dfn{bivalent stream} can be used to read and write both
-@code{character} and @code{(unsigned-byte 8)} values. A bivalent
-stream is created by calling @code{open} with the argument @code{:element-type
-:default}. On such a stream, both binary and character data can be
+A @emph{bivalent stream} can be used to read and write both
+@code{character} and @code{(unsigned-byte 8)} values. A bivalent stream is
+created by calling @code{open} with the argument @code{:element-type}
+@code{:default}. On such a stream, both binary and character data can be
read and written with the usual input and output functions.
-@c Horrible visual markup
-@quotation
Streams are @emph{not} created bivalent by default for performance
-reasons. Bivalent streams are incompatible with
-@code{fast-read-char}, an internal optimization in SBCL's stream
-machinery that bulk-converts octets to characters and implements a
-fast path through @code{read-char}.
-@end quotation
+reasons. Bivalent streams are incompatible with @code{fast-read-char}, an
+internal optimization in SBCL's stream machinery that bulk-converts
+octets to characters and implements a fast path through @code{read-char}.
-@node Gray Streams
+@node gray streams
@section Gray Streams
+@menu
+* Gray Streams classes: gray streams classes.
+* Methods common to all streams: methods common to all streams.
+* Input stream methods: input stream methods.
+* Character input stream methods: character input stream methods.
+* Output stream methods: output stream methods.
+* Character output stream methods: character output stream methods.
+* Binary stream methods: binary stream methods.
+* Gray Streams Examples: gray streams examples.
+@end menu
The Gray Streams interface is a widely supported extension that
-provides for definition of CLOS-extensible stream classes. Gray
-stream classes are implemented by adding methods to generic functions
-analogous to Common Lisp's standard I/O functions. Instances of Gray
-stream classes may be used with any I/O operation where a non-Gray
-stream can, provided that all required methods have been implemented
-suitably.
+provides for definition of CLOS-extensible stream classes. Gray
+stream classes are implemented by adding methods to generic
+functions analogous to Common Lisp's standard I/O functions.
+Instances of Gray stream classes may be used with any I/O operation
+where a non-Gray stream can, provided that all required methods have
+been implemented suitably.
-@menu
-* Gray Streams classes::
-* Methods common to all streams::
-* Input stream methods::
-* Character input stream methods::
-* Output stream methods::
-* Character output stream methods::
-* Binary stream methods::
-* Gray Streams examples::
-@end menu
-
-@node Gray Streams classes
+@node gray streams classes
@subsection Gray Streams classes
The defined Gray Stream classes are these:
-@include class-sb-gray-fundamental-stream.texinfo
-@include class-sb-gray-fundamental-input-stream.texinfo
+@anchor{Class sb-gray fundamental-stream}
+@ttindex @sortas{fundamental-stream sb-gray} fundamental-stream [sb-gray]
+@deffn{Class} sb-gray:fundamental-stream
+Base class for all Gray streams.
+@end deffn
+@anchor{Class sb-gray fundamental-input-stream}
+@ttindex @sortas{fundamental-input-stream sb-gray} fundamental-input-stream [sb-gray]
+@deffn{Class} sb-gray:fundamental-input-stream
+Superclass of all Gray input streams.
+@end deffn
+The function @code{input-stream-p} will return true of any generalized
+instance of @code{sb-gray:fundamental-input-stream}.
-@noindent
-The function input-stream-p will return true of any generalized
-instance of fundamental-input-stream.
+@anchor{Class sb-gray fundamental-output-stream}
+@ttindex @sortas{fundamental-output-stream sb-gray} fundamental-output-stream [sb-gray]
+@deffn{Class} sb-gray:fundamental-output-stream
+Superclass of all Gray output streams.
+@end deffn
+The function @code{output-stream-p} will return true of any generalized
+instance of @code{sb-gray:fundamental-output-stream}.
-@include class-sb-gray-fundamental-output-stream.texinfo
+@anchor{Class sb-gray fundamental-binary-stream}
+@ttindex @sortas{fundamental-binary-stream sb-gray} fundamental-binary-stream [sb-gray]
+@deffn{Class} sb-gray:fundamental-binary-stream
+Superclass of all Gray streams whose element-type
+is a subtype of unsigned-byte or signed-byte.
+@end deffn
+Note that instantiable subclasses of @code{sb-gray:fundamental-binary-stream}
+should provide (or inherit) an applicable method for the generic
+function @code{stream-element-type}.
-@noindent
-The function output-stream-p will return true of any generalized
-instance of fundamental-output-stream.
-
-@include class-sb-gray-fundamental-binary-stream.texinfo
-
-@noindent
-Note that instantiable subclasses of fundamental-binary-stream should
-provide (or inherit) an applicable method for the generic function
-stream-element-type.
-
-@include class-sb-gray-fundamental-character-stream.texinfo
-@include class-sb-gray-fundamental-binary-input-stream.texinfo
-@include class-sb-gray-fundamental-binary-output-stream.texinfo
-@include class-sb-gray-fundamental-character-input-stream.texinfo
-@include class-sb-gray-fundamental-character-output-stream.texinfo
-
-@node Methods common to all streams
+@anchor{Class sb-gray fundamental-character-stream}
+@ttindex @sortas{fundamental-character-stream sb-gray} fundamental-character-stream [sb-gray]
+@deffn{Class} sb-gray:fundamental-character-stream
+Superclass of all Gray streams whose element-type is a subtype of character.
+@end deffn
+@anchor{Class sb-gray fundamental-binary-input-stream}
+@ttindex @sortas{fundamental-binary-input-stream sb-gray} fundamental-binary-input-stream [sb-gray]
+@deffn{Class} sb-gray:fundamental-binary-input-stream
+Superclass of all Gray input streams whose element-type
+is a subtype of unsigned-byte or signed-byte.
+@end deffn
+@anchor{Class sb-gray fundamental-binary-output-stream}
+@ttindex @sortas{fundamental-binary-output-stream sb-gray} fundamental-binary-output-stream [sb-gray]
+@deffn{Class} sb-gray:fundamental-binary-output-stream
+Superclass of all Gray output streams whose element-type
+is a subtype of unsigned-byte or signed-byte.
+@end deffn
+@anchor{Class sb-gray fundamental-character-input-stream}
+@ttindex @sortas{fundamental-character-input-stream sb-gray} fundamental-character-input-stream [sb-gray]
+@deffn{Class} sb-gray:fundamental-character-input-stream
+Superclass of all Gray input streams whose element-type
+is a subtype of character.
+@end deffn
+@anchor{Class sb-gray fundamental-character-output-stream}
+@ttindex @sortas{fundamental-character-output-stream sb-gray} fundamental-character-output-stream [sb-gray]
+@deffn{Class} sb-gray:fundamental-character-output-stream
+Superclass of all Gray output streams whose element-type
+is a subtype of character.
+@end deffn
+@node methods common to all streams
@subsection Methods common to all streams
These generic functions can be specialized on any generalized instance
of fundamental-stream.
-@include fun-common-lisp-stream-element-type.texinfo
-@include fun-common-lisp-close.texinfo
-@include fun-sb-gray-stream-file-position.texinfo
-
-
-
-@node Input stream methods
+@anchor{Generic function common-lisp stream-element-type}
+@ffindex @sortas{stream-element-type common-lisp} stream-element-type [common-lisp]
+@deffn{Generic function} stream-element-type stream
+Return a type specifier for the kind of object returned by the
+@code{stream}. The class @code{sb-gray:fundamental-character-stream} provides a
+default method which returns @code{character}.
+@end deffn
+@anchor{Generic function common-lisp close}
+@ffindex @sortas{close common-lisp} close [common-lisp]
+@deffn{Generic function} close stream &key abort
+Close the given @code{stream}. No more I/O may be performed, but
+inquiries may still be made. If @code{:abort} is true, an attempt is made
+to clean up the side effects of having created the stream.
+@end deffn
+@anchor{Generic function sb-gray stream-file-position}
+@ffindex @sortas{stream-file-position sb-gray} stream-file-position [sb-gray]
+@deffn{Generic function} sb-gray:stream-file-position stream &optional position-spec
+Used by @code{file-position}. Returns or changes the current position within @code{stream}.
+@end deffn
+@node input stream methods
@subsection Input stream methods
These generic functions may be specialized on any generalized instance
of fundamental-input-stream.
-@include fun-sb-gray-stream-clear-input.texinfo
-@include fun-sb-gray-stream-read-sequence.texinfo
-
-@node Character input stream methods
+@anchor{Generic function sb-gray stream-clear-input}
+@ffindex @sortas{stream-clear-input sb-gray} stream-clear-input [sb-gray]
+@deffn{Generic function} sb-gray:stream-clear-input stream
+This is like @code{cl:clear-input}, but for Gray streams, returning @code{nil}.
+The default method does nothing.
+@end deffn
+@anchor{Generic function sb-gray stream-read-sequence}
+@ffindex @sortas{stream-read-sequence sb-gray} stream-read-sequence [sb-gray]
+@deffn{Generic function} sb-gray:stream-read-sequence stream seq &optional start end
+This is like @code{cl:read-sequence}, but for Gray streams.
+@end deffn
+@node character input stream methods
@subsection Character input stream methods
These generic functions are used to implement subclasses of
-fundamental-input-stream:
+@code{sb-gray:fundamental-input-stream}:
-@include fun-sb-gray-stream-peek-char.texinfo
-@include fun-sb-gray-stream-read-char-no-hang.texinfo
-@include fun-sb-gray-stream-read-char.texinfo
-@include fun-sb-gray-stream-read-line.texinfo
-@include fun-sb-gray-stream-listen.texinfo
-@include fun-sb-gray-stream-unread-char.texinfo
-
-@node Output stream methods
+@anchor{Generic function sb-gray stream-peek-char}
+@ffindex @sortas{stream-peek-char sb-gray} stream-peek-char [sb-gray]
+@deffn{Generic function} sb-gray:stream-peek-char stream
+This is used to implement @code{peek-char}; this corresponds to @code{peek-type}
+of @code{nil}. It returns either a character or @code{:eof}. The default method
+calls @code{stream-read-char} and @code{stream-unread-char}.
+@end deffn
+@anchor{Generic function sb-gray stream-read-char-no-hang}
+@ffindex @sortas{stream-read-char-no-hang sb-gray} stream-read-char-no-hang [sb-gray]
+@deffn{Generic function} sb-gray:stream-read-char-no-hang stream
+This is used to implement @code{read-char-no-hang}. It returns either a
+character, or @code{nil} if no input is currently available, or @code{:eof} if
+end-of-file is reached. The default method provided by
+@code{fundamental-character-input-stream} simply calls @code{stream-read-char}; this
+is sufficient for file streams, but interactive streams should define
+their own method.
+@end deffn
+@anchor{Generic function sb-gray stream-read-char}
+@ffindex @sortas{stream-read-char sb-gray} stream-read-char [sb-gray]
+@deffn{Generic function} sb-gray:stream-read-char stream
+Read one character from the stream. Return either a
+character object, or the symbol @code{:eof} if the stream is at end-of-file.
+Every subclass of @code{fundamental-character-input-stream} must define a
+method for this function.
+@end deffn
+@anchor{Generic function sb-gray stream-read-line}
+@ffindex @sortas{stream-read-line sb-gray} stream-read-line [sb-gray]
+@deffn{Generic function} sb-gray:stream-read-line stream
+This is used by @code{read-line}. A string is returned as the first value. The
+second value is true if the string was terminated by end-of-file
+instead of the end of a line. The default method uses repeated
+calls to @code{stream-read-char}.
+@end deffn
+@anchor{Generic function sb-gray stream-listen}
+@ffindex @sortas{stream-listen sb-gray} stream-listen [sb-gray]
+@deffn{Generic function} sb-gray:stream-listen stream
+This is used by @code{listen}. It returns true or false. The default method uses
+@code{stream-read-char-no-hang} and @code{stream-unread-char}. Most streams should
+define their own method since it will usually be trivial and will
+always be more efficient than the default method.
+@end deffn
+@anchor{Generic function sb-gray stream-unread-char}
+@ffindex @sortas{stream-unread-char sb-gray} stream-unread-char [sb-gray]
+@deffn{Generic function} sb-gray:stream-unread-char stream character
+Undo the last call to @code{stream-read-char}, as in @code{unread-char}.
+Return @code{nil}. Every subclass of @code{fundamental-character-input-stream}
+must define a method for this function.
+@end deffn
+@node output stream methods
@subsection Output stream methods
These generic functions are used to implement subclasses of
-fundamental-output-stream:
+@code{sb-gray:fundamental-output-stream}:
-@include fun-sb-gray-stream-clear-output.texinfo
-@include fun-sb-gray-stream-finish-output.texinfo
-@include fun-sb-gray-stream-force-output.texinfo
-@include fun-sb-gray-stream-write-sequence.texinfo
-
-@node Character output stream methods
+@anchor{Generic function sb-gray stream-clear-output}
+@ffindex @sortas{stream-clear-output sb-gray} stream-clear-output [sb-gray]
+@deffn{Generic function} sb-gray:stream-clear-output stream
+This is like @code{cl:clear-output}, but for Gray streams: clear the given
+output @code{stream}. The default method does nothing.
+@end deffn
+@anchor{Generic function sb-gray stream-finish-output}
+@ffindex @sortas{stream-finish-output sb-gray} stream-finish-output [sb-gray]
+@deffn{Generic function} sb-gray:stream-finish-output stream
+Attempts to ensure that all output sent to the Stream has reached
+its destination, and only then returns false. Implements
+@code{finish-output}. The default method does nothing.
+@end deffn
+@anchor{Generic function sb-gray stream-force-output}
+@ffindex @sortas{stream-force-output sb-gray} stream-force-output [sb-gray]
+@deffn{Generic function} sb-gray:stream-force-output stream
+Attempts to force any buffered output to be sent. Implements
+@code{force-output}. The default method does nothing.
+@end deffn
+@anchor{Generic function sb-gray stream-write-sequence}
+@ffindex @sortas{stream-write-sequence sb-gray} stream-write-sequence [sb-gray]
+@deffn{Generic function} sb-gray:stream-write-sequence stream seq &optional start end
+This is like @code{cl:write-sequence}, but for Gray streams.
+@end deffn
+@node character output stream methods
@subsection Character output stream methods
These generic functions are used to implement subclasses of
-fundamental-character-output-stream:
+@code{sb-gray:fundamental-character-output-stream}:
-@include fun-sb-gray-stream-advance-to-column.texinfo
-@include fun-sb-gray-stream-fresh-line.texinfo
-@include fun-sb-gray-stream-line-column.texinfo
-@include fun-sb-gray-stream-line-length.texinfo
-@include fun-sb-gray-stream-start-line-p.texinfo
-@include fun-sb-gray-stream-terpri.texinfo
-@include fun-sb-gray-stream-write-char.texinfo
-@include fun-sb-gray-stream-write-string.texinfo
-
-@node Binary stream methods
+@anchor{Generic function sb-gray stream-advance-to-column}
+@ffindex @sortas{stream-advance-to-column sb-gray} stream-advance-to-column [sb-gray]
+@deffn{Generic function} sb-gray:stream-advance-to-column stream column
+Write enough blank space so that the next character will be
+written at the specified column. Returns true if the operation is
+successful, or @code{nil} if it is not supported for this stream. This is
+intended for use by by @code{pprint} and @code{format} ~T. The default method
+uses @code{stream-line-column} and repeated calls to @code{stream-write-char}
+with a #SPACE character; it returns @code{nil} if @code{stream-line-column}
+returns @code{nil}.
+@end deffn
+@anchor{Generic function sb-gray stream-fresh-line}
+@ffindex @sortas{stream-fresh-line sb-gray} stream-fresh-line [sb-gray]
+@deffn{Generic function} sb-gray:stream-fresh-line stream
+Outputs a new line to the Stream if it is not positioned at the
+beginning of a line. Returns @code{t} if it output a new line, nil
+otherwise. Used by @code{fresh-line}. The default method uses
+@code{stream-start-line-p} and @code{stream-terpri}.
+@end deffn
+@anchor{Generic function sb-gray stream-line-column}
+@ffindex @sortas{stream-line-column sb-gray} stream-line-column [sb-gray]
+@deffn{Generic function} sb-gray:stream-line-column stream
+Return the column number where the next character
+will be written, or @code{nil} if that is not meaningful for this stream.
+The first column on a line is numbered 0. This function is used in
+the implementation of @code{pprint} and the @code{format} ~T directive. For every
+character output stream class that is defined, a method must be
+defined for this function, although it is permissible for it to
+always return @code{nil}.
+@end deffn
+@anchor{Generic function sb-gray stream-line-length}
+@ffindex @sortas{stream-line-length sb-gray} stream-line-length [sb-gray]
+@deffn{Generic function} sb-gray:stream-line-length stream
+Return the stream line length or @code{nil}.
+@end deffn
+@anchor{Generic function sb-gray stream-start-line-p}
+@ffindex @sortas{stream-start-line-p sb-gray} stream-start-line-p [sb-gray]
+@deffn{Generic function} sb-gray:stream-start-line-p stream
+Is @code{stream} known to be positioned at the beginning of a line?
+It is permissible for an implementation to always return
+@code{nil}. This is used in the implementation of @code{fresh-line}. Note that
+while a value of 0 from @code{stream-line-column} also indicates the
+beginning of a line, there are cases where @code{stream-start-line-p} can be
+meaningfully implemented although @code{stream-line-column} can't be. For
+example, for a window using variable-width characters, the column
+number isn't very meaningful, but the beginning of the line does have
+a clear meaning. The default method for @code{stream-start-line-p} on class
+@code{fundamental-character-output-stream} uses @code{stream-line-column}, so if
+that is defined to return @code{nil}, then a method should be provided for
+either @code{stream-start-line-p} or @code{stream-fresh-line}.
+@end deffn
+@anchor{Generic function sb-gray stream-terpri}
+@ffindex @sortas{stream-terpri sb-gray} stream-terpri [sb-gray]
+@deffn{Generic function} sb-gray:stream-terpri stream
+Writes an end of line, as for @code{terpri}. Returns @code{nil}. The default
+method does (@code{stream-write-char} stream @code{#\Newline}).
+@end deffn
+@anchor{Generic function sb-gray stream-write-char}
+@ffindex @sortas{stream-write-char sb-gray} stream-write-char [sb-gray]
+@deffn{Generic function} sb-gray:stream-write-char stream character
+Write @code{character} to @code{stream} and return @code{character}. Every
+subclass of @code{fundamental-character-output-stream} must have a method
+defined for this function.
+@end deffn
+@anchor{Generic function sb-gray stream-write-string}
+@ffindex @sortas{stream-write-string sb-gray} stream-write-string [sb-gray]
+@deffn{Generic function} sb-gray:stream-write-string stream string &optional start end
+This is used by @code{write-string}. It writes the string to the stream,
+optionally delimited by start and end, which default to 0 and @code{nil}.
+The string argument is returned. The default method provided by
+@code{fundamental-character-output-stream} uses repeated calls to
+@code{stream-write-char}.
+@end deffn
+@node binary stream methods
@subsection Binary stream methods
The following generic functions are available for subclasses of
-fundamental-binary-stream:
+@code{sb-gray:fundamental-binary-stream}:
-@include fun-sb-gray-stream-read-byte.texinfo
-@include fun-sb-gray-stream-write-byte.texinfo
+@anchor{Generic function sb-gray stream-read-byte}
+@ffindex @sortas{stream-read-byte sb-gray} stream-read-byte [sb-gray]
+@deffn{Generic function} sb-gray:stream-read-byte stream
+Used by @code{read-byte}; returns either an integer, or the symbol @code{:eof}
+if the stream is at end-of-file.
+@end deffn
+@anchor{Generic function sb-gray stream-write-byte}
+@ffindex @sortas{stream-write-byte sb-gray} stream-write-byte [sb-gray]
+@deffn{Generic function} sb-gray:stream-write-byte stream integer
+Implements @code{write-byte}; writes the integer to the stream and
+returns the integer as the result.
+@end deffn
+@node gray streams examples
+@subsection Gray Streams Examples
-@include gray-streams-examples.texinfo
+@menu
+* Character Counting Input Stream: character counting input stream.
+* Output Prefixing Character Stream: output prefixing character stream.
+@end menu
-@node Simple Streams
-@comment node-name, next, previous, up
-@section Simple Streams
-@include sb-simple-streams/sb-simple-streams.texinfo
+Below are two classes of stream that can be conveniently defined as
+wrappers for Common Lisp streams. These are meant to serve as
+examples of minimal implementations of the protocols that must be
+followed when defining Gray streams. Realistic uses of the Gray
+Streams API would implement the various methods that can do I/O in
+batches, such as @code{sb-gray:stream-read-line},
+@code{sb-gray:stream-write-string}, @code{sb-gray:stream-read-sequence}, and
+@code{sb-gray:stream-write-sequence}.
+
+@node character counting input stream
+@subsubsection Character Counting Input Stream
+
+ It is occasionally handy for programs that process input files to
+count the number of characters and lines seen so far, and the number
+of characters seen on the current line, so that useful messages may
+be reported in case of parsing errors, etc. Here is a character
+input stream class that keeps track of these counts. Note that all
+character input streams must implement @code{sb-gray:stream-read-char} and
+@code{sb-gray:stream-unread-char}.
+
+@example
+(defclass wrapped-stream (fundamental-stream)
+ ((stream :initarg :stream :reader stream-of)))
+
+(defmethod stream-element-type ((stream wrapped-stream))
+ (stream-element-type (stream-of stream)))
+
+(defmethod close ((stream wrapped-stream) &key abort)
+ (close (stream-of stream) :abort abort))
+
+(defclass wrapped-character-input-stream
+ (wrapped-stream fundamental-character-input-stream)
+ ())
+
+(defmethod stream-read-char ((stream wrapped-character-input-stream))
+ (read-char (stream-of stream) nil :eof))
+
+(defmethod stream-unread-char ((stream wrapped-character-input-stream)
+ char)
+ (unread-char char (stream-of stream)))
+
+(defclass counting-character-input-stream
+ (wrapped-character-input-stream)
+ ((char-count :initform 1 :accessor char-count-of)
+ (line-count :initform 1 :accessor line-count-of)
+ (col-count :initform 1 :accessor col-count-of)
+ (prev-col-count :initform 1 :accessor prev-col-count-of)))
+
+(defmethod stream-read-char ((stream counting-character-input-stream))
+ (with-accessors ((inner-stream stream-of) (chars char-count-of)
+ (lines line-count-of) (cols col-count-of)
+ (prev prev-col-count-of)) stream
+ (let ((char (call-next-method)))
+ (cond ((eql char :eof)
+ :eof)
+ ((char= char #Newline)
+ (incf lines)
+ (incf chars)
+ (setf prev cols)
+ (setf cols 1)
+ char)
+ (t
+ (incf chars)
+ (incf cols)
+ char)))))
+
+(defmethod stream-unread-char ((stream counting-character-input-stream)
+ char)
+ (with-accessors ((inner-stream stream-of) (chars char-count-of)
+ (lines line-count-of) (cols col-count-of)
+ (prev prev-col-count-of)) stream
+ (cond ((char= char #Newline)
+ (decf lines)
+ (decf chars)
+ (setf cols prev))
+ (t
+ (decf chars)
+ (decf cols)
+ char))
+ (call-next-method)))
+@end example
+
+The default methods for @code{sb-gray:stream-read-char-no-hang},
+@code{sb-gray:stream-peek-char}, @code{sb-gray:stream-listen},
+@code{sb-gray:stream-clear-input}, @code{sb-gray:stream-read-line}, and
+@code{sb-gray:stream-read-sequence} should be sufficient (though the last
+two will probably be slower than methods that forwarded directly).
+
+Here's a sample use of this class:
+
+@example
+(with-input-from-string (input "1 2
+ 3 :foo ")
+ (let ((counted-stream (make-instance 'counting-character-input-stream
+ :stream input)))
+ (loop for thing = (read counted-stream) while thing
+ unless (numberp thing) do
+ (error "Non-number ~S (line ~D, column ~D)" thing
+ (line-count-of counted-stream)
+ (- (col-count-of counted-stream)
+ (length (format nil "~S" thing))))
+ end
+ do (print thing))))
+@end example
+
+Output:
+
+@example
+1
+2
+3
+Non-number :FOO (line 2, column 5)
+ [Condition of type SIMPLE-ERROR]
+@end example
+
+@node output prefixing character stream
+@subsubsection Output Prefixing Character Stream
+
+One use for a wrapped output stream might be to prefix each line of
+text with a timestamp, e.g. for a logging stream. Here's a simple
+stream that does this, though without any fancy line-wrapping. Note
+that all character output stream classes must implement
+@code{sb-gray:stream-write-char} and @code{sb-gray:stream-line-column}.
+
+@example
+(defclass wrapped-stream (fundamental-stream)
+ ((stream :initarg :stream :reader stream-of)))
+
+(defmethod stream-element-type ((stream wrapped-stream))
+ (stream-element-type (stream-of stream)))
+
+(defmethod close ((stream wrapped-stream) &key abort)
+ (close (stream-of stream) :abort abort))
+
+(defclass wrapped-character-output-stream
+ (wrapped-stream fundamental-character-output-stream)
+ ((col-index :initform 0 :accessor col-index-of)))
+
+(defmethod stream-line-column ((stream wrapped-character-output-stream))
+ (col-index-of stream))
+
+(defmethod stream-write-char ((stream wrapped-character-output-stream)
+ char)
+ (with-accessors ((inner-stream stream-of) (cols col-index-of)) stream
+ (write-char char inner-stream)
+ (if (char= char #Newline)
+ (setf cols 0)
+ (incf cols))))
+
+(defclass prefixed-character-output-stream
+ (wrapped-character-output-stream)
+ ((prefix :initarg :prefix :reader prefix-of)))
+
+(defgeneric write-prefix (prefix stream)
+ (:method ((prefix string) stream) (write-string prefix stream))
+ (:method ((prefix function) stream) (funcall prefix stream)))
+
+(defmethod stream-write-char ((stream prefixed-character-output-stream)
+ char)
+ (with-accessors ((inner-stream stream-of) (cols col-index-of)
+ (prefix prefix-of)) stream
+ (when (zerop cols)
+ (write-prefix prefix inner-stream))
+ (call-next-method)))
+@end example
+
+As with the example input stream, this implements only the minimal
+protocol. A production implementation should also provide methods
+for at least @code{sb-gray:stream-write-string},
+@code{sb-gray:stream-write-sequence}.
+
+And here's a sample use of this class:
+
+@example
+(flet ((format-timestamp (stream)
+ (apply #'format stream "[~2@@*~2,' D:~1@@*~2,'0D:~0@@*~2,'0D] "
+ (multiple-value-list (get-decoded-time)))))
+ (let ((output (make-instance 'prefixed-character-output-stream
+ :stream *standard-output*
+ :prefix #'format-timestamp)))
+ (loop for string in '("abc" "def" ")ghi") do
+ (write-line string output)
+ (sleep 1))))
+@end example
+
+Output:
+
+@example
+[ 0:30:05] abc
+[ 0:30:06] def
+[ 0:30:07] ghi
+NIL
+@end example
+
+@include ../../contrib/sb-simple-streams/sb-simple-streams.texinfo
diff --git a/doc/manual/support-and-bugs.texinfo b/doc/manual/support-and-bugs.texinfo
index 67a09085f..528b39330 100644
--- a/doc/manual/support-and-bugs.texinfo
+++ b/doc/manual/support-and-bugs.texinfo
@@ -1,23 +1,23 @@
-@node Getting Support and Reporting Bugs
-@comment node-name, next, previous, up
+@c Generated by the sb-manual contrib. Do not edit.
+
+@node support and bugs
@chapter Getting Support and Reporting Bugs
@menu
-* Volunteer Support::
-* Commercial Support::
-* Reporting Bugs::
+* Volunteer Support: volunteer support.
+* Commercial Support: commercial support.
+* Reporting Bugs: reporting bugs.
@end menu
-@node Volunteer Support
-@comment node-name, next, previous, up
+@node volunteer support
@section Volunteer Support
Your primary source of SBCL support should probably be the mailing
-list @strong{sbcl-help}: in addition to other users SBCL developers
-monitor this list and are available for advice. As an anti-spam
-measure subscription is required for posting:
+list @code{sbcl-help}: in addition to other users SBCL developers monitor
+this list and are available for advice. As an anti-spam measure
+subscription is required for posting:
-@urlline{https://lists.sourceforge.net/lists/listinfo/sbcl-help}
+@url{https://lists.sourceforge.net/lists/listinfo/sbcl-help}
Remember that the people answering your question are volunteers, so
you stand a much better chance of getting a good answer if you ask a
@@ -25,22 +25,21 @@ good question.
Before sending mail, check the list archives at either
-@urlline{http://sourceforge.net/mailarchive/forum.php?forum_name=sbcl-help}
+@url{http://sourceforge.net/mailarchive/forum.php?forum_name=sbcl-help}
or
-@urlline{http://news.gmane.org/gmane.lisp.steel-bank.general}
+@url{http://news.gmane.org/gmane.lisp.steel-bank.general}
to see if your question has been answered already. Checking the bug
-database is also worth it @xref{Reporting Bugs}, to see if the issue
+database is also worth it (see @ref{reporting bugs}), to see if the issue
is already known.
For general advice on asking good questions, see
-@urlline{http://www.catb.org/~esr/faqs/smart-questions.html}.
+@url{http://www.catb.org/~esr/faqs/smart-questions.html}.
-@node Commercial Support
-@comment node-name, next, previous, up
+@node commercial support
@section Commercial Support
There is no formal organization developing SBCL, but if you need a
@@ -49,31 +48,36 @@ list of companies and consultants below. Use it to identify service
providers with appropriate skills and interests, and contact them
directly.
-The SBCL project cannot verify the accuracy of the information or the
-competence of the people listed, and they have provided their own
-blurbs below: you must make your own judgement of suitability from the
-available information - refer to the links they provide, the CREDITS
-file, mailing list archives, CVS commit messages, and so on. Please
-feel free to ask for advice on the sbcl-help list.
+The SBCL project cannot verify the accuracy of the information or
+the competence of the people listed, and they have provided their
+own blurbs below: you must make your own judgement of suitability
+from the available information - refer to the links they provide,
+the CREDITS file, mailing list archives, CVS commit messages, and so
+on. Please feel free to ask for advice on the sbcl-help list.
-(At present, no companies or consultants wish to advertise paid support
-or custom SBCL development in this manual).
+(At present, no companies or consultants wish to advertise paid
+support or custom SBCL development in this manual).
-@node Reporting Bugs
-@comment node-name, next, previous, up
+@node reporting bugs
@section Reporting Bugs
+@menu
+* How to Report Bugs Effectively: how to report bugs effectively.
+* How to Report Signal-related Bugs: how to report signal related bugs.
+@end menu
+
SBCL uses Launchpad to track bugs. The bug database is available at
-@urlline{https://bugs.launchpad.net/sbcl}
+@url{https://bugs.launchpad.net/sbcl}
-Reporting bugs there requires registering at Launchpad. However, bugs
-can also be reported on the mailing list @strong{sbcl-bugs}, which is
-moderated but does @emph{not} require subscribing.
+Reporting bugs there requires registering at Launchpad. However,
+bugs can also be reported on the mailing list @code{sbcl-bugs},
+which is moderated but does @emph{not} require subscribing.
-Simply send email to @email{sbcl-bugs@@lists.sourceforge.net} and the
-bug will be checked and added to Launchpad by SBCL maintainers.
+Simply send email to @code{sbcl-bugs@@lists.sourceforge.net} and the bug
+will be checked and added to Launchpad by SBCL maintainers.
+@node how to report bugs effectively
@subsection How to Report Bugs Effectively
Please include enough information in a bug report that someone reading
@@ -99,52 +103,43 @@ then at the command line type
the program loops endlessly instead of printing the object.
@end example
-A more in-depth discussion on reporting bugs effectively can be found
-at
+A more in-depth discussion on reporting bugs effectively can be
+found at
-@urlline{http://www.chiark.greenend.org.uk/~sgtatham/bugs.html}.
+@url{http://www.chiark.greenend.org.uk/~sgtatham/bugs.html}.
-@subsection Signal Related Bugs
+@node how to report signal related bugs
+@subsection How to Report Signal-related Bugs
If you run into a signal related bug, you are getting fatal errors
such as @code{signal N is [un]blocked} or just hangs, and you want to
send a useful bug report then:
-@enumerate
+@itemize
+@item Compile SBCL with ldb enabled (feature @code{:sb-ldb}, see
+ @code{base-target-features.lisp-expr}).
-@item
-@cindex ldb
-Compile SBCL with ldb enabled (feature @code{:sb-ldb}, see
-@file{base-target-features.lisp-expr}).
+@item Isolate a smallish test case, run it.
-@item
-Isolate a smallish test case, run it.
+@item If it just hangs kill it with @code{sigabrt}: @code{kill -ABRT <pidof sbcl>}.
-@item
-If it just hangs kill it with sigabrt: @code{kill -ABRT <pidof sbcl>}.
+@item Print the backtrace from ldb by typing @code{ba}.
-@item
-Print the backtrace from ldb by typing @code{ba}.
+@item Attach gdb: @code{gdb -p <pidof sbcl>} and get backtraces for all
+ threads: @code{thread apply all ba}.
-@item
-Attach gdb: @code{gdb -p <pidof sbcl>} and get backtraces for all threads:
-@code{thread apply all ba}.
+@item If multiple threads are in play then still in gdb, try to get Lisp
+ backtrace for all threads: @code{thread apply all call
+ backtrace_from_fp($ebp, 100, 0)}. Substitute @code{$ebp} with @code{$rbp} on
+ x86-64. The backtraces will appear in the stdout of the SBCL
+ process.
-@item
-If multiple threads are in play then still in gdb, try to get Lisp
-backtrace for all threads: @code{thread apply all call
-backtrace_from_fp($ebp, 100, 0)}. Substitute @code{$ebp} with @code{$rbp}
-on x86-64. The backtraces will appear in the stdout of the SBCL
-process.
+@item Send a report with the backtraces and the output (both stdout and
+ stderr) produced by SBCL.
-@item
-Send a report with the backtraces and the output (both stdout and
-stderr) produced by SBCL.
+@item Don't forget to include OS and SBCL version.
-@item
-Don't forget to include OS and SBCL version.
+@item If available, include information on outcome of the same test with
+ other versions of SBCL, OS, ...
+@end itemize
-@item
-If available, include information on outcome of the same test with
-other versions of SBCL, OS, ...
-@end enumerate
diff --git a/doc/manual/threading.texinfo b/doc/manual/threading.texinfo
index 621c4fa39..59a213575 100644
--- a/doc/manual/threading.texinfo
+++ b/doc/manual/threading.texinfo
@@ -1,80 +1,346 @@
-@node Threading
-@comment node-name, next, previous, up
+@c Generated by the sb-manual contrib. Do not edit.
+
+@node threading
@chapter Threading
+@menu
+* Threading Basics: threading basics.
+* Special Variables: special variables.
+* Atomic Operations: atomic operations.
+* Mutex Support: mutex support.
+* Semaphores: semaphores.
+* Waitqueue/condition variables: waitqueue/condition variables.
+* Barriers: barriers.
+* Sessions/Debugging: sessions/debugging.
+* Foreign threads: foreign threads.
+* Implementation on Linux x86oids: implementation on linux x86oids.
+@end menu
+
SBCL supports a fairly low-level threading interface that maps onto
the host operating system's concept of threads or lightweight
-processes. This means that threads may take advantage of hardware
+processes. This means that threads may take advantage of hardware
multiprocessing on machines that have more than one CPU, but it does
-not allow Lisp control of the scheduler. This is found in the
-SB-THREAD package.
+not allow Lisp control of the scheduler. This is found in the
+@code{sb-thread} package.
-Threads are part of the default build on x86[-64]/ARM64 Linux and Windows.
+Threads are part of the default build on x86[-64]/ARM64 Linux and
+Windows.
They are also supported on: x86[-64] Darwin (Mac OS X), x86[-64]
-FreeBSD, x86 SunOS (Solaris), PPC Linux, ARM64 Linux, RISC-V Linux. On
-these platforms threads must be explicitly enabled at build-time, see
-@file{INSTALL} for directions.
+FreeBSD, x86 SunOS (Solaris), PPC Linux, ARM64 Linux, RISC-V Linux.
+On these platforms threads must be explicitly enabled at build-time,
+see @code{install} for directions.
+
+@node threading basics
+@section Threading Basics
@menu
-* Threading basics::
-* Special Variables::
-* Atomic Operations::
-* Mutex Support::
-* Semaphores::
-* Waitqueue/condition variables::
-* Barriers::
-* Sessions/Debugging::
-* Foreign threads::
-* Implementation (Linux x86/x86-64)::
+* Thread Objects: thread objects.
+* Running Threads: running threads.
+* Asynchronous Operations: asynchronous operations.
+* Miscellaneous Operations: miscellaneous operations.
+* Error Conditions: error conditions.
@end menu
-@node Threading basics
-@comment node-name, next, previous, up
-@section Threading basics
-
-@lisp
+@example
(make-thread (lambda () (write-line "Hello, world")))
-@end lisp
+@end example
+@node thread objects
@subsection Thread Objects
-@include struct-sb-thread-thread.texinfo
-@include var-sb-thread-star-current-thread-star.texinfo
-@include fun-sb-thread-list-all-threads.texinfo
-@include fun-sb-thread-thread-alive-p.texinfo
-@include fun-sb-thread-thread-name.texinfo
-@include fun-sb-thread-main-thread-p.texinfo
-@include fun-sb-thread-main-thread.texinfo
-
-@subsection Making, Returning From, Joining, and Yielding Threads
-
-@include fun-sb-thread-make-thread.texinfo
-@include macro-sb-thread-return-from-thread.texinfo
-@include fun-sb-thread-abort-thread.texinfo
-@include fun-sb-thread-join-thread.texinfo
-@include fun-sb-thread-thread-yield.texinfo
+@anchor{Structure sb-thread thread}
+@ttindex @sortas{thread sb-thread} thread [sb-thread]
+@deffn{Structure} sb-thread:thread
+Thread type. Do not rely on threads being structs as it may change
+in future versions.
+@end deffn
+@anchor{Variable sb-thread *current-thread*}
+@vvindex @sortas{current-thread* sb-thread} *current-thread* [sb-thread]
+@deffn{Variable} sb-thread:*current-thread*
+Bound in each thread to the thread itself.
+@end deffn
+@anchor{Function sb-thread list-all-threads}
+@ffindex @sortas{list-all-threads sb-thread} list-all-threads [sb-thread]
+@deffn{Function} sb-thread:list-all-threads
+Return a list of the live threads. Note that the return value is
+potentially stale even before the function returns, as new threads may be
+created and old ones may exit at any time.
+@end deffn
+@anchor{Function sb-thread thread-alive-p}
+@ffindex @sortas{thread-alive-p sb-thread} thread-alive-p [sb-thread]
+@deffn{Function} sb-thread:thread-alive-p thread
+Return @code{t} if @code{thread} is still alive. Note that the return value is
+potentially stale even before the function returns, as the thread may exit at
+any time.
+@end deffn
+@anchor{Function sb-thread thread-name}
+@ffindex @sortas{thread-name sb-thread} thread-name [sb-thread]
+@deffn{Function} sb-thread:thread-name thread
+Name of the thread. Can be assigned to using @code{setf}. A thread name must be
+a simple-string (not necessarily unique) or @code{nil}.
+@end deffn
+@anchor{Function sb-thread main-thread-p}
+@ffindex @sortas{main-thread-p sb-thread} main-thread-p [sb-thread]
+@deffn{Function} sb-thread:main-thread-p &optional thread
+True if @code{thread}, defaulting to current thread, is the main thread of the process.
+@end deffn
+@anchor{Function sb-thread main-thread}
+@ffindex @sortas{main-thread sb-thread} main-thread [sb-thread]
+@deffn{Function} sb-thread:main-thread
+Returns the main thread of the process.
+@end deffn
+@node running threads
+@subsection Running Threads
+@anchor{Function sb-thread make-thread}
+@ffindex @sortas{make-thread sb-thread} make-thread [sb-thread]
+@deffn{Function} sb-thread:make-thread function &key name arguments
+Create a new thread of @code{name} that runs @code{function} with the argument
+list designator provided (defaults to no argument). Thread exits when
+the function returns. The return values of @code{function} are kept around
+and can be retrieved by @code{join-thread}.
+
+Invoking the initial @code{abort} restart established by @code{make-thread}
+terminates the thread.
+@end deffn
+@anchor{Macro sb-thread return-from-thread}
+@ffindex @sortas{return-from-thread sb-thread} return-from-thread [sb-thread]
+@deffn{Macro} sb-thread:return-from-thread values-form &key allow-exit
+Unwinds from and terminates the current thread, with values from
+@code{values-form} as the results visible to @code{join-thread}.
+
+If current thread is the main thread of the process (see
+@code{main-thread-p}), signals an error unless @code{allow-exit} is true, as
+terminating the main thread would terminate the entire process. If
+@code{allow-exit} is true, returning from the main thread is equivalent to
+calling @code{sb-ext:exit} with @code{:code} 0 and @code{:abort} @code{nil}.
+@end deffn
+@anchor{Function sb-thread abort-thread}
+@ffindex @sortas{abort-thread sb-thread} abort-thread [sb-thread]
+@deffn{Function} sb-thread:abort-thread &key allow-exit
+Unwinds from and terminates the current thread abnormally, causing
+@code{join-thread} on current thread to signal an error unless a
+default-value is provided.
+
+If current thread is the main thread of the process (see
+@code{main-thread-p}), signals an error unless @code{allow-exit} is true, as
+terminating the main thread would terminate the entire process. If
+@code{allow-exit} is true, aborting the main thread is equivalent to calling
+@code{sb-ext:exit} code 1 and @code{:abort} @code{nil}.
+
+Invoking the initial @code{abort} restart established by @code{make-thread} is
+equivalent to calling @code{abort-thread} in other than main threads.
+However, whereas @code{abort} restart may be rebound, @code{abort-thread} always
+unwinds the entire thread. (Behaviour of the initial @code{abort} restart for
+main thread depends on the @code{:toplevel} argument to
+@code{sb-ext:save-lisp-and-die}.)
+@end deffn
+@anchor{Function sb-thread join-thread}
+@ffindex @sortas{join-thread sb-thread} join-thread [sb-thread]
+@deffn{Function} sb-thread:join-thread thread &key default timeout
+Suspend current thread until @code{thread} exits. Return the result values
+of the thread function.
+
+If @code{thread} does not exit within @code{timeout} seconds and @code{default} is
+supplied, return two values: 1) @code{default} 2) @code{:timeout}. If @code{default} is not
+supplied, signal a @code{join-thread-error} with @code{join-thread-problem} equal
+to @code{:timeout}.
+
+If @code{thread} does not exit normally (i.e. aborted) and @code{default} is
+supplied, return two values: 1) @code{default} 2) @code{:abort}. If @code{default} is not
+supplied, signal a @code{join-thread-error} with @code{join-thread-problem} equal
+to @code{:abort}.
+
+If @code{thread} is the current thread, signal a @code{join-thread-error} with
+@code{join-thread-problem} equal to @code{:self-join}.
+
+Trying to join the main thread causes @code{join-thread} to block until
+@code{timeout} occurs or the process exits: when the main thread exits, the
+entire process exits.
+
+Users should not rely on the ability to join a chosen @code{thread} from more
+than one other thread simultaneously. Future changes to @code{join-thread} may
+directly call the underlying thread library, and not all threading
+implementations consider such usage to be well-defined.
+
+@quotation
+@emph{Note}: Return convention in case of a timeout is experimental and
+subject to change.
+@end quotation
+@end deffn
+@anchor{Function sb-thread thread-yield}
+@ffindex @sortas{thread-yield sb-thread} thread-yield [sb-thread]
+@deffn{Function} sb-thread:thread-yield
+Yield the processor to other threads.
+@end deffn
+@node asynchronous operations
@subsection Asynchronous Operations
-@include fun-sb-thread-interrupt-thread.texinfo
-@include fun-sb-thread-terminate-thread.texinfo
+@anchor{Function sb-thread interrupt-thread}
+@ffindex @sortas{interrupt-thread sb-thread} interrupt-thread [sb-thread]
+@deffn{Function} sb-thread:interrupt-thread thread function
+Interrupt @code{thread} and make it run @code{function}.
+The interrupt is asynchronous, and can occur anywhere with the exception of
+sections protected using @code{sb-sys:without-interrupts}.
+
+@code{function} is called with interrupts disabled, under
+@code{sb-sys:allow-with-interrupts}. Since functions such as @code{grab-mutex} may try to
+enable interrupts internally, in most cases @code{function} should either enter
+@code{sb-sys:with-interrupts} to allow nested interrupts, or
+@code{sb-sys:without-interrupts} to prevent them completely.
+
+When a thread receives multiple interrupts, they are executed in the order
+they were sent -- first in, first out.
+
+This means that a great degree of care is required to use @code{interrupt-thread}
+safely and sanely in a production environment. The general recommendation is
+to limit uses of @code{interrupt-thread} for interactive debugging, banning it
+entirely from production environments -- it is simply exceedingly hard to use
+correctly.
+
+With those caveats in mind, what you need to know when using it:
+
+@itemize
+@item If calling @code{function} causes a non-local transfer of control (ie. an
+ unwind), all normal cleanup forms will be executed.
+
+However, if the interrupt occurs during cleanup forms of an
+@code{unwind-protect}, it is just as if that had happened due to a
+regular @code{go}, @code{throw}, or @code{return-from}: the interrupted cleanup form
+and those following it in the same @code{unwind-protect} do not get
+executed.
+
+SBCL tries to keep its own internals asynch-unwind-safe, but this
+is frankly an unreasonable expectation for third party libraries,
+especially given that asynch-unwind-safety does not compose: a
+function calling only asynch-unwind-safe function isn't
+automatically asynch-unwind-safe.
+
+This means that in order for an asynch unwind to be safe, the
+entire callstack at the point of interruption needs to be
+asynch-unwind-safe.
+
+@item In addition to asynch-unwind-safety you must consider the issue of
+ reentrancy. @code{interrupt-thread} can cause function that are never
+ normally called recursively to be re-entered during their dynamic
+ contour, which may cause them to misbehave. (Consider binding of
+ special variables, values of global variables, etc.)
+@end itemize
+
+Taken together, these two restrict the "safe" things to do using
+@code{interrupt-thread} to a fairly minimal set. One useful one -- exclusively for
+interactive development use is using it to force entry to debugger to inspect
+the state of a thread:
+
+@example
+(interrupt-thread thread #'break)
+@end example
+
+Short version: be careful out there.
+@end deffn
+@anchor{Function sb-thread terminate-thread}
+@ffindex @sortas{terminate-thread sb-thread} terminate-thread [sb-thread]
+@deffn{Function} sb-thread:terminate-thread thread
+Terminate the thread identified by @code{thread}, by interrupting it and
+causing it to call @code{sb-thread:abort-thread} with @code{:allow-exit} @code{t}.
+
+The unwind caused by @code{terminate-thread} is asynchronous, meaning that
+eg. thread executing
+
+@example
+(let (foo)
+ (unwind-protect
+ (progn
+ (setf foo (get-foo))
+ (work-on-foo foo))
+ (when foo
+ ;; An interrupt occurring inside the cleanup clause
+ ;; will cause cleanups from the current UNWIND-PROTECT
+ ;; to be dropped.
+ (release-foo foo))))
+@end example
+
+might miss calling @code{release-foo} despite GET-FOO having returned true
+if the interrupt occurs inside the cleanup clause, eg. during
+execution of @code{release-foo}.
+
+Thus, in order to write an asynch unwind safe @code{unwind-protect} you need
+to use @code{without-interrupts}:
+
+@example
+(let (foo)
+ (sb-sys:without-interrupts
+ (unwind-protect
+ (progn
+ (setf foo (sb-sys:allow-with-interrupts
+ (get-foo)))
+ (sb-sys:with-local-interrupts
+ (work-on-foo foo)))
+ (when foo
+ (release-foo foo)))))
+@end example
+
+Since most libraries using @code{unwind-protect} do not do this, you should never
+assume that unknown code can safely be terminated using @code{terminate-thread}.
+@end deffn
+@node miscellaneous operations
@subsection Miscellaneous Operations
-@include fun-sb-thread-symbol-value-in-thread.texinfo
+@anchor{Function sb-thread symbol-value-in-thread}
+@ffindex @sortas{symbol-value-in-thread sb-thread} symbol-value-in-thread [sb-thread]
+@deffn{Function} sb-thread:symbol-value-in-thread symbol thread &optional errorp
+Return the local value of @code{symbol} in @code{thread}, and a secondary value of @code{t}
+on success.
+If the value cannot be retrieved (because the thread has exited or because it
+has no local binding for @code{name}) and @code{errorp} is true signals an error of type
+@code{symbol-value-in-thread-error}; if @code{errorp} is false returns a primary value of
+@code{nil}, and a secondary value of @code{nil}.
+
+Can also be used with @code{setf} to change the thread-local value of @code{symbol}.
+
+@code{symbol-value-in-thread} is primarily intended as a debugging tool, and not as a
+mechanism for inter-thread communication.
+@end deffn
+@node error conditions
@subsection Error Conditions
-@include condition-sb-thread-thread-error.texinfo
-@include fun-sb-thread-thread-error-thread.texinfo
-
-@c @include condition-sb-thread-symbol-value-in-thread-error.texinfo
-@include condition-sb-thread-interrupt-thread-error.texinfo
-@include condition-sb-thread-join-thread-error.texinfo
-
-@node Special Variables
-@comment node-name, next, previous, up
+@anchor{Condition sb-thread thread-error}
+@ttindex @sortas{thread-error sb-thread} thread-error [sb-thread]
+@deffn{Condition} sb-thread:thread-error
+Conditions of type @code{thread-error} are signalled when thread operations fail.
+The offending thread is initialized by the @code{:thread} initialization argument and
+read by the function @code{thread-error-thread}.
+@end deffn
+@anchor{Function sb-thread thread-error-thread}
+@ffindex @sortas{thread-error-thread sb-thread} thread-error-thread [sb-thread]
+@deffn{Function} sb-thread:thread-error-thread condition
+Return the offending thread that the @code{thread-error} pertains to.
+@end deffn
+@anchor{Condition sb-thread symbol-value-in-thread-error}
+@ttindex @sortas{symbol-value-in-thread-error sb-thread} symbol-value-in-thread-error [sb-thread]
+@deffn{Condition} sb-thread:symbol-value-in-thread-error
+Signalled when @code{symbol-value-in-thread} or its @code{setf} version fails due to eg.
+the symbol not having a thread-local value, or the target thread having
+exited. The offending symbol can be accessed using @code{cell-error-name}, and the
+offending thread using @code{thread-error-thread}.
+@end deffn
+@anchor{Condition sb-thread interrupt-thread-error}
+@ttindex @sortas{interrupt-thread-error sb-thread} interrupt-thread-error [sb-thread]
+@deffn{Condition} sb-thread:interrupt-thread-error
+Signalled when interrupting a thread fails because the thread has already
+exited. The offending thread can be accessed using @code{thread-error-thread}.
+@end deffn
+@anchor{Condition sb-thread join-thread-error}
+@ttindex @sortas{join-thread-error sb-thread} join-thread-error [sb-thread]
+@deffn{Condition} sb-thread:join-thread-error
+Signalled when joining a thread fails due to abnormal exit of the thread
+to be joined. The offending thread can be accessed using
+@code{thread-error-thread}.
+@end deffn
+@node special variables
@section Special Variables
The interaction of special variables with multiple threads is mostly
@@ -82,54 +348,260 @@ as one would expect, with behaviour very similar to other
implementations.
@itemize
-@item
-global special values are visible across all threads;
-@item
-bindings (e.g. using LET) are local to the thread;
-@item
-threads do not inherit dynamic bindings from the parent thread
+@item Global special values are visible across all threads.
+
+@item Bindings (e.g. using @code{let}) are local to the thread.
+
+@item Threads do not inherit dynamic bindings from the parent thread.
@end itemize
The last point means that
-@lisp
+@example
(defparameter *x* 0)
(let ((*x* 1))
(sb-thread:make-thread (lambda () (print *x*))))
-@end lisp
+@end example
-prints @code{0} and not @code{1} as of 0.9.6.
+prints @code{0} and not @code{1}.
Note, however, that there is a hard limit on the number of distinct
symbols that can be bound dynamically in threaded builds (see
-@code{--tls-limit} in @ref{Runtime Options}). Exceeding this limit
-triggers the low-level error ``Thread local storage exhausted.''
+@code{--tls-limit} in @ref{runtime options}). Exceeding this limit triggers
+the low-level error @code{Thread local storage exhausted.}
-@node Atomic Operations
-@comment node-name, next, previous, up
+@node atomic operations
@section Atomic Operations
Following atomic operations are particularly useful for implementing
lockless algorithms.
-@include macro-sb-ext-atomic-decf.texinfo
-@include macro-sb-ext-atomic-incf.texinfo
-@include macro-sb-ext-atomic-pop.texinfo
-@include macro-sb-ext-atomic-push.texinfo
-@include macro-sb-ext-atomic-update.texinfo
-@include macro-sb-ext-compare-and-swap.texinfo
+@anchor{Macro sb-ext atomic-decf}
+@ffindex @sortas{atomic-decf sb-ext} atomic-decf [sb-ext]
+@deffn{Macro} sb-ext:atomic-decf place &optional diff
+Atomically decrements @code{place} by @code{diff}, and returns the value of @code{place} before
+the decrement.
-@unnumberedsubsec CAS Protocol
+@code{place} must access one of the following:
-Our @code{compare-and-swap} is user-extensible by defining functions
-named (CAS place), allowing users to add CAS support to new
+@itemize
+@item a @code{defstruct} slot with declared type @code{(unsigned-byte 64)} or @code{aref}
+ of a @code{(simple-array (unsigned-byte 64) (*))} (the type
+ @code{sb-ext:word} can be used for these purposes)
+
+@item @code{car} or @code{cdr} (respectively @code{first} or @code{rest}) of a @code{cons},
+
+@item a variable defined using @code{defglobal} with a proclaimed type of @code{fixnum}.
+@end itemize
+
+Macroexpansion is performed on @code{place} before expanding @code{atomic-decf}.
+
+Decrementing is done using modular arithmetic,
+which is well-defined over two different domains:
+
+@itemize
+@item For structures and arrays, the operation accepts and produces
+ an (@code{unsigned-byte} 64), and @code{diff} must be of type @code{(signed-byte
+ 64)}. @code{atomic-decf} of @code{#x0} by one results in @code{#xFFFFFFFFFFFFFFFF} being stored in
+ @code{place}.
+
+@item For other places, the domain is @code{fixnum}, and @code{diff} must be a @code{fixnum}.
+ @code{atomic-decf} of @code{#x-4000000000000000} by one results in @code{#x3FFFFFFFFFFFFFFF} being stored in
+ @code{place}.
+@end itemize
+
+@code{diff} defaults to 1.
+
+EXPERIMENTAL: Interface subject to change.
+@end deffn
+@anchor{Macro sb-ext atomic-incf}
+@ffindex @sortas{atomic-incf sb-ext} atomic-incf [sb-ext]
+@deffn{Macro} sb-ext:atomic-incf place &optional diff
+Atomically increments @code{place} by @code{diff}, and returns the value of @code{place} before
+the increment.
+
+@code{place} must access one of the following:
+
+@itemize
+@item a @code{defstruct} slot with declared type (@code{unsigned-byte} 64)
+ or @code{aref} of a (@code{simple-array} (@code{unsigned-byte} 64) (*))
+ The type @code{sb-ext:word} can be used for these purposes.
+
+@item @code{car} or @code{cdr} (respectively @code{first} or @code{rest}) of a @code{cons}.
+
+@item a variable defined using @code{defglobal} with a proclaimed type of @code{fixnum}.
+ Macroexpansion is performed on @code{place} before expanding @code{atomic-incf}.
+@end itemize
+
+Incrementing is done using modular arithmetic, which is well-defined
+over two different domains:
+
+@itemize
+@item For structures and arrays, the operation accepts and produces
+ an (@code{unsigned-byte} 64), and @code{diff} must be of type (@code{signed-byte} 64).
+ @code{atomic-incf} of @code{#xFFFFFFFFFFFFFFFF} by one results in #x0 being stored in @code{place}.
+
+@item For other places, the domain is @code{fixnum}, and @code{diff} must be a @code{fixnum}.
+ @code{atomic-incf} of @code{#x3FFFFFFFFFFFFFFF} by one results in @code{#x-4000000000000000}
+ being stored in @code{place}.
+@end itemize
+
+@code{diff} defaults to 1.
+
+EXPERIMENTAL: Interface subject to change.
+@end deffn
+@anchor{Macro sb-ext atomic-pop}
+@ffindex @sortas{atomic-pop sb-ext} atomic-pop [sb-ext]
+@deffn{Macro} sb-ext:atomic-pop place
+Like @code{pop}, but atomic. @code{place} may be read multiple times before
+the operation completes -- the write does not occur until such time
+that no other thread modified @code{place} between the read and the write.
+
+Works on all @code{cas}able places.
+@end deffn
+@anchor{Macro sb-ext atomic-push}
+@ffindex @sortas{atomic-push sb-ext} atomic-push [sb-ext]
+@deffn{Macro} sb-ext:atomic-push obj place
+Like @code{push}, but atomic. @code{place} may be read multiple times before
+the operation completes -- the write does not occur until such time
+that no other thread modified @code{place} between the read and the write.
+
+Works on all @code{cas}able places.
+@end deffn
+@anchor{Macro sb-ext atomic-update}
+@ffindex @sortas{atomic-update sb-ext} atomic-update [sb-ext]
+@deffn{Macro} sb-ext:atomic-update place update-fn &rest arguments
+Updates @code{place} atomically to the value returned by calling function
+designated by @code{update-fn} with @code{arguments} and the previous value of @code{place}.
+
+@code{place} may be read and @code{update-fn} evaluated and called multiple times before the
+update succeeds: atomicity in this context means that the value of @code{place} did
+not change between the time it was read, and the time it was replaced with the
+computed value.
+
+@code{place} can be any place supported by @code{sb-ext:compare-and-swap}.
+
+Examples:
+
+@example
+;;; Conses T to the head of FOO-LIST.
+(defstruct foo list)
+(defvar *foo* (make-foo))
+(atomic-update (foo-list *foo*) #'cons t)
+
+(let ((x (cons :count 0)))
+ (mapc #'sb-thread:join-thread
+ (loop repeat 1000
+ collect (sb-thread:make-thread
+ (lambda ()
+ (loop repeat 1000
+ do (atomic-update (cdr x) #'1+)
+ (sleep 0.00001))))))
+ ;; Guaranteed to be (:COUNT . 1000000) -- if you replace
+ ;; atomic update with (INCF (CDR X)) above, the result becomes
+ ;; unpredictable.
+ x)
+@end example
+@end deffn
+@anchor{Macro sb-ext compare-and-swap}
+@ffindex @sortas{compare-and-swap sb-ext} compare-and-swap [sb-ext]
+@deffn{Macro} sb-ext:compare-and-swap place old new
+Atomically stores @code{new} in @code{place} if @code{old} matches the current value of @code{place}.
+Two values are considered to match if they are @code{eq}. Returns the previous value
+of @code{place}: if the returned value is @code{eq} to @code{old}, the swap was carried out.
+
+@code{place} must be an @code{cas}-able place. Built-in @code{cas}-able places are accessor forms
+whose @code{car} is one of the following:
+
+ @code{car}, @code{cdr}, @code{first}, @code{rest}, @code{svref}, @code{symbol-plist}, @code{symbol-value}, @code{slot-value}
+ @code{sb-mop:standard-instance-access}, @code{sb-mop:funcallable-standard-instance-access},
+
+or the name of a @code{defstruct} created accessor for a slot whose storage type
+is not raw. (Refer to the the "Efficiency" chapter of the manual
+for the list of raw slot types. Future extensions to this macro may allow
+it to work on some raw slot types.)
+
+In case of @code{slot-value}, if the slot is unbound, @code{slot-unbound} is called unless
+@code{old} is @code{eq} to @code{sb-pcl:+slot-unbound+} in which case @code{sb-pcl:+slot-unbound+} is
+returned and @code{new} is assigned to the slot. Additionally, the results are
+unspecified if there is an applicable method on either
+@code{sb-mop:slot-value-using-class}, (@code{setf} @code{sb-mop:slot-value-using-class}), or
+@code{sb-mop:slot-boundp-using-class}.
+
+Additionally, the @code{place} can be a anything for which a @code{cas}-function has
+been defined.
+@end deffn
+Our @code{sb-ext:compare-and-swap} is user-extensible by defining functions
+named @code{(cas <place>)}, allowing users to add CAS support to new
places.
-@include macro-sb-ext-cas.texinfo
-@include fun-sb-ext-get-cas-expansion.texinfo
+@anchor{Macro sb-ext cas}
+@ffindex @sortas{cas sb-ext} cas [sb-ext]
+@deffn{Macro} sb-ext:cas place old new
+Synonym for @code{compare-and-swap}.
-@node Mutex Support
-@comment node-name, next, previous, up
+Additionally @code{defun}, @code{defgeneric}, @code{defmethod}, @code{flet}, and @code{labels} can be also used to
+define @code{cas}-functions analogously to @code{setf}-functions:
+
+@example
+(defvar *foo* nil)
+
+(defun (cas foo) (old new)
+ (cas (symbol-value '*foo*) old new))
+@end example
+
+First argument of a @code{cas} function is the expected old value, and the second
+argument of is the new value. Note that the system provides no automatic
+atomicity for @code{cas} functions, nor can it verify that they are atomic: it is up
+to the implementor of a @code{cas} function to ensure its atomicity.
+
+EXPERIMENTAL: Interface subject to change.
+@end deffn
+@anchor{Function sb-ext get-cas-expansion}
+@ffindex @sortas{get-cas-expansion sb-ext} get-cas-expansion [sb-ext]
+@deffn{Function} sb-ext:get-cas-expansion place &optional environment
+Analogous to @code{get-setf-expansion}. Returns the following six values:
+
+@itemize
+@item list of temporary variables
+
+@item list of value-forms whose results those variable must be bound
+
+@item temporary variable for the old value of @code{place}
+
+@item temporary variable for the new value of @code{place}
+
+@item form using the aforementioned temporaries which performs the
+ compare-and-swap operation on @code{place}
+
+@item form using the aforementioned temporaries with which to perform a volatile
+ read of @code{place}
+@end itemize
+
+Example:
+
+@example
+(get-cas-expansion '(car x))
+; => (#:CONS871), (X), #:OLD872, #:NEW873,
+; (SB-KERNEL:%COMPARE-AND-SWAP-CAR #:CONS871 #:OLD872 :NEW873).
+; (CAR #:CONS871)
+
+(defmacro my-atomic-incf (place &optional (delta 1) &environment env)
+ (multiple-value-bind (vars vals old new cas-form read-form)
+ (get-cas-expansion place env)
+ (let ((delta-value (gensym "DELTA")))
+ `(let* (,@@(mapcar 'list vars vals)
+ (,old ,read-form)
+ (,delta-value ,delta)
+ (,new (+ ,old ,delta-value)))
+ (loop until (eq ,old (setf ,old ,cas-form))
+ do (setf ,new (+ ,old ,delta-value)))
+ ,new))))
+@end example
+
+EXPERIMENTAL: Interface subject to change.
+@end deffn
+@node mutex support
@section Mutex Support
Mutexes are used for controlling access to a shared resource. One
@@ -137,7 +609,7 @@ thread is allowed to hold the mutex, others which attempt to take it
will be made to wait until it's free. Threads are woken in the order
that they go to sleep.
-@lisp
+@example
(defpackage :demo (:use "CL" "SB-THREAD" "SB-EXT"))
(in-package :demo)
@@ -153,87 +625,256 @@ that they go to sleep.
(make-thread #'thread-fn)
(make-thread #'thread-fn)
-@end lisp
+@end example
-@include struct-sb-thread-mutex.texinfo
+@anchor{Structure sb-thread mutex}
+@ttindex @sortas{mutex sb-thread} mutex [sb-thread]
+@deffn{Structure} sb-thread:mutex
+Mutex type.
+@end deffn
+@anchor{Macro sb-thread with-mutex}
+@ffindex @sortas{with-mutex sb-thread} with-mutex [sb-thread]
+@deffn{Macro} sb-thread:with-mutex (mutex &key wait-p timeout value) &body body
+Acquire @code{mutex} for the dynamic scope of @code{body}. If @code{wait-p} is true (the default),
+and the @code{mutex} is not immediately available, sleep until it is available.
-@include macro-sb-thread-with-mutex.texinfo
-@include macro-sb-thread-with-recursive-lock.texinfo
+If @code{timeout} is given, it specifies a relative timeout, in seconds, on how long
+the system should try to acquire the lock in the contended case.
-@include fun-sb-thread-make-mutex.texinfo
-@include fun-sb-thread-mutex-name.texinfo
-@include fun-sb-thread-mutex-owner.texinfo
-@include fun-sb-thread-mutex-value.texinfo
-@include fun-sb-thread-grab-mutex.texinfo
-@include fun-sb-thread-release-mutex.texinfo
+If the mutex isn't acquired successfully due to either @code{wait-p} or
+@code{timeout}, @code{body} is not executed, and @code{with-mutex} returns @code{nil}.
-@node Semaphores
-@comment node-name, next, previous, up
+Otherwise body is executed with the mutex held by current thread, and
+@code{with-mutex} returns the values of @code{body}.
+
+Historically @code{with-mutex} also accepted a @code{value} argument, which when provided
+was used as the new owner of the mutex instead of the current thread. This is
+no longer supported: if @code{value} is provided, it must be either @code{nil} or the
+current thread.
+@end deffn
+@anchor{Macro sb-thread with-recursive-lock}
+@ffindex @sortas{with-recursive-lock sb-thread} with-recursive-lock [sb-thread]
+@deffn{Macro} sb-thread:with-recursive-lock (mutex &key wait-p timeout) &body body
+Acquire @code{mutex} for the dynamic scope of @code{body}.
+
+If @code{wait-p} is true (the default), and the @code{mutex} is not immediately available or
+held by the current thread, sleep until it is available.
+
+If @code{timeout} is given, it specifies a relative timeout, in seconds, on how long
+the system should try to acquire the lock in the contended case.
+
+If the mutex isn't acquired successfully due to either @code{wait-p} or
+@code{timeout}, @code{body} is not executed, and @code{with-recursive-lock} returns @code{nil}.
+
+Otherwise body is executed with the mutex held by current thread, and
+@code{with-recursive-lock} returns the values of @code{body}.
+
+Unlike @code{with-mutex}, which signals an error on attempt to re-acquire an already
+held mutex, @code{with-recursive-lock} allows recursive lock attempts to succeed.
+@end deffn
+@anchor{Function sb-thread make-mutex}
+@ffindex @sortas{make-mutex sb-thread} make-mutex [sb-thread]
+@deffn{Function} sb-thread:make-mutex &key name
+Create a @code{mutex}.
+@end deffn
+@anchor{Function sb-thread mutex-name}
+@ffindex @sortas{mutex-name sb-thread} mutex-name [sb-thread]
+@deffn{Function} sb-thread:mutex-name instance
+The name of the @code{mutex}. @code{setf}able.
+@end deffn
+@anchor{Function sb-thread mutex-owner}
+@ffindex @sortas{mutex-owner sb-thread} mutex-owner [sb-thread]
+@deffn{Function} sb-thread:mutex-owner mutex
+Current owner of @code{mutex}, @code{nil} if the mutex is free. Naturally,
+this is racy by design (another thread may acquire the mutex after
+this function returns), it is intended for informative purposes. For
+testing whether the current thread is holding a mutex see
+@code{holding-mutex-p}.
+@end deffn
+@anchor{Function sb-thread mutex-value}
+@ffindex @sortas{mutex-value sb-thread} mutex-value [sb-thread]
+@deffn{Function} sb-thread:mutex-value mutex
+Current owner of @code{mutex}, @code{nil} if the mutex is free. May return a
+stale value, use @code{mutex-owner} instead.
+@end deffn
+@anchor{Function sb-thread grab-mutex}
+@ffindex @sortas{grab-mutex sb-thread} grab-mutex [sb-thread]
+@deffn{Function} sb-thread:grab-mutex mutex &key waitp timeout
+Acquire @code{mutex} for the current thread. If @code{waitp} is true (the default) and
+the mutex is not immediately available, sleep until it is available.
+
+If @code{timeout} is given, it specifies a relative timeout, in seconds, on how long
+@code{grab-mutex} should try to acquire the lock in the contended case.
+
+If @code{grab-mutex} returns @code{t}, the lock acquisition was successful. In case of @code{waitp}
+being @code{nil}, or an expired @code{timeout}, @code{grab-mutex} may also return @code{nil} which denotes
+that @code{grab-mutex} did -not- acquire the lock.
+
+Notes:
+
+@itemize
+@item @code{grab-mutex} is not interrupt safe. The correct way to call it is:
+
+@example
+(without-interrupts
+ ...
+ (allow-with-interrupts (grab-mutex ...))
+ ...)
+@end example
+
+ @code{without-interrupts} is necessary to avoid an interrupt unwinding the call
+ while the mutex is in an inconsistent state while @code{allow-with-interrupts}
+ allows the call to be interrupted from sleep.
+
+@item @code{(grab-mutex <mutex> :timeout 0.0)} differs from
+ @code{(grab-mutex <mutex> :waitp nil)} in that the former may signal a
+ @code{deadline-timeout} if the global deadline was due already on
+ entering @code{grab-mutex}.
+
+ The exact interplay of @code{grab-mutex} and deadlines are reserved to change in
+ future versions.
+
+@item It is recommended that you use @code{with-mutex} instead of calling @code{grab-mutex}
+ directly.
+@end itemize
+@end deffn
+@anchor{Function sb-thread release-mutex}
+@ffindex @sortas{release-mutex sb-thread} release-mutex [sb-thread]
+@deffn{Function} sb-thread:release-mutex mutex &key if-not-owner
+Release @code{mutex} and wake up any other thread waiting for it.
+
+@code{release-mutex} is not interrupt safe: interrupts should be disabled
+around calls to it.
+
+The @code{if-not-owner} keyword dictates behavior when the current thread does not own the
+mutex. Do nothing and silently return if @code{:punt}, signal a @code{warning} or @code{error} if @code{:warn}
+or @code{:error} respectively, or release the mutex anyway if @code{:force}.
+@end deffn
+@node semaphores
@section Semaphores
Semaphores are among other things useful for keeping track of a
countable resource, e.g. messages in a queue, and sleep when the
resource is exhausted.
-@include struct-sb-thread-semaphore.texinfo
-@include fun-sb-thread-make-semaphore.texinfo
-@include fun-sb-thread-signal-semaphore.texinfo
-@include fun-sb-thread-wait-on-semaphore.texinfo
-@include fun-sb-thread-try-semaphore.texinfo
-@include fun-sb-thread-semaphore-count.texinfo
-@include fun-sb-thread-semaphore-name.texinfo
-
-@include struct-sb-thread-semaphore-notification.texinfo
-@include fun-sb-thread-make-semaphore-notification.texinfo
-@include fun-sb-thread-semaphore-notification-status.texinfo
-@include fun-sb-thread-clear-semaphore-notification.texinfo
-
-@node Waitqueue/condition variables
-@comment node-name, next, previous, up
+@anchor{Structure sb-thread semaphore}
+@ttindex @sortas{semaphore sb-thread} semaphore [sb-thread]
+@deffn{Structure} sb-thread:semaphore
+Semaphore type. The fact that a @code{semaphore} is a @code{structure-object}
+should be considered an implementation detail, and may change in the
+future.
+@end deffn
+@anchor{Function sb-thread make-semaphore}
+@ffindex @sortas{make-semaphore sb-thread} make-semaphore [sb-thread]
+@deffn{Function} sb-thread:make-semaphore &key name count
+Create a semaphore with the supplied @code{count} and @code{name}.
+@end deffn
+@anchor{Function sb-thread signal-semaphore}
+@ffindex @sortas{signal-semaphore sb-thread} signal-semaphore [sb-thread]
+@deffn{Function} sb-thread:signal-semaphore semaphore &optional n
+Increment the count of @code{semaphore} by @code{n}. If there are threads waiting
+on this semaphore, then @code{n} of them is woken up.
+@end deffn
+@anchor{Function sb-thread wait-on-semaphore}
+@ffindex @sortas{wait-on-semaphore sb-thread} wait-on-semaphore [sb-thread]
+@deffn{Function} sb-thread:wait-on-semaphore semaphore &key n timeout notification
+Decrement the count of @code{semaphore} by @code{n} if the count would not be negative.
+
+Else blocks until the semaphore can be decremented. Returns the new count of
+@code{semaphore} on success.
+
+If @code{timeout} is given, it is the maximum number of seconds to wait. If the count
+cannot be decremented in that time, returns @code{nil} without decrementing the
+count.
+
+If @code{notification} is given, it must be a @code{semaphore-notification} object whose
+@code{semaphore-notification-status} is @code{nil}. If @code{wait-on-semaphore} succeeds and
+decrements the count, the status is set to @code{t}.
+@end deffn
+@anchor{Function sb-thread try-semaphore}
+@ffindex @sortas{try-semaphore sb-thread} try-semaphore [sb-thread]
+@deffn{Function} sb-thread:try-semaphore semaphore &optional n notification
+Try to decrement the count of @code{semaphore} by @code{n}. If the count were to
+become negative, punt and return @code{nil}, otherwise return the new count of
+@code{semaphore}.
+
+If @code{notification} is given it must be a semaphore notification object
+with @code{semaphore-notification-status} of @code{nil}. If the count is decremented,
+the status is set to @code{t}.
+@end deffn
+@anchor{Function sb-thread semaphore-count}
+@ffindex @sortas{semaphore-count sb-thread} semaphore-count [sb-thread]
+@deffn{Function} sb-thread:semaphore-count semaphore
+Returns the current count of @code{semaphore}.
+@end deffn
+@anchor{Function sb-thread semaphore-name}
+@ffindex @sortas{semaphore-name sb-thread} semaphore-name [sb-thread]
+@deffn{Function} sb-thread:semaphore-name semaphore
+The name of the semaphore @code{instance}. @code{setf}able.
+@end deffn
+@anchor{Structure sb-thread semaphore-notification}
+@ttindex @sortas{semaphore-notification sb-thread} semaphore-notification [sb-thread]
+@deffn{Structure} sb-thread:semaphore-notification
+Semaphore notification object. Can be passed to @code{wait-on-semaphore} and
+@code{try-semaphore} as the @code{:notification} argument. Consequences are undefined if
+multiple threads are using the same notification object in parallel.
+@end deffn
+@anchor{Function sb-thread make-semaphore-notification}
+@ffindex @sortas{make-semaphore-notification sb-thread} make-semaphore-notification [sb-thread]
+@deffn{Function} sb-thread:make-semaphore-notification
+Constructor for @code{semaphore-notification} objects. @code{semaphore-notification-status}
+is initially @code{nil}.
+@end deffn
+@anchor{Function sb-thread semaphore-notification-status}
+@ffindex @sortas{semaphore-notification-status sb-thread} semaphore-notification-status [sb-thread]
+@deffn{Function} sb-thread:semaphore-notification-status semaphore-notification
+Returns @code{t} if a @code{wait-on-semaphore} or @code{try-semaphore} using
+@code{semaphore-notification} has succeeded since the notification object was created
+or cleared.
+@end deffn
+@anchor{Function sb-thread clear-semaphore-notification}
+@ffindex @sortas{clear-semaphore-notification sb-thread} clear-semaphore-notification [sb-thread]
+@deffn{Function} sb-thread:clear-semaphore-notification semaphore-notification
+Resets the @code{semaphore-notification} object for use with another call to
+@code{wait-on-semaphore} or @code{try-semaphore}.
+@end deffn
+@node waitqueue/condition variables
@section Waitqueue/condition variables
These are based on the POSIX condition variable design, hence the
annoyingly CL-conflicting name. For use when you want to check a
condition and sleep until it's true. For example: you have a shared
-queue, a writer process checking ``queue is empty'' and one or more
-readers that need to know when ``queue is not empty''. It sounds
-simple, but is astonishingly easy to deadlock if another process runs
+queue, a writer process checking @emph{queue is empty} and one or more
+readers that need to know when @emph{queue is not empty}. It sounds
+simple but is astonishingly easy to deadlock if another process runs
when you weren't expecting it to.
There are three components:
@itemize
-@item
-the condition itself (not represented in code)
+@item the condition itself (not represented in code)
-@item
-the condition variable (a.k.a. waitqueue) which proxies for it
+@item the condition variable (a.k.a. waitqueue) which proxies for it
-@item
-a lock to hold while testing the condition
+@item a lock to hold while testing the condition
@end itemize
Important stuff to be aware of:
@itemize
-@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;
+@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;
-@item
-likewise, you must be holding the mutex around calls to
-condition-notify;
+@item likewise, you must be holding the mutex around calls to
+ @code{sb-thread:condition-notify};
-@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.
+@item a process may return from @code{sb-thread: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.
-@end itemize
-
-@lisp
+@example
(defvar *buffer-queue* (make-waitqueue))
(defvar *buffer-lock* (make-mutex :name "buffer lock"))
@@ -256,24 +897,91 @@ it.
(with-mutex (*buffer-lock*)
(let ((el (intern
(string (code-char
- (+ (char-code #\A) (random 26)))))))
+ (+ (char-code #A) (random 26)))))))
(setf *buffer* (cons el *buffer*)))
(condition-notify *buffer-queue*))))
(make-thread #'writer)
(make-thread #'reader)
(make-thread #'reader)
-@end lisp
+@end example
+@end itemize
-@include struct-sb-thread-waitqueue.texinfo
-@include fun-sb-thread-make-waitqueue.texinfo
-@include fun-sb-thread-waitqueue-name.texinfo
-@include fun-sb-thread-condition-wait.texinfo
-@include fun-sb-thread-condition-notify.texinfo
-@include fun-sb-thread-condition-broadcast.texinfo
+@anchor{Structure sb-thread waitqueue}
+@ttindex @sortas{waitqueue sb-thread} waitqueue [sb-thread]
+@deffn{Structure} sb-thread:waitqueue
+Waitqueue type.
+@end deffn
+@anchor{Function sb-thread make-waitqueue}
+@ffindex @sortas{make-waitqueue sb-thread} make-waitqueue [sb-thread]
+@deffn{Function} sb-thread:make-waitqueue &key name
+Create a @code{waitqueue}.
+@end deffn
+@anchor{Function sb-thread waitqueue-name}
+@ffindex @sortas{waitqueue-name sb-thread} waitqueue-name [sb-thread]
+@deffn{Function} sb-thread:waitqueue-name instance
+The name of the waitqueue. @code{setf}able.
+@end deffn
+@anchor{Function sb-thread condition-wait}
+@ffindex @sortas{condition-wait sb-thread} condition-wait [sb-thread]
+@deffn{Function} sb-thread:condition-wait queue mutex &key timeout
+Atomically release @code{mutex} and start waiting on @code{queue} until another thread
+wakes us up using either @code{condition-notify} or @code{condition-broadcast} on
+@code{queue}, at which point we re-acquire @code{mutex} and return @code{t}.
-@node Barriers
-@comment node-name, next, previous, up
+Spurious wakeups are possible.
+
+If @code{timeout} is given, it is the maximum number of seconds to wait,
+including both waiting for the wakeup and the time to re-acquire
+@code{mutex}. When neither a wakeup nor a re-acquisition occurs within the
+given time, returns @code{nil} without re-acquiring @code{mutex}.
+
+If @code{condition-wait} unwinds, it may do so with or without @code{mutex} being
+held.
+
+Important: Since @code{condition-wait} may return without @code{condition-notify} or
+@code{condition-broadcast} having occurred, the correct way to write code
+that uses @code{condition-wait} is to loop around the call, checking the
+associated data:
+
+@example
+(defvar *data* nil)
+(defvar *queue* (make-waitqueue))
+(defvar *lock* (make-mutex))
+
+;; Consumer
+(defun pop-data (&optional timeout)
+ (with-mutex (*lock*)
+ (loop until *data*
+ do (or (condition-wait *queue* *lock* :timeout timeout)
+ ;; Lock not held, must unwind without touching *data*.
+ (return-from pop-data nil)))
+ (pop *data*)))
+
+;; Producer
+(defun push-data (data)
+ (with-mutex (*lock*)
+ (push data *data*)
+ (condition-notify *queue*)))
+@end example
+@end deffn
+@anchor{Function sb-thread condition-notify}
+@ffindex @sortas{condition-notify sb-thread} condition-notify [sb-thread]
+@deffn{Function} sb-thread:condition-notify queue &optional n
+Notify @code{n} threads waiting on @code{queue}.
+
+IMPORTANT: The same mutex that is used in the corresponding @code{condition-wait}
+must be held by this thread during this call.
+@end deffn
+@anchor{Function sb-thread condition-broadcast}
+@ffindex @sortas{condition-broadcast sb-thread} condition-broadcast [sb-thread]
+@deffn{Function} sb-thread:condition-broadcast queue
+Notify all threads waiting on @code{queue}.
+
+IMPORTANT: The same mutex that is used in the corresponding @code{condition-wait}
+must be held by this thread during this call.
+@end deffn
+@node barriers
@section Barriers
These are based on the Linux kernel barrier design, which is in turn
@@ -285,98 +993,143 @@ In addition to explicit use of the @code{sb-thread:barrier} macro, the
following functions and macros also serve as @code{:memory} barriers:
@itemize
-@item
-@code{sb-ext:atomic-decf}, @code{sb-ext:atomic-incf}, @code{sb-ext:atomic-push},
-and @code{sb-ext:atomic-pop}.
-@item
-@code{sb-ext:compare-and-swap}.
-@item
-@code{sb-thread:grab-mutex}, @code{sb-thread:release-mutex},
-@code{sb-thread:with-mutex} and @code{sb-thread:with-recursive-lock}.
-@item
-@code{sb-thread:signal-semaphore}, @code{sb-thread:try-semaphore} and
-@code{sb-thread:wait-on-semaphore}.
-@item
-@code{sb-thread:condition-wait}, @code{sb-thread:condition-notify} and
-@code{sb-thread:condition-broadcast}.
+@item @code{sb-ext:atomic-decf}, @code{sb-ext:atomic-incf}, @code{sb-ext:atomic-push},
+ and @code{sb-ext:atomic-pop}
+
+@item @code{sb-ext:compare-and-swap}
+
+@item @code{sb-thread:grab-mutex}, @code{sb-thread:release-mutex},
+ @code{sb-thread:with-mutex} and @code{sb-thread:with-recursive-lock}
+
+@item @code{sb-thread:signal-semaphore}, @code{sb-thread:try-semaphore} and
+ @code{sb-thread:wait-on-semaphore}
+
+@item @code{sb-thread:condition-wait}, @code{sb-thread:condition-notify} and
+ @code{sb-thread:condition-broadcast}.
+@end itemize
+
+@anchor{Macro sb-thread barrier}
+@ffindex @sortas{barrier sb-thread} barrier [sb-thread]
+@deffn{Macro} sb-thread:barrier (kind) &body forms
+Insert a barrier in the code stream, preventing some sort of
+reordering.
+
+@code{kind} should be one of:
+
+@itemize
+@item @code{:compiler}: Prevent the compiler from reordering memory access across
+ the barrier.
+
+@item @code{:memory}: Prevent the CPU from reordering any memory access across
+ the barrier.
+
+@item @code{:read}: Prevent the CPU from reordering any read access across the
+ barrier.
+
+@item @code{:write}: Prevent the cpu from reordering any write access across the
+ barrier.
+
+@item @code{:data-dependency}: Prevent the cpu from reordering dependent memory
+ reads across the barrier (requiring reads before the barrier to
+ complete before any reads after the barrier that depend on them).
+ This is a weaker form of the @code{:read} barrier.
@end itemize
-@include macro-sb-thread-barrier.texinfo
+@code{forms} is an implicit @code{progn}, evaluated before the barrier. @code{barrier}
+returns the values of the last form in @code{forms}.
-@node Sessions/Debugging
-@comment node-name, next, previous, up
+The file @code{memory-barriers.txt} in the Linux kernel documentation is
+highly recommended reading for anyone programming at this level.
+@end deffn
+@node sessions/debugging
@section Sessions/Debugging
If the user has multiple views onto the same Lisp image (for example,
using multiple terminals, or a windowing system, or network access)
-they are typically set up as multiple @dfn{sessions} such that each
-view has its own collection of foreground/background/stopped threads.
-A thread which wishes to create a new session can use
+they are typically set up as multiple @emph{sessions} such that each view
+has its own collection of foreground, background, and stopped
+threads. A thread which wishes to create a new session can use
@code{sb-thread:with-new-session} to remove itself from the current
session (which it shares with its parent and siblings) and create a
fresh one.
-# See also @code{sb-thread:make-listener-thread}.
-Within a single session, threads arbitrate between themselves for the
-user's attention. A thread may be in one of three notional states:
-foreground, background, or stopped. When a background process
-attempts to print a repl prompt or to enter the debugger, it will stop
-and print a message saying that it has stopped. The user at his
-leisure may switch to that thread to find out what it needs. If a
-background thread enters the debugger, selecting any restart will put
-it back into the background before it resumes. Arbitration for the
-input stream is managed by calls to @code{sb-thread:get-foreground}
-(which may block) and @code{sb-thread:release-foreground}.
+@anchor{Macro sb-thread with-new-session}
+@ffindex @sortas{with-new-session sb-thread} with-new-session [sb-thread]
+@deffn{Macro} sb-thread:with-new-session args &body forms
+@end deffn
+@anchor{Function sb-thread make-listener-thread}
+@ffindex @sortas{make-listener-thread sb-thread} make-listener-thread [sb-thread]
+@deffn{Function} sb-thread:make-listener-thread tty-name
+@end deffn
+Within a single session, threads arbitrate between themselves for
+the user's attention. A thread may be in one of three notional
+states: foreground, background, or stopped. When a background
+process attempts to print a repl prompt or to enter the debugger, it
+will stop and print a message saying that it has stopped. The user
+at his leisure may switch to that thread to find out what it needs.
+If a background thread enters the debugger, selecting any restart
+will put it back into the background before it resumes. Arbitration
+for the input stream is managed by calls to
+@code{sb-thread:get-foreground} (which may block) and
+@code{sb-thread:release-foreground}.
-@node Foreign threads
-@comment node-name, next, previous, up
+@anchor{Function sb-thread get-foreground}
+@ffindex @sortas{get-foreground sb-thread} get-foreground [sb-thread]
+@deffn{Function} sb-thread:get-foreground
+@end deffn
+@anchor{Function sb-thread release-foreground}
+@ffindex @sortas{release-foreground sb-thread} release-foreground [sb-thread]
+@deffn{Function} sb-thread:release-foreground &optional next
+Background this thread. If @code{next} is supplied, arrange for it to
+have the foreground next.
+@end deffn
+@node foreign threads
@section Foreign threads
-Direct calls to @code{pthread_create} (instead of @code{MAKE-THREAD})
+Direct calls to @code{pthread_create(3)} (instead of @code{sb-thread:make-thread})
create threads that SBCL is not aware of, these are called foreign
threads. Currently, it is not possible to run Lisp code in such
threads. This means that the Lisp side signal handlers cannot work.
The best solution is to start foreign threads with signals blocked,
but since third party libraries may create threads, it is not always
feasible to do so. As a workaround, upon receiving a signal in a
-foreign thread, SBCL changes the thread's sigmask to block all signals
-that it wants to handle and resends the signal to the current process
-which should land in a thread that does not block it, that is, a Lisp
-thread.
+foreign thread, SBCL changes the thread's sigmask to block all
+signals that it wants to handle and resends the signal to the
+current process which should land in a thread that does not block
+it, that is, a Lisp thread.
The resignalling trick cannot work for synchronously triggered signals
-(SIGSEGV and co), take care not to trigger any. Resignalling for
+(@code{sigsegv} and co), take care not to trigger any. Resignalling for
synchronously triggered signals in foreign threads is subject to
-@code{--lose-on-corruption}, see @ref{Runtime Options}.
+@code{--lose-on-corruption}, see @ref{runtime options}.
-@node Implementation (Linux x86/x86-64)
-@comment node-name, next, previous, up
-@section Implementation (Linux x86/x86-64)
+@node implementation on linux x86oids
+@section Implementation on Linux x86oids
Threading is implemented using pthreads and some Linux specific bits
like futexes.
-On x86 the per-thread local bindings for special variables is achieved
-using the %fs segment register to point to a per-thread storage area.
-This may cause interesting results if you link to foreign code that
-expects threading or creates new threads, and the thread library in
-question uses %fs in an incompatible way. On x86-64 the r12 register
-has a similar role.
+On x86, the per-thread local bindings for special variables is
+achieved using the @code{%fs} segment register to point to a per-thread
+storage area. This may cause interesting results if you link to
+foreign code that expects threading or creates new threads, and the
+thread library in question uses %fs in an incompatible way. On
+x86-64 the r12 register has a similar role.
-Queues require the @code{sys_futex()} system call to be available:
-this is the reason for the NPTL requirement. We test at runtime that
-this system call exists.
+Queues require the @code{futex(2)} system call to be available: this is
+the reason for the NPTL requirement. We test at runtime that this
+system call exists.
-Garbage collection is done with the existing Conservative Generational
-GC. Allocation is done in small (typically 8k) regions: each thread
-has its own region so this involves no stopping. However, when a
-region fills, a lock must be obtained while another is allocated, and
-when a collection is required, all processes are stopped. This is
-achieved by sending them signals, which may make for interesting
-behaviour if they are interrupted in system calls. The streams
-interface is believed to handle the required system call restarting
-correctly, but this may be a consideration when making other blocking
-calls e.g. from foreign library code.
+Garbage collection is done with the existing Conservative
+Generational GC. Allocation is done in small (typically 8k) regions:
+each thread has its own region so this involves no stopping.
+However, when a region fills, a lock must be obtained while another
+is allocated, and when a collection is required, all processes are
+stopped. This is achieved by sending them signals, which may make
+for interesting behaviour if they are interrupted in system calls.
+The streams interface is believed to handle the required system call
+restarting correctly, but this may be a consideration when making
+other blocking calls e.g. from foreign library code.
Large amounts of the SBCL library have not been inspected for
thread-safety. Some of the obviously unsafe areas have large locks
@@ -386,12 +1139,13 @@ parallelized. Work is ongoing in this area.
A new thread by default is created in the same POSIX process group and
session as the thread it was created by. This has an impact on
keyboard interrupt handling: pressing your terminal's intr key
-(typically @kbd{Control-C}) will interrupt all processes in the
+(typically @code{Control-C}) will interrupt all processes in the
foreground process group, including Lisp threads that SBCL considers
-to be notionally `background'. This is undesirable, so background
-threads are set to ignore the SIGINT signal.
+to be notionally @emph{background}. This is undesirable, so background
+threads are set to ignore the @code{sigint} signal.
+
+@code{sb-thread:make-listener-thread} in addition to creating a new Lisp
+session makes a new POSIX session, so that pressing @code{Control-C} in
+one window will not interrupt another listener - this has been found
+to be embarrassing.
-@code{sb-thread:make-listener-thread} in addition to creating a new
-Lisp session makes a new POSIX session, so that pressing
-@kbd{Control-C} in one window will not interrupt another listener -
-this has been found to be embarrassing.
diff --git a/doc/manual/timers.texinfo b/doc/manual/timers.texinfo
index 58d596961..ffbdc18d9 100644
--- a/doc/manual/timers.texinfo
+++ b/doc/manual/timers.texinfo
@@ -1,28 +1,29 @@
-@node Timers
-@comment node-name, next, previous, up
+@c Generated by the sb-manual contrib. Do not edit.
+
+@node timers
@chapter Timers
SBCL supports a system-wide event scheduler implemented on top of
-@code{setitimer} that also works with threads but does not require a
+@code{setitimer(2)} that also works with threads but does not require a
separate scheduler thread.
-The following example schedules a timer that writes ``Hello, world'' after
-two seconds.
+The following example schedules a timer that writes @code{Hello, world}
+after two seconds.
-@lisp
+@example
(schedule-timer (make-timer (lambda ()
(write-line "Hello, world")
(force-output)))
2)
-@end lisp
+@end example
-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:
+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
+@example
(defvar *foo* nil)
(defun show-foo ()
@@ -36,14 +37,64 @@ a cautionary tale:
(sleep 1.0))
(let ((*foo* :surprise!))
(sleep 2.0)))
-@end lisp
+@end example
-@section Timer Dictionary
+@anchor{Structure sb-ext timer}
+@ttindex @sortas{timer sb-ext} timer [sb-ext]
+@deffn{Structure} sb-ext:timer
+Timer type. Do not rely on timers being structs as it may change in
+future versions.
+@end deffn
+@anchor{Function sb-ext make-timer}
+@ffindex @sortas{make-timer sb-ext} make-timer [sb-ext]
+@deffn{Function} sb-ext:make-timer function &key name thread
+Create a timer that runs @code{function} when triggered.
-@include struct-sb-ext-timer.texinfo
-@include fun-sb-ext-make-timer.texinfo
-@include fun-sb-ext-timer-name.texinfo
-@include fun-sb-ext-timer-scheduled-p.texinfo
-@include fun-sb-ext-schedule-timer.texinfo
-@include fun-sb-ext-unschedule-timer.texinfo
-@include fun-sb-ext-list-all-timers.texinfo
+If a @code{thread} is supplied, @code{function} is run in that thread. If @code{thread} is
+@code{t}, a new thread is created for @code{function} each time the timer is
+triggered. If @code{thread} is @code{nil}, @code{function} is run in an unspecified thread.
+
+When @code{thread} is not @code{t}, @code{sb-thread:interrupt-thread} is used to run
+@code{function} and the ordering guarantees of @code{sb-thread:interrupt-thread}
+apply. In that case, @code{function} runs with interrupts disabled but
+@code{with-interrupts} is allowed.
+@end deffn
+@anchor{Function sb-ext timer-name}
+@ffindex @sortas{timer-name sb-ext} timer-name [sb-ext]
+@deffn{Function} sb-ext:timer-name timer
+Return the name of @code{timer}.
+@end deffn
+@anchor{Function sb-ext timer-scheduled-p}
+@ffindex @sortas{timer-scheduled-p sb-ext} timer-scheduled-p [sb-ext]
+@deffn{Function} sb-ext:timer-scheduled-p timer &key delta
+See if @code{timer} will still need to be triggered after @code{delta} seconds
+from now. For timers with a repeat interval it returns true.
+@end deffn
+@anchor{Function sb-ext schedule-timer}
+@ffindex @sortas{schedule-timer sb-ext} schedule-timer [sb-ext]
+@deffn{Function} sb-ext:schedule-timer timer time &key repeat-interval absolute-p catch-up
+Schedule @code{timer} to be triggered at @code{time}. If @code{absolute-p} then @code{time} is
+universal time, but non-integral values are also allowed, else @code{time} is
+measured as the number of seconds from the current time.
+
+If @code{repeat-interval} is given, @code{timer} is automatically rescheduled upon
+expiry.
+
+If @code{repeat-interval} is non-@code{nil}, the Boolean @code{catch-up} controls whether
+@code{timer} will "catch up" by repeatedly calling its function without
+delay in case calls are missed because of a clock discontinuity such
+as a suspend and resume cycle of the computer. The default is @code{nil},
+i.e. do not catch up.
+@end deffn
+@anchor{Function sb-ext unschedule-timer}
+@ffindex @sortas{unschedule-timer sb-ext} unschedule-timer [sb-ext]
+@deffn{Function} sb-ext:unschedule-timer timer
+Cancel @code{timer}. Once this function returns it is guaranteed that
+@code{timer} shall not be triggered again and there are no unfinished
+triggers.
+@end deffn
+@anchor{Function sb-ext list-all-timers}
+@ffindex @sortas{list-all-timers sb-ext} list-all-timers [sb-ext]
+@deffn{Function} sb-ext:list-all-timers
+Return a list of all timers in the system.
+@end deffn
-----------------------------------------------------------------------
hooks/post-receive
--
SBCL
_______________________________________________
Sbcl-commits mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/sbcl-commits