mirror of
git://git.code.sf.net/p/sbcl/sbcl
synced 2026-09-10 07:26:40 -04:00
sb-manual: readd concepts
This commit is contained in:
Gabor Melis
parent
40658bfd6a
commit
34812e52a1
|
|
@ -1,6 +1,7 @@
|
|||
(in-package :sb-manual)
|
||||
|
||||
(defsection @beyond-the-ansi-standard (:title "Beyond the ANSI Standard")
|
||||
(defsection @beyond-the-ansi-standard (:title "Beyond the ANSI Standard"
|
||||
:concepts (("reader" "extensions")))
|
||||
"SBCL is derived from CMUCL, which implements many extensions to the
|
||||
ANSI standard. SBCL doesn't support as many extensions as CMUCL, but
|
||||
it still has quite a few. See @CONTRIBUTED-MODULES."
|
||||
|
|
@ -30,10 +31,12 @@
|
|||
(@decimal-syntax-for-rationals section))
|
||||
|
||||
(defsection @extended-package-prefix-syntax
|
||||
(:title "Extended Package Prefix Syntax")
|
||||
(:title "Extended Package Prefix Syntax"
|
||||
:concepts (("extended" "package prefix syntax")
|
||||
("package prefix syntax," "extended")))
|
||||
"SBCL supports extended package prefix syntax, which allows specifying
|
||||
an alternate package instead of *PACKAGE* for the reader to use as
|
||||
the default package for interning symbols:
|
||||
the default package for @INTERNING-SYMBOLS:
|
||||
|
||||
<package-name>::<form-with-interning-into-package>
|
||||
|
||||
|
|
@ -43,11 +46,14 @@
|
|||
|
||||
*PACKAGE* is not rebound during the course of reading a form with
|
||||
extended package prefix syntax; if `FOO::BAR` would cause a
|
||||
read-time package lock violation, so does `FOO::(BAR)`.")
|
||||
read-time @PACKAGE-LOCK violation, so does `FOO::(BAR)`.")
|
||||
|
||||
(defsection @symbol-name-normalization (:title "Symbol Name Normalization")
|
||||
(defsection @symbol-name-normalization
|
||||
(:title "Symbol Name Normalization"
|
||||
:concepts (("symbol name" "normalization")
|
||||
("normalization" "of symbol name")))
|
||||
"SBCL also extends the reader to normalize all symbols to _Normalization
|
||||
Form KC_ in builds with Unicode enabled. Whether symbols are
|
||||
Form KC_ in builds with @UNICODE enabled. Whether symbols are
|
||||
normalized is controlled by"
|
||||
(sb-ext:readtable-normalization function)
|
||||
"Symbols created by INTERN and similar functions are not affected by
|
||||
|
|
@ -55,7 +61,9 @@
|
|||
are not normalized are escaped during printing.")
|
||||
|
||||
(defsection @decimal-syntax-for-rationals
|
||||
(:title "Decimal Syntax for Rationals")
|
||||
(:title "Decimal Syntax for Rationals"
|
||||
:concepts ("decimal syntax for rationals"
|
||||
("rational," "decimal syntax")))
|
||||
"SBCL supports a decimal syntax for rationals, modelled after the
|
||||
standard syntax for floating-point numbers. If a number with
|
||||
floating-point syntax has an exponent marker of `r` or `R`
|
||||
|
|
@ -74,7 +82,10 @@
|
|||
however, rational numbers are printed in their standard syntax,
|
||||
irrespective of the value of *READ-DEFAULT-FLOAT-FORMAT*.")
|
||||
|
||||
(defsection @package-local-nicknames (:title "Package-Local Nicknames")
|
||||
(defsection @package-local-nicknames
|
||||
(:title "Package-Local Nicknames"
|
||||
:concepts (("package-local" "nicknames")
|
||||
("nicknames," "package-local")))
|
||||
"SBCL allows giving packages local nicknames: they allow short and
|
||||
easy-to-use names to be used without fear of name conflict associated
|
||||
with normal nicknames.
|
||||
|
|
@ -118,7 +129,8 @@
|
|||
the following variable."
|
||||
(sb-ext:*on-package-variance* variable))
|
||||
|
||||
(defsection @garbage-collection (:title "Garbage Collection")
|
||||
(defsection @garbage-collection (:title "Garbage Collection"
|
||||
:concepts ("garbage collection"))
|
||||
"SBCL provides additional garbage collection functionality not
|
||||
specified by ANSI."
|
||||
(sb-ext:gc function)
|
||||
|
|
@ -128,14 +140,16 @@
|
|||
(@introspection-and-tuning section)
|
||||
(@tracing-live-objects-back-to-roots section))
|
||||
|
||||
(defsection @finalization (:title "Finalization")
|
||||
(defsection @finalization (:title "Finalization"
|
||||
:concepts ("finalization"))
|
||||
"Finalization allows code to be executed after an object has been
|
||||
garbage collected. This is useful for example for releasing foreign
|
||||
memory associated with a Lisp object."
|
||||
(sb-ext:finalize function)
|
||||
(sb-ext:cancel-finalization function))
|
||||
|
||||
(defsection @weak-pointers (:title "Weak Pointers")
|
||||
(defsection @weak-pointers (:title "Weak Pointers"
|
||||
:concepts ("weak pointers"))
|
||||
"Weak pointers allow references to objects to be maintained without
|
||||
keeping them from being garbage collected: useful for building caches
|
||||
among other things.
|
||||
|
|
@ -234,7 +248,7 @@
|
|||
|
||||
- SLOT-VALUE and SLOT-BOUNDP function as expected, including (for
|
||||
SLOT-VALUE) calling and respecting the return value of
|
||||
SLOT-UNBOUND if the slot is unbound;
|
||||
SLOT-UNBOUND if the slot is unbound; ~UNBOUND-SLOT
|
||||
|
||||
- `(SETF SLOT-VALUE)` functions as expected, including performing
|
||||
type checks to verify that the new value is of an appropriate type
|
||||
|
|
@ -440,8 +454,8 @@
|
|||
methods convert between classes and proper names and between lists
|
||||
of the form `(EQL <x>)` and interned eql specializer objects.
|
||||
|
||||
- Distinguishing unbound instance allocated slots from bound ones
|
||||
when using SB-MOP:STANDARD-INSTANCE-ACCESS and
|
||||
- Distinguishing unbound instance allocated slots ~UNBOUND-SLOT from
|
||||
bound ones when using SB-MOP:STANDARD-INSTANCE-ACCESS and
|
||||
SB-MOP:FUNCALLABLE-STANDARD-INSTANCE-ACCESS is possible by
|
||||
comparison to the symbol-macro SB-PCL:+SLOT-UNBOUND+.")
|
||||
|
||||
|
|
@ -633,7 +647,8 @@
|
|||
(sb-ext:process-close function)
|
||||
(sb-ext:process-kill function))
|
||||
|
||||
(defsection @unicode-support (:title "Unicode Support")
|
||||
(defsection @unicode-support (:title "Unicode Support"
|
||||
:concepts (@unicode))
|
||||
"SBCL provides support for working with Unicode text and querying the
|
||||
standard Unicode database for information about individual codepoints.
|
||||
Unicode-related functions are located in the `SB-UNICODE` package.
|
||||
|
|
@ -702,7 +717,8 @@
|
|||
(sb-unicode:sentence-break-class function)
|
||||
(sb-unicode:line-break-class function))
|
||||
|
||||
(defsection @string-operations (:title "String operations")
|
||||
(defsection @string-operations (:title "String operations"
|
||||
:concepts (("normalization" "of strings")))
|
||||
"SBCL can normalize strings using:"
|
||||
(sb-unicode:normalize-string function)
|
||||
(sb-unicode:normalized-p function)
|
||||
|
|
@ -781,7 +797,7 @@
|
|||
the condition accessor SB-EXT:NAME-CONFLICT-SYMBOLS.")
|
||||
|
||||
(defsection @hash-table-extensions (:title "Hash Table Extensions")
|
||||
"Hash table extensions supported by SBCL are all controlled by keyword
|
||||
"@HASH-TABLE extensions supported by SBCL are all controlled by keyword
|
||||
arguments to MAKE-HASH-TABLE."
|
||||
(make-hash-table function)
|
||||
(sb-ext:define-hash-table-test macro)
|
||||
|
|
@ -789,7 +805,8 @@
|
|||
(sb-ext:hash-table-synchronized-p function)
|
||||
(sb-ext:hash-table-weakness function))
|
||||
|
||||
(defsection @random-number-generation (:title "Random Number Generation")
|
||||
(defsection @random-number-generation (:title "Random Number Generation"
|
||||
:concepts ("random number generation"))
|
||||
"The initial value of *RANDOM-STATE* is the same each time SBCL
|
||||
is started. This makes it possible for user code to obtain
|
||||
repeatable pseudo random numbers using only standard-provided
|
||||
|
|
@ -883,7 +900,8 @@
|
|||
(@asynchronous-timeouts section)
|
||||
(@operations-supporting-timeouts-and-deadlines section))
|
||||
|
||||
(defsection @timeout-parameters (:title "Timeout Parameters")
|
||||
(defsection @timeout-parameters (:title "Timeout Parameters"
|
||||
:concepts (("timeout" "parameters")))
|
||||
"Certain operations accept :TIMEOUT keyword arguments. These only
|
||||
affect the specific operation and must be specified at each call
|
||||
site by passing a :TIMEOUT keyword argument and a corresponding
|
||||
|
|
@ -916,7 +934,10 @@
|
|||
;; here.
|
||||
)
|
||||
|
||||
(defsection @synchronous-timeouts (:title "Synchronous Timeouts")
|
||||
(defsection @synchronous-timeouts (:title "Synchronous Timeouts"
|
||||
:concepts (("synchronous" "timeout")
|
||||
("timeout," "synchronous")
|
||||
"deadline"))
|
||||
"Deadlines, in contrast to timeout parameters, are established for a
|
||||
dynamic scope using the SB-SYS:WITH-DEADLINE macro and indirectly
|
||||
affect operations within that scope. In case of nested uses, the
|
||||
|
|
@ -957,7 +978,9 @@
|
|||
three seconds, a SB-SYS:DEADLINE-TIMEOUT condition will be signaled
|
||||
after the SLEEP call has been executing for one second.")
|
||||
|
||||
(defsection @asynchronous-timeouts (:title "Asynchronous Timeouts")
|
||||
(defsection @asynchronous-timeouts (:title "Asynchronous Timeouts"
|
||||
:concepts (("asynchronous" "timeout")
|
||||
("timeout," "asynchronous")))
|
||||
"Asynchronous timeouts are established for a dynamic scope using the
|
||||
SB-EXT:WITH-TIMEOUT macro:"
|
||||
(sb-ext:with-timeout macro)
|
||||
|
|
@ -1038,8 +1061,8 @@
|
|||
is well suited to the program's memory usage pattern. It also allows
|
||||
permanent code to be frozen at fixed addresses, a precondition for
|
||||
using copy-on-write to share code between multiple Lisp processes.
|
||||
This is less important with modern generational garbage collectors,
|
||||
but not all SBCL platforms use such a garbage collector.
|
||||
This is less important with modern @GENERATIONAL-GC, but not all
|
||||
SBCL platforms use such a garbage collector.
|
||||
|
||||
The SB-EXT:TRULY-THE special form declares the type of the result of
|
||||
the operations, producing its argument; the declaration is not
|
||||
|
|
|
|||
|
|
@ -16,12 +16,17 @@
|
|||
(@interpreter section)
|
||||
(@advanced-compiler-use-and-efficiency-hints section))
|
||||
|
||||
(defsection @diagnostic-messages (:title "Diagnostic Messages")
|
||||
(defsection @diagnostic-messages (:title "Diagnostic Messages"
|
||||
:concepts (("compiler" "messsage")
|
||||
("messsage," "compiler")))
|
||||
(@controlling-verbosity section)
|
||||
(@diagnostic-severity section)
|
||||
(@understanding-compiler-diagnostics section))
|
||||
|
||||
(defsection @controlling-verbosity (:title "Controlling Verbosity")
|
||||
(defsection @controlling-verbosity
|
||||
(:title "Controlling Verbosity"
|
||||
:concepts (("compiler" "messsage" "verbosity")
|
||||
("verbosity" "of compiler messsages")))
|
||||
"The compiler can be quite verbose in its diagnostic reporting, rather
|
||||
more then some users would prefer -- the amount of noise emitted can
|
||||
be controlled, however.
|
||||
|
|
@ -91,7 +96,10 @@
|
|||
;; associated with anonymous functions.
|
||||
;; \end{defmac}
|
||||
|
||||
(defsection @diagnostic-severity (:title "Diagnostic Severity")
|
||||
(defsection @diagnostic-severity
|
||||
(:title "Diagnostic Severity"
|
||||
:concepts (("compiler" "message" "severity")
|
||||
("severity" "of compiler message")))
|
||||
"There are four levels of compiler diagnostic severity:
|
||||
|
||||
- error
|
||||
|
|
@ -137,7 +145,7 @@
|
|||
defined anywhere."
|
||||
(@parts-of-a-compiler-diagnostic section)
|
||||
(@original-and-actual-source section)
|
||||
(@processing-path section))
|
||||
(@processing-paths section))
|
||||
|
||||
(defsection @parts-of-a-compiler-diagnostic
|
||||
(:title "Parts of a Compiler Diagnostic")
|
||||
|
|
@ -170,17 +178,17 @@
|
|||
they are all printed from the outside in, separated by `=>`s. In
|
||||
this example, the problem was in the DEFUN for `FOO`.
|
||||
|
||||
- `(ZOQ Y)` is the _original source_ form responsible for the
|
||||
- `(ZOQ Y)` is the _@ORIGINAL-SOURCE_ form responsible for the
|
||||
diagnostic. Original source means that the form directly appeared
|
||||
in the original input to the compiler, i.e. in the lambda passed
|
||||
to COMPILE or in the top level form read from the source file. In
|
||||
this example, the expansion of the `ZOQ` macro was responsible for
|
||||
the message.
|
||||
|
||||
- `--> ROQ PLOQ` This is the _processing path_ that the compiler
|
||||
- `--> ROQ PLOQ` This is the _@PROCESSING-PATH_ that the compiler
|
||||
used to produce the code that caused the message to be emitted.
|
||||
The processing path is a representation of the evaluated forms
|
||||
enclosing the actual source that the compiler encountered when
|
||||
enclosing the @ACTUAL-SOURCE that the compiler encountered when
|
||||
processing the original source. The path is the first element of
|
||||
each form, or the form itself if the form is not a list. These
|
||||
forms result from the expansion of macros or source-to-source
|
||||
|
|
@ -254,7 +262,9 @@
|
|||
intervene between the original source and the actual source, then
|
||||
the processing path will also be omitted.")
|
||||
|
||||
(defsection @original-and-actual-source (:title "Original and Actual Source")
|
||||
(defsection @original-and-actual-source (:title "Original and Actual Source"
|
||||
:concepts (@original-source
|
||||
@actual-source))
|
||||
"The _original source_ displayed will almost always be a list. If
|
||||
the actual source for an message is a symbol, the original source will
|
||||
be the immediately enclosing evaluated list form. So even if the
|
||||
|
|
@ -295,7 +305,8 @@
|
|||
this example, the problem is that `A`'s NIL initial value is not a
|
||||
FIXNUM.")
|
||||
|
||||
(defsection @processing-path (:title "Processing Path")
|
||||
(defsection @processing-paths (:title "Processing Paths"
|
||||
:concepts (@processing-path))
|
||||
"The processing path is mainly useful for debugging macros, so if you
|
||||
don't write macros, you can probably ignore it. Consider this example:
|
||||
|
||||
|
|
@ -320,7 +331,8 @@
|
|||
((>= i #:g1) *undefined*)
|
||||
(declare (type unsigned-byte i)))
|
||||
|
||||
The rest of the processing path results from the expansion of DO:
|
||||
The rest of the processing path results from the @MACROEXPANSION of
|
||||
DO: ~SOURCE-TRANSFORM
|
||||
|
||||
(block nil
|
||||
(let ((i 0) (#:g1 n))
|
||||
|
|
@ -377,10 +389,11 @@
|
|||
|
||||
CLOS slot types form a notable exception. Types declared using the
|
||||
:TYPE slot option in DEFCLASS are asserted if and only if the class
|
||||
was defined in _safe code_ and the slot access location is in _safe
|
||||
code_ as well. This laxness does not pose any internal consistency
|
||||
issues, as the CLOS slot types are not available for the type
|
||||
inferencer, nor do CLOS slot types provide any efficiency benefits.
|
||||
was defined in _safe code_ ~SAFETY and the slot access location is
|
||||
in _safe code_ as well. This laxness does not pose any internal
|
||||
consistency issues, as the CLOS slot types are not available for the
|
||||
type inferencer, nor do CLOS slot types provide any efficiency
|
||||
benefits.
|
||||
|
||||
There are three type checking policies available in SBCL, selectable
|
||||
via OPTIMIZE declarations."
|
||||
|
|
@ -415,7 +428,9 @@
|
|||
|
||||
Used when `(= SAFETY 0)`.")
|
||||
|
||||
(defsection @precise-type-checking (:title "Precise Type Checking")
|
||||
(defsection @precise-type-checking (:title "Precise Type Checking"
|
||||
:concepts (("type checking," "precise")
|
||||
("precise" "type checking")))
|
||||
"Precise checking means that the check is done as though TYPEP
|
||||
had been called with the exact type specifier that appeared in the
|
||||
declaration.
|
||||
|
|
@ -432,7 +447,10 @@
|
|||
MEMBER, and other list-style type specifiers.")
|
||||
|
||||
(defsection @getting-existing-programs-to-run
|
||||
(:title "Getting Existing Programs to Run")
|
||||
(:title "Getting Existing Programs to Run"
|
||||
:concepts (("existing programs," "getting them to run")
|
||||
("types," "portability")
|
||||
("compatibility" "with other Lisps")))
|
||||
"Since SBCL's compiler does much more comprehensive type checking than
|
||||
most Lisp compilers, SBCL may detect type errors in programs that have
|
||||
been debugged using other compilers. These errors are mostly incorrect
|
||||
|
|
@ -441,7 +459,7 @@
|
|||
|
||||
Some incorrect declarations can only be detected by run-time type
|
||||
checking. It is very important to initially compile a program with
|
||||
full type checks (high SAFETY optimization) and then test this safe
|
||||
full type checks (high @SAFETY optimization) and then test this safe
|
||||
version. After the checking version has been tested, then you can
|
||||
consider weakening or eliminating type checks. _This applies even to
|
||||
previously debugged programs_ because the SBCL compiler does much
|
||||
|
|
@ -721,7 +739,10 @@
|
|||
(@errors-during-macroexpansion section)
|
||||
(@read-errors section))
|
||||
|
||||
(defsection @type-errors-at-compile-time (:title "Type Errors at Compile Time")
|
||||
(defsection @type-errors-at-compile-time
|
||||
(:title "Type Errors at Compile Time"
|
||||
:concepts (("compile-time" "type error")
|
||||
("type error," "compile-time")))
|
||||
"If the compiler can prove at compile time that some portion of the
|
||||
program cannot be executed without a type error, then it will give a
|
||||
warning at compile time.
|
||||
|
|
@ -766,7 +787,8 @@
|
|||
an error if it is executed) and gives a warning.")
|
||||
|
||||
(defsection @errors-during-macroexpansion
|
||||
(:title "Errors During Macroexpansion")
|
||||
(:title "Errors During Macroexpansion"
|
||||
:concepts (("macroexpansion," "errors during")))
|
||||
"The compiler handles errors that happen during macroexpansion, turning
|
||||
them into compiler errors. If you want to debug the error (to debug
|
||||
a macro), you can set *BREAK-ON-SIGNALS* to ERROR. For example, this
|
||||
|
|
@ -789,13 +811,18 @@
|
|||
; (hint: For more precise location, try *BREAK-ON-SIGNALS*.)
|
||||
; DO step variable is not a symbol: (ATOM CURRENT)")
|
||||
|
||||
(defsection @read-errors (:title "Read Errors")
|
||||
(defsection @read-errors (:title "Read Errors"
|
||||
:concepts (("compiler" "read error")
|
||||
("read error," "compiler")))
|
||||
"SBCL's compiler does not attempt to recover from read errors when
|
||||
reading a source file, but instead just reports the offending
|
||||
character position and gives up on the entire source file.")
|
||||
|
||||
(defsection @open-coding-and-inline-expansion
|
||||
(:title "Open Coding and Inline Expansion")
|
||||
(:title "Open Coding and Inline Expansion"
|
||||
:concepts ("open-coding"
|
||||
("inline" "expansion")
|
||||
("static" "functions")))
|
||||
"Since Common Lisp forbids the redefinition of standard functions, the
|
||||
compiler can have special knowledge of these standard functions
|
||||
embedded in it. This special knowledge is used in various ways (open
|
||||
|
|
@ -849,7 +876,8 @@
|
|||
or compiled as _static call_. Static function call uses a more
|
||||
efficient calling convention that forbids redefinition.")
|
||||
|
||||
(defsection @interpreter (:title "Interpreter")
|
||||
(defsection @interpreter (:title "Interpreter"
|
||||
:concepts ("interpreter"))
|
||||
"By default SBCL implements EVAL by calling the native code
|
||||
compiler.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,5 +1,108 @@
|
|||
(in-package :sb-manual)
|
||||
|
||||
(define-concept @interning-symbols (:title "interning symbols"
|
||||
:keys (("interning" "symbols")
|
||||
("symbols," "interning"))))
|
||||
|
||||
(define-concept @package-lock (:title "package lock"
|
||||
:keys (("package" "lock")
|
||||
("lock," "package"))))
|
||||
|
||||
(define-concept @unicode (:title "Unicode" :keys ("Unicode")))
|
||||
|
||||
(define-concept @nfkc (:title "NFKC"
|
||||
:keys ("NFKC"
|
||||
"normalization form compatibility composition")))
|
||||
|
||||
(define-concept ~unbound-slot (:keys (("unbound" "slot")
|
||||
("slot," "unbound"))))
|
||||
|
||||
(define-concept ~character-name (:keys (("character" "name")
|
||||
("name" "of character"))))
|
||||
|
||||
(define-concept @hash-table (:title "hash table"
|
||||
:keys (("hash" "table"))))
|
||||
|
||||
(define-concept @actual-source (:title "actual source"
|
||||
:keys (("actual" "source")
|
||||
("source," "actual"))))
|
||||
|
||||
(define-concept @original-source (:title "original source"
|
||||
:keys (("original" "source")
|
||||
("source," "original"))))
|
||||
|
||||
(define-concept @processing-path (:title "processing path"
|
||||
:keys (("processing" "path"))))
|
||||
|
||||
(define-concept @macroexpansion (:title "macroexpansion"
|
||||
:keys ("macroexpansion")))
|
||||
|
||||
(define-concept ~source-transform (:keys (("source" "transform"))))
|
||||
|
||||
(define-concept ~safety (:keys (("safety," "optimization quality")
|
||||
("optimization quality" "safety"))))
|
||||
|
||||
(define-concept @safety (:title "safety" :keys (~safety)))
|
||||
|
||||
(define-concept ~debug (:keys (("debug," "optimization quality")
|
||||
("optimization quality" "debug"))))
|
||||
|
||||
(define-concept @debug (:title "debug" :keys (~debug)))
|
||||
|
||||
(define-concept @tail-recursion (:title "tail recursion"
|
||||
:keys (("tail" "recursion")
|
||||
("recursion," "tail"))))
|
||||
|
||||
(define-concept @tail-recursive (:title "tail recursive"
|
||||
:keys (@tail-recursion)))
|
||||
|
||||
(define-concept @interrupt (:title "interrupt"
|
||||
:keys ("interrupt")))
|
||||
|
||||
(define-concept ~run-time-error (:keys (("run-time" "error")
|
||||
("error," "run-time"))))
|
||||
|
||||
(define-concept @basic-block (:title "basic block"
|
||||
:keys ("basic block"
|
||||
("block," "basic"))))
|
||||
|
||||
(define-concept @block-start (:title "block start"
|
||||
:keys (("block," "start location"))))
|
||||
|
||||
(define-concept @semi-inline (:title "semi inline"
|
||||
:keys (("inline," "semi")
|
||||
("semi-inline"))))
|
||||
|
||||
(define-concept @external-format (:title "external format"
|
||||
:keys (("external" "format")
|
||||
("format," "external"))))
|
||||
|
||||
(define-concept @generational-gc
|
||||
(:title "generational GC"
|
||||
:keys (("garbage collector," "generational")
|
||||
("generational" "garbage collector"))))
|
||||
|
||||
(define-concept @conservative-gc
|
||||
(:title "conservative GC"
|
||||
:keys (("garbage collector," "conservative")
|
||||
("conservative" "garbage collector"))))
|
||||
|
||||
(define-concept @declaration (:title "declaration"
|
||||
:keys ("declaration")))
|
||||
|
||||
(define-concept @logical-pathname (:title "logical pathname"
|
||||
:keys (("logical" "pathname")
|
||||
("pathname," "logical"))))
|
||||
|
||||
(define-concept @ldb (:title "LDB" :keys ("LDB")))
|
||||
|
||||
(define-concept ~disabling-ldb (:title "disabling LDB"
|
||||
:keys (("disabling" "LDB")
|
||||
("LDB," "disabling"))))
|
||||
|
||||
(define-concept ~enabling-ldb (:title "enabling LDB"
|
||||
:keys (("enabling" "LDB")
|
||||
("LDB," "enabling"))))
|
||||
(define-concept ~repl (:keys ("Read-Eval-Print Loop" "REPL")))
|
||||
|
||||
(define-concept @repl (:title "REPL" :keys (~repl)))
|
||||
|
|
|
|||
|
|
@ -1,6 +1,7 @@
|
|||
(in-package :sb-manual)
|
||||
|
||||
(defsection @debugger (:title "Debugger")
|
||||
(defsection @debugger (:title "Debugger"
|
||||
:concepts ("debugger"))
|
||||
"This chapter documents the debugging facilities of SBCL, including
|
||||
the debugger, single-stepper and TRACE, and the effect of `(OPTIMIZE
|
||||
DEBUG)` declarations."
|
||||
|
|
@ -98,7 +99,8 @@
|
|||
debugger by using the SB-EXT:*DEBUG-PRINT-VARIABLE-ALIST*."
|
||||
(sb-ext:*debug-print-variable-alist* variable))
|
||||
|
||||
(defsection @stack-frames (:title "Stack Frames")
|
||||
(defsection @stack-frames (:title "Stack Frames"
|
||||
:concepts ("stack frame"))
|
||||
"A _stack frame_ is the run-time representation of a call to a
|
||||
function; the frame stores the state that a function needs to
|
||||
remember what it is doing. Frames have:
|
||||
|
|
@ -209,7 +211,14 @@
|
|||
lambdas will appear as `(LAMBDA <LAMBDA-LIST>)`."
|
||||
(@entry-point-details section))
|
||||
|
||||
(defsection @entry-point-details (:title "Entry Point Details")
|
||||
(defsection @entry-point-details
|
||||
(:title "Entry Point Details"
|
||||
:concepts (("external" "entry point")
|
||||
("entry point," "external")
|
||||
("block compilation," "debugger implications")
|
||||
("external," "stack frame kind")
|
||||
("optional," "stack frame kind")
|
||||
("cleanup," "stack frame kind")))
|
||||
"Sometimes the compiler introduces new functions that are used to
|
||||
implement a user function, but are not directly specified in the
|
||||
source. This is mostly done for argument type and count checking.
|
||||
|
|
@ -224,7 +233,7 @@
|
|||
|
||||
(defsection @debug-tail-recursion (:title "Debug Tail Recursion")
|
||||
"The compiler is _properly tail recursive_. If a function call is
|
||||
in a tail-recursive position, the stack frame will be deallocated
|
||||
in a @TAIL-RECURSIVE position, the stack frame will be deallocated
|
||||
_at the time of the call_, rather than after the call returns.
|
||||
Consider this backtrace:
|
||||
|
||||
|
|
@ -263,7 +272,9 @@
|
|||
)
|
||||
|
||||
(defsection @unknown-locations-and-interrupts
|
||||
(:title "Unknown Locations and Interrupts")
|
||||
(:title "Unknown Locations and Interrupts"
|
||||
:concepts (("unknown code location")
|
||||
("code location" "unknown")))
|
||||
"The debugger operates using special debugging information attached to
|
||||
the compiled code. This debug information tells the debugger what it
|
||||
needs to know about the locations in the code where the debugger can
|
||||
|
|
@ -278,10 +289,10 @@
|
|||
- There is inadequate debug information due to the value of the
|
||||
DEBUG optimization quality. See @DEBUGGER-POLICY-CONTROL.
|
||||
|
||||
- The debugger was entered because of an interrupt such as `C-c`.
|
||||
- The debugger was entered because of an @INTERRUPT such as `C-c`.
|
||||
|
||||
- A hardware error such as a bus error occurred in code that was
|
||||
compiled unsafely due to the value of the SAFETY
|
||||
- A hardware error ~RUN-TIME-ERROR such as a bus error occurred in
|
||||
code that was compiled unsafely due to the value of the SAFETY
|
||||
optimization quality."
|
||||
;; FIXME: reinstate link when section on optimize qualities exists.
|
||||
;; @OPTIMIZE-DECLARATION.
|
||||
|
|
@ -296,7 +307,9 @@
|
|||
be located. If this happens, return from the interrupt and try
|
||||
again.")
|
||||
|
||||
(defsection @variable-access (:title "Variable Access")
|
||||
(defsection @variable-access (:title "Variable Access"
|
||||
:concepts (("debug" "variables")
|
||||
("variable," "debugger access")))
|
||||
"There are two ways to access the current frame's local variables in
|
||||
the debugger: `list-locals` and SB-DEBUG:VAR.
|
||||
|
||||
|
|
@ -331,7 +344,10 @@
|
|||
(@variable-value-availability section)
|
||||
(@note-on-lexical-variable-access section))
|
||||
|
||||
(defsection @variable-value-availability (:title "Variable Value Availability")
|
||||
(defsection @variable-value-availability
|
||||
(:title "Variable Value Availability"
|
||||
:concepts (("variable," "value availabilty in debugger")
|
||||
("debug variable," "value availabilty")))
|
||||
"The value of a variable may be unavailable to the debugger in portions
|
||||
of the program where Lisp says that the variable is defined. If a
|
||||
variable value is not available, the debugger will not let you read
|
||||
|
|
@ -353,10 +369,10 @@
|
|||
|
||||
The value of a variable may be unavailable for these reasons:
|
||||
|
||||
- The value of the DEBUG optimization quality may have omitted debug
|
||||
information needed to determine whether the variable is available.
|
||||
Unless a variable is an argument, its value will only be available
|
||||
when DEBUG is at least 2.
|
||||
- The value of the @DEBUG optimization quality may have omitted
|
||||
debug information needed to determine whether the variable is
|
||||
available. Unless a variable is an argument, its value will only
|
||||
be available when DEBUG is at least 2.
|
||||
|
||||
- The compiler did lifetime analysis and determined that the value
|
||||
was no longer needed, even though its scope had not been exited.
|
||||
|
|
@ -418,7 +434,9 @@
|
|||
proved the variable could never take on. This may result in bad
|
||||
things happening.")
|
||||
|
||||
(defsection @source-location-printing (:title "Source Location Printing")
|
||||
(defsection @source-location-printing
|
||||
(:title "Source Location Printing"
|
||||
:concepts (("source location" "in debugger")))
|
||||
"One of the debugger's capabilities is source level debugging of
|
||||
compiled code. These commands display the source location for the
|
||||
current frame:
|
||||
|
|
@ -525,7 +543,7 @@
|
|||
|
||||
(defsection @source-location-availability
|
||||
(:title "Source Location Availability")
|
||||
"Source location information is only available when the DEBUG
|
||||
"Source location information is only available when the @DEBUG
|
||||
optimization quality is at least 2. If source location information
|
||||
is unavailable, the source commands will give an error message.
|
||||
|
||||
|
|
@ -537,11 +555,11 @@
|
|||
Unknown location: using block start.
|
||||
|
||||
and then proceed to print the source location for the start of the
|
||||
_basic block_ enclosing the code location. It's a bit complicated to
|
||||
_@BASIC-BLOCK_ enclosing the code location. It's a bit complicated to
|
||||
explain exactly what a basic block is, but here are some properties
|
||||
of the block start location:
|
||||
|
||||
- The block start location may be the same as the true location.
|
||||
- The @BLOCK-START location may be the same as the true location.
|
||||
|
||||
- The block start location will never be later in the program's flow
|
||||
of control than the true location.
|
||||
|
|
@ -561,9 +579,11 @@
|
|||
and the next conditional (but watch out because the compiler may
|
||||
have changed the program on you.)")
|
||||
|
||||
(defsection @debugger-policy-control (:title "Debugger Policy Control")
|
||||
(defsection @debugger-policy-control (:title "Debugger Policy Control"
|
||||
:concepts (("debugger" "policy")
|
||||
("policy," "debugger")))
|
||||
"The compilation policy specified by OPTIMIZE declarations
|
||||
affects the behavior seen in the debugger. The DEBUG quality
|
||||
affects the behavior seen in the debugger. The @DEBUG quality
|
||||
directly affects the debugger by controlling the amount of debugger
|
||||
information dumped. Other optimization qualities have indirect but
|
||||
observable effects due to changes in the way compilation is done.
|
||||
|
|
@ -629,9 +649,9 @@
|
|||
functions are inline expanded. If a function is inline expanded,
|
||||
then there will be no frame to represent the call, and the arguments
|
||||
will be treated like any other local variable. Functions may also be
|
||||
_semi-inline_, in which case there is a frame to represent the call,
|
||||
but the call is to an optimized local version of the function, not
|
||||
to the original function."
|
||||
_@SEMI-INLINE_, in which case there is a frame to represent the
|
||||
call, but the call is to an optimized local version of the function,
|
||||
not to the original function."
|
||||
;; FIXME: link to section about inline expansion when it exists
|
||||
;; (@INLINE-EXPANSION).
|
||||
)
|
||||
|
|
@ -684,7 +704,8 @@
|
|||
bottom. Only shows `<n>` frames if specified. The printing is
|
||||
controlled by SB-DEBUG:*DEBUG-PRINT-VARIABLE-ALIST*.")
|
||||
|
||||
(defsection @breakpoint-commands (:title "Breakpoint Commands")
|
||||
(defsection @breakpoint-commands (:title "Breakpoint Commands"
|
||||
:concepts ("breakpoint"))
|
||||
"SBCL supports setting of breakpoints inside compiled functions and
|
||||
stepping of compiled code. Breakpoints can only be set at known
|
||||
locations (see @UNKNOWN-LOCATIONS-AND-INTERRUPTS), so these commands
|
||||
|
|
@ -801,7 +822,9 @@
|
|||
> stepping may be improved enough to subsume the instrumentation
|
||||
> based stepping commands, which have much higher overhead.")
|
||||
|
||||
(defsection @function-tracing (:title "Function Tracing")
|
||||
(defsection @function-tracing (:title "Function Tracing"
|
||||
:concepts ("tracing"
|
||||
("function," "tracing")))
|
||||
"The tracer causes selected functions to print their arguments and
|
||||
their results whenever they are called. Options allow conditional
|
||||
printing of the trace information and conditional breakpoints on
|
||||
|
|
@ -830,7 +853,9 @@
|
|||
(sb-debug:*trace-encapsulate-default* variable)
|
||||
(sb-debug:*trace-report-default* variable))
|
||||
|
||||
(defsection @single-stepping (:title "Single Stepping")
|
||||
(defsection @single-stepping (:title "Single Stepping"
|
||||
:concepts ("stepper"
|
||||
"single-stepping"))
|
||||
"SBCL includes an instrumentation based single-stepper for compiled
|
||||
code, that can be invoked via the STEP macro, or from within the
|
||||
debugger. See @DEBUGGER-POLICY-CONTROL, for details on enabling
|
||||
|
|
@ -857,7 +882,13 @@
|
|||
(step macro))
|
||||
|
||||
(defsection @enabling-and-disabling-the-debugger
|
||||
(:title "Enabling and Disabling the Debugger")
|
||||
(:title "Enabling and Disabling the Debugger"
|
||||
:concepts (("debugger," "enabling")
|
||||
("debugger," "disabling")
|
||||
("enabling" "debugger")
|
||||
("disabling" "debugger")
|
||||
~enabling-ldb
|
||||
~disabling-ldb))
|
||||
"In certain contexts (e.g. non-interactive applications), it may be
|
||||
desirable to turn off the SBCL debugger (and possibly re-enable it).
|
||||
The functions here control the debugger."
|
||||
|
|
|
|||
|
|
@ -1,6 +1,7 @@
|
|||
(in-package :sb-manual)
|
||||
|
||||
(defsection @deprecation (:title "Deprecation")
|
||||
(defsection @deprecation (:title "Deprecation"
|
||||
:concepts ("deprecation"))
|
||||
"In order to support evolution of interfaces in SBCL as well as in user
|
||||
code, SBCL allows declaring functions, variables and types as
|
||||
deprecated. Users of deprecated things are notified by means of
|
||||
|
|
|
|||
|
|
@ -1,6 +1,7 @@
|
|||
(in-package :sb-manual)
|
||||
|
||||
(defsection @efficiency (:title "Efficiency")
|
||||
(defsection @efficiency (:title "Efficiency"
|
||||
:concepts ("efficicency"))
|
||||
(@slot-access section)
|
||||
(@stack-allocation section)
|
||||
(@modular-arithmetic section)
|
||||
|
|
@ -8,7 +9,8 @@
|
|||
(@global-and-always-bound-variables section)
|
||||
(@miscellaneous-efficiency-issues section))
|
||||
|
||||
(defsection @slot-access (:title "Slot Access")
|
||||
(defsection @slot-access (:title "Slot Access"
|
||||
:concepts (("slot" "access")))
|
||||
(@structure-object-slot-access section)
|
||||
(@standard-object-slot-access section))
|
||||
|
||||
|
|
@ -88,7 +90,7 @@
|
|||
|
||||
> __Warning__: Stack space is limited, so allocation of a large
|
||||
> vector may cause stack overflow. Stack overflow checks are
|
||||
> done except in zero SAFETY policies.
|
||||
> done except in 0 @SAFETY policies.
|
||||
|
||||
- closures defined with FLET or LABELS with a bound DYNAMIC-EXTENT
|
||||
declaration;
|
||||
|
|
@ -231,7 +233,10 @@
|
|||
(declare (optimize speed (safety 0) (debug 0)))
|
||||
(trivial-hof (lambda (a b) (+ a b x)) 92))")
|
||||
|
||||
(defsection @modular-arithmetic (:title "Modular Arithmetic")
|
||||
(defsection @modular-arithmetic (:title "Modular Arithmetic"
|
||||
:concepts ("modular arithmetic"
|
||||
("arithmetic," "modular")
|
||||
("arithmetic," "hardware")))
|
||||
"Some numeric functions have a property: n lower bits of the
|
||||
result depend only on n lower bits of (all or some) arguments. If
|
||||
the compiler sees an expression of form `(LOGAND <EXPR> <MASK>)`,
|
||||
|
|
@ -272,7 +277,10 @@
|
|||
(let ((u (ldb (byte 64 0) (+ a b))))
|
||||
(logior u (- (mask-field (byte 1 63) u)))))")
|
||||
|
||||
(defsection @recognized-idioms (:title "Recognized Idioms")
|
||||
(defsection @recognized-idioms (:title "Recognized Idioms"
|
||||
:concepts ("modular arithmetic"
|
||||
("arithmetic," "modular")
|
||||
("arithmetic," "hardware")))
|
||||
"Common Lisp doesn't directly expose all features present in
|
||||
modern hardware. Some code patterns are recognized and turned into
|
||||
more efficient hardware instructions without requiring the use of
|
||||
|
|
@ -335,10 +343,10 @@
|
|||
;; real problems are loop induction, closed over variables and
|
||||
;; aliases.
|
||||
"- Since the time the CMUCL manual was written, CMUCL (and thus SBCL)
|
||||
has gotten a generational garbage collector. This means that there
|
||||
are some efficiency implications of various patterns of memory
|
||||
usage which aren't discussed in the CMUCL manual. (Some new
|
||||
material should be written about this.)
|
||||
has gotten a @GENERATIONAL-GC. This means that there are some
|
||||
efficiency implications of various patterns of memory usage which
|
||||
aren't discussed in the CMUCL manual. (Some new material should be
|
||||
written about this.)
|
||||
|
||||
- SBCL has some important known efficiency problems. Perhaps the
|
||||
most important are
|
||||
|
|
|
|||
|
|
@ -1,6 +1,7 @@
|
|||
(in-package :sb-manual)
|
||||
|
||||
(defsection @external-formats (:title "External Formats")
|
||||
(defsection @external-formats (:title "External Formats"
|
||||
:concepts (@external-format))
|
||||
"External formats determine the coding of characters from/to sequences
|
||||
of octets when exchanging data with the outside world. Examples of
|
||||
such exchanges are:
|
||||
|
|
|
|||
|
|
@ -225,17 +225,17 @@
|
|||
declare that no useful value is returned. Using ALIEN-FUNCALL to
|
||||
call a VOID foreign function will return zero values.
|
||||
|
||||
- The foreign type specifier `(C-STRING &KEY <external-format>
|
||||
<element-type> <not-null>)` is similar to `(* CHAR)` but is
|
||||
- The foreign type specifier `(C-STRING &KEY <EXTERNAL-FORMAT>
|
||||
<ELEMENT-TYPE> <NOT-NULL>)` is similar to `(* CHAR)` but is
|
||||
interpreted as a null-terminated string, and is automatically
|
||||
converted into a Lisp string when accessed; or if the pointer is C
|
||||
`\\NULL` or 0, then accessing it gives Lisp NIL unless
|
||||
`<not-null>` is true, in which case a TYPE-ERROR is signalled.
|
||||
`<NOT-NULL>` is true, in which case a TYPE-ERROR is signalled.
|
||||
|
||||
External format conversion is automatically done when Lisp
|
||||
@EXTERNAL-FORMAT conversion is automatically done when Lisp
|
||||
strings are passed to foreign code, or when foreign strings are
|
||||
passed to Lisp code. If the type specifier has an explicit
|
||||
`<external-format>`, that external format will be used.
|
||||
`<EXTERNAL-FORMAT>`, that external format will be used.
|
||||
Otherwise SB-EXT:*DEFAULT-C-STRING-EXTERNAL-FORMAT* will be
|
||||
used. For example, when the following alien routine is called,
|
||||
the Lisp string given as argument is converted to an \\EBCDIC
|
||||
|
|
@ -249,7 +249,7 @@
|
|||
assuming that the `<EXTERNAL-FORMAT>` and `<ELEMENT-TYPE>` of
|
||||
the C-STRING type are compatible with the internal
|
||||
representation of the string. For an SBCL built with Unicode
|
||||
support that means an `<external-format>` of :ASCII and an
|
||||
support that means an `<EXTERNAL-FORMAT>` of :ASCII and an
|
||||
`<ELEMENT-TYPE>` of BASE-CHAR. Without Unicode support the
|
||||
`<EXTERNAL-FORMAT>` can also be :ISO-8859-1, and the
|
||||
`<ELEMENT-TYPE>` can also be [CHARACTER][type]. If
|
||||
|
|
@ -615,11 +615,10 @@
|
|||
|
||||
- SB-SYS:WITH-PINNED-OBJECTS is a macro which arranges for some set
|
||||
of objects to be pinned in memory for the dynamic extent of its
|
||||
body forms. On ports which use the generational garbage
|
||||
collector (most, as of this writing) this affects exactly the
|
||||
specified objects. On other ports it is implemented by turning off
|
||||
GC for the duration (so could be said to have a whole-world
|
||||
granularity).
|
||||
body forms. On ports which use the @GENERATIONAL-GC
|
||||
(most, as of this writing) this affects exactly the specified
|
||||
objects. On other ports it is implemented by turning off GC for
|
||||
the duration (so could be said to have a whole-world granularity).
|
||||
|
||||
- Disable GC, using the SB-EXT:WITHOUT-GCING macro."
|
||||
(@lisp-as-a-shared-library section))
|
||||
|
|
|
|||
|
|
@ -128,8 +128,8 @@
|
|||
regression and unit-test framework.
|
||||
|
||||
- __MD5 Sums:__ The @SB-MD5 module provides an implementation of the
|
||||
MD5 message digest algorithm for Common Lisp, using the modular
|
||||
arithmetic optimizations provided by SBCL.")
|
||||
MD5 message digest algorithm for Common Lisp, using the
|
||||
@MODULAR-ARITHMETIC optimizations provided by SBCL.")
|
||||
|
||||
(defsection @idiosyncrasies (:title "Idiosyncrasies")
|
||||
"The information in this section describes some of the ways that SBCL
|
||||
|
|
@ -435,9 +435,8 @@
|
|||
|
||||
SBCL also inherited some newer architectural features from CMUCL.
|
||||
The most important is that on some architectures it has a
|
||||
generational garbage collector (GC), which has various
|
||||
implications (mostly good) for performance. These are discussed in
|
||||
another chapter, @EFFICIENCY.
|
||||
@GENERATIONAL-GC, which has various implications (mostly good) for
|
||||
performance. These are discussed in another chapter, @EFFICIENCY.
|
||||
|
||||
SBCL has diverged from CMUCL in that SBCL is now essentially a
|
||||
compiler-only implementation of Common Lisp. This is a change in
|
||||
|
|
@ -463,7 +462,7 @@
|
|||
(and has already improved in some other areas), but it takes a while.
|
||||
|
||||
On the x86 SBCL -- like the x86 port of CMUCL -- uses a
|
||||
_conservative_ GC. This means that it doesn't maintain a strict
|
||||
_@CONSERVATIVE-GC. This means that it doesn't maintain a strict
|
||||
separation between tagged and untagged data, instead treating some
|
||||
untagged data (e.g. raw floating point numbers) as possibly-tagged
|
||||
data and so not collecting any Lisp objects that they point to. This
|
||||
|
|
@ -471,9 +470,9 @@
|
|||
possibly no worse than the negative consequences of trying to
|
||||
implement an exact GC on a processor architecture as register-poor
|
||||
as the X86) and also has potentially unlimited consequences for
|
||||
worst-case memory efficiency. In practice, conservative garbage
|
||||
collectors work reasonably well, not getting anywhere near the worst
|
||||
case. But they can occasionally cause odd patterns of memory usage.
|
||||
worst-case memory efficiency. In practice, @CONSERVATIVE-GCs work
|
||||
reasonably well, not getting anywhere near the worst case. But they
|
||||
can occasionally cause odd patterns of memory usage.
|
||||
|
||||
The fork from CMUCL was based on a major rewrite of the system
|
||||
bootstrap process. CMUCL has for many years tolerated a very unusual
|
||||
|
|
|
|||
|
|
@ -1,6 +1,8 @@
|
|||
(in-package :sb-manual)
|
||||
|
||||
(defsection @package-locks (:title "Package Locks")
|
||||
(defsection @package-locks (:title "Package Locks"
|
||||
:concepts (("package" "lock")
|
||||
("lock," "package")))
|
||||
"None of the following sections apply to SBCL built without package
|
||||
locking support.
|
||||
|
||||
|
|
@ -49,7 +51,7 @@
|
|||
|
||||
(defsection @lexical-bindings-and-declarations
|
||||
(:title "Lexical Bindings and Declarations")
|
||||
"Lexical bindings or declarations that violate package locks cause a
|
||||
"Lexical bindings or @DECLARATIONs that violate package locks cause a
|
||||
compile-time warning, and a runtime PROGRAM-ERROR when the form that
|
||||
violates package locks would be executed.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,7 @@
|
|||
(in-package :sb-manual)
|
||||
|
||||
(defsection @pathnames (:title "Pathnames")
|
||||
(defsection @pathnames (:title "Pathnames"
|
||||
:concepts ("pathname"))
|
||||
(@lisp-pathnames section)
|
||||
(@native-filenames section))
|
||||
|
||||
|
|
@ -84,7 +85,7 @@
|
|||
(:title "The SYS Logical Pathname Host")
|
||||
;; The existence and meaning of SYS: logical pathnames is
|
||||
;; implementation-defined (CLHS 19.3.1.1.1).
|
||||
"The logical pathname host named by `\"SYS\"` exists in SBCL.
|
||||
"The @LOGICAL-PATHNAME host named by `\"SYS\"` exists in SBCL.
|
||||
Its LOGICAL-PATHNAME-TRANSLATIONS may be set by the site or the user
|
||||
applicable to point to the locations of the system's sources; in
|
||||
particular, the core system's source files match the logical
|
||||
|
|
|
|||
|
|
@ -1,6 +1,7 @@
|
|||
(in-package :sb-manual)
|
||||
|
||||
(defsection @profiling (:title "Profiling")
|
||||
(defsection @profiling (:title "Profiling"
|
||||
:concepts ("profiling"))
|
||||
"SBCL includes both a deterministic profiler, that can collect
|
||||
statistics on individual functions, and a more \"modern\",
|
||||
statistical profiler.
|
||||
|
|
@ -9,7 +10,9 @@
|
|||
(@deterministic-profiler section)
|
||||
(@statistical-profiler section))
|
||||
|
||||
(defsection @deterministic-profiler (:title "Deterministic Profiler")
|
||||
(defsection @deterministic-profiler
|
||||
(:title "Deterministic Profiler"
|
||||
:concepts (("profiling," "deterministic")))
|
||||
"The package `SB-PROFILE` provides a classic, per-function-call
|
||||
profiler.
|
||||
|
||||
|
|
@ -20,7 +23,8 @@
|
|||
(sb-profile:report function)
|
||||
(sb-profile:reset function))
|
||||
|
||||
(defsection @statistical-profiler (:title "Statistical Profiler")
|
||||
(defsection @statistical-profiler (:title "Statistical Profiler"
|
||||
:concepts (("profiling," "statistical")))
|
||||
"The `SB-SPROF` module, loadable by
|
||||
|
||||
(require :sb-sprof)
|
||||
|
|
@ -134,8 +138,8 @@
|
|||
__Platform support__
|
||||
|
||||
Allocation profiling is only supported on SBCL builds that use the
|
||||
generational garbage collector. Tracking of call stacks at a depth
|
||||
of more than two levels is only supported on x86 and x86-64.
|
||||
@GENERATIONAL-GC. Tracking of call stacks at a depth of more than
|
||||
two levels is only supported on x86 and x86-64.
|
||||
|
||||
__Macros__"
|
||||
(sb-sprof:with-profiling macro)
|
||||
|
|
|
|||
|
|
@ -174,7 +174,7 @@
|
|||
- `--disable-ldb`
|
||||
|
||||
Disable the low-level debugger. Only effective if SBCL is
|
||||
compiled with LDB.
|
||||
compiled with @LDB. ~DISABLING-LDB
|
||||
|
||||
- `--lose-on-corruption`
|
||||
|
||||
|
|
@ -184,7 +184,7 @@
|
|||
to continue and handle the error in Lisp, but this will not
|
||||
always work, and SBCL may malfunction or even hang. With this
|
||||
option, upon encountering such an error, SBCL will exit instead
|
||||
of invoking LDB (if present and enabled).
|
||||
of invoking @LDB (if present and enabled ~ENABLING-LDB).
|
||||
|
||||
- `--script <filename>`
|
||||
|
||||
|
|
|
|||
|
|
@ -30,7 +30,7 @@
|
|||
|
||||
(defsection @stream-external-formats (:title "Stream External Formats")
|
||||
"The function STREAM-EXTERNAL-FORMAT returns the canonical name of
|
||||
the external format (See @EXTERNAL-FORMATS) used by the stream for
|
||||
the @EXTERNAL-FORMAT (see @EXTERNAL-FORMATS) used by the stream for
|
||||
character-based input and/or output.
|
||||
|
||||
When constructing file streams, for example using OPEN or
|
||||
|
|
|
|||
|
|
@ -96,7 +96,7 @@
|
|||
such as `signal N is [un]blocked` or just hangs, and you want to
|
||||
send a useful bug report then:
|
||||
|
||||
- Compile SBCL with ldb enabled (feature `:sb-ldb`, see
|
||||
- Compile SBCL with @LDB enabled (feature `:SB-LDB`, see
|
||||
`base-target-features.lisp-expr`).
|
||||
|
||||
- Isolate a smallish test case, run it.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,7 @@
|
|||
@c Generated by the sb-manual contrib. Do not edit.
|
||||
|
||||
@node statistical profiler
|
||||
@cindex profiling, statistical
|
||||
@section Statistical Profiler
|
||||
|
||||
The @code{sb-sprof} module, loadable by
|
||||
|
|
@ -123,9 +124,11 @@ sampling runs.
|
|||
|
||||
@strong{Platform support}
|
||||
|
||||
@cindex garbage collector, generational
|
||||
@cindex generational garbage collector
|
||||
Allocation profiling is only supported on SBCL builds that use the
|
||||
generational garbage collector. Tracking of call stacks at a depth
|
||||
of more than two levels is only supported on x86 and x86-64.
|
||||
generational GC. Tracking of call stacks at a depth of more than
|
||||
two levels is only supported on x86 and x86-64.
|
||||
|
||||
@strong{Macros}
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,7 @@
|
|||
@c Generated by the sb-manual contrib. Do not edit.
|
||||
|
||||
@node beyond the ansi standard
|
||||
@cindex reader extensions
|
||||
@chapter Beyond the ANSI Standard
|
||||
|
||||
@menu
|
||||
|
|
@ -39,8 +40,12 @@ it still has quite a few. See @ref{contributed modules}.
|
|||
@end menu
|
||||
|
||||
@node extended package prefix syntax
|
||||
@cindex extended package prefix syntax
|
||||
@cindex package prefix syntax, extended
|
||||
@subsection Extended Package Prefix Syntax
|
||||
|
||||
@cindex interning symbols
|
||||
@cindex symbols, interning
|
||||
SBCL supports extended package prefix syntax, which allows specifying
|
||||
an alternate package instead of @code{*package*} for the reader to use as
|
||||
the default package for interning symbols:
|
||||
|
|
@ -55,13 +60,18 @@ Example:
|
|||
'foo::(bar quux zot) == '(foo::bar foo::quux foo::zot)
|
||||
@end example
|
||||
|
||||
@cindex package lock
|
||||
@cindex lock, package
|
||||
@code{*package*} is not rebound during the course of reading a form with
|
||||
extended package prefix syntax; if @code{foo::bar} would cause a
|
||||
read-time package lock violation, so does @code{foo::(bar)}.
|
||||
|
||||
@node symbol name normalization
|
||||
@cindex symbol name normalization
|
||||
@cindex normalization of symbol name
|
||||
@subsection Symbol Name Normalization
|
||||
|
||||
@cindex Unicode
|
||||
SBCL also extends the reader to normalize all symbols to @emph{Normalization
|
||||
Form KC} in builds with Unicode enabled. Whether symbols are
|
||||
normalized is controlled by
|
||||
|
|
@ -69,14 +79,18 @@ normalized is controlled by
|
|||
@anchor{Function sb-ext readtable-normalization}
|
||||
@ffindex @sortas{readtable-normalization sb-ext} readtable-normalization [sb-ext]
|
||||
@deffn{Function} sb-ext:readtable-normalization readtable
|
||||
Returns @code{t} if @code{readtable} normalizes symbols to NFKC, and @code{nil} otherwise.
|
||||
The @code{readtable-normalization} of the standard readtable is @code{t}.
|
||||
@cindex NFKC
|
||||
@cindex normalization form compatibility composition
|
||||
Returns @code{t} if @code{readtable} normalizes symbols to NFKC, and @code{nil}
|
||||
otherwise. The @code{readtable-normalization} of the standard readtable is @code{t}.
|
||||
@end deffn
|
||||
Symbols created by @code{intern} and similar functions are not affected by
|
||||
this setting. If @code{sb-ext:readtable-normalization} is @code{t}, symbols that
|
||||
are not normalized are escaped during printing.
|
||||
|
||||
@node decimal syntax for rationals
|
||||
@cindex decimal syntax for rationals
|
||||
@cindex rational, decimal syntax
|
||||
@subsection Decimal Syntax for Rationals
|
||||
|
||||
SBCL supports a decimal syntax for rationals, modelled after the
|
||||
|
|
@ -98,6 +112,8 @@ however, rational numbers are printed in their standard syntax,
|
|||
irrespective of the value of @code{*read-default-float-format*}.
|
||||
|
||||
@node package local nicknames
|
||||
@cindex package-local nicknames
|
||||
@cindex nicknames, package-local
|
||||
@section Package-Local Nicknames
|
||||
|
||||
SBCL allows giving packages local nicknames: they allow short and
|
||||
|
|
@ -239,6 +255,7 @@ specifies to signal a warning if SWANK package is in variance, and an
|
|||
error otherwise.
|
||||
@end deffn
|
||||
@node garbage collection
|
||||
@cindex garbage collection
|
||||
@section Garbage Collection
|
||||
|
||||
@menu
|
||||
|
|
@ -269,6 +286,7 @@ triggered during thread exits. In a multithreaded environment these hooks may
|
|||
run in any thread.
|
||||
@end deffn
|
||||
@node finalization
|
||||
@cindex finalization
|
||||
@subsection Finalization
|
||||
|
||||
Finalization allows code to be executed after an object has been
|
||||
|
|
@ -339,6 +357,7 @@ Examples:
|
|||
Cancel all finalizations for @code{object}, returning @code{t} if it had a finalizer.
|
||||
@end deffn
|
||||
@node weak pointers
|
||||
@cindex weak pointers
|
||||
@subsection Weak Pointers
|
||||
|
||||
Weak pointers allow references to objects to be maintained without
|
||||
|
|
@ -636,6 +655,8 @@ limitations, on structures (of metaclass @code{structure-class}).
|
|||
|
||||
For structures:
|
||||
|
||||
@cindex unbound slot
|
||||
@cindex slot, unbound
|
||||
@itemize
|
||||
@item The name of a slot for the purposes of the slot access functions
|
||||
is the symbol used as the slot-name in the slot-description in the
|
||||
|
|
@ -643,7 +664,7 @@ For structures:
|
|||
|
||||
@item @code{slot-value} and @code{slot-boundp} function as expected, including (for
|
||||
@code{slot-value}) calling and respecting the return value of
|
||||
@code{slot-unbound} if the slot is unbound;
|
||||
@code{slot-unbound} if the slot is unbound;
|
||||
|
||||
@item @code{(setf slot-value)} functions as expected, including performing
|
||||
type checks to verify that the new value is of an appropriate type
|
||||
|
|
@ -839,6 +860,8 @@ part of the contract of the @code{:instance} or @code{:class} allocations.
|
|||
In addition, SBCL supports extensions to the Metaobject protocol from
|
||||
AMOP; at present, they are:
|
||||
|
||||
@cindex unbound slot
|
||||
@cindex slot, unbound
|
||||
@itemize
|
||||
@item Compile-time support for generating specializer metaobjects from
|
||||
specializer names in @code{defmethod} forms is provided by the
|
||||
|
|
@ -863,8 +886,8 @@ AMOP; at present, they are:
|
|||
methods convert between classes and proper names and between lists
|
||||
of the form @code{(EQL <x>)} and interned eql specializer objects.
|
||||
|
||||
@item Distinguishing unbound instance allocated slots from bound ones
|
||||
when using @code{sb-mop:standard-instance-access} and
|
||||
@item Distinguishing unbound instance allocated slots from
|
||||
bound ones when using @code{sb-mop:standard-instance-access} and
|
||||
@code{sb-mop:funcallable-standard-instance-access} is possible by
|
||||
comparison to the symbol-macro @code{sb-pcl:+slot-unbound+}.
|
||||
@end itemize
|
||||
|
|
@ -1618,6 +1641,7 @@ Returns @code{t} if successful, otherwise returns @code{nil} and error
|
|||
number (two values).
|
||||
@end deffn
|
||||
@node unicode support
|
||||
@cindex Unicode
|
||||
@section Unicode Support
|
||||
|
||||
@menu
|
||||
|
|
@ -1859,6 +1883,7 @@ is @code{:east-asian}, Ambigious (class @code{:ai}) characters will be mapped to
|
|||
Ideographic (@code{:id}) class instead of Alphabetic (@code{:al}).
|
||||
@end deffn
|
||||
@node string operations
|
||||
@cindex normalization of strings
|
||||
@subsection String operations
|
||||
|
||||
SBCL can normalize strings using:
|
||||
|
|
@ -2083,7 +2108,8 @@ the condition accessor @code{sb-ext:name-conflict-symbols}.
|
|||
@node hash table extensions
|
||||
@section Hash Table Extensions
|
||||
|
||||
Hash table extensions supported by SBCL are all controlled by keyword
|
||||
@cindex hash table
|
||||
hash table extensions supported by SBCL are all controlled by keyword
|
||||
arguments to @code{make-hash-table}.
|
||||
|
||||
@anchor{Function common-lisp make-hash-table}
|
||||
|
|
@ -2246,6 +2272,7 @@ Return the @code{weakness} of @code{hash-table} which is one of @code{nil}, @cod
|
|||
@code{:value}, @code{:key-and-value}, @code{:key-or-value}.
|
||||
@end deffn
|
||||
@node random number generation
|
||||
@cindex random number generation
|
||||
@section Random Number Generation
|
||||
|
||||
The initial value of @code{*random-state*} is the same each time SBCL
|
||||
|
|
@ -2387,6 +2414,7 @@ available to individual operations or parts of computations:
|
|||
@end itemize
|
||||
|
||||
@node timeout parameters
|
||||
@cindex timeout parameters
|
||||
@subsection Timeout Parameters
|
||||
|
||||
Certain operations accept @code{:timeout} keyword arguments. These only
|
||||
|
|
@ -2432,6 +2460,9 @@ deadline.
|
|||
Experimental: subject to change without prior notice.
|
||||
@end deffn
|
||||
@node synchronous timeouts
|
||||
@cindex synchronous timeout
|
||||
@cindex timeout, synchronous
|
||||
@cindex deadline
|
||||
@subsection Synchronous Timeouts
|
||||
|
||||
Deadlines, in contrast to timeout parameters, are established for a
|
||||
|
|
@ -2511,6 +2542,8 @@ three seconds, a @code{sb-sys:deadline-timeout} condition will be signaled
|
|||
after the @code{sleep} call has been executing for one second.
|
||||
|
||||
@node asynchronous timeouts
|
||||
@cindex asynchronous timeout
|
||||
@cindex timeout, asynchronous
|
||||
@subsection Asynchronous Timeouts
|
||||
|
||||
Asynchronous timeouts are established for a dynamic scope using the
|
||||
|
|
@ -2716,6 +2749,8 @@ code and bring it up on the developers' mailing list.
|
|||
@node efficiency hacks
|
||||
@section Efficiency Hacks
|
||||
|
||||
@cindex garbage collector, generational
|
||||
@cindex generational garbage collector
|
||||
The @code{sb-ext:purify} function (available when @code{#+cheneygc}) causes
|
||||
SBCL first to collect all garbage, then to mark all uncollected
|
||||
objects as permanent, never again attempting to collect them as
|
||||
|
|
@ -2725,8 +2760,8 @@ efficiency when using a more sophisticated garbage collector which
|
|||
is well suited to the program's memory usage pattern. It also allows
|
||||
permanent code to be frozen at fixed addresses, a precondition for
|
||||
using copy-on-write to share code between multiple Lisp processes.
|
||||
This is less important with modern generational garbage collectors,
|
||||
but not all SBCL platforms use such a garbage collector.
|
||||
This is less important with modern generational GC, but not all
|
||||
SBCL platforms use such a garbage collector.
|
||||
|
||||
The @code{sb-ext:truly-the} special form declares the type of the result of
|
||||
the operations, producing its argument; the declaration is not
|
||||
|
|
|
|||
|
|
@ -22,6 +22,8 @@ naive translation. Efficiency issues are sufficiently varied and
|
|||
separate that they have their own chapter, @ref{efficiency}.
|
||||
|
||||
@node diagnostic messages
|
||||
@cindex compiler messsage
|
||||
@cindex messsage, compiler
|
||||
@section Diagnostic Messages
|
||||
|
||||
@menu
|
||||
|
|
@ -31,6 +33,8 @@ separate that they have their own chapter, @ref{efficiency}.
|
|||
@end menu
|
||||
|
||||
@node controlling verbosity
|
||||
@cindex compiler messsage verbosity
|
||||
@cindex verbosity of compiler messsages
|
||||
@subsection Controlling Verbosity
|
||||
|
||||
The compiler can be quite verbose in its diagnostic reporting, rather
|
||||
|
|
@ -102,6 +106,8 @@ For information about muffling warnings signaled outside of the
|
|||
compiler, see @ref{customization hooks for users}.
|
||||
|
||||
@node diagnostic severity
|
||||
@cindex compiler message severity
|
||||
@cindex severity of compiler message
|
||||
@subsection Diagnostic Severity
|
||||
|
||||
There are four levels of compiler diagnostic severity:
|
||||
|
|
@ -150,7 +156,7 @@ has written, having proved that it is unreachable.
|
|||
@menu
|
||||
* Parts of a Compiler Diagnostic: parts of a compiler diagnostic.
|
||||
* Original and Actual Source: original and actual source.
|
||||
* Processing Path: processing path.
|
||||
* Processing Paths: processing paths.
|
||||
@end menu
|
||||
|
||||
The messages emitted by the compiler contain a lot of detail in a
|
||||
|
|
@ -190,6 +196,11 @@ When processing this program, the compiler will produce this warning:
|
|||
In this example we see each of the six possible parts of a compiler
|
||||
diagnostic:
|
||||
|
||||
@cindex original source
|
||||
@cindex source, original
|
||||
@cindex processing path
|
||||
@cindex actual source
|
||||
@cindex source, actual
|
||||
@itemize
|
||||
@item @code{file: /tmp/foo.lisp} is the name of the file that the compiler
|
||||
read the relevant code from. The file name is displayed because it
|
||||
|
|
@ -295,6 +306,10 @@ intervene between the original source and the actual source, then
|
|||
the processing path will also be omitted.
|
||||
|
||||
@node original and actual source
|
||||
@cindex original source
|
||||
@cindex source, original
|
||||
@cindex actual source
|
||||
@cindex source, actual
|
||||
@subsubsection Original and Actual Source
|
||||
|
||||
The @emph{original source} displayed will almost always be a list. If
|
||||
|
|
@ -341,8 +356,9 @@ This message is not saying that there is a problem somewhere in this
|
|||
this example, the problem is that @code{a}'s @code{nil} initial value is not a
|
||||
@code{fixnum}.
|
||||
|
||||
@node processing path
|
||||
@subsubsection Processing Path
|
||||
@node processing paths
|
||||
@cindex processing path
|
||||
@subsubsection Processing Paths
|
||||
|
||||
The processing path is mainly useful for debugging macros, so if you
|
||||
don't write macros, you can probably ignore it. Consider this example:
|
||||
|
|
@ -374,7 +390,10 @@ Note that @code{do} appears in the processing path. This is because
|
|||
(declare (type unsigned-byte i)))
|
||||
@end example
|
||||
|
||||
The rest of the processing path results from the expansion of @code{do}:
|
||||
@cindex macroexpansion
|
||||
@cindex source transform
|
||||
The rest of the processing path results from the macroexpansion of
|
||||
@code{do}:
|
||||
|
||||
@example
|
||||
(block nil
|
||||
|
|
@ -431,12 +450,15 @@ not been proven to always hold are asserted at runtime.
|
|||
provide some exceptions to this rule, see
|
||||
@ref{implementation limitations}.}
|
||||
|
||||
@cindex safety, optimization quality
|
||||
@cindex optimization quality safety
|
||||
CLOS slot types form a notable exception. Types declared using the
|
||||
@code{:type} slot option in @code{defclass} are asserted if and only if the class
|
||||
was defined in @emph{safe code} and the slot access location is in @emph{safe
|
||||
code} as well. This laxness does not pose any internal consistency
|
||||
issues, as the CLOS slot types are not available for the type
|
||||
inferencer, nor do CLOS slot types provide any efficiency benefits.
|
||||
was defined in @emph{safe code} and the slot access location is
|
||||
in @emph{safe code} as well. This laxness does not pose any internal
|
||||
consistency issues, as the CLOS slot types are not available for the
|
||||
type inferencer, nor do CLOS slot types provide any efficiency
|
||||
benefits.
|
||||
|
||||
There are three type checking policies available in SBCL, selectable
|
||||
via @code{optimize} declarations.
|
||||
|
|
@ -477,6 +499,8 @@ Used when @code{(= safety 0)}.
|
|||
@end itemize
|
||||
|
||||
@node precise type checking
|
||||
@cindex type checking, precise
|
||||
@cindex precise type checking
|
||||
@subsection Precise Type Checking
|
||||
|
||||
Precise checking means that the check is done as though @code{typep}
|
||||
|
|
@ -495,6 +519,9 @@ slots as precisely as possible. This often involves the use of @code{or},
|
|||
@code{member}, and other list-style type specifiers.
|
||||
|
||||
@node getting existing programs to run
|
||||
@cindex existing programs, getting them to run
|
||||
@cindex types, portability
|
||||
@cindex compatibility with other Lisps
|
||||
@subsection Getting Existing Programs to Run
|
||||
|
||||
Since SBCL's compiler does much more comprehensive type checking than
|
||||
|
|
@ -503,9 +530,11 @@ been debugged using other compilers. These errors are mostly incorrect
|
|||
declarations, although compile-time type errors can find actual bugs
|
||||
if parts of the program have never been tested.
|
||||
|
||||
@cindex safety, optimization quality
|
||||
@cindex optimization quality safety
|
||||
Some incorrect declarations can only be detected by run-time type
|
||||
checking. It is very important to initially compile a program with
|
||||
full type checks (high @code{safety} optimization) and then test this safe
|
||||
full type checks (high safety optimization) and then test this safe
|
||||
version. After the checking version has been tested, then you can
|
||||
consider weakening or eliminating type checks. @emph{This applies even to
|
||||
previously debugged programs} because the SBCL compiler does much
|
||||
|
|
@ -787,6 +816,8 @@ Examples:
|
|||
@end menu
|
||||
|
||||
@node type errors at compile time
|
||||
@cindex compile-time type error
|
||||
@cindex type error, compile-time
|
||||
@subsection Type Errors at Compile Time
|
||||
|
||||
If the compiler can prove at compile time that some portion of the
|
||||
|
|
@ -837,6 +868,7 @@ executed), so it compiles the erroneous code (which will always signal
|
|||
an error if it is executed) and gives a warning.
|
||||
|
||||
@node errors during macroexpansion
|
||||
@cindex macroexpansion, errors during
|
||||
@subsection Errors During Macroexpansion
|
||||
|
||||
The compiler handles errors that happen during macroexpansion, turning
|
||||
|
|
@ -866,6 +898,8 @@ gives this error:
|
|||
@end example
|
||||
|
||||
@node read errors
|
||||
@cindex compiler read error
|
||||
@cindex read error, compiler
|
||||
@subsection Read Errors
|
||||
|
||||
SBCL's compiler does not attempt to recover from read errors when
|
||||
|
|
@ -873,6 +907,9 @@ reading a source file, but instead just reports the offending
|
|||
character position and gives up on the entire source file.
|
||||
|
||||
@node open coding and inline expansion
|
||||
@cindex open-coding
|
||||
@cindex inline expansion
|
||||
@cindex static functions
|
||||
@section Open Coding and Inline Expansion
|
||||
|
||||
Since Common Lisp forbids the redefinition of standard functions, the
|
||||
|
|
@ -941,6 +978,7 @@ or compiled as @emph{static call}. Static function call uses a more
|
|||
efficient calling convention that forbids redefinition.
|
||||
|
||||
@node interpreter
|
||||
@cindex interpreter
|
||||
@section Interpreter
|
||||
|
||||
By default SBCL implements @code{eval} by calling the native code
|
||||
|
|
|
|||
|
|
@ -1,6 +1,7 @@
|
|||
@c Generated by the sb-manual contrib. Do not edit.
|
||||
|
||||
@node debugger
|
||||
@cindex debugger
|
||||
@chapter Debugger
|
||||
|
||||
@menu
|
||||
|
|
@ -145,6 +146,7 @@ Initially empty, @code{*debug-print-variable-alist*} is typically used to
|
|||
provide bindings for printer control variables.
|
||||
@end deffn
|
||||
@node stack frames
|
||||
@cindex stack frame
|
||||
@section Stack Frames
|
||||
|
||||
@menu
|
||||
|
|
@ -288,6 +290,12 @@ by that name. Functions defined by @code{labels} and @code{flet} will appear as
|
|||
lambdas will appear as @code{(lambda <lambda-list>)}.
|
||||
|
||||
@node entry point details
|
||||
@cindex external entry point
|
||||
@cindex entry point, external
|
||||
@cindex block compilation, debugger implications
|
||||
@cindex external, stack frame kind
|
||||
@cindex optional, stack frame kind
|
||||
@cindex cleanup, stack frame kind
|
||||
@subsubsection Entry Point Details
|
||||
|
||||
Sometimes the compiler introduces new functions that are used to
|
||||
|
|
@ -305,8 +313,10 @@ entry points.
|
|||
@node debug tail recursion
|
||||
@subsection Debug Tail Recursion
|
||||
|
||||
@cindex tail recursion
|
||||
@cindex recursion, tail
|
||||
The compiler is @emph{properly tail recursive}. If a function call is
|
||||
in a tail-recursive position, the stack frame will be deallocated
|
||||
in a tail recursive position, the stack frame will be deallocated
|
||||
@emph{at the time of the call}, rather than after the call returns.
|
||||
Consider this backtrace:
|
||||
|
||||
|
|
@ -346,6 +356,8 @@ optimization quality is greater than 2. See
|
|||
@ref{debugger policy control}.
|
||||
|
||||
@node unknown locations and interrupts
|
||||
@cindex unknown code location
|
||||
@cindex code location unknown
|
||||
@subsection Unknown Locations and Interrupts
|
||||
|
||||
The debugger operates using special debugging information attached to
|
||||
|
|
@ -359,14 +371,17 @@ displayed.
|
|||
|
||||
There are three reasons why a code location could be unknown:
|
||||
|
||||
@cindex interrupt
|
||||
@cindex run-time error
|
||||
@cindex error, run-time
|
||||
@itemize
|
||||
@item There is inadequate debug information due to the value of the
|
||||
@code{debug} optimization quality. See @ref{debugger policy control}.
|
||||
|
||||
@item The debugger was entered because of an interrupt such as @code{C-c}.
|
||||
|
||||
@item A hardware error such as a bus error occurred in code that was
|
||||
compiled unsafely due to the value of the @code{safety}
|
||||
@item A hardware error such as a bus error occurred in
|
||||
code that was compiled unsafely due to the value of the @code{safety}
|
||||
optimization quality.
|
||||
@end itemize
|
||||
|
||||
|
|
@ -382,6 +397,8 @@ be located. If this happens, return from the interrupt and try
|
|||
again.
|
||||
|
||||
@node variable access
|
||||
@cindex debug variables
|
||||
@cindex variable, debugger access
|
||||
@section Variable Access
|
||||
|
||||
@menu
|
||||
|
|
@ -445,6 +462,8 @@ The result of this function is limited to the availability of
|
|||
variable information. This is @code{setf}able.
|
||||
@end deffn
|
||||
@node variable value availability
|
||||
@cindex variable, value availabilty in debugger
|
||||
@cindex debug variable, value availabilty
|
||||
@subsection Variable Value Availability
|
||||
|
||||
The value of a variable may be unavailable to the debugger in portions
|
||||
|
|
@ -470,11 +489,13 @@ never be available in the interrupted frame. See
|
|||
|
||||
The value of a variable may be unavailable for these reasons:
|
||||
|
||||
@cindex debug, optimization quality
|
||||
@cindex optimization quality debug
|
||||
@itemize
|
||||
@item The value of the @code{debug} optimization quality may have omitted debug
|
||||
information needed to determine whether the variable is available.
|
||||
Unless a variable is an argument, its value will only be available
|
||||
when @code{debug} is at least 2.
|
||||
@item The value of the debug optimization quality may have omitted
|
||||
debug information needed to determine whether the variable is
|
||||
available. Unless a variable is an argument, its value will only
|
||||
be available when @code{debug} is at least 2.
|
||||
|
||||
@item The compiler did lifetime analysis and determined that the value
|
||||
was no longer needed, even though its scope had not been exited.
|
||||
|
|
@ -543,6 +564,7 @@ proved the variable could never take on. This may result in bad
|
|||
things happening.
|
||||
|
||||
@node source location printing
|
||||
@cindex source location in debugger
|
||||
@section Source Location Printing
|
||||
|
||||
@menu
|
||||
|
|
@ -671,7 +693,9 @@ same @code{eq} list twice. If you don't define read macros and don't use
|
|||
@node source location availability
|
||||
@subsection Source Location Availability
|
||||
|
||||
Source location information is only available when the @code{debug}
|
||||
@cindex debug, optimization quality
|
||||
@cindex optimization quality debug
|
||||
Source location information is only available when the debug
|
||||
optimization quality is at least 2. If source location information
|
||||
is unavailable, the source commands will give an error message.
|
||||
|
||||
|
|
@ -684,11 +708,14 @@ print
|
|||
Unknown location: using block start.
|
||||
@end example
|
||||
|
||||
@cindex basic block
|
||||
@cindex block, basic
|
||||
and then proceed to print the source location for the start of the
|
||||
@emph{basic block} enclosing the code location. It's a bit complicated to
|
||||
explain exactly what a basic block is, but here are some properties
|
||||
of the block start location:
|
||||
|
||||
@cindex block, start location
|
||||
@itemize
|
||||
@item The block start location may be the same as the true location.
|
||||
|
||||
|
|
@ -712,10 +739,14 @@ and the next conditional (but watch out because the compiler may
|
|||
have changed the program on you.)
|
||||
|
||||
@node debugger policy control
|
||||
@cindex debugger policy
|
||||
@cindex policy, debugger
|
||||
@section Debugger Policy Control
|
||||
|
||||
@cindex debug, optimization quality
|
||||
@cindex optimization quality debug
|
||||
The compilation policy specified by @code{optimize} declarations
|
||||
affects the behavior seen in the debugger. The @code{debug} quality
|
||||
affects the behavior seen in the debugger. The debug quality
|
||||
directly affects the debugger by controlling the amount of debugger
|
||||
information dumped. Other optimization qualities have indirect but
|
||||
observable effects due to changes in the way compilation is done.
|
||||
|
|
@ -780,14 +811,16 @@ variable special-casing (see @ref{variable value availability}). Some
|
|||
degree of speed/debuggability tradeoff is unavoidable, but the
|
||||
effect is not too drastic when @code{debug} is at least 2.
|
||||
|
||||
@cindex inline, semi
|
||||
@cindex semi-inline
|
||||
In addition to @code{inline} and @code{notinline} declarations, the relative
|
||||
values of the @code{speed} and @code{space} qualities also change whether
|
||||
functions are inline expanded. If a function is inline expanded,
|
||||
then there will be no frame to represent the call, and the arguments
|
||||
will be treated like any other local variable. Functions may also be
|
||||
@emph{semi-inline}, in which case there is a frame to represent the call,
|
||||
but the call is to an optimized local version of the function, not
|
||||
to the original function.
|
||||
@emph{semi inline}, in which case there is a frame to represent the
|
||||
call, but the call is to an optimized local version of the function,
|
||||
not to the original function.
|
||||
|
||||
@node exiting commands
|
||||
@section Exiting Commands
|
||||
|
|
@ -846,6 +879,7 @@ function, but a few show general information.
|
|||
@end itemize
|
||||
|
||||
@node breakpoint commands
|
||||
@cindex breakpoint
|
||||
@section Breakpoint Commands
|
||||
|
||||
@menu
|
||||
|
|
@ -982,6 +1016,8 @@ based stepping commands, which have much higher overhead.
|
|||
@end quotation
|
||||
|
||||
@node function tracing
|
||||
@cindex tracing
|
||||
@cindex function, tracing
|
||||
@section Function Tracing
|
||||
|
||||
The tracer causes selected functions to print their arguments and
|
||||
|
|
@ -1152,6 +1188,8 @@ The default value for the @code{:encapsulate} option to @code{trace}.
|
|||
The default value for the @code{:report} option to @code{trace}.
|
||||
@end deffn
|
||||
@node single stepping
|
||||
@cindex stepper
|
||||
@cindex single-stepping
|
||||
@section Single Stepping
|
||||
|
||||
SBCL includes an instrumentation based single-stepper for compiled
|
||||
|
|
@ -1189,6 +1227,14 @@ functions in question have been compiled with sufficient @code{debug} policy
|
|||
to be at least partially steppable.
|
||||
@end deffn
|
||||
@node enabling and disabling the debugger
|
||||
@cindex debugger, enabling
|
||||
@cindex debugger, disabling
|
||||
@cindex enabling debugger
|
||||
@cindex disabling debugger
|
||||
@cindex enabling LDB
|
||||
@cindex LDB, enabling
|
||||
@cindex disabling LDB
|
||||
@cindex LDB, disabling
|
||||
@section Enabling and Disabling the Debugger
|
||||
|
||||
In certain contexts (e.g. non-interactive applications), it may be
|
||||
|
|
|
|||
|
|
@ -1,6 +1,7 @@
|
|||
@c Generated by the sb-manual contrib. Do not edit.
|
||||
|
||||
@node deprecation
|
||||
@cindex deprecation
|
||||
@chapter Deprecation
|
||||
|
||||
@menu
|
||||
|
|
|
|||
|
|
@ -1,6 +1,7 @@
|
|||
@c Generated by the sb-manual contrib. Do not edit.
|
||||
|
||||
@node efficiency
|
||||
@cindex efficicency
|
||||
@chapter Efficiency
|
||||
|
||||
@menu
|
||||
|
|
@ -13,6 +14,7 @@
|
|||
@end menu
|
||||
|
||||
@node slot access
|
||||
@cindex slot access
|
||||
@section Slot Access
|
||||
|
||||
@menu
|
||||
|
|
@ -109,9 +111,11 @@ of values when they are recognized as having dynamic extent:
|
|||
and one-dimensional, and has a constant @code{:element-type};
|
||||
|
||||
@quotation
|
||||
@cindex safety, optimization quality
|
||||
@cindex optimization quality safety
|
||||
@strong{Warning}: Stack space is limited, so allocation of a large
|
||||
vector may cause stack overflow. Stack overflow checks are
|
||||
done except in zero @code{safety} policies.
|
||||
done except in 0 safety policies.
|
||||
@end quotation
|
||||
|
||||
@item closures defined with @code{flet} or @code{labels} with a bound @code{dynamic-extent}
|
||||
|
|
@ -271,6 +275,9 @@ detect incorrect usage of dynamic extent declarations.
|
|||
@end example
|
||||
|
||||
@node modular arithmetic
|
||||
@cindex modular arithmetic
|
||||
@cindex arithmetic, modular
|
||||
@cindex arithmetic, hardware
|
||||
@section Modular Arithmetic
|
||||
|
||||
@menu
|
||||
|
|
@ -323,6 +330,9 @@ translated into signed modular arithmetic:
|
|||
@end example
|
||||
|
||||
@node recognized idioms
|
||||
@cindex modular arithmetic
|
||||
@cindex arithmetic, modular
|
||||
@cindex arithmetic, hardware
|
||||
@section Recognized Idioms
|
||||
|
||||
@menu
|
||||
|
|
@ -431,12 +441,14 @@ points to keep in mind.
|
|||
explicit type declarations.)
|
||||
@end itemize
|
||||
|
||||
@cindex garbage collector, generational
|
||||
@cindex generational garbage collector
|
||||
@itemize
|
||||
@item Since the time the CMUCL manual was written, CMUCL (and thus SBCL)
|
||||
has gotten a generational garbage collector. This means that there
|
||||
are some efficiency implications of various patterns of memory
|
||||
usage which aren't discussed in the CMUCL manual. (Some new
|
||||
material should be written about this.)
|
||||
has gotten a generational GC. This means that there are some
|
||||
efficiency implications of various patterns of memory usage which
|
||||
aren't discussed in the CMUCL manual. (Some new material should be
|
||||
written about this.)
|
||||
|
||||
@item SBCL has some important known efficiency problems. Perhaps the
|
||||
most important are
|
||||
|
|
|
|||
|
|
@ -1,6 +1,8 @@
|
|||
@c Generated by the sb-manual contrib. Do not edit.
|
||||
|
||||
@node external formats
|
||||
@cindex external format
|
||||
@cindex format, external
|
||||
@chapter External Formats
|
||||
|
||||
@menu
|
||||
|
|
|
|||
|
|
@ -181,6 +181,8 @@ the first dimension. Fixed-size arrays can be allocated as array
|
|||
elements, structure slots or @code{with-alien} variables. Dynamic arrays
|
||||
can only be allocated using @code{make-alien}.
|
||||
|
||||
@cindex external format
|
||||
@cindex format, external
|
||||
@itemize
|
||||
@item The foreign type specifier @code{(struct <name> &rest <fields>)}
|
||||
describes a structure type with the specified @code{<name>} and
|
||||
|
|
@ -256,14 +258,14 @@ current (local or global) alien structure type definition of
|
|||
declare that no useful value is returned. Using @code{alien-funcall} to
|
||||
call a @code{void} foreign function will return zero values.
|
||||
|
||||
@item The foreign type specifier @code{(C-STRING &KEY <external-format>
|
||||
@item The foreign type specifier @code{(c-string &key <external-format>
|
||||
<element-type> <not-null>)} is similar to @code{(* char)} but is
|
||||
interpreted as a null-terminated string, and is automatically
|
||||
converted into a Lisp string when accessed; or if the pointer is C
|
||||
@code{null} or 0, then accessing it gives Lisp @code{nil} unless
|
||||
@code{<not-null>} is true, in which case a @code{type-error} is signalled.
|
||||
|
||||
External format conversion is automatically done when Lisp
|
||||
external format conversion is automatically done when Lisp
|
||||
strings are passed to foreign code, or when foreign strings are
|
||||
passed to Lisp code. If the type specifier has an explicit
|
||||
@code{<external-format>}, that external format will be used.
|
||||
|
|
@ -974,6 +976,8 @@ Note that the garbage collector moves objects, and won't be able to fix
|
|||
up any references in C variables. There are three mechanisms for
|
||||
coping with this:
|
||||
|
||||
@cindex garbage collector, generational
|
||||
@cindex generational garbage collector
|
||||
@itemize
|
||||
@item @code{sb-ext:purify} moves all live Lisp data into static or read-only
|
||||
areas such that it will never be moved (or freed) again in the
|
||||
|
|
@ -981,11 +985,10 @@ coping with this:
|
|||
|
||||
@item @code{sb-sys:with-pinned-objects} is a macro which arranges for some set
|
||||
of objects to be pinned in memory for the dynamic extent of its
|
||||
body forms. On ports which use the generational garbage
|
||||
collector (most, as of this writing) this affects exactly the
|
||||
specified objects. On other ports it is implemented by turning off
|
||||
GC for the duration (so could be said to have a whole-world
|
||||
granularity).
|
||||
body forms. On ports which use the generational GC
|
||||
(most, as of this writing) this affects exactly the specified
|
||||
objects. On other ports it is implemented by turning off GC for
|
||||
the duration (so could be said to have a whole-world granularity).
|
||||
|
||||
@item Disable GC, using the SB-EXT:WITHOUT-GCING macro.
|
||||
@end itemize
|
||||
|
|
|
|||
|
|
@ -139,8 +139,8 @@ also supports allocation profiling.
|
|||
regression and unit-test framework.
|
||||
|
||||
@item @strong{MD5 Sums:} The @ref{sb md5} module provides an implementation of the
|
||||
MD5 message digest algorithm for Common Lisp, using the modular
|
||||
arithmetic optimizations provided by SBCL.
|
||||
MD5 message digest algorithm for Common Lisp, using the
|
||||
@ref{modular arithmetic} optimizations provided by SBCL.
|
||||
@end itemize
|
||||
|
||||
@node idiosyncrasies
|
||||
|
|
@ -506,11 +506,12 @@ still reflected in the current implementation:
|
|||
supplying low-level services and loading a Lisp @code{.core} file.
|
||||
@end itemize
|
||||
|
||||
@cindex garbage collector, generational
|
||||
@cindex generational garbage collector
|
||||
SBCL also inherited some newer architectural features from CMUCL.
|
||||
The most important is that on some architectures it has a
|
||||
generational garbage collector (GC), which has various
|
||||
implications (mostly good) for performance. These are discussed in
|
||||
another chapter, @ref{efficiency}.
|
||||
generational GC, which has various implications (mostly good) for
|
||||
performance. These are discussed in another chapter, @ref{efficiency}.
|
||||
|
||||
SBCL has diverged from CMUCL in that SBCL is now essentially a
|
||||
compiler-only implementation of Common Lisp. This is a change in
|
||||
|
|
@ -535,8 +536,10 @@ x86 architecture. Some things (like tracing and debugging) do not work
|
|||
particularly well there. SBCL should be able to improve in these areas
|
||||
(and has already improved in some other areas), but it takes a while.
|
||||
|
||||
@cindex garbage collector, conservative
|
||||
@cindex conservative garbage collector
|
||||
On the x86 SBCL -- like the x86 port of CMUCL -- uses a
|
||||
@emph{conservative} GC. This means that it doesn't maintain a strict
|
||||
_@@CONSERVATIVE-GC. This means that it doesn't maintain a strict
|
||||
separation between tagged and untagged data, instead treating some
|
||||
untagged data (e.g. raw floating point numbers) as possibly-tagged
|
||||
data and so not collecting any Lisp objects that they point to. This
|
||||
|
|
@ -544,9 +547,9 @@ has some negative consequences for average time efficiency (though
|
|||
possibly no worse than the negative consequences of trying to
|
||||
implement an exact GC on a processor architecture as register-poor
|
||||
as the X86) and also has potentially unlimited consequences for
|
||||
worst-case memory efficiency. In practice, conservative garbage
|
||||
collectors work reasonably well, not getting anywhere near the worst
|
||||
case. But they can occasionally cause odd patterns of memory usage.
|
||||
worst-case memory efficiency. In practice, conservative GCs work
|
||||
reasonably well, not getting anywhere near the worst case. But they
|
||||
can occasionally cause odd patterns of memory usage.
|
||||
|
||||
The fork from CMUCL was based on a major rewrite of the system
|
||||
bootstrap process. CMUCL has for many years tolerated a very unusual
|
||||
|
|
|
|||
|
|
@ -1,6 +1,8 @@
|
|||
@c Generated by the sb-manual contrib. Do not edit.
|
||||
|
||||
@node package locks
|
||||
@cindex package lock
|
||||
@cindex lock, package
|
||||
@chapter Package Locks
|
||||
|
||||
@menu
|
||||
|
|
@ -66,6 +68,7 @@ Unless explicitly altered by @code{defpackage},
|
|||
@node lexical bindings and declarations
|
||||
@subsubsection Lexical Bindings and Declarations
|
||||
|
||||
@cindex declaration
|
||||
Lexical bindings or declarations that violate package locks cause a
|
||||
compile-time warning, and a runtime @code{program-error} when the form that
|
||||
violates package locks would be executed.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,7 @@
|
|||
@c Generated by the sb-manual contrib. Do not edit.
|
||||
|
||||
@node pathnames
|
||||
@cindex pathname
|
||||
@chapter Pathnames
|
||||
|
||||
@menu
|
||||
|
|
@ -40,6 +41,8 @@ Using @code{(:home} @code{"user")} form on Windows signals an error.
|
|||
@node the sys logical pathname host
|
||||
@subsection The SYS Logical Pathname Host
|
||||
|
||||
@cindex logical pathname
|
||||
@cindex pathname, logical
|
||||
The logical pathname host named by @code{"SYS"} exists in SBCL.
|
||||
Its @code{logical-pathname-translations} may be set by the site or the user
|
||||
applicable to point to the locations of the system's sources; in
|
||||
|
|
|
|||
|
|
@ -1,6 +1,7 @@
|
|||
@c Generated by the sb-manual contrib. Do not edit.
|
||||
|
||||
@node profiling
|
||||
@cindex profiling
|
||||
@chapter Profiling
|
||||
|
||||
@menu
|
||||
|
|
@ -15,6 +16,7 @@ statistical profiler.
|
|||
Inlined functions do not appear in the results reported by either.
|
||||
|
||||
@node deterministic profiler
|
||||
@cindex profiling, deterministic
|
||||
@section Deterministic Profiler
|
||||
|
||||
The package @code{sb-profile} provides a classic, per-function-call
|
||||
|
|
|
|||
|
|
@ -382,6 +382,12 @@ system.
|
|||
@node runtime options
|
||||
@subsection Runtime Options
|
||||
|
||||
@cindex LDB
|
||||
@cindex disabling LDB
|
||||
@cindex LDB, disabling
|
||||
@cindex LDB
|
||||
@cindex enabling LDB
|
||||
@cindex LDB, enabling
|
||||
@itemize
|
||||
@item @code{--core <corefilename>}
|
||||
|
||||
|
|
@ -415,7 +421,7 @@ and @code{--disable-debugger} options.
|
|||
@item @code{--disable-ldb}
|
||||
|
||||
Disable the low-level debugger. Only effective if SBCL is
|
||||
compiled with @code{ldb}.
|
||||
compiled with LDB. disabling LDB
|
||||
|
||||
@item @code{--lose-on-corruption}
|
||||
|
||||
|
|
@ -425,7 +431,7 @@ corrupt the image. By default, SBCL prints a warning, then tries
|
|||
to continue and handle the error in Lisp, but this will not
|
||||
always work, and SBCL may malfunction or even hang. With this
|
||||
option, upon encountering such an error, SBCL will exit instead
|
||||
of invoking @code{ldb} (if present and enabled).
|
||||
of invoking LDB (if present and enabled enabling LDB).
|
||||
|
||||
@item @code{--script <filename>}
|
||||
|
||||
|
|
|
|||
|
|
@ -38,8 +38,10 @@ streams:
|
|||
@node stream external formats
|
||||
@section Stream External Formats
|
||||
|
||||
@cindex external format
|
||||
@cindex format, external
|
||||
The function @code{stream-external-format} returns the canonical name of
|
||||
the external format (See @ref{external formats}) used by the stream for
|
||||
the external format (see @ref{external formats}) used by the stream for
|
||||
character-based input and/or output.
|
||||
|
||||
When constructing file streams, for example using @code{open} or
|
||||
|
|
|
|||
|
|
@ -115,8 +115,9 @@ If you run into a signal related bug, you are getting fatal errors
|
|||
such as @code{signal N is [un]blocked} or just hangs, and you want to
|
||||
send a useful bug report then:
|
||||
|
||||
@cindex LDB
|
||||
@itemize
|
||||
@item Compile SBCL with ldb enabled (feature @code{:sb-ldb}, see
|
||||
@item Compile SBCL with LDB enabled (feature @code{:sb-ldb}, see
|
||||
@code{base-target-features.lisp-expr}).
|
||||
|
||||
@item Isolate a smallish test case, run it.
|
||||
|
|
|
|||
|
|
@ -249,8 +249,8 @@
|
|||
|
||||
(declaim (inline readtable-normalization))
|
||||
(defun readtable-normalization (readtable)
|
||||
"Returns T if READTABLE normalizes symbols to NFKC, and NIL otherwise.
|
||||
The READTABLE-NORMALIZATION of the standard readtable is T."
|
||||
"Returns T if READTABLE normalizes symbols to SB-MANUAL::@NFKC, and NIL
|
||||
otherwise. The READTABLE-NORMALIZATION of the standard readtable is T."
|
||||
(%readtable-normalization readtable))
|
||||
|
||||
(defun (setf readtable-normalization) (new-value readtable)
|
||||
|
|
|
|||
Loading…
Reference in a new issue