Re: master: doc: update lisp definition docstrings for Markdown
Stas Boukarev <[email protected]> Mon, 29 Jun 2026 16:26:19 +0300
| Newsgroups | gmane.lisp.steel-bank.cvs,gmane.lisp.steel-bank.devel |
|---|---|
| Message-ID | <CAF63=10h=9Yh4HZUuvgSkUZe0oCp1mkvf_5a=ziiY5++sFxw9w@mail.gmail.com> |
This may look good in a compiled document, but when doing DESCRIBE/DOCUMENTATION at runtime it looks weird. On Mon, Jun 29, 2026 at 3:19 PM melisgl via Sbcl-commits <[email protected]> wrote: > > 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 _______________________________________________ Sbcl-commits mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/sbcl-commits