master: doc: update lisp definition docstrings for Markdown
melisgl via Sbcl-commits <[email protected]> Mon, 29 Jun 2026 12:19:35 +0000
| Newsgroups | gmane.lisp.steel-bank.cvs |
|---|---|
| Message-ID | <[email protected]> |
The branch "master" has been updated in SBCL:
via 316291e3718890758a58882417d292dbd1c00942 (commit)
from 4271a2f375adcba295a6207bb700901c95d96ac3 (commit)
- Log -----------------------------------------------------------------
commit 316291e3718890758a58882417d292dbd1c00942
Author: Gabor Melis <[email protected]>
Date: Sun Jun 7 19:24:47 2026 +0200
doc: update lisp definition docstrings for Markdown
This is a follow up to the "PAXlike docs" commit.
---
contrib/sb-aclrepl/repl.lisp | 2 +-
contrib/sb-bsd-sockets/inet.lisp | 2 +-
contrib/sb-bsd-sockets/local.lisp | 2 +-
contrib/sb-bsd-sockets/name-service.lisp | 6 +-
contrib/sb-bsd-sockets/protocol.lisp | 23 ++-
contrib/sb-bsd-sockets/sockopt.lisp | 9 +-
contrib/sb-cltl2/env.lisp | 128 +++++++--------
contrib/sb-concurrency/frlock.lisp | 56 +++----
contrib/sb-concurrency/mailbox.lisp | 16 +-
contrib/sb-cover/genhtml.lisp | 10 +-
contrib/sb-introspect/introspect.lisp | 6 +-
contrib/sb-manual/doc/beyond-ansi.lisp | 1 +
contrib/sb-manual/doc/compiler.lisp | 10 +-
contrib/sb-manual/doc/ffi.lisp | 2 +-
contrib/sb-manual/doc/sbcl.lisp | 11 ++
contrib/sb-md5/md5.lisp | 4 +-
contrib/sb-posix/interface.lisp | 4 +-
contrib/sb-posix/macros.lisp | 14 +-
contrib/sb-sprof/call-counting.lisp | 4 +-
contrib/sb-sprof/interface.lisp | 100 +++++++-----
contrib/sb-sprof/report.lisp | 38 +++--
src/code/alien-callback.lisp | 4 +-
src/code/array.lisp | 6 +-
src/code/barrier.lisp | 37 ++---
src/code/cold-init.lisp | 10 +-
src/code/cross-early.lisp | 7 +-
src/code/debug.lisp | 25 +--
src/code/defpackage.lisp | 6 +-
src/code/filesys.lisp | 4 +-
src/code/foreign-load.lisp | 8 +-
src/code/gc.lisp | 12 +-
src/code/globals.lisp | 4 +-
src/code/macros.lisp | 101 +++++++-----
src/code/misc-aliens.lisp | 8 +-
src/code/module.lisp | 2 +-
src/code/ntrace.lisp | 29 ++--
src/code/print.lisp | 2 +-
src/code/profile.lisp | 4 +-
src/code/run-program.lisp | 32 ++--
src/code/save.lisp | 32 ++--
src/code/stubs.lisp | 9 +
src/code/target-alieneval.lisp | 272 +++++++++++++++++++++++--------
src/code/target-error.lisp | 4 +
src/code/target-extensions.lisp | 2 +-
src/code/target-hash-table.lisp | 4 +-
src/code/target-misc.lisp | 8 +-
src/code/target-package.lisp | 14 +-
src/code/target-random.lisp | 3 +
src/code/target-thread.lisp | 173 ++++++++++----------
src/code/target-unicode.lisp | 70 ++++----
src/code/thread.lisp | 12 +-
src/code/timer.lisp | 16 +-
src/code/toplevel.lisp | 9 +
src/code/traceroot.lisp | 4 +-
src/code/unix.lisp | 6 +-
src/compiler/generic/genesis.lisp | 2 +-
src/compiler/macros.lisp | 10 +-
src/compiler/main.lisp | 38 +++--
src/pcl/gray-streams.lisp | 13 +-
src/pcl/sequence.lisp | 14 +-
60 files changed, 839 insertions(+), 625 deletions(-)
diff --git a/contrib/sb-aclrepl/repl.lisp b/contrib/sb-aclrepl/repl.lisp
index f25129944..93ad1b5e9 100644
--- a/contrib/sb-aclrepl/repl.lisp
+++ b/contrib/sb-aclrepl/repl.lisp
@@ -33,7 +33,7 @@
(defparameter *prompt* #.*default-prompt*
"The current prompt string or formatter function.")
(defparameter *use-short-package-name* t
- "when T, use the shortnest package nickname in a prompt")
+ "When T, use the shortnest package nickname in a prompt")
(defparameter *dir-stack* nil
"The top-level directory stack")
(defparameter *command-char* #\:
diff --git a/contrib/sb-bsd-sockets/inet.lisp b/contrib/sb-bsd-sockets/inet.lisp
index 68063f907..e5e619c58 100644
--- a/contrib/sb-bsd-sockets/inet.lisp
+++ b/contrib/sb-bsd-sockets/inet.lisp
@@ -22,7 +22,7 @@
;;; getprotobyname if it's available.
(defun get-protocol-by-name (name)
"Given a protocol name, return the protocol number, the protocol name, and
-a list of protocol aliases"
+a list of protocol aliases."
(let ((result (cdr (if (keywordp name)
(assoc name *protocols*)
(assoc name *protocols* :test #'string-equal)))))
diff --git a/contrib/sb-bsd-sockets/local.lisp b/contrib/sb-bsd-sockets/local.lisp
index bb5580927..c82d88b38 100644
--- a/contrib/sb-bsd-sockets/local.lisp
+++ b/contrib/sb-bsd-sockets/local.lisp
@@ -7,7 +7,7 @@
((family :initform sockint::af-local))
(:documentation
"Class representing local domain (`\\\\AF_LOCAL`) sockets,
-also known as unix-domain sockets."))
+also known as Unix-domain sockets."))
(defmethod socket-namestring ((socket local-socket))
(ignore-errors (socket-name socket)))
diff --git a/contrib/sb-bsd-sockets/name-service.lisp b/contrib/sb-bsd-sockets/name-service.lisp
index 59b6347bc..054132a1d 100644
--- a/contrib/sb-bsd-sockets/name-service.lisp
+++ b/contrib/sb-bsd-sockets/name-service.lisp
@@ -67,14 +67,14 @@
(defun get-host-by-name (host-name)
"Returns a HOST-ENT instance for HOST-NAME or signals a NAME-SERVICE-ERROR.
HOST-NAME may also be an IP address in dotted quad notation or some other
-weird stuff - see gethostbyname(3) for the details."
+weird stuff -- see `gethostbyname(3)` for the details."
(sb-int:with-system-mutex (**gethostby-lock** :allow-with-interrupts t)
(make-host-ent (sockint::gethostbyname host-name))))
(defun get-host-by-address (address)
"Returns a HOST-ENT instance for ADDRESS, which should be a vector of
- (integer 0 255), or signals a NAME-SERVICE-ERROR. See gethostbyaddr(3)
- for details."
+ `(INTEGER 0 255)`, or signals a NAME-SERVICE-ERROR. See
+ `gethostbyaddr(3)` for details."
(sb-int:with-system-mutex (**gethostby-lock** :allow-with-interrupts t)
(sockint::with-in-addr packed-addr ()
(let ((addr-vector (coerce address 'vector)))
diff --git a/contrib/sb-bsd-sockets/protocol.lisp b/contrib/sb-bsd-sockets/protocol.lisp
index 202c802c0..0c7ea7c80 100644
--- a/contrib/sb-bsd-sockets/protocol.lisp
+++ b/contrib/sb-bsd-sockets/protocol.lisp
@@ -58,23 +58,22 @@ peer."))
"Close SOCKET, unless it was already closed.
If SOCKET-MAKE-STREAM has been called, calls CLOSE using ABORT on that
-stream. Otherwise closes the socket file descriptor using
-close(2)."))
+stream. Otherwise closes the socket file descriptor using `close(2)`."))
(defgeneric socket-bind (socket &rest address)
(:documentation
"Bind SOCKET to ADDRESS, which may vary according to socket family.
-For the INET family, pass ADDRESS and PORT as two arguments; for FILE
-address family sockets, pass the filename string. See also bind(2)"))
+For the INET family, pass ADDRESS and PORT as two arguments; for local
+address family sockets, pass the filename string. See also `bind(2)`."))
(defgeneric socket-accept (socket)
(:documentation
- "Perform the accept(2) call, returning a newly-created connected
+ "Perform the `accept(2)` call, returning a newly-created connected
socket and the peer address as multiple values"))
(defgeneric socket-connect (socket &rest address)
(:documentation
- "Perform the connect(2) call to connect SOCKET to a remote PEER.
+ "Perform the `connect(2)` call to connect SOCKET to a remote PEER.
No useful return value."))
(defgeneric socket-receive (socket buffer length
@@ -82,13 +81,13 @@ No useful return value."))
oob peek waitall dontwait element-type)
(:documentation
"Read LENGTH octets from SOCKET into BUFFER (or a freshly-consed
-buffer if NIL), using recvfrom(2). If LENGTH is NIL, the length of
+buffer if NIL), using `recvfrom(2)`. If LENGTH is NIL, the length of
BUFFER is used, so at least one of these two arguments must be
non-NIL. If 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
-MSG_TRUNC so that the actual packet length is returned even if the
-buffer was too small."))
+`\\\\MSG_TRUNC` so that the actual packet length is returned even if
+the buffer was too small."))
(defgeneric socket-send (socket buffer length
&key
@@ -97,12 +96,12 @@ buffer was too small."))
oob eor dontroute dontwait nosignal
#+linux confirm #+linux more)
(:documentation
- "Send LENGTH octets from BUFFER into SOCKET, using sendto(2). If
+ "Send LENGTH octets from BUFFER into SOCKET, using `sendto(2)`. If
BUFFER is a string, it will converted to octets according to
EXTERNAL-FORMAT. If LENGTH is NIL, the length of the octet buffer is
used. The format of 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, send(2) will be called
+port). If no socket address is provided, `send(2)` will be called
instead. Returns the number of octets written."))
(defgeneric socket-listen (socket backlog)
@@ -110,7 +109,7 @@ instead. Returns the number of octets written."))
"Mark SOCKET as willing to accept incoming connections. The
integer BACKLOG defines the maximum length that the queue of pending
connections may grow to before new connection attempts are refused.
-See also listen(2)"))
+See also `listen(2)`."))
(defgeneric socket-shutdown (socket &key direction)
(:documentation
diff --git a/contrib/sb-bsd-sockets/sockopt.lisp b/contrib/sb-bsd-sockets/sockopt.lisp
index abd5aea0b..bc696bd87 100644
--- a/contrib/sb-bsd-sockets/sockopt.lisp
+++ b/contrib/sb-bsd-sockets/sockopt.lisp
@@ -52,7 +52,10 @@ Code for options that not every system has should be conditionalised:
`(progn
(export ',lisp-name)
(defun ,lisp-name (socket)
- ,@(when documentation (list (concatenate 'string documentation " " info)))
+ ,@(when documentation
+ (list (if (plusp (length info))
+ (format nil "~A ~A" documentation info)
+ documentation)))
,@(if supportedp
`((sb-alien:with-alien ((size sb-alien:int)
(buffer ,buffer-type))
@@ -135,9 +138,9 @@ Code for options that not every system has should be conditionalised:
(defmacro define-socket-option-bool (name level c-name &optional features (info ""))
`(define-socket-option ,name
- ,(format nil "~@<Return the value of the ~A socket option for SOCKET. ~
+ ,(format nil "~@<Return the value of the ~A socket option for SOCKET. ~
This can also be updated with SETF.~:@>"
- (symbol-name c-name))
+ (symbol-name c-name))
,level ,c-name
sb-alien:int bool-to-foreign-int foreign-int-to-bool sb-alien:addr
,features ,info))
diff --git a/contrib/sb-cltl2/env.lisp b/contrib/sb-cltl2/env.lisp
index e13c7c9d7..1ff43469b 100644
--- a/contrib/sb-cltl2/env.lisp
+++ b/contrib/sb-cltl2/env.lisp
@@ -180,18 +180,14 @@ Note that the global function binding may differ from the local one.
This function returns three values. The first indicates the type of
function definition or binding:
- NIL
- There is no apparent definition for NAME.
+- NIL: There is no apparent definition for NAME.
- :FUNCTION
- NAME refers to a function.
+- :FUNCTION: NAME refers to a function.
- :MACRO
- NAME refers to a macro.
+- :MACRO: NAME refers to a macro.
- :SPECIAL-FORM
- NAME refers to a special operator. If the name refers to both a
- macro and a special operator, the macro takes precedence.
+- :SPECIAL-FORM: NAME refers to a special operator. If the name refers
+ to both a macro and a special operator, the macro takes precedence.
The second value is true if NAME is bound locally.
@@ -199,26 +195,23 @@ The third value is an alist describing the declarations that apply to
the function NAME. Standard declaration specifiers that may appear in
CARS of the alist include:
- DYNAMIC-EXTENT
- If the CDR is T, NAME has been declared DYNAMIC-EXTENT. If the CDR
- is NIL, the alist element may be omitted.
+- DYNAMIC-EXTENT: If the CDR is T, NAME has been declared
+ DYNAMIC-EXTENT. If the CDR is NIL, the alist element may be omitted.
- INLINE
- The CDR is one of the symbols INLINE, NOTINLINE, or NIL, to
- indicate if the function has been declared INLINE or NOTINLINE. If
- the CDR is NIL the alist element may be omitted.
+- INLINE: The CDR is one of the symbols INLINE, NOTINLINE, or NIL, to
+ indicate if the function has been declared INLINE or NOTINLINE. If
+ the CDR is NIL the alist element may be omitted.
- FTYPE
- The CDR is the type specifier associated with NAME, or the symbol
- FUNCTION if there is functional type declaration or proclamation
- associated with NAME. If the CDR is FUNCTION the alist element may
- be omitted.
+- FTYPE: The CDR is the type specifier associated with NAME, or the
+ symbol FUNCTION if there is functional type declaration or
+ proclamation associated with NAME. If the CDR is FUNCTION the alist
+ element may be omitted.
- SB-EXT:DEPRECATED
- \(SBCL specific)
- The CDR is a plist containing the following properties
+- SB-EXT:DEPRECATED: (SBCL specific) The CDR is a plist containing the
+ following properties:
+
+ - :STATE ( :EARLY | :LATE | :FINAL )
- :STATE ( :EARLY | :LATE | :FINAL )
Use of :EARLY deprecated functions signals a STYLE-WARNING at
compile-time.
@@ -228,14 +221,16 @@ CARS of the alist include:
Use of :FINAL deprecated functions signals a full WARNING at
compile-time and an error at runtime.
- :SINCE (SOFTWARE VERSION)
- VERSION is a string designating the version since which the
- function has been deprecated. SOFTWARE is NIL or the name of
- the software to which VERSION refers, e.g. \"SBCL\" for
+ - :SINCE `(SOFTWARE VERSION)`
+
+ `VERSION` is a string designating the version since which the
+ function has been deprecated. `SOFTWARE` is NIL or the name of
+ the software to which `VERSION` refers, e.g. `\"SBCL\"` for
deprecated functions in SBCL.
- :REPLACEMENTS REPLACEMENTS
- When this property is present, REPLACEMENTS is a list of
+ - :REPLACEMENTS `REPLACEMENTS`
+
+ When this property is present, `REPLACEMENTS` is a list of
symbols naming functions that should be used instead of the
deprecated function.
@@ -314,27 +309,20 @@ Note that the global binding may differ from the local one.
This function returns three values. The first indicated the type of the variable
binding:
- NIL
- There is no apparent binding for NAME.
+- NIL: There is no apparent binding for NAME.
- :SPECIAL
- NAME refers to a special variable.
+- :SPECIAL: NAME refers to a special variable.
- :LEXICAL
- NAME refers to a lexical variable.
+- :LEXICAL: NAME refers to a lexical variable.
- :SYMBOL-MACRO
- NAME refers to a symbol macro.
+- :SYMBOL-MACRO: NAME refers to a symbol macro.
- :CONSTANT
- NAME refers to a named constant defined using DEFCONSTANT, or NAME
- is a keyword.
+- :CONSTANT: NAME refers to a named constant defined using
+ DEFCONSTANT, or NAME is a keyword.
- :GLOBAL
- NAME refers to a global variable. (SBCL specific extension.)
+- :GLOBAL: NAME refers to a global variable. (SBCL specific extension.)
- :ALIEN
- NAME refers to an alien variable. (SBCL specific extension.)
+- :ALIEN NAME refers to an alien variable. (SBCL specific extension.)
The second value is true if NAME is bound locally. This is currently
always NIL for special variables, although arguably it should be T
@@ -344,30 +332,26 @@ The third value is an alist describing the declarations that apply to
the function NAME. Standard declaration specifiers that may appear in
CARS of the alist include:
- DYNAMIC-EXTENT
- If the CDR is T, NAME has been declared DYNAMIC-EXTENT. If the CDR
- is NIL, the alist element may be omitted.
+- DYNAMIC-EXTENT: If the CDR is T, NAME has been declared
+ DYNAMIC-EXTENT. If the CDR is NIL, the alist element may be omitted.
- IGNORE
- If the CDR is T, NAME has been declared IGNORE. If the CDR is NIL,
- the alist element may be omitted.
+- IGNORE: If the CDR is T, NAME has been declared IGNORE. If the CDR
+ is NIL, the alist element may be omitted.
- TYPE
- The CDR is the type specifier associated with NAME, or the symbol
- T if there is explicit type declaration or proclamation associated
- with NAME. The type specifier may be equivalent to or a supertype
- of the original declaration. If the CDR is T the alist element may
- be omitted.
+- TYPE: The CDR is the type specifier associated with NAME, or the
+ symbol T if there is explicit type declaration or proclamation
+ associated with NAME. The type specifier may be equivalent to or a
+ supertype of the original declaration. If the CDR is T the alist
+ element may be omitted.
- SB-EXT:ALWAYS-BOUND
- \(SBCL specific)
- If CDR is T, NAME has been declared as SB-EXT:ALWAYS-BOUND
+- SB-EXT:ALWAYS-BOUND: (SBCL specific) If CDR is T, NAME has been
+ declared as SB-EXT:ALWAYS-BOUND.
- SB-EXT:DEPRECATED
- \(SBCL specific)
- The CDR is a plist containing the following properties
+- SB-EXT:DEPRECATED: (SBCL specific) The CDR is a plist containing the
+ following properties:
+
+ - :STATE ( :EARLY | :LATE | :FINAL )
- :STATE ( :EARLY | :LATE | :FINAL )
Use of :EARLY deprecated variables signals a STYLE-WARNING at
compile-time.
@@ -377,14 +361,16 @@ CARS of the alist include:
Use of :FINAL deprecated variables signals a full WARNING at
compile-time and an error at runtime.
- :SINCE (SOFTWARE VERSION)
- VERSION is a string designating the version since which the
- variable has been deprecated. SOFTWARE is NIL or the name of
- the software to which VERSION refers, e.g. \"SBCL\" for
+ - :SINCE `(SOFTWARE VERSION)`
+
+ `VERSION` is a string designating the version since which the
+ variable has been deprecated. `SOFTWARE` is NIL or the name of
+ the software to which `VERSION` refers, e.g. `\"SBCL\"` for
deprecated variables in SBCL.
- :REPLACEMENTS REPLACEMENTS
- When this property is present, REPLACEMENTS is a list of
+ - :REPLACEMENTS `REPLACEMENTS`
+
+ When this property is present, `REPLACEMENTS` is a list of
symbols naming variables that should be used instead of the
deprecated variable.
diff --git a/contrib/sb-concurrency/frlock.lisp b/contrib/sb-concurrency/frlock.lisp
index 90c0eab41..d1b172009 100644
--- a/contrib/sb-concurrency/frlock.lisp
+++ b/contrib/sb-concurrency/frlock.lisp
@@ -101,31 +101,30 @@ 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.
-FRlocks are 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 eg. 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.
+FRlocks are _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 FRLOCK-READ and FRLOCK-WRITE, but those
needing it can also use a lower-level interface.
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)))))
-"
+ ;; 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)))))"
.
#-new-frlock (
(mutex (make-mutex :name "FRLock mutex") :type mutex :read-only t)
@@ -212,14 +211,13 @@ Using FRLOCK-READ instead is recommended.
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))))
-"
+ (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))))"
(barrier (:read))
(values (frlock-pre-counter frlock)
(frlock-epoch frlock)))
@@ -247,7 +245,7 @@ set, and returns that as multiple values."
;; 0, they will still be holding on to the old epoch. While it is
;; extremely unlikely, it isn't quite "not before heath death of the
;; universe" stuff: a 30 bit counter can roll over in a couple of
- ;; seconds -- and a thread can easily be interrupted by eg. a timer for
+ ;; seconds -- and a thread can easily be interrupted by e.g. a timer for
;; that long, so a pathological system could be have a thread in a
;; danger-zone every second. Run that system for a year, and it would
;; have a 1 in 3 chance of hitting the incipient bug. Adding an epoch
@@ -268,7 +266,7 @@ set, and returns that as multiple values."
(defun grab-frlock-write-lock (frlock &key (wait-p t) timeout)
"Acquires FRLOCK for writing, invalidating existing and future read-tokens
for the duration. Returns T on success, and NIL if the lock wasn't acquired
-due to eg. a timeout. Using FRLOCK-WRITE instead is recommended."
+due to e.g. a timeout. Using FRLOCK-WRITE instead is recommended."
(without-interrupts
(allow-with-interrupts (%%grab-frlock-write-lock frlock wait-p timeout))))
diff --git a/contrib/sb-concurrency/mailbox.lisp b/contrib/sb-concurrency/mailbox.lisp
index 3225b6218..049ebba74 100644
--- a/contrib/sb-concurrency/mailbox.lisp
+++ b/contrib/sb-concurrency/mailbox.lisp
@@ -22,7 +22,7 @@ SEND-MESSAGE adds a message to the mailbox, RECEIVE-MESSAGE waits till
a message becomes available, whereas RECEIVE-MESSAGE-NO-HANG is a non-blocking
variant, and RECEIVE-PENDING-MESSAGES empties the entire mailbox in one go.
-Messages can be arbitrary objects"
+Messages can be arbitrary objects."
(queue (missing-arg) :type queue)
(semaphore (missing-arg) :type semaphore)
(name nil))
@@ -56,7 +56,7 @@ Messages can be arbitrary objects"
(declaim (ftype (sfunction (mailbox) unsigned-byte) mailbox-count))
(defun mailbox-count (mailbox)
- "Returns the number of messages currently in the mailbox."
+ "Returns the number of messages currently in MAILBOX."
(semaphore-count (mailbox-semaphore mailbox)))
(declaim (ftype (sfunction (mailbox) boolean) mailbox-empty-p))
@@ -66,8 +66,8 @@ Messages can be arbitrary objects"
(declaim (ftype (sfunction (mailbox) list) list-mailbox-messages))
(defun list-mailbox-messages (mailbox)
- "Returns a fresh list containing all the messages in the
-mailbox. Does not remove messages from the mailbox."
+ "Returns a fresh list containing all the messages in MAILBOX. Does not
+remove messages from the mailbox."
(list-queue-contents (mailbox-queue mailbox)))
(declaim (ftype (sfunction (mailbox t) null) send-message))
@@ -126,10 +126,10 @@ message could be received."
"Removes and returns all (or at most N) currently pending messages
from MAILBOX, or returns NIL if no messages are pending.
-Note: Concurrent threads may be snarfing messages during the run of
-this function, so even `X` and `Y` appearing right next to each other
-in the result does not necessarily mean that `Y` was the message sent
-right after `X`."
+> _Note_: Concurrent threads may be snarfing messages during the run
+> of this function, so even `X` and `Y` appearing right next to each
+> other in the result does not necessarily mean that `Y` was the
+> message sent right after `X`."
(prog* ((msgs '())
(sem (mailbox-semaphore mailbox))
(queue (mailbox-queue mailbox))
diff --git a/contrib/sb-cover/genhtml.lisp b/contrib/sb-cover/genhtml.lisp
index abc634280..b32629cc8 100644
--- a/contrib/sb-cover/genhtml.lisp
+++ b/contrib/sb-cover/genhtml.lisp
@@ -102,11 +102,11 @@ If 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 EXTERNAL-FORMAT parameter.
-If the keyword argument FORM-MODE has the value :CAR, the annotations in
-the coverage report will be placed on the CARs of any cons-forms, while if
-it has the value :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.
+If the keyword argument :FORM-MODE has the value :CAR, the annotations
+in the coverage report will be placed on the CARs of any cons-forms,
+while if it has the value :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.
The keyword argument IF-MATCHES should be a designator for a function
of one argument, called for the namestring of each file with code
diff --git a/contrib/sb-introspect/introspect.lisp b/contrib/sb-introspect/introspect.lisp
index 4eda5e3ca..7f29ed8b0 100644
--- a/contrib/sb-introspect/introspect.lisp
+++ b/contrib/sb-introspect/introspect.lisp
@@ -759,7 +759,7 @@ or a method combination name."
This can make previously garbage objects live.
SPACES should be a list of the symbols :DYNAMIC, :STATIC, :READ-ONLY,
-or :IMMOBILE on #+IMMOBILE-SPACE. The shorthand (:ALL) is also
+or :IMMOBILE on `#+IMMOBILE-SPACE`. The shorthand (:ALL) is also
accepted."
(let ((referrers '()))
(map-caller-code-components
@@ -1160,8 +1160,8 @@ actually contained in the object but found in certain well-known
indirect containers: FDEFINITIONs, EQL specializers, classes, and
thread-local symbol values in other threads fall into this category.
-NOTE: calling MAP-ROOT with a THREAD does not currently map over
-conservative roots from the thread registers and interrupt contexts.
+> _Note_: calling MAP-ROOT with a THREAD does not currently map over
+> conservative roots from the thread registers and interrupt contexts.
Experimental: interface subject to change."
(when (typep object '(or bignum float sb-sys:system-area-pointer
diff --git a/contrib/sb-manual/doc/beyond-ansi.lisp b/contrib/sb-manual/doc/beyond-ansi.lisp
index f4e39cd58..e66d1f639 100644
--- a/contrib/sb-manual/doc/beyond-ansi.lisp
+++ b/contrib/sb-manual/doc/beyond-ansi.lisp
@@ -1043,6 +1043,7 @@
the operations, producing its argument; the declaration is not
checked. In short: don't use it."
;; FIXME: It's not a macro.
+ #+nil
(sb-ext:truly-the macro)
"The SB-EXT:FREEZE-TYPE declaration declares that a type will never
change, which can make type testing (e.g. with TYPEP) more efficient
diff --git a/contrib/sb-manual/doc/compiler.lisp b/contrib/sb-manual/doc/compiler.lisp
index f88382826..6ff4dc23a 100644
--- a/contrib/sb-manual/doc/compiler.lisp
+++ b/contrib/sb-manual/doc/compiler.lisp
@@ -285,11 +285,11 @@
diagnostic message, it always displays the most specific (innermost)
responsible form. For example, compiling this function
- (defun bar (x)
- (let (a)
- (declare (fixnum a))
- (setq a (foo x))
- a))
+ (defun bar (x)
+ (let (a)
+ (declare (fixnum a))
+ (setq a (foo x))
+ a))
gives this error message
diff --git a/contrib/sb-manual/doc/ffi.lisp b/contrib/sb-manual/doc/ffi.lisp
index 7796381e3..abfdb0034 100644
--- a/contrib/sb-manual/doc/ffi.lisp
+++ b/contrib/sb-manual/doc/ffi.lisp
@@ -713,7 +713,7 @@
(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))
diff --git a/contrib/sb-manual/doc/sbcl.lisp b/contrib/sb-manual/doc/sbcl.lisp
index f2033a3f0..e1eb9c741 100644
--- a/contrib/sb-manual/doc/sbcl.lisp
+++ b/contrib/sb-manual/doc/sbcl.lisp
@@ -1,6 +1,17 @@
(in-package :sb-manual)
(defsection @sbcl-manual (:title "SBCL Manual")
+ #.(format nil "This manual – for SBCL version `~A`, generated _~A_ –
+ is part of the SBCL software system. See the `\\\\README` file for
+ more information.
+
+ This manual is largely derived from the manual for the CMUCL system,
+ which was produced at Carnegie Mellon University and later released
+ into the public domain. This manual is in the public domain and is
+ provided with absolutely no warranty. See the `\\\\COPYING` and
+ `\\\\CREDITS` files for more information."
+ (lisp-implementation-version)
+ (documentation-generation-date-string :long t))
(@support-and-bugs section)
(@introduction section)
(@starting-and-stopping section)
diff --git a/contrib/sb-md5/md5.lisp b/contrib/sb-md5/md5.lisp
index 501c521af..ff974b211 100644
--- a/contrib/sb-md5/md5.lisp
+++ b/contrib/sb-md5/md5.lisp
@@ -634,7 +634,7 @@ FINALIZE-MD5-STATE results in unspecified behaviour."
(defun md5sum-sequence (sequence &key (start 0) end)
"Calculate the MD5 message-digest of data in SEQUENCE, which should
-be a 1d simple-array with element type (unsigned-byte 8). On CMU CL
+be a 1d SIMPLE-ARRAY with element type (UNSIGNED-BYTE 8). On CMU CL
and SBCL non-simple and non-1d arrays with this element-type are also
supported."
(declare (optimize (speed 3) (safety 3) (space 0) (debug 1))
@@ -723,7 +723,7 @@ operations. This should be a multiple of 64, the MD5 block size."))
(defun md5sum-stream (stream)
"Calculate an MD5 message-digest of the contents of STREAM. Its
-element-type has to be (unsigned-byte 8). Use on character streams is
+element-type has to be (UNSIGNED-BYTE 8). Use on character streams is
DEPRECATED, as this will not work correctly on implementations with
CHAR-CODE-LIMIT > 256 and ignores character coding issues."
(declare (optimize (speed 3) (safety 3) (space 0) (debug 1)))
diff --git a/contrib/sb-posix/interface.lisp b/contrib/sb-posix/interface.lisp
index 06918ee1e..be51a8a6d 100644
--- a/contrib/sb-posix/interface.lisp
+++ b/contrib/sb-posix/interface.lisp
@@ -337,7 +337,7 @@
:documentation
"Process ID of the process holding the lock;
returned with `\\\\F_GETLK`."))
- (:documentation "Class representing locks used in fcntl(2)."))
+ (:documentation "Class representing locks used in `\\fcntl(2)`."))
(define-entry-point "fcntl" (fd cmd &optional (arg nil argp))
(if argp
(etypecase arg
@@ -1072,7 +1072,7 @@ not supported."
(defun syslog (priority format &rest args)
"Send a message to the syslog facility, with severity level
PRIORITY. The message will be formatted as by CL:FORMAT (rather
-than C's printf) with format string FORMAT and arguments ARGS."
+than C's `printf`) with format string FORMAT and arguments ARGS."
(flet ((syslog1 (priority message)
(alien-funcall (extern-alien
"syslog" (function void int
diff --git a/contrib/sb-posix/macros.lisp b/contrib/sb-posix/macros.lisp
index d74f71d56..2a704e275 100644
--- a/contrib/sb-posix/macros.lisp
+++ b/contrib/sb-posix/macros.lisp
@@ -5,7 +5,7 @@
Note that native namestring syntax is distinct from Lisp namestring syntax:
- \(pathname \"/foo*/bar\")
+ (pathname \"/foo*/bar\")
is a wild pathname with a pattern-matching directory component.
SB-EXT:PARSE-NATIVE-NAMESTRING may be used to construct Lisp pathnames that
@@ -15,16 +15,16 @@ 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 MY-DEFAULTS for which
+POSIX filename syntax into a pathname `MY-DEFAULTS` for which
- \(merge-pathnames (make-pathname :name \"FOO\" :case :common)
- my-defaults)
+ (merge-pathnames (make-pathname :name \"FOO\" :case :common)
+ my-defaults)
returns a pathname that denotes a file in the directory, supply a true
:AS-DIRECTORY argument to SB-EXT:PARSE-NATIVE-NAMESTRING. Likewise, to supply
the name of a directory to a POSIX function in non-directory syntax, supply a
true :AS-FILE argument to SB-EXT:NATIVE-NAMESTRING."
- "Designator for a FILENAME: a STRING designating itself, or a
+ "Designator for a [FILENAME][type]: a STRING designating itself, or a
designator for a PATHNAME designating the corresponding native namestring."
"Converts FILENAME-DESIGNATOR into a FILENAME.")
(pathname
@@ -43,8 +43,8 @@ native file descriptor.
Note that mixing I/O operations on a FILE-STREAM with operations directly on its
descriptor may produce unexpected results if the stream is buffered."
- "Designator for a FILE-DESCRIPTOR: either a fixnum designating itself, or
-a FILE-STREAM designating the underlying file-descriptor."
+ "Designator for a [FILE-DESCRIPTOR][type]: either a fixnum designating
+itself, or a FILE-STREAM designating the underlying file-descriptor."
"Converts FILE-DESCRIPTOR-DESIGNATOR into a FILE-DESCRIPTOR.")
(file-stream
(sb-sys:fd-stream-fd file-descriptor))
diff --git a/contrib/sb-sprof/call-counting.lisp b/contrib/sb-sprof/call-counting.lisp
index b61cb5be4..a111e27ae 100644
--- a/contrib/sb-sprof/call-counting.lisp
+++ b/contrib/sb-sprof/call-counting.lisp
@@ -20,8 +20,8 @@
"Mark the functions named by 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 X or (SETF X), where X is a symbol
-with the package as its home package."
+done for all functions with names like `X` or `(SETF X)`, where `X` is
+a symbol with the package as its home package."
(dolist (name names)
(if (stringp name)
(let ((package (find-package name)))
diff --git a/contrib/sb-sprof/interface.lisp b/contrib/sb-sprof/interface.lisp
index 938b36902..325217d5f 100644
--- a/contrib/sb-sprof/interface.lisp
+++ b/contrib/sb-sprof/interface.lisp
@@ -35,40 +35,49 @@ Returns the values from the last evaluation of BODY.
The following keyword args are recognized:
- :SAMPLE-INTERVAL <n>
- Take a sample every <n> seconds. Default is *SAMPLE-INTERVAL*.
+- :SAMPLE-INTERVAL `<n>`
- :MODE <mode>
- If :CPU, run the profiler in CPU profiling mode. If :ALLOC, run the
- profiler in allocation profiling mode. If :TIME, run the profiler
- in wallclock profiling mode.
+ Take a sample every <n> seconds. Default is *SAMPLE-INTERVAL*.
- :MAX-SAMPLES <max>
- If :LOOP is NIL (the default), collect no more than <max> samples.
- If :LOOP is T, repeat evaluating body until <max> samples are taken.
- Default is *MAX-SAMPLES*.
+- :MODE `<mode>`
- :REPORT <type>
- If specified, call REPORT with :TYPE <type> at the end.
+ If :CPU, run the profiler in CPU profiling mode. If :ALLOC, run
+ the profiler in allocation profiling mode. If :TIME, run the
+ profiler in wallclock profiling mode.
- :RESET <bool>
- If true, call RESET at the beginning.
+- :MAX-SAMPLES `<max>`
- :THREADS <list-form>
- Form that evaluates to the list threads to profile, or :ALL to indicate
- that all threads should be profiled. Defaults to all threads.
+ If :LOOP is NIL (the default), collect no more than `<max>`
+ samples. If :LOOP is T, repeat evaluating body until `<max>`
+ samples are taken. Default is *MAX-SAMPLES*.
- :THREADS has no effect on call-counting at the moment.
+- :REPORT `<type>`
- On some platforms (eg. Darwin) the signals used by the profiler are
- not properly delivered to threads in proportion to their CPU usage
- when doing :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 :MODE :TIME is likely to work better.
+ If specified, call REPORT with :TYPE `<type>` at the end.
- :LOOP <bool>
- If false (the default), evaluate BODY only once. If true repeatedly
- evaluate BODY."
+- :RESET `<bool>`
+
+ If true, call RESET at the beginning.
+
+- :THREADS `<list-form>`
+
+ Form that evaluates to the list threads to profile, or :ALL to
+ indicate that all threads should be profiled. Defaults to all
+ threads.
+
+ :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 :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 :MODE :TIME is
+ likely to work better.
+
+- :LOOP `<bool>`
+
+ If false (the default), evaluate BODY only once. If true
+ repeatedly evaluate BODY."
(declare (type report-type report))
(check-type loop boolean)
#-sb-thread (unless (eq threads :all) (warn ":THREADS is ignored"))
@@ -121,28 +130,33 @@ inappropriate set of sampled threads, or possibly a profiler bug.~:@>"))
"Start profiling statistically in the current thread if not already profiling.
The following keyword args are recognized:
- :SAMPLE-INTERVAL <n>
- Take a sample every <n> seconds. Default is *SAMPLE-INTERVAL*.
+- :SAMPLE-INTERVAL `<n>`
- :MODE <mode>
- If :CPU, run the profiler in CPU profiling mode. If :ALLOC, run
- the profiler in allocation profiling mode. If :TIME, run the profiler
- in wallclock profiling mode.
+ Take a sample every `<n>` seconds. Default is *SAMPLE-INTERVAL*.
- :MAX-SAMPLES <max>
- Maximum number of stack traces to collect. Default is *MAX-SAMPLES*.
+- :MODE `<mode>`
- :THREADS <list>
- List threads to profile, or :ALL to indicate that all threads should be
- profiled. Defaults to :ALL.
+ If :CPU, run the profiler in CPU profiling mode. If :ALLOC, run
+ the profiler in allocation profiling mode. If :TIME, run the
+ profiler in wallclock profiling mode.
- :THREADS has no effect on call-counting at the moment.
+- :MAX-SAMPLES `<max>`
- On some platforms (eg. Darwin) the signals used by the profiler are
- not properly delivered to threads in proportion to their CPU usage
- when doing :CPU profiling. If you see empty call graphs, or are obviously
- missing several samples from certain threads, you may be falling afoul
- of this."
+ Maximum number of stack traces to collect. Default is
+ *MAX-SAMPLES*.
+
+- :THREADS `<list>`
+
+ List threads to profile, or :ALL to indicate that all threads
+ should be profiled. Defaults to :ALL.
+
+ :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 :CPU profiling. If you see empty call graphs, or
+ are obviously missing several samples from certain threads, you
+ may be falling afoul of this."
;; Starting the clock with an interval of zero or negative is meaningless.
;; If, by 0, you mean STOP-PROFILING then you should use STOP-PROFILING.
(declare (type (real (0)) sample-interval))
diff --git a/contrib/sb-sprof/report.lisp b/contrib/sb-sprof/report.lisp
index b537580fe..9aed54ab8 100644
--- a/contrib/sb-sprof/report.lisp
+++ b/contrib/sb-sprof/report.lisp
@@ -223,41 +223,49 @@
"Report statistical profiling results. The following keyword
args are recognized:
- :TYPE <type>
- Specifies the type of report to generate. If :FLAT, show
- flat report, if :GRAPH show a call graph and a flat report.
- If nil, don't print out a report.
+ - :TYPE `<type>`
+
+ Specifies the type of report to generate. If :FLAT, show flat
+ report, if :GRAPH show a call graph and a flat report. If nil,
+ don't print out a report.
+
+ - :STREAM `<stream>`
- :STREAM <stream>
Specify a stream to print the report on. Default is
*STANDARD-OUTPUT*.
- :MAX <max>
- Don't show more than <max> entries in the flat report.
+ - :MAX `<max>`
- :MIN-PERCENT <min-percent>
- Don't show functions taking less than <min-percent> of the
+ Don't show more than `<max>` entries in the flat report.
+
+ - :MIN-PERCENT `<min-percent>`
+
+ Don't show functions taking less than `<min-percent>` of the
total time in the flat report.
- :SORT-BY <column>
+ - :SORT-BY `<column>`
+
If :SAMPLES, sort flat report by number of samples taken.
If :CUMULATIVE-SAMPLES, sort flat report by cumulative number of samples
taken (shows how much time each function spent on stack.) Default
is *REPORT-SORT-BY*.
- :SORT-ORDER <order>
+ - :SORT-ORDER `<order>`
+
If :DESCENDING, sort flat report in descending order. If :ASCENDING,
sort flat report in ascending order. Default is *REPORT-SORT-ORDER*.
- :SHOW-PROGRESS <bool>
+ - :SHOW-PROGRESS `<bool>`
+
If true, print progress messages while generating the call graph.
- :CALL-GRAPH <graph>
- Print a report from <graph> instead of the latest profiling
+ - :CALL-GRAPH `<graph>`
+
+ Print a report from `<graph>` instead of the latest profiling
results.
Value of this function is a CALL-GRAPH object representing the
-resulting call-graph, or NIL if there are no samples (eg. right after
+resulting call-graph, or NIL if there are no samples (e.g. right after
calling RESET.)
Profiling is stopped before the call graph is generated."
diff --git a/src/code/alien-callback.lisp b/src/code/alien-callback.lisp
index b55b1d695..811a5f4c9 100644
--- a/src/code/alien-callback.lisp
+++ b/src/code/alien-callback.lisp
@@ -275,9 +275,9 @@ Create new alien callable (old alien callable gets freed)."))
&body body
&environment env)
"Define an alien function which can be called by alien code. The alien
-function returned by (alien-callable-function NAME) expects alien
+function returned by (ALIEN-CALLABLE-FUNCTION NAME) expects alien
arguments of the specified `ARG-TYPE`s and returns an alien of type
-`RESULT-TYPE`.
+RESULT-TYPE.
TYPED-LAMBDA-LIST is a list of `(ARG-NAME ARG-TYPE)` elements, and
BODY is `{DOC-STRING} {DECL}* {FORM}*`.
diff --git a/src/code/array.lisp b/src/code/array.lisp
index f70d27cb5..20a768d31 100644
--- a/src/code/array.lisp
+++ b/src/code/array.lisp
@@ -1756,9 +1756,9 @@ vector. Multidimensional arrays, arrays with fill pointers, and adjustable
arrays have an underlying storage vector with the same ARRAY-ELEMENT-TYPE as
ARRAY, which this function returns.
-Important 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."
+> _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."
;; KLUDGE: Without TRULY-THE the system is not smart enough to figure out that
;; the return value is always of the known type.
(truly-the (simple-array * (*))
diff --git a/src/code/barrier.lisp b/src/code/barrier.lisp
index d267c7a0f..9fc87c60f 100644
--- a/src/code/barrier.lisp
+++ b/src/code/barrier.lisp
@@ -38,28 +38,27 @@ reordering.
KIND should be one of:
- :COMPILER
- Prevent the compiler from reordering memory access across the
- barrier.
- :MEMORY
- Prevent the cpu from reordering any memory access across the
- barrier.
- :READ
- Prevent the cpu from reordering any read access across the
- barrier.
- :WRITE
- Prevent the cpu from reordering any write access across the
- barrier.
- :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 :READ barrier.
+- :COMPILER: Prevent the compiler from reordering memory access across
+ the barrier.
-FORMS is an implicit PROGN, evaluated before the barrier. BARRIER
+- :MEMORY: Prevent the CPU from reordering any memory access across
+ the barrier.
+
+- :READ: Prevent the CPU from reordering any read access across the
+ barrier.
+
+- :WRITE: Prevent the cpu from reordering any write access across the
+ barrier.
+
+- :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 :READ barrier.
+
+FORMS is an implicit PROGN, evaluated before the barrier. BARRIER
returns the values of the last form in FORMS.
-The file \"memory-barriers.txt\" in the Linux kernel documentation is
+The file `memory-barriers.txt` in the Linux kernel documentation is
highly recommended reading for anyone programming at this level."
`(multiple-value-prog1
(progn ,@forms)
diff --git a/src/code/cold-init.lisp b/src/code/cold-init.lisp
index 6ed8b445a..46a4db48b 100644
--- a/src/code/cold-init.lisp
+++ b/src/code/cold-init.lisp
@@ -397,13 +397,13 @@ defaults to 0 when ABORT is false, and 1 when it is true.
When ABORT is false (the default), current thread is first unwound,
*EXIT-HOOKS* are run, other threads are terminated, and standard
-output streams are flushed before SBCL calls `exit`(3) -- at which point
-`atexit`(3) functions will run. If multiple threads call EXIT with ABORT
+output streams are flushed before SBCL calls `exit(3)` -- at which point
+`atexit(3)` functions will run. If multiple threads call EXIT with ABORT
being false, the first one to call it will complete the protocol.
-When ABORT is true, SBCL exits immediately by calling `_exit`(2)
-without unwinding stack, or calling exit hooks. Note that `_exit`(2)
-does not call `atexit`(3) functions unlike `exit`(3).
+When ABORT is true, SBCL exits immediately by calling `_exit(2)`
+without unwinding stack, or calling exit hooks. Note that `_exit(2)`
+does not call `atexit(3)` functions unlike `exit(3)`.
Recursive calls to EXIT cause EXIT to behave as if ABORT was true.
diff --git a/src/code/cross-early.lisp b/src/code/cross-early.lisp
index d958b073e..4fa4e078a 100644
--- a/src/code/cross-early.lisp
+++ b/src/code/cross-early.lisp
@@ -25,7 +25,12 @@
#+host-quirks-cmu
(declaim (notinline position position-if position-if-not))
-(defvar *default-source-external-format* :default)
+(defvar *default-source-external-format* :default
+ "If COMPILE-FILE's :EXTERNAL-FORMAT is :DEFAULT, the source file is
+ OPENed with *DEFAULT-SOURCE-EXTERNAL-FORMAT*. :DEFAULT, the default
+ value of this variable, tells OPEN to default to
+ *DEFAULT-EXTERNAL-FORMAT*. Since :DEFAULT is OPEN's default
+ :EXTERNAL-FORMAT, this is all very default.")
(defmacro defglobal (name value &rest doc)
`(eval-when (:compile-toplevel :load-toplevel :execute)
diff --git a/src/code/debug.lisp b/src/code/debug.lisp
index c1b5c0edd..0ea8659be 100644
--- a/src/code/debug.lisp
+++ b/src/code/debug.lisp
@@ -1758,20 +1758,21 @@ forms that explicitly control this kind of evaluation.")
;;; work! Alas, it doesn't seem to work in CMU CL X86 either..
(defun var (name &optional (id 0 id-supplied))
"Return a variable's value if possible. 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 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 return no values after displaying the ambiguous names. If name
- determines multiple variables with the same name, then you must use the
- optional id argument to specify which one you want. If you left id
- unspecified, then this returns no values after displaying the distinguishing
- id values.
+ 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 ID argument to specify which one you want. If
+ you left 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 SETF'able."
+ The result of this function is limited to the availability of
+ variable information. This is SETFable."
(define-var-operation :ref))
(defun (setf var) (value name &optional (id 0 id-supplied))
(define-var-operation :set value))
diff --git a/src/code/defpackage.lisp b/src/code/defpackage.lisp
index dde0627c0..fe00712b2 100644
--- a/src/code/defpackage.lisp
+++ b/src/code/defpackage.lisp
@@ -217,9 +217,9 @@ implementation it is ~S." *!default-package-use-list*)
(defmacro defpackage (package &rest options)
#.(format nil
"Defines a new package called PACKAGE. Each of OPTIONS should be one of the
- following: ~{~&~4T(~S ~A)~}
- All options except ~{~S, ~}and :DOCUMENTATION can be used multiple
- times."
+following:~% ~{~%~4T(~S ~A)~}~%
+All options except ~{~S, ~}and :DOCUMENTATION can be used multiple
+times."
'(:use "{package-name}*"
:export "{symbol-name}*"
:import-from "<package-name> {symbol-name}*"
diff --git a/src/code/filesys.lisp b/src/code/filesys.lisp
index 2ded542d5..75ba97188 100644
--- a/src/code/filesys.lisp
+++ b/src/code/filesys.lisp
@@ -621,8 +621,8 @@ Both
(DELETE-DIRECTORY \"/tmp/foo\")
(DELETE-DIRECTORY \"/tmp/foo/\")
-delete the \"foo\" subdirectory of \"/tmp\", or signal an error if it does not
-exist or if is a file or a symbolic link."
+delete the `\"foo\"` subdirectory of `\"/tmp\"`, or signal an error if
+it does not exist or if is a file or a symbolic link."
(declare (type pathname-designator pathspec))
(labels ((recurse-merged (dir)
(lambda (sub)
diff --git a/src/code/foreign-load.lisp b/src/code/foreign-load.lisp
index a6f3b642b..119bf63ad 100644
--- a/src/code/foreign-load.lisp
+++ b/src/code/foreign-load.lisp
@@ -33,17 +33,17 @@
container specified by designated PATHNAME, such as a .so on an ELF platform.
Locating the shared object follows standard rules of the platform, consult the
-manual page for `dlopen`(3) for details. Typically paths specified by
+manual page for `dlopen(3)` for details. Typically paths specified by
environment variables such as LD_LIBRARY_PATH are searched if the PATHNAME has
no directory, but on some systems (eg. Mac OS X) search may happen even if
-PATHNAME is absolute. (On Windows LoadLibrary is used instead of `dlopen`(3).)
+PATHNAME is absolute. (On Windows LoadLibrary is used instead of `dlopen(3)`.)
On non-Windows platforms calling LOAD-SHARED-OBJECT again with a PATHNAME
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 `dlopen`(3) on the
-same shared object or running on a system where `dlclose`(3) is a noop.
+may not work as expected if user or library-code has called `dlopen(3)` on the
+same shared object or running on a system where `dlclose(3)` is a noop.
LOAD-SHARED-OBJECT interacts with SB-EXT:SAVE-LISP-AND-DIE:
diff --git a/src/code/gc.lisp b/src/code/gc.lisp
index cd7b2b92d..7380e7b83 100644
--- a/src/code/gc.lisp
+++ b/src/code/gc.lisp
@@ -57,11 +57,11 @@
(declaim (ftype (sfunction () unsigned-byte) get-bytes-consed))
(defun 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
-SB-PROFILE package does), or to design a more microefficient interface
-and submit it as a patch."
+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 `SB-PROFILE` package does), or to design a
+more microefficient interface and submit it as a patch."
(+ (dynamic-usage)
*n-bytes-freed-or-purified*))
@@ -333,7 +333,7 @@ collection is initiated. This can be set with SETF.
On GENCGC platforms this is the nursery size, and defaults to 5% of dynamic
space size.
-Note: currently changes to this value are lost when saving core."
+Note that currently, changes to this value are lost when saving core."
(extern-alien "bytes_consed_between_gcs" os-vm-size-t))
(defun (setf bytes-consed-between-gcs) (val)
diff --git a/src/code/globals.lisp b/src/code/globals.lisp
index d4e78e73d..79b19b005 100644
--- a/src/code/globals.lisp
+++ b/src/code/globals.lisp
@@ -92,7 +92,9 @@
(define-thread-local *load-pathname* nil)
#+ansi-compliant-load-truename (define-thread-local *load-truename* nil)
-(defvar *default-external-format* :utf-8)
+(defvar *default-external-format* :utf-8
+ "Most functions interacting with external formats (OPEN, notably)
+ use this default.")
(defvar *default-source-external-format*
#+win32 '(:default :newline :crlf)
#-win32 :default)
diff --git a/src/code/macros.lisp b/src/code/macros.lisp
index 177ce8bdf..102380f4c 100644
--- a/src/code/macros.lisp
+++ b/src/code/macros.lisp
@@ -1805,38 +1805,38 @@ invoked. In that case it will store into PLACE and start over."
(defun get-cas-expansion (place &optional environment)
"Analogous to GET-SETF-EXPANSION. Returns the following six values:
- * list of temporary variables
+* list of temporary variables
- * list of value-forms whose results those variable must be bound
+* list of value-forms whose results those variable must be bound
- * temporary variable for the old value of PLACE
+* temporary variable for the old value of PLACE
- * temporary variable for the new value of PLACE
+* temporary variable for the new value of PLACE
- * form using the aforementioned temporaries which performs the
- compare-and-swap operation on PLACE
+* form using the aforementioned temporaries which performs the
+ compare-and-swap operation on PLACE
- * form using the aforementioned temporaries with which to perform a volatile
- read of PLACE
+* form using the aforementioned temporaries with which to perform a volatile
+ read of PLACE
Example:
- (get-cas-expansion '(car x))
- ; => (#:CONS871), (X), #:OLD872, #:NEW873,
- ; (SB-KERNEL:%COMPARE-AND-SWAP-CAR #:CONS871 #:OLD872 :NEW873).
- ; (CAR #:CONS871)
+ (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))))
+ (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))))
EXPERIMENTAL: Interface subject to change."
;; FIXME: this seems wrong on two points:
@@ -1945,8 +1945,7 @@ SB-MOP:SLOT-VALUE-USING-CLASS, (SETF SB-MOP:SLOT-VALUE-USING-CLASS), or
SB-MOP:SLOT-BOUNDP-USING-CLASS.
Additionally, the PLACE can be a anything for which a CAS-function has
-been defined. (See SB-EXT:CAS for more information.)
-"
+been defined."
`(cas ,place ,old ,new))
@@ -2049,20 +2048,25 @@ been defined. (See SB-EXT:CAS for more information.)
the increment.
PLACE must access one of the following:
- - a DEFSTRUCT slot with declared type (UNSIGNED-BYTE ~D~:*)
- or AREF of a (SIMPLE-ARRAY (UNSIGNED-BYTE ~D~:*) (*))
- The type SB-EXT:WORD can be used for these purposes.
- - CAR or CDR (respectively FIRST or REST) of a CONS.
- - a variable defined using DEFGLOBAL with a proclaimed type of FIXNUM.
-Macroexpansion is performed on PLACE before expanding ATOMIC-INCF.
-
-Incrementing is done using modular arithmetic,
-which is well-defined over two different domains:
+
+- a DEFSTRUCT slot with declared type (UNSIGNED-BYTE ~D~:*)
+ or AREF of a (SIMPLE-ARRAY (UNSIGNED-BYTE ~D~:*) (*))
+ The type SB-EXT:WORD can be used for these purposes.
+
+- CAR or CDR (respectively FIRST or REST) of a CONS.
+
+- a variable defined using DEFGLOBAL with a proclaimed type of FIXNUM.
+ Macroexpansion is performed on PLACE before expanding ATOMIC-INCF.
+
+Incrementing is done using modular arithmetic, which is well-defined
+over two different domains:
+
- For structures and arrays, the operation accepts and produces
an (UNSIGNED-BYTE ~D~:*), and DIFF must be of type (SIGNED-BYTE ~D).
- ATOMIC-INCF of #x~x by one results in #x0 being stored in PLACE.
+ ATOMIC-INCF of `#x~x` by one results in #x0 being stored in PLACE.
+
- For other places, the domain is FIXNUM, and DIFF must be a FIXNUM.
- ATOMIC-INCF of #x~x by one results in #x~x
+ ATOMIC-INCF of `#x~x` by one results in `#x~x`
being stored in PLACE.
DIFF defaults to 1.
@@ -2078,21 +2082,28 @@ EXPERIMENTAL: Interface subject to change."
the decrement.
PLACE must access one of the following:
- - a DEFSTRUCT slot with declared type (UNSIGNED-BYTE ~D~:*)
- or AREF of a (SIMPLE-ARRAY (UNSIGNED-BYTE ~D~:*) (*))
- The type SB-EXT:WORD can be used for these purposes.
- - CAR or CDR (respectively FIRST or REST) of a CONS.
- - a variable defined using DEFGLOBAL with a proclaimed type of FIXNUM.
+
+- a DEFSTRUCT slot with declared type `(UNSIGNED-BYTE ~D~:*)` or AREF
+ of a `(SIMPLE-ARRAY (UNSIGNED-BYTE ~D~:*) (*))` (the type
+ SB-EXT:WORD can be used for these purposes)
+
+- CAR or CDR (respectively FIRST or REST) of a CONS,
+
+- a variable defined using DEFGLOBAL with a proclaimed type of FIXNUM.
+
Macroexpansion is performed on PLACE before expanding ATOMIC-DECF.
Decrementing is done using modular arithmetic,
which is well-defined over two different domains:
+
- For structures and arrays, the operation accepts and produces
- an (UNSIGNED-BYTE ~D~:*), and DIFF must be of type (SIGNED-BYTE ~D).
- ATOMIC-DECF of #x0 by one results in #x~x being stored in PLACE.
+ an (UNSIGNED-BYTE ~D~:*), and DIFF must be of type `(SIGNED-BYTE
+ ~D)`. ATOMIC-DECF of `#x0` by one results in `#x~x` being stored in
+ PLACE.
+
- For other places, the domain is FIXNUM, and DIFF must be a FIXNUM.
- ATOMIC-DECF of #x~x by one results in #x~x
- being stored in PLACE.
+ ATOMIC-DECF of `#x~x` by one results in `#x~x` being stored in
+ PLACE.
DIFF defaults to 1.
diff --git a/src/code/misc-aliens.lisp b/src/code/misc-aliens.lisp
index 6c8d73139..e8bc74cb3 100644
--- a/src/code/misc-aliens.lisp
+++ b/src/code/misc-aliens.lisp
@@ -87,7 +87,13 @@
(declaim (maybe-inline get-errno))
(define-alien-routine ("os_get_errno" get-errno) int)
(setf (documentation 'get-errno 'function)
- "Return the value of the C library pseudo-variable named \"errno\".")
+ "Return the value of the \\C library pseudo-variable named `errno`.
+
+Since in modern \\C libraries, `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 DEFINE-ALIEN-VARIABLE
+mechanism.")
(define-alien-routine ("os_set_errno" set-errno) void (new-errno int))
(setf (documentation 'set-errno 'function)
diff --git a/src/code/module.lisp b/src/code/module.lisp
index a7e066fb6..0781a5a30 100644
--- a/src/code/module.lisp
+++ b/src/code/module.lisp
@@ -22,7 +22,7 @@
It is used by PROVIDE and REQUIRE.")
(defvar *module-provider-functions* (list 'module-provide-contrib)
- "See function documentation for REQUIRE.")
+ "See REQUIRE.")
;;;; PROVIDE and REQUIRE
diff --git a/src/code/ntrace.lisp b/src/code/ntrace.lisp
index d17ca1b57..7c2ef8cf2 100644
--- a/src/code/ntrace.lisp
+++ b/src/code/ntrace.lisp
@@ -686,17 +686,18 @@ functions are called. In its simplest form:
(TRACE NAME-1 NAME-2 ...)
The NAMEs are not evaluated. Each may be one of the following:
- * SYMBOL, denoting a function or macro.
- * FNAME, a valid function name, denoting a function.
- * `(METHOD FNAME QUALIFIERS* (SPECIALIZERS*))` denoting a method.
- * `(COMPILER-MACRO SYMBOL)` denoting a compiler macro.
- * `(LABELS FNAME :IN OUTER-NAME)` or `(FLET FNAME :IN OUTER-NAME)`
- denoting a local function where `OUTER-NAME` may be any of the
- previous names for functions, macros, methods or compiler macros.
- Tracing local functions may require DEBUG policy 3 to inhibit
- inlining.
- * STRING denoting all functions fbound to symbols whose home package
- is the package with the given name.
+
+- SYMBOL, denoting a function or macro.
+- FNAME, a valid function name, denoting a function.
+- `(METHOD FNAME QUALIFIERS* (SPECIALIZERS*))` denoting a method.
+- `(COMPILER-MACRO SYMBOL)` denoting a compiler macro.
+- `(LABELS FNAME :IN OUTER-NAME)` or `(FLET FNAME :IN OUTER-NAME)`
+ denoting a local function where `OUTER-NAME` may be any of the
+ previous names for functions, macros, methods or compiler macros.
+ Tracing local functions may require DEBUG policy 3 to inhibit
+ inlining.
+- STRING denoting all functions fbound to symbols whose home package
+ is the package with the given name.
Options allow modification of the default behavior. Each option is a
pair of an option keyword and a value form. Global options are
@@ -779,9 +780,9 @@ The following options are defined:
:CONDITION, :BREAK and :PRINT forms are evaluated in a context which
mocks up the lexical environment of the called function, so that
SB-DEBUG:VAR and SB-DEBUG:ARG can be used.
-The -AFTER and -ALL forms can use also use SB-DEBUG:ARG. In forms
-which are evaluated after the function call, (SB-DEBUG:ARG N) returns
-the N-th value returned by the function."
+The `*-AFTER` and `*-ALL` forms can use also use SB-DEBUG:ARG. In forms
+which are evaluated after the function call, `(SB-DEBUG:ARG N)` returns
+the `N`th value returned by the function."
(if specs
(expand-trace specs)
'(%list-traced-funs)))
diff --git a/src/code/print.lisp b/src/code/print.lisp
index 9ba59ba2c..c52dd184e 100644
--- a/src/code/print.lisp
+++ b/src/code/print.lisp
@@ -54,7 +54,7 @@ structures are printed with #n#.")
"The position of the right margin in ems (for pretty-printing).")
(defvar *print-miser-width* nil
"If the remaining space between the current column and the right margin
- is less than this, then print using ``miser-style'' output. Miser
+ is less than this, then print using \"miser-style\" output. Miser
style conditional newlines are turned on, and all indentations are
turned off. If NIL, never use miser mode.")
(defvar *print-pprint-dispatch*
diff --git a/src/code/profile.lisp b/src/code/profile.lisp
index 3af48279f..4327e641b 100644
--- a/src/code/profile.lisp
+++ b/src/code/profile.lisp
@@ -296,9 +296,7 @@
(values))
(defmacro profile (&rest names)
- "PROFILE Name*
-
- If no names are supplied, return the list of profiled functions.
+ "If no names are supplied, return the list of profiled functions.
If names are supplied, wrap profiling code around the named functions.
As in TRACE, the names are not evaluated. A symbol names a function.
diff --git a/src/code/run-program.lisp b/src/code/run-program.lisp
index 84259d90d..3304d8ea5 100644
--- a/src/code/run-program.lisp
+++ b/src/code/run-program.lisp
@@ -47,7 +47,7 @@
#-win32
(defun posix-environ ()
- "Return the Unix environment (\"man environ\") as a list of SIMPLE-STRINGs."
+ "Return the Unix environment as a list of SIMPLE-STRINGs. See `man environ`."
(c-strings->string-list (extern-alien environ (* c-string))))
#+win32
@@ -290,8 +290,9 @@ PROCESS."
#-win32
(defun process-kill (process signal &optional (whom :pid))
"Hand SIGNAL to PROCESS. If WHOM is :PID, use the kill Unix system call. If
- WHOM is :PROCESS-GROUP, use the killpg Unix system call.
- Returns T if successful, otherwise returns NIL and error number (two values)."
+ WHOM is :PROCESS-GROUP, use the `killpg(1)` Unix system call.
+ Returns T if successful, otherwise returns NIL and error
+ number (two values)."
(let ((pid (process-pid process)))
(let ((result (ecase whom
(:process-group
@@ -774,6 +775,7 @@ The &KEY arguments have the following meanings:
the current process.
- :ENV
+
An alternative lossy representation of the new Unix environment,
for compatibility with CMU CL.
@@ -807,7 +809,7 @@ The &KEY arguments have the following meanings:
- :STREAM: the PROCESS-INPUT slot is filled in with a stream that
sends its output to the process.
-- :IF-INPUT-DOES-NOT-EXIST (when :INPUT is the name of a file)
+- :IF-INPUT-DOES-NOT-EXIST (when :INPUT is the name of a file)
It is one of:
@@ -834,12 +836,12 @@ The &KEY arguments have the following meanings:
- :IF-OUTPUT-EXISTS (when :OUTPUT is the name of a file)
- It is one of:
+ It is one of:
- - :ERROR (the default) to generate an error
- - :SUPERSEDE to supersede the file with output from the program
- - :APPEND to append output from the program to the file
- - NIL to return NIL from RUN-PROGRAM, without doing anything
+ - :ERROR (the default) to generate an error
+ - :SUPERSEDE to supersede the file with output from the program
+ - :APPEND to append output from the program to the file
+ - NIL to return NIL from RUN-PROGRAM, without doing anything
- :IF-ERROR-EXISTS
@@ -877,11 +879,13 @@ Windows specific options:
The following options control how the subprocess window should be
displayed: `:HIDE`, `:SHOW-NORMAL`, `:SHOW-MAXIMIZED`,
`:SHOW-MINIMIZED`, `:SHOW-NO-ACTIVATE`, `:SHOW-MIN-NO-ACTIVE`,
- `:SHOW-NA`. 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 `cmd /c start` to
- consistently display a console window or use the `:WINDOW` `:HIDE`
- option to consistently hide the console window."
+ `:SHOW-NA`.
+
+ > _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 `cmd /c start` to
+ > consistently display a console window or use the `:WINDOW`
+ > `:HIDE` option to consistently hide the console window."
(when (and env-p environment-p)
(error "can't specify :ENV and :ENVIRONMENT simultaneously"))
(let* (;; Clear various specials used by GET-DESCRIPTOR-FOR to
diff --git a/src/code/save.lisp b/src/code/save.lisp
index 4655e1f77..b612473a7 100644
--- a/src/code/save.lisp
+++ b/src/code/save.lisp
@@ -114,9 +114,10 @@ The following &KEY arguments are defined:
- :TOPLEVEL
The function to run when the created core file is resumed. The
- default function handles command line toplevel option processing
- and runs the top level read-eval-print loop. This function
- returning is equivalent to (SB-EXT:EXIT :CODE 0) being called.
+ default function handles command line toplevel option
+ processing (see SB-MANUAL:@TOPLEVEL-OPTIONS) and runs the top
+ level read-eval-print loop. This function returning is equivalent
+ to (SB-EXT:EXIT :CODE 0) being called.
TOPLEVEL functions should always provide an ABORT restart:
otherwise code they call will run without one.
@@ -130,13 +131,13 @@ The following &KEY arguments are defined:
- :SAVE-RUNTIME-OPTIONS
- If true, values of runtime options --dynamic-space-size and
- --control-stack-size that were used to start SBCL are stored in
+ If true, values of runtime options `--dynamic-space-size` and
+ `--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
- :ACCEPT-RUNTIME-OPTIONS then --dynamic-space-size and
- --control-stack-size are still processed by the runtime.
+ :ACCEPT-RUNTIME-OPTIONS then `--dynamic-space-size` and
+ `--control-stack-size` are still processed by the runtime.
Meaningless if :EXECUTABLE is NIL.
- :CALLABLE-EXPORTS
@@ -210,13 +211,16 @@ be 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:
- * 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.
- * 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.
+
+- 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.
+
+- 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.
+
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."
diff --git a/src/code/stubs.lisp b/src/code/stubs.lisp
index 0ccb4c952..bdaf5f1af 100644
--- a/src/code/stubs.lisp
+++ b/src/code/stubs.lisp
@@ -176,6 +176,15 @@
(def %numerator)
(def %denominator))
+;;; Document only those that SB-MANUAL:@UNTYPED-MEMORY singles out as
+;;; examples.
+(setf (documentation 'int-sap 'function)
+ "Creates a SAP pointing at the virtual address `X`.")
+(setf
+ (documentation 'sap-ref-32 'function)
+ "Access the value of the memory location at OFFSET bytes from SAP. SETFable.")
+(setf (documentation 'sap= 'function) "Compare the SAPs X and Y for equality.")
+
#+sb-simd-pack
(macrolet ((def (name)
`(defun ,name (pack)
diff --git a/src/code/target-alieneval.lisp b/src/code/target-alieneval.lisp
index b2fa2593e..19ad54179 100644
--- a/src/code/target-alieneval.lisp
+++ b/src/code/target-alieneval.lisp
@@ -56,10 +56,31 @@
(oops))))))
(defmacro define-alien-variable (name type &environment env)
- "Define NAME as an external alien variable of type TYPE. NAME should
-be a list of a string holding the alien name and a symbol to use as
-the Lisp name. If NAME is just a symbol or string, then the other name
-is guessed from the one supplied."
+ "Define NAME as an external alien variable of type TYPE.
+ Neither is evaluated.
+
+ In its full form, NAME is `(<ALIEN-NAME-STRING>
+ <LISP-NAME-SYMBOL>)`. If NAME is just a symbol or string, then the
+ other name is guessed from the one supplied as described
+ SB-MANUAL:@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 TYPE. Someday, they may well be
+ implemented using the ANSI 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 `foo`, one could write
+
+ (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)"
(multiple-value-bind (lisp-name alien-name) (pick-lisp-and-alien-names name)
(with-auxiliary-alien-types env
(let ((alien-type (parse-alien-type type env)))
@@ -92,13 +113,14 @@ variable is undefined."
(error 'unbound-variable :name symbol))))
(defmacro extern-alien (name type &environment env)
- "Access the alien variable named NAME, assuming it is of type TYPE.
-This is SETFable."
+ "Return an alien of TYPE which points to an externally defined value of NAME.
+ NAME is not evaluated and may be either a string or a symbol. TYPE
+ is an unevaluated alien type specifier. SETFable."
(let* ((name (if (and env (constantp name env)) (constant-form-value name env) name))
(alien-name (possibly-base-stringize
(etypecase name
- (symbol (guess-alien-name-from-lisp-name name))
- (string name))))
+ (symbol (guess-alien-name-from-lisp-name name))
+ (string name))))
(alien-type (parse-alien-type type env))
(datap (not (alien-fun-type-p alien-type))))
`(%alien-value (foreign-symbol-sap ,alien-name ,datap) 0 ',alien-type)))
@@ -135,16 +157,40 @@ This is SETFable."
`(alien-funcall-into ,func-expr ,var ,@args)))))
(defmacro with-alien (bindings &body body &environment env)
- "Establish some local alien variables. Each of BINDINGS is of the form:
+ "Establish some local alien variables of dynamic extent.
+ Each of BINDINGS is of the form:
VAR TYPE [ ALLOCATION ] [ INITIAL-VALUE | EXTERNAL-NAME ]
`ALLOCATION` should be one of:
- :LOCAL (the default)
- The alien is allocated on the stack, and has dynamic extent.
- :EXTERN
- No alien is allocated, but VAR is established as a local name for
- the external alien given by `EXTERNAL-NAME`."
+
+ - :LOCAL (the default): The alien is allocated on the stack, and
+ has dynamic extent.
+
+ - :EXTERN: No alien is allocated, but `VAR` is established as a
+ local name for the external alien given by `EXTERNAL-NAME`.
+
+ `VAR`s are established as symbol-macros; the bindings have lexical
+ scope, and may be assigned with SETQ or SETF.
+
+ The WITH-ALIEN macro also establishes a new scope for named
+ structures and unions. Any 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 `FOO` can be referenced by its name using
+ `(STRUCT FOO)`.
+
+ When a foreign function returns a structure by value, using
+ ALIEN-FUNCALL as the `INITIAL-VALUE` allows the returned struct to
+ be stack-allocated directly into the local variable's storage,
+ avoiding heap allocation:
+
+ (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)))"
;; FIXME:
;; :STATIC
;; The alien is allocated on the heap, and has infinite extent. The alien
@@ -259,15 +305,17 @@ This is SETFable."
(zerop (sap-int (alien-sap x))))
(defmacro sap-alien (sap type &environment env)
- "Convert the system area pointer SAP to an ALIEN of the specified TYPE (not
- evaluated.) TYPE must be pointer-like."
+ "Convert the SYSTEM-AREA-POINTER SAP to an ALIEN of the specified
+ TYPE (not evaluated). TYPE must be pointer-like (foreign pointer,
+ array, or record type)."
(let ((alien-type (parse-alien-type type env)))
(if (eq (compute-alien-rep-type alien-type) 'system-area-pointer)
`(%sap-alien ,sap ',alien-type)
(error "cannot make an alien of type ~S out of a SAP" type))))
(defun alien-sap (alien)
- "Return a System-Area-Pointer pointing to Alien's data."
+ "Return a SYSTEM-AREA-POINTER pointing to ALIEN's data.
+ ALIEN must be of some foreign pointer, array, or record type."
(declare (type alien-value alien))
(alien-value-sap alien))
@@ -276,8 +324,8 @@ This is SETFable."
(defmacro make-alien (type &optional size &environment env)
"Allocate an alien of type 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 `malloc`(3), so it can
-be passed to foreign functions which use `free`(3), or released using
+contain garbage. The memory is allocated using `malloc(3)`, so it can
+be passed to foreign functions which use `free(3)`, or released using
FREE-ALIEN.
For alien stack allocation, see macro WITH-ALIEN.
@@ -293,7 +341,7 @@ interpreted depends on TYPE:
* When TYPE is any other foreign type, then an object for that type is
allocated, and a pointer to it is returned. So
- (make-alien int) returns a (* int).
+ (MAKE-ALIEN INT) returns a (* INT).
If SIZE is specified, then a block of that many objects is
allocated, with the result pointing to the first one.
@@ -381,7 +429,7 @@ Examples:
(declaim (inline free-alien))
(defun free-alien (alien)
"Dispose of the storage pointed to by ALIEN. The ALIEN must have been
-allocated by MAKE-ALIEN, MAKE-ALIEN-STRING or `malloc`(3)."
+allocated by MAKE-ALIEN, MAKE-ALIEN-STRING or `malloc(3)`."
(alien-funcall (extern-alien "free" (function (values) system-area-pointer))
(alien-sap alien))
nil)
@@ -408,7 +456,7 @@ allocated by MAKE-ALIEN, MAKE-ALIEN-STRING or `malloc`(3)."
(external-format :default)
(null-terminate t))
"Copy part of STRING delimited by START and END into freshly
-allocated foreign memory, freeable using `free`(3) or FREE-ALIEN.
+allocated foreign memory, freeable using `free(3)` or FREE-ALIEN.
Returns the allocated string as a (* CHAR) alien, and the number of
bytes allocated as secondary value.
@@ -439,7 +487,12 @@ null byte."
;;; Extract the value from the named slot from the record ALIEN. If
;;; ALIEN is actually a pointer, then DEREF it first.
(defun slot (alien slot)
- "Extract SLOT from the Alien STRUCT or UNION ALIEN. May be set with SETF."
+ "Extract the value of the slot named SLOT from a foreign STRUCT or
+ UNION ALIEN. If ALIEN is a pointer to a structure or union, then it
+ is automatically dereferenced. SETFable.
+
+ Note that SLOT is evaluated, and need not be a compile-time
+ constant (but only constant slot accesses are efficiently compiled)."
(declare (type alien-value alien)
(type symbol slot))
(let ((type (alien-value-type alien)))
@@ -528,9 +581,11 @@ null byte."
;;; Dereference the alien and return the results.
(defun deref (alien &rest indices)
- "Dereference an Alien pointer or array. If an array, the indices are used
- as the indices of the array element to access. If a pointer, one index can
- optionally be specified, giving the equivalent of C pointer arithmetic."
+ "Dereference an 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. SETFable."
(declare (type alien-value alien)
(type list indices))
(multiple-value-bind (target-type offset) (deref-guts alien indices)
@@ -633,8 +688,9 @@ null byte."
;;;; the ADDR macro
(defmacro addr (expr &environment env)
- "Return an Alien pointer to the data addressed by Expr, which must be a call
- to SLOT or DEREF, or a reference to an Alien variable."
+ "Return an Alien pointer to the data addressed by EXPR,
+ which must be a foreign variable, a call to DEREF or SLOT, or a use
+ of EXTERN-ALIEN."
(let ((form (%macroexpand expr env)))
(or (typecase form
(cons
@@ -668,8 +724,11 @@ null byte."
;;;; the CAST macro
(defmacro cast (alien type &environment env)
- "Convert ALIEN to an Alien of the specified TYPE (not evaluated.) Both types
- must be Alien array, pointer or function types."
+ "Convert ALIEN to an Alien of the specified TYPE (not evaluated).
+ Both types must be Alien array, pointer or function types.
+
+ Note that the resulting Lisp foreign variable object is not EQ to
+ the argument, but it points to the same foreign memory address."
`(%cast ,alien ',(parse-alien-type type env)))
(defun %cast (alien target-type)
@@ -756,8 +815,40 @@ null byte."
;;;; ALIEN-FUNCALL, DEFINE-ALIEN-ROUTINE
(defun alien-funcall (alien &rest args)
- "Call the foreign function ALIEN with the specified arguments. ALIEN's
-type specifies the argument and result types."
+ "Call the foreign function ALIEN with ARGS and return its C return value
+ as a Lisp value. ALIEN's foreign type specifies the argument and
+ result types. ALIEN is typically an EXTERN-ALIEN or a value defined
+ with DEFINE-ALIEN-ROUTINE.
+
+ The type of ALIEN must be `(ALIEN (FUNCTION ...))` or `(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
+ and AAPCS64 specifications respectively.
+
+ Here is an example which allocates a `(STRUCT FOO)`, calls a foreign
+ function to initialize it, then returns a Lisp vector of all
+ the `(* (STRUCT FOO))` objects filled in by the foreign call:
+
+ ;; Allocate a foo on the stack.
+ (with-alien ((f (struct foo)))
+ ;; Call some C function to fill in foo fields.
+ (alien-funcall (extern-alien \"mangle_foo\" (function void (* foo)))
+ (addr f))
+ ;; Find how many foos to use by getting the A field.
+ (let* ((num (slot f 'a))
+ (result (make-array num)))
+ ;; Get a pointer to the array so that we don't have to keep extracting it:
+ (with-alien ((a (* (array (* (struct foo)) 100)) (addr (slot f 'b))))
+ ;; Loop over the first N elements and stash them in the result vector.
+ (dotimes (i num)
+ (setf (svref result i) (deref (deref a) i)))
+ ;; Voila.
+ result)))"
(declare (type alien-value alien))
(let ((type (alien-value-type alien)))
(typecase type
@@ -788,8 +879,23 @@ type specifies the argument and result types."
#+(or x86-64 arm64)
(defun alien-funcall-into (alien result-buffer &rest args)
"Call the foreign function ALIEN, writing the struct result to RESULT-BUFFER.
-RESULT-BUFFER should be a system-area-pointer to appropriately sized memory.
-Only supported on x86-64 and ARM64."
+Returns no values.
+
+RESULT-BUFFER should be a SYSTEM-AREA-POINTER to appropriately sized memory.
+Only supported on x86-64 and ARM64.
+
+Here is an example that calls a C function returning a struct, writing
+the result to a stack-allocated buffer:
+
+ (define-alien-type nil (struct point (x double) (y double)))
+
+ (with-alien ((result (struct point)))
+ (alien-funcall-into
+ (extern-alien \"make_point\"
+ (function (struct point) double double))
+ (alien-sap (addr result))
+ 1.0d0 2.0d0)
+ (values (slot result 'x) (slot result 'y)))"
(declare (type alien-value alien)
(type system-area-pointer result-buffer))
(let ((type (alien-value-type alien)))
@@ -819,43 +925,79 @@ Only supported on x86-64 and ARM64."
(defmacro define-alien-routine (name result-type
&rest args
&environment lexenv)
- "DEFINE-ALIEN-ROUTINE name result-type {(arg-name arg-type [style])}*
+ "Define a foreign interface function for the routine with the specified NAME.
+Also automatically DECLAIM the FTYPE of the defined function. The
+semantics of the actual call are the same as for ALIEN-FUNCALL.
-Define a foreign interface function for the routine with the specified NAME.
-Also automatically DECLAIM the FTYPE of the defined function.
+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.
-NAME may be either a string, a symbol, or a list of the form (string symbol).
+NAME may be either a string, a symbol, or a list of the
+form `(<FOREIGN-NAME-STRING> <LISP-NAME-SYMBOL>)`.
RESULT-TYPE is the alien type for the function return value. VOID may be
used to specify a function with no result.
-The remaining forms specify individual arguments that are passed to
-the routine. `ARG-NAME` is a symbol that names the argument, primarily
-for documentation. `ARG-TYPE` is the C type of the argument. `STYLE`
-specifies the way that the argument is passed.
-
-:IN
- An :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 :In arguments. This is the default mode.
-
-:OUT
- The specified argument type must be a pointer to a fixed sized object.
- A pointer to a preallocated object is passed to the routine, and the
- the object is accessed on return, with the value being returned from
- the interface function. :OUT and :IN-OUT cannot be used with pointers
- to arrays, records or functions.
-
-:COPY
- This is similar to :IN, except that the argument values are stored
- on the stack, and a pointer to the object is passed instead of
- the value itself.
-
-:IN-OUT
- This is a combination of :OUT and :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."
+ARGS is a list of `(ARG-NAME ARG-TYPE &OPTIONAL STYLE)` elements.
+`ARG-NAME` is a symbol that names the argument, primarily for
+documentation. `ARG-TYPE` is the C type of the argument.
+
+`STYLE` specifies the way that the argument is passed:
+
+- :IN: An :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 :IN arguments. This is the default mode.
+
+- :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). :OUT and :IN-OUT cannot
+ be used with pointers to arrays, records or functions.
+
+- :COPY: This is similar to :IN, except that the argument values are
+ stored on the stack, and a pointer to the object is passed instead
+ of the value itself.
+
+- :IN-OUT: This is a combination of :OUT and :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.
+
+> _Note_: Any efficiency-critical foreign interface function should be
+> inline expanded, which can be done by preceding the
+> DEFINE-ALIEN-ROUTINE call with:
+>
+> (declaim (inline lisp-name))
+>
+> In addition to avoiding the Lisp call overhead, this allows
+> pointers, word-integers and floats to be passed using non-descriptor
+> representations, avoiding consing.
+
+Consider the C function `cfoo` with the following calling
+convention:
+
+ void
+ cfoo (str, a, i)
+ char *str;
+ char *a; /* update */
+ int *i; /* out */
+ {
+ /* body of cfoo(...) */
+ }
+
+This can be described by the following call to DEFINE-ALIEN-ROUTINE:
+
+ (define-alien-routine \"cfoo\" void
+ (str c-string)
+ (a char :in-out)
+ (i int :out))
+
+The Lisp function `cfoo` will have two arguments (`str` and `a`) and
+two return values (`a` and `i`)."
(binding* (((lisp-name alien-name) (pick-lisp-and-alien-names name))
;; The local name is uninterned so that we don't preclude
;; (defconstant kill 9)
diff --git a/src/code/target-error.lisp b/src/code/target-error.lisp
index 9074a3424..9a7f1e820 100644
--- a/src/code/target-error.lisp
+++ b/src/code/target-error.lisp
@@ -1333,6 +1333,10 @@ signalled when an operation on a symbol violates a package lock. The
symbol that caused the violation is accessed by the function
SB-EXT:PACKAGE-LOCKED-ERROR-SYMBOL."))
+(setf (documentation #'package-locked-error-symbol t)
+ "Return the symbol that caused the SYMBOL-PACKAGE-LOCKED-ERROR
+ condition.")
+
(define-condition undefined-alien-error (cell-error) ()
(:report
(lambda (condition stream)
diff --git a/src/code/target-extensions.lisp b/src/code/target-extensions.lisp
index 8644646f7..28659a81a 100644
--- a/src/code/target-extensions.lisp
+++ b/src/code/target-extensions.lisp
@@ -66,7 +66,7 @@ order when SBCL process exits.
Unused by SBCL itself: reserved for user and applications.
-Using (SB-EXT:EXIT :ABORT T), or calling `exit`(3) directly circumvents
+Using (SB-EXT:EXIT :ABORT T), or calling `exit(3)` directly circumvents
these hooks.")
(defun call-hooks (kind hooks &key (on-error :error))
diff --git a/src/code/target-hash-table.lisp b/src/code/target-hash-table.lisp
index ba15d3ccc..764e83e55 100644
--- a/src/code/target-hash-table.lisp
+++ b/src/code/target-hash-table.lisp
@@ -729,8 +729,8 @@ environment. The hash function must compute the same hash code for any two
objects for which NAME returns true, and subsequent calls with already hashed
objects must always return the same hash code.
-Note: The :HASH-FUNCTION keyword argument to MAKE-HASH-TABLE can be used to
-override the specified default hash-function.
+> _Note_: The :HASH-FUNCTION keyword argument to MAKE-HASH-TABLE can
+> be used to override the specified default hash-function.
Attempting to define NAME in a locked package as hash-table test causes a
package lock violation.
diff --git a/src/code/target-misc.lisp b/src/code/target-misc.lisp
index 962a9b3e7..19c6e8781 100644
--- a/src/code/target-misc.lisp
+++ b/src/code/target-misc.lisp
@@ -58,7 +58,7 @@ are running on, or NIL if we can't find any useful information."
;;;; ED
(declaim (type list *ed-functions*))
(defvar *ed-functions* '()
- "See function documentation for ED.")
+ "See ED.")
(defun ed (&optional x)
"Starts the editor (on a file or a function if named). Functions
@@ -250,9 +250,9 @@ 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, (assert-version->= 1 1 4) asserts that the current SBCL is
-version 1.1.4[.0.0...] or greater, and (assert-version->= 1) that it is
-version 1[.0.0...] or greater."
+For example, (ASSERT-VERSION->= 1 1 4) asserts that the current SBCL
+is version 1.1.4[.0.0...] or greater, and (ASSERT-VERSION->= 1) that
+it is version 1[.0.0...] or greater."
(let ((version (split-version-string (lisp-implementation-version))))
(unless (version>= version subversions)
(cerror "Disregard this version requirement."
diff --git a/src/code/target-package.lisp b/src/code/target-package.lisp
index b6ce75127..988178556 100644
--- a/src/code/target-package.lisp
+++ b/src/code/target-package.lisp
@@ -919,7 +919,7 @@ REMOVE-PACKAGE-LOCAL-NICKNAME, and the DEFPACKAGE option :LOCAL-NICKNAMES."
(def package-shadowing-symbols package-%shadowing-symbols))
(defun package-local-nicknames (package-designator)
- "Returns an alist of \(local-nickname . actual-package) describing the
+ "Returns an alist of `(LOCAL-NICKNAME . ACTUAL-PACKAGE)` describing the
nicknames local to the designated package.
When in the designated package, calls to FIND-PACKAGE with the any of the
@@ -931,9 +931,6 @@ 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.
-See also: ADD-PACKAGE-LOCAL-NICKNAME, PACKAGE-LOCALLY-NICKNAMED-BY-LIST,
-REMOVE-PACKAGE-LOCAL-NICKNAME, and the DEFPACKAGE option :LOCAL-NICKNAMES.
-
Experimental: interface subject to change."
(package-local-nickname-alist
(package-%local-nicknames (find-undeleted-package-or-lose package-designator))
@@ -957,9 +954,6 @@ Experimental: interface subject to change."
"Returns a list of packages which have a local nickname for the designated
package.
-See also: ADD-PACKAGE-LOCAL-NICKNAME, PACKAGE-LOCAL-NICKNAMES,
-REMOVE-PACKAGE-LOCAL-NICKNAME, and the DEFPACKAGE option :LOCAL-NICKNAMES.
-
Experimental: interface subject to change."
(let ((designee (find-undeleted-package-or-lose package-designator))
(result))
@@ -994,9 +988,6 @@ 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.
-See also: PACKAGE-LOCAL-NICKNAMES, PACKAGE-LOCALLY-NICKNAMED-BY-LIST,
-REMOVE-PACKAGE-LOCAL-NICKNAME, and the DEFPACKAGE option :LOCAL-NICKNAMES.
-
Experimental: interface subject to change."
(let ((package (find-undeleted-package-or-lose package-designator)))
(%add-package-local-nickname local-nickname actual-package package)
@@ -1068,9 +1059,6 @@ Experimental: interface subject to change."
another package, it is removed. Returns true if the nickname existed and was
removed, and NIL otherwise.
-See also: ADD-PACKAGE-LOCAL-NICKNAME, PACKAGE-LOCAL-NICKNAMES,
-PACKAGE-LOCALLY-NICKNAMED-BY-LIST, and the DEFPACKAGE option :LOCAL-NICKNAMES.
-
Experimental: interface subject to change."
(let* ((nick (string old-nickname))
(package (find-undeleted-package-or-lose package-designator))
diff --git a/src/code/target-random.lisp b/src/code/target-random.lisp
index 2204ac9b0..1b11d895b 100644
--- a/src/code/target-random.lisp
+++ b/src/code/target-random.lisp
@@ -136,6 +136,7 @@ See SB-EXT:SEED-RANDOM-STATE for a SBCL extension to this functionality."
for deterministic pseudo-random number generation.
As per the Common Lisp standard for MAKE-RANDOM-STATE,
+
- If STATE is NIL or not supplied, return a copy of the default
*RANDOM-STATE*.
- If STATE is a random state, return a copy of it.
@@ -145,8 +146,10 @@ As per the Common Lisp standard for MAKE-RANDOM-STATE,
As a supported SBCL extension, we also support receiving as a seed an object
of the following types:
+
- (SIMPLE-ARRAY (UNSIGNED-BYTE 8) (*))
- UNSIGNED-BYTE
+
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.
diff --git a/src/code/target-thread.lisp b/src/code/target-thread.lisp
index 4a60e675e..cccf0644b 100644
--- a/src/code/target-thread.lisp
+++ b/src/code/target-thread.lisp
@@ -448,9 +448,7 @@ If current thread is the main thread of the process (see
MAIN-THREAD-P), signals an error unless ALLOW-EXIT is true, as
terminating the main thread would terminate the entire process. If
ALLOW-EXIT is true, returning from the main thread is equivalent to
-calling SB-EXT:EXIT with :CODE 0 and :ABORT NIL.
-
-See also: ABORT-THREAD and SB-EXT:EXIT."
+calling SB-EXT:EXIT with :CODE 0 and :ABORT NIL."
`(%return-from-thread (multiple-value-call #'sys-tlab-list ,values-form) ,allow-exit))
(defun %return-from-thread (values allow-exit)
@@ -482,9 +480,7 @@ equivalent to calling ABORT-THREAD in other than main threads.
However, whereas ABORT restart may be rebound, ABORT-THREAD always
unwinds the entire thread. (Behaviour of the initial ABORT restart for
main thread depends on the :TOPLEVEL argument to
-SB-EXT:SAVE-LISP-AND-DIE.)
-
-See also: RETURN-FROM-THREAD and SB-EXT:EXIT."
+SB-EXT:SAVE-LISP-AND-DIE.)"
(let ((self *current-thread*))
(cond ((main-thread-p self)
(unless allow-exit
@@ -562,8 +558,9 @@ See also: RETURN-FROM-THREAD and SB-EXT:EXIT."
;;;; Mutexes
-(setf (documentation 'make-mutex 'function) "Create a mutex."
- (documentation 'mutex-name 'function) "The name of the mutex. Setfable.")
+(setf (documentation 'make-mutex 'function) "Create a MUTEX.")
+(setf (documentation 'mutex-name 'function)
+ "The name of the MUTEX. SETFable.")
(sb-ext:define-load-time-global **deadlock-lock** nil)
@@ -982,26 +979,25 @@ Notes:
- GRAB-MUTEX is not interrupt safe. The correct way to call it is:
- (WITHOUT-INTERRUPTS
- ...
- (ALLOW-WITH-INTERRUPTS (GRAB-MUTEX ...))
- ...)
+ (without-interrupts
+ ...
+ (allow-with-interrupts (grab-mutex ...))
+ ...)
WITHOUT-INTERRUPTS is necessary to avoid an interrupt unwinding the call
while the mutex is in an inconsistent state while ALLOW-WITH-INTERRUPTS
allows the call to be interrupted from sleep.
- - (GRAB-MUTEX <mutex> :timeout 0.0) differs from
- (GRAB-MUTEX <mutex> :waitp nil) in that the former may signal a
- DEADLINE-TIMEOUT if the global deadline was due already on entering
- GRAB-MUTEX.
+ - `(GRAB-MUTEX <MUTEX> :TIMEOUT 0.0)` differs from
+ `(GRAB-MUTEX <MUTEX> :WAITP NIL)` in that the former may signal a
+ DEADLINE-TIMEOUT if the global deadline was due already on
+ entering GRAB-MUTEX.
The exact interplay of GRAB-MUTEX and deadlines are reserved to change in
future versions.
- It is recommended that you use WITH-MUTEX instead of calling GRAB-MUTEX
- directly.
-"
+ directly."
(declare (ignorable waitp timeout))
(or (%try-mutex mutex)
#+sb-thread
@@ -1139,8 +1135,8 @@ or :ERROR respectively, or release the mutex anyway if :FORCE."
(print-unreadable-object (waitqueue stream :type t :identity t)
(format stream "~:[-~;~:*~S~]" (waitqueue-name waitqueue))))
-(setf (documentation 'waitqueue-name 'function) "The name of the waitqueue. Setfable."
- (documentation 'make-waitqueue 'function) "Create a waitqueue.")
+(setf (documentation 'waitqueue-name 'function) "The name of the waitqueue. SETFable."
+ (documentation 'make-waitqueue 'function) "Create a WAITQUEUE.")
(defmacro nlx-protect-futex (protected &body cleanup)
(declare (ignorable cleanup))
@@ -1297,25 +1293,24 @@ CONDITION-BROADCAST having occurred, the correct way to write code
that uses CONDITION-WAIT is to loop around the call, checking the
associated data:
- (defvar *data* nil)
- (defvar *queue* (make-waitqueue))
- (defvar *lock* (make-mutex))
+ (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*)))
+ ;; 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*)))
-"
+ ;; Producer
+ (defun push-data (data)
+ (with-mutex (*lock*)
+ (push data *data*)
+ (condition-notify *queue*)))"
(declare (explicit-check timeout))
;; %CONDITION-WAIT can return 3 values. In most situations the values are never used,
;; but the semaphore implementation uses them.
@@ -1376,7 +1371,7 @@ must be held by this thread during this call."
(make-waitqueue :name name)))
(defun semaphore-name (semaphore)
- "The name of the semaphore INSTANCE. Setfable."
+ "The name of the semaphore INSTANCE. SETFable."
(waitqueue-name (semaphore-queue semaphore)))
(defun (setf semaphore-name) (newval semaphore)
@@ -1410,10 +1405,10 @@ WAIT-ON-SEMAPHORE or TRY-SEMAPHORE."
(setf (semaphore-notification-%status semaphore-notification) nil)))
(declaim (inline semaphore-count))
-(defun semaphore-count (instance)
- "Returns the current count of the semaphore INSTANCE."
+(defun semaphore-count (semaphore)
+ "Returns the current count of SEMAPHORE."
(barrier (:read))
- (semaphore-%count instance))
+ (semaphore-%count semaphore))
(declaim (ftype (sfunction (semaphore (integer 1) (or boolean real)
(or null semaphore-notification) symbol)
@@ -1620,10 +1615,11 @@ on this semaphore, then N of them is woken up."
(defvar sb-ext:*invoke-debugger-hook* nil
"This is either 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 *INVOKE-DEBUGGER-HOOK* bound to NIL to minimize recursive
- errors, and receives as arguments the condition that triggered
- debugger entry and the previous value of *INVOKE-DEBUGGER-HOOK*
+ to be run when the debugger is about to be entered. The function is
+ run with `*INVOKE-DEBUGGER-HOOK*` bound to NIL to minimize
+ recursive errors, and receives as arguments the condition that
+ triggered debugger entry and the previous value of
+ `*INVOKE-DEBUGGER-HOOK*`.
This mechanism is an SBCL extension similar to the standard *DEBUGGER-HOOK*.
In contrast to *DEBUGGER-HOOK*, it is observed by INVOKE-DEBUGGER even when
@@ -2129,9 +2125,7 @@ the function returns. The return values of FUNCTION are kept around
and can be retrieved by JOIN-THREAD.
Invoking the initial ABORT restart established by MAKE-THREAD
-terminates the thread.
-
-See also: RETURN-FROM-THREAD, ABORT-THREAD."
+terminates the thread."
#-sb-thread (declare (ignore function name arguments))
#-sb-thread (error "Not supported in unithread builds.")
#+sb-thread
@@ -2298,8 +2292,8 @@ than one other thread simultaneously. Future changes to JOIN-THREAD may
directly call the underlying thread library, and not all threading
implementations consider such usage to be well-defined.
-NOTE: Return convention in case of a timeout is experimental and
-subject to change."
+> _Note_: Return convention in case of a timeout is experimental and
+> subject to change."
(when (eq thread *current-thread*)
(error 'join-thread-error :thread thread :problem :self-join))
@@ -2417,34 +2411,37 @@ correctly.
With those caveats in mind, what you need to know when using it:
- * If calling FUNCTION causes a non-local transfer of control (ie. an
- unwind), all normal cleanup forms will be executed.
+* If calling 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 UNWIND-PROTECT,
- it is just as if that had happened due to a regular GO, THROW, or
- RETURN-FROM: the interrupted cleanup form and those following it in the
- same UNWIND-PROTECT do not get executed.
+ However, if the interrupt occurs during cleanup forms of an
+ UNWIND-PROTECT, it is just as if that had happened due to a
+ regular GO, THROW, or RETURN-FROM: the interrupted cleanup form
+ and those following it in the same 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.
+ 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.
+ 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.
- * In addition to asynch-unwind-safety you must consider the issue of
- reentrancy. 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.)
+* In addition to asynch-unwind-safety you must consider the issue of
+ reentrancy. 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.)
Taken together, these two restrict the \"safe\" things to do using
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:
- (interrupt-thread thread #'break)
+ (interrupt-thread thread #'break)
Short version: be careful out there."
(unless (%interrupt-thread thread function)
@@ -2481,16 +2478,16 @@ causing it to call SB-THREAD:ABORT-THREAD with :ALLOW-EXIT T.
The unwind caused by TERMINATE-THREAD is asynchronous, meaning that
eg. thread executing
- (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))))
+ (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))))
might miss calling `RELEASE-FOO` despite GET-FOO having returned true
if the interrupt occurs inside the cleanup clause, eg. during
@@ -2499,16 +2496,16 @@ execution of `RELEASE-FOO`.
Thus, in order to write an asynch unwind safe UNWIND-PROTECT you need
to use WITHOUT-INTERRUPTS:
- (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)))))
+ (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)))))
Since most libraries using UNWIND-PROTECT do not do this, you should never
assume that unknown code can safely be terminated using TERMINATE-THREAD."
diff --git a/src/code/target-unicode.lisp b/src/code/target-unicode.lisp
index f5e7b2d45..accc1edac 100644
--- a/src/code/target-unicode.lisp
+++ b/src/code/target-unicode.lisp
@@ -638,7 +638,7 @@ 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, `(decimal-digit c) <=> (digit-char-p c 10)` in
-#+sb-unicode builds"
+`#+sb-unicode` builds"
(sb-impl::ucd-decimal-digit character))
(defun digit-value (character)
@@ -1042,10 +1042,10 @@ The result is not guaranteed to have the same length as the input."
;;; (nobrk) prevents a break between `first` and `second`
;;; Setting flag=T/state=:nobrk-next prevents a break between `second` and `third`
-(defun grapheme-break-class (char)
+(defun grapheme-break-class (character)
"Returns the grapheme breaking class of CHARACTER, as specified in UAX #29."
- (let ((cp (when char (char-code char)))
- (gc (when char (general-category char)))
+ (let ((cp (when character (char-code character)))
+ (gc (when character (general-category character)))
(not-spacing-mark
#(#x102B #x102C #x1038 #x1062 #x1063 #x1064 #x1067 #x1068 #x1069
#x106A #x106B #x106C #x106D #x1083 #x1087 #x1088 #x1089 #x108A
@@ -1053,11 +1053,11 @@ The result is not guaranteed to have the same length as the input."
#x19B3 #x19B4 #x19B8 #x19B9 #x19BB #x19BC #x19BD #x19BE #x19BF
#x19C0 #x19C8 #x19C9 #x1A61 #x1A63 #x1A64 #xAA7B #xAA7D)))
(cond
- ((not char) nil)
+ ((not character) nil)
((= cp 10) :LF)
((= cp 13) :CR)
((or (and (member gc '(:Zl :Zp :Cc :Cs :Cf))
- (not (proplist-p char :prepended-concatenation-mark))
+ (not (proplist-p character :prepended-concatenation-mark))
(not (<= #x200C cp #x200D))
;; not documented but in the normative file
(not (<= #xE0020 cp #xE007F)))
@@ -1068,8 +1068,8 @@ The result is not guaranteed to have the same length as the input."
(<= #xE0080 cp #xE00FF)
(<= #xE01F0 cp #xE0FFF)) :control)
((or (member gc '(:Mn :Me))
- (proplist-p char :other-grapheme-extend)
- (proplist-p char :emoji-modifier))
+ (proplist-p character :other-grapheme-extend)
+ (proplist-p character :emoji-modifier))
:extend)
((= cp #x200D) :zwj)
((<= #x1F1E6 cp #x1F1FF) :regional-indicator)
@@ -1078,12 +1078,12 @@ The result is not guaranteed to have the same length as the input."
(= cp #x0D4E) (= cp #x11941) (= cp #x11D46) (= cp #x11F02)
;; Consonant_Prefixed
(<= #x111C2 cp #x111C3) (= cp #x1193F) (= cp #x11A3A) (<= #x11A84 cp #x11A89)
- (proplist-p char :prepended-concatenation-mark))
+ (proplist-p character :prepended-concatenation-mark))
:prepend)
((and (or (eql gc :Mc)
(eql cp #x0E33) (eql cp #x0EB3))
(not (binary-search cp not-spacing-mark))) :spacing-mark)
- ((hangul-syllable-type char)))))
+ ((hangul-syllable-type character)))))
(macrolet ((def (name extendedp)
`(defun ,name (function string)
@@ -1150,12 +1150,13 @@ grapheme breaking rules specified in UAX #29, returning a list of strings."
(map-graphemes (lambda (a) (push (subseq a 0) result)) string)
(nreverse result)))
-(defun word-break-class (char)
+(defun word-break-class (character)
"Returns the word breaking class of CHARACTER, as specified in UAX #29."
;; Words use graphemes as characters to deal with the ignore rule
- (when (listp char) (setf char (car char)))
- (let ((cp (when char (char-code char)))
- (gc (when char (general-category char)))
+ (when (listp character)
+ (setf character (car character)))
+ (let ((cp (when character (char-code character)))
+ (gc (when character (general-category character)))
(newlines
(coerce-to-ordered-ranges #(#xB #xC #x0085 #x0085 #x2028 #x2029)))
(also-katakana
@@ -1184,22 +1185,22 @@ grapheme breaking rules specified in UAX #29, returning a list of strings."
;; Grepping of Line_Break = ";GL.*Zs"
#(#x00A0 #x2007 #x202F)))
(cond
- ((not char) nil)
+ ((not character) nil)
((= cp 10) :LF)
((= cp 13) :CR)
((ordered-ranges-member cp newlines) :newline)
- ((or (eql (grapheme-break-class char) :extend)
+ ((or (eql (grapheme-break-class character) :extend)
(and (eql gc :mc) (not (= cp #x200D)))) :extend)
((= cp #x200D) :zwj)
((<= #x1F1E6 cp #x1F1FF) :regional-indicator)
((and (eql gc :Cf) (not (<= #x200B cp #x200D))) :format)
- ((or (eql (script char) :katakana)
+ ((or (eql (script character) :katakana)
(ordered-ranges-member cp also-katakana)) :katakana)
- ((and (eql (script char) :Hebrew) (eql gc :lo)) :hebrew-letter)
- ((and (or (alphabetic-p char) (binary-search cp also-aletter))
- (not (or (ideographic-p char)
- (eql (line-break-class char) :sa)
- (eql (script char) :hiragana)))) :aletter)
+ ((and (eql (script character) :Hebrew) (eql gc :lo)) :hebrew-letter)
+ ((and (or (alphabetic-p character) (binary-search cp also-aletter))
+ (not (or (ideographic-p character)
+ (eql (line-break-class character) :sa)
+ (eql (script character) :hiragana)))) :aletter)
((= cp #x27) :single-quote)
((= cp #x22) :double-quote)
((binary-search cp midnumlet) :midnumlet)
@@ -1296,43 +1297,44 @@ word breaking rules specified in UAX #29. Returns a list of strings"
(nobrk))
(t (brk))))))))))
-(defun sentence-break-class (char)
+(defun sentence-break-class (character)
"Returns the sentence breaking class of CHARACTER, as specified in UAX #29."
- (when (listp char) (setf char (car char)))
- (let ((cp (when char (char-code char)))
- (gc (when char (general-category char)))
+ (when (listp character)
+ (setf character (car character)))
+ (let ((cp (when character (char-code character)))
+ (gc (when character (general-category character)))
(aterms #(#x002E #x2024 #xFE52 #xFF0E))
(scontinues
#(#x002C #x002D #x003A #x055D #x060C #x060D #x07F8 #x1802 #x1808
#x2013 #x2014 #x3001 #xFE10 #xFE11 #xFE13 #xFE31 #xFE32 #xFE50
#xFE51 #xFE55 #xFE58 #xFE63 #xFF0C #xFF0D #xFF1A #xFF64)))
(cond
- ((not char) nil)
+ ((not character) nil)
((= cp 10) :LF)
((= cp 13) :CR)
- ((or (eql (grapheme-break-class char) :extend)
+ ((or (eql (grapheme-break-class character) :extend)
(= cp #x200D)
(eql gc :mc))
:extend)
((or (eql cp #x0085) (<= #x2028 cp #x2029)) :sep)
((and (eql gc :Cf) (not (<= #x200C cp #x200D))) :format)
- ((whitespace-p char) :sp)
- ((and (lowercase-p char)
+ ((whitespace-p character) :sp)
+ ((and (lowercase-p character)
(not (<= #x10D0 cp #x10FA))
(not (<= #x10FD cp #x10FF)))
:lower)
((or (eql gc :Lt)
- (and (uppercase-p char)
+ (and (uppercase-p character)
(not (<= #x1C90 cp #x1CBA))
(not (<= #x1CBD cp #x1CBF))))
:upper)
- ((or (alphabetic-p char) (eql cp #x00A0) (eql cp #x05F3)) :oletter)
+ ((or (alphabetic-p character) (eql cp #x00A0) (eql cp #x05F3)) :oletter)
((or (eql gc :Nd) (<= #x066B cp #x066C)) :numeric)
((binary-search cp aterms) :aterm)
((binary-search cp scontinues) :scontinue)
- ((proplist-p char :sentence-terminal) :sterm)
+ ((proplist-p character :sentence-terminal) :sterm)
((and (or (member gc '(:Po :Ps :Pe :Pf :Pi))
- (eql (line-break-class char) :qu)))
+ (eql (line-break-class character) :qu)))
:close)
(t nil))))
diff --git a/src/code/thread.lisp b/src/code/thread.lisp
index 81c7b6486..66d7088c5 100644
--- a/src/code/thread.lisp
+++ b/src/code/thread.lisp
@@ -29,7 +29,7 @@ any time."
(defmacro owner-tid-from-word (word) `(ash ,word -32)))
(defun mutex-value (mutex)
- "Current owner of the mutex, NIL if the mutex is free. May return a
+ "Current owner of MUTEX, NIL if the mutex is free. May return a
stale value, use MUTEX-OWNER instead."
(mutex-owner-lookup (mutex-%owner mutex)))
@@ -66,7 +66,7 @@ stale value, use MUTEX-OWNER instead."
#-bitpacked-mutex (current-vmthread-id)))
(defun mutex-owner (mutex)
- "Current owner of the mutex, NIL if the mutex is free. Naturally,
+ "Current owner of MUTEX, 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
@@ -200,8 +200,8 @@ and the MUTEX is not immediately available, sleep until it is available.
If 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 WAIT-P or TIMEOUT, the
-body is not executed, and WITH-MUTEX returns NIL.
+If the mutex isn't acquired successfully due to either WAIT-P or
+TIMEOUT, BODY is not executed, and WITH-MUTEX returns NIL.
Otherwise body is executed with the mutex held by current thread, and
WITH-MUTEX returns the values of BODY.
@@ -261,8 +261,8 @@ held by the current thread, sleep until it is available.
If 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 WAIT-P or TIMEOUT, the
-body is not executed, and WITH-RECURSIVE-LOCK returns NIL.
+If the mutex isn't acquired successfully due to either WAIT-P or
+TIMEOUT, BODY is not executed, and WITH-RECURSIVE-LOCK returns NIL.
Otherwise body is executed with the mutex held by current thread, and
WITH-RECURSIVE-LOCK returns the values of BODY.
diff --git a/src/code/timer.lisp b/src/code/timer.lisp
index a69fe1e88..6a14c27f3 100644
--- a/src/code/timer.lisp
+++ b/src/code/timer.lisp
@@ -494,14 +494,14 @@ condition after at least EXPIRES seconds have passed.
Note that it is never safe to unwind from an asynchronous condition. Consider:
- (defun call-with-foo (function)
- (let (foo)
- (unwind-protect
- (progn
- (setf foo (get-foo))
- (funcall function foo))
- (when foo
- (release-foo foo)))))
+ (defun call-with-foo (function)
+ (let (foo)
+ (unwind-protect
+ (progn
+ (setf foo (get-foo))
+ (funcall function foo))
+ (when foo
+ (release-foo foo)))))
If TIMEOUT occurs after `GET-FOO` has executed, but before the
assignment, then `RELEASE-FOO` will be missed. While individual sites
diff --git a/src/code/toplevel.lisp b/src/code/toplevel.lisp
index 01ab83a3e..cfe5bb51a 100644
--- a/src/code/toplevel.lisp
+++ b/src/code/toplevel.lisp
@@ -417,6 +417,15 @@ any non-negative real number."
"--end-runtime-options" "--merge-core-pages" "--no-merge-core-pages")
#'equalp)
+(defvar *posix-argv*)
+(setf
+ (documentation '*posix-argv* 'variable)
+ "A list of strings related to the UNIX command line (`argv` in \\C).
+
+ SB-MANUAL:@RUNTIME-OPTIONS are processed and removed by the runtime.
+ The default toplevel (see SB-EXT:SAVE-LISP-AND-DIE) also removes the
+ SB-MANUAL:@TOPLEVEL-OPTIONS that it processes.")
+
;;; the default system top level function
(defun toplevel-init ()
(/show0 "entering TOPLEVEL-INIT")
diff --git a/src/code/traceroot.lisp b/src/code/traceroot.lisp
index a5ca39a49..9a3a37be8 100644
--- a/src/code/traceroot.lisp
+++ b/src/code/traceroot.lisp
@@ -178,8 +178,8 @@ to be considered. Possible values are:
- :STATIC
- To find a root of an image-backed object, you want to stop only at a
- truly :STATIC object.
+ To find a root of an image-backed object, you want to stop only at
+ a truly :STATIC object.
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
diff --git a/src/code/unix.lisp b/src/code/unix.lisp
index 87e37c148..379a983ea 100644
--- a/src/code/unix.lisp
+++ b/src/code/unix.lisp
@@ -133,8 +133,8 @@ SYSCALL-FORM. Repeat evaluation of SYSCALL-FORM if it is interrupted."
(declaim (ftype (function (t) (values (or simple-string null) &optional))
posix-getenv))
(defun posix-getenv (name)
- "Return the \"value\" part of the environment string \"name=value\" which
-corresponds to NAME, or NIL if there is none."
+ "Return the `value` part of the environment string `name=value` which
+corresponds to NAME, or NIL if there is none. See `getenv(3)`."
(with-alien ((posix-getenv (function c-string (c-string :not-null t)) :extern "getenv"))
(acond ((alien-funcall posix-getenv name) (possibly-base-stringize it))))))
@@ -458,7 +458,7 @@ corresponds to NAME, or NIL if there is none."
`(signed-byte 32))
(defun os-exit (code &key abort)
"Exit the process with CODE. If ABORT is true, exit is performed using _exit(2),
-avoiding `atexit`(3) hooks, etc. Otherwise `exit`(2) is called."
+avoiding `atexit(3)` hooks, etc. Otherwise `exit(2)` is called."
(unless (typep code 'exit-code)
(setf code (if abort 1 0)))
(if abort
diff --git a/src/compiler/generic/genesis.lisp b/src/compiler/generic/genesis.lisp
index b6abb1602..bbe38acfe 100644
--- a/src/compiler/generic/genesis.lisp
+++ b/src/compiler/generic/genesis.lisp
@@ -806,7 +806,7 @@
pointing to them."
(allocate-cold-descriptor gspace (ash length sb-vm:word-shift) lowtag))
(defun allocate-otherptr (gspace length widetag)
- "Allocate LENGTH words in GSPACE and return an ``other-pointer'' descriptor.
+ "Allocate LENGTH words in GSPACE and return an \"other-pointer\" descriptor.
LENGTH must count the header word itself as 1 word. The header word is
initialized with the payload size as (1- LENGTH), and WIDETAG."
(let* ((page-type (or (and (eq gspace *dynamic*)
diff --git a/src/compiler/macros.lisp b/src/compiler/macros.lisp
index 0462bd2f3..dd2e31397 100644
--- a/src/compiler/macros.lisp
+++ b/src/compiler/macros.lisp
@@ -1003,17 +1003,17 @@
;;; *COMPILER-PRINT-VARIABLE-ALIST* for user customization.
(defvar *compiler-print-variable-alist* nil
"An association list describing new bindings for special variables
-to be used by the compiler for error-reporting, etc. Eg.
-
- ((*PRINT-LENGTH* . 10) (*PRINT-LEVEL* . 6) (*PRINT-PRETTY* . NIL))
+to be used by the compiler for error-reporting, etc.
+E.g. ((*PRINT-LENGTH* . 10) (*PRINT-LEVEL* . 6) (*PRINT-PRETTY* .
+NIL)).
The variables in the CAR positions are bound to the values in the 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, *COMPILER-PRINT-VARIABLE-ALIST* is typically used to
-specify bindings for printer control variables.")
+Initially empty, `*COMPILER-PRINT-VARIABLE-ALIST*` is typically used
+to specify bindings for printer control variables.")
(defmacro with-compiler-io-syntax (&body forms)
`(with-sane-io-syntax
diff --git a/src/compiler/main.lisp b/src/compiler/main.lisp
index 8c53c62b0..09d600efb 100644
--- a/src/compiler/main.lisp
+++ b/src/compiler/main.lisp
@@ -77,7 +77,7 @@ Following options are defined:
until the end of the form, instead of giving them at the end of
each compilation. If OVERRIDE is NIL (the default), then the
outermost WITH-COMPILATION-UNIT form grabs the undefined warnings.
- Specifying OVERRIDE true causes that form to grab any enclosed
+ Specifying :OVERRIDE true causes that form to grab any enclosed
warnings, even if it is enclosed by another WITH-COMPILATION-UNIT.
- :POLICY `<optimize-declaration-form>`
@@ -87,36 +87,37 @@ Following options are defined:
OPTIMIZE proclamations and calls to
SB-EXT:RESTRICT-COMPILER-POLICY to the dynamic scope of BODY.
- If OVERRIDE is false, specified POLICY is merged with current
- global policy. If OVERRIDE is true, current global policy,
- including any restrictions, is discarded in favor of the specified
- POLICY.
+ If :OVERRIDE is false, the specified :POLICY is merged with
+ current global policy. If :OVERRIDE is true, current global
+ policy, including any restrictions, is discarded in favor of the
+ specified
+ :POLICY.
- Supplying POLICY NIL is equivalent to the option not being
- supplied at all, ie. dynamic scoping of policy does not take
+ Supplying :POLICY 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.
-:SOURCE-NAMESTRING `<namestring-form>`
+- :SOURCE-NAMESTRING `<namestring-form>`
- Attaches the value returned by the Namestring-Form to the internal
- debug-source information as the namestring of the source file.
- Normally the namestring of the input-file for COMPILE-FILE is
- used: this option can be used to provide source-file information
- for functions compiled using COMPILE, or to override the
- input-file of COMPILE-FILE.
+ Attaches the value returned by the `<namestring-form>` to the
+ internal debug-source information as the namestring of the source
+ file. Normally the namestring of the input-file for COMPILE-FILE
+ is used: this option can be used to provide source-file
+ information for functions compiled using COMPILE, or to override
+ the input-file of COMPILE-FILE.
If both an outer and an inner WITH-COMPILATION-UNIT provide a
- SOURCE-NAMESTRING, the inner one takes precedence. Unaffected
- by :OVERRIDE.
+ :SOURCE-NAMESTRING, the inner one takes precedence. Unaffected by
+ :OVERRIDE.
This is an SBCL-specific extension.
- :SOURCE-PLIST `<plist-form>`
- Attaches the value returned by the Plist-Form to internal
+ Attaches the value returned by the `<plist-form>` to internal
debug-source information of functions compiled in within the
dynamic extent of BODY.
@@ -153,7 +154,8 @@ Examples:
;; proclamation leaks out from WITH-COMPILATION-UNIT.
(with-compilation-unit (:policy nil)
(declaim (optimize safety))
- (load \"foo.lisp\"))"
+ (load \"foo.lisp\"))
+```"
`(%with-compilation-unit (lambda () ,@body) ,@options))
(defvar *source-plist* nil)
diff --git a/src/pcl/gray-streams.lisp b/src/pcl/gray-streams.lisp
index 5317807e4..2ebe1c8ff 100644
--- a/src/pcl/gray-streams.lisp
+++ b/src/pcl/gray-streams.lisp
@@ -282,7 +282,7 @@
(defgeneric stream-terpri (stream)
(:documentation
"Writes an end of line, as for TERPRI. Returns NIL. The default
- method does (STREAM-WRITE-CHAR stream #\\NEWLINE)."))
+ method does (STREAM-WRITE-CHAR stream `#\\Newline`)."))
(defmethod stream-terpri ((stream fundamental-character-output-stream))
(stream-write-char stream #\Newline))
@@ -327,11 +327,12 @@
(defgeneric stream-advance-to-column (stream column)
(:documentation
"Write enough blank space so that the next character will be
- written at the specified column. Returns true if the operation is
- successful, or NIL if it is not supported for this stream. This is
- intended for use by by PPRINT and FORMAT ~T. The default method uses
- STREAM-LINE-COLUMN and repeated calls to STREAM-WRITE-CHAR with a
- #\\SPACE character; it returns NIL if STREAM-LINE-COLUMN returns NIL."))
+ written at the specified column. Returns true if the operation is
+ successful, or NIL if it is not supported for this stream. This is
+ intended for use by by PPRINT and FORMAT ~T. The default method
+ uses STREAM-LINE-COLUMN and repeated calls to STREAM-WRITE-CHAR
+ with a #\\SPACE character; it returns NIL if STREAM-LINE-COLUMN
+ returns NIL."))
(defmethod stream-advance-to-column ((stream fundamental-character-output-stream)
column)
diff --git a/src/pcl/sequence.lisp b/src/pcl/sequence.lisp
index 3a789ecd2..fa13a2cce 100644
--- a/src/pcl/sequence.lisp
+++ b/src/pcl/sequence.lisp
@@ -191,7 +191,15 @@
If FROM-END is NIL, the constructed iterator visits the specified
elements in the order in which they appear in SEQUENCE. Otherwise,
- the elements are visited in the opposite order."))
+ 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
+ SB-MANUAL:@EXSEQ-SIMPLE-ITERATOR-PROTOCOL. In fact, when there is
+ no specialized method for a particular SEQUENCE subclass,
+ SB-SEQUENCE:MAKE-SEQUENCE-ITERATOR calls
+ SB-SEQUENCE:MAKE-SIMPLE-SEQUENCE-ITERATOR and returns those six
+ generic functions."))
;;; magic termination value for list :from-end t
(define-load-time-global *exhausted* (cons nil nil))
@@ -301,9 +309,7 @@
3. from-end
The returned iterator can be used with the generic iterator
- functions SEQUENCE:ITERATOR-STEP, SEQUENCE:ITERATOR-STEP,
- SEQUENCE:ITERATOR-ELEMENT, (SETF SEQUENCE:ITERATOR-ELEMENT),
- SEQUENCE:ITERATOR-INDEX and SEQUENCE:ITERATOR-COPY."))
+ functions described in SB-MANUAL:@EXSEQ-SIMPLE-ITERATOR-PROTOCOL."))
(defgeneric sequence:iterator-step (sequence iterator from-end)
(:method ((s list) iterator from-end)
-----------------------------------------------------------------------
hooks/post-receive
--
SBCL
_______________________________________________
Sbcl-commits mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/sbcl-commits