X-Git-Url: http://repo.macrolet.net/gitweb/?a=blobdiff_plain;f=doc%2Fmanual%2Fbeyond-ansi.texinfo;h=348208c9097de1f4e3d06ae92e77071866dc008c;hb=6129b1ebc5125c57d6446c061155f5f653f41725;hp=224a1f7a895c4295b3787a50fef37f02bc68e7d1;hpb=838316d0ad9affb2a4284ece65798aed6313d7e7;p=sbcl.git diff --git a/doc/manual/beyond-ansi.texinfo b/doc/manual/beyond-ansi.texinfo index 224a1f7..348208c 100644 --- a/doc/manual/beyond-ansi.texinfo +++ b/doc/manual/beyond-ansi.texinfo @@ -7,18 +7,106 @@ ANSI standard. SBCL doesn't support as many extensions as CMUCL, but it still has quite a few. @xref{Contributed Modules}. @menu -* Garbage Collection:: -* Metaobject Protocol:: -* Support For Unix:: -* Customization Hooks for Users:: -* Tools To Help Developers:: -* Resolution of Name Conflicts:: -* Hash Table Extensions:: -* Miscellaneous Extensions:: -* Stale Extensions:: -* Efficiency Hacks:: +* Reader Extensions:: +* Package-Local Nicknames:: +* Garbage Collection:: +* Metaobject Protocol:: +* Support For Unix:: +* Customization Hooks for Users:: +* Tools To Help Developers:: +* Resolution of Name Conflicts:: +* Hash Table Extensions:: +* Random Number Generation:: +* Miscellaneous Extensions:: +* Stale Extensions:: +* Efficiency Hacks:: @end menu +@node Reader Extensions +@comment node-name, next, previous, up +@section Reader Extensions +@cindex Reader Extensions + +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: + +@lisp +:: +@end lisp + +Example: + +@lisp + 'foo::(bar quux zot) == '(foo::bar foo::quux foo::zot) +@end lisp + +Doesn't alter @code{*package*}: if @code{foo::bar} would cause a +read-time package lock violation, so does @code{foo::(bar)}. + +@node Package-Local Nicknames +@comment node-name, next, previous, up +@section Package-Local Nicknames +@cindex Package-Local Nicknames + +SBCL allows giving packages local nicknames: they allow short and +easy-to-use names to be used without fear of name conflict associated +with normal nicknames. + +A local nickname is valid only when inside the package for which it +has been specified. Different packages can use same local nickname for +different global names, or different local nickname for same global +name. + +Symbol @code{:package-local-nicknames} in @code{*features*} denotes the +support for this feature. + +@findex @cl{defpackage} +@defmac @cl{defpackage} name [[option]]* @result{} package + +Options are extended to include + +@itemize +@item +@code{:local-nicknames} @var{(local-nickname actual-package-name)}* + +The package has the specified local nicknames for the corresponding +actual packages. +@end itemize + +Example: + +@lisp +(defpackage :bar (:intern "X")) +(defpackage :foo (:intern "X")) +(defpackage :quux (:use :cl) (:local-nicknames (:bar :foo) (:foo :bar))) +(find-symbol "X" :foo) ; => FOO::X +(find-symbol "X" :bar) ; => BAR::X +(let ((*package* (find-package :quux))) + (find-symbol "X" :foo)) ; => BAR::X +(let ((*package* (find-package :quux))) + (find-symbol "X" :bar)) ; => FOO::X +@end lisp +@end defmac + +@include fun-sb-ext-package-local-nicknames.texinfo +@include fun-sb-ext-package-locally-nicknamed-by.texinfo +@include fun-sb-ext-add-package-local-nickname.texinfo +@include fun-sb-ext-remove-package-local-nickname.texinfo + +@node Package Variance +@comment node-name, next, previous, up +@section Package Variance + +Common Lisp standard specifies that ``If the new definition is at +variance with the current state of that package, the consequences are +undefined;'' SBCL by default signals a full warning and retains as +much of the package state as possible. + +This can be adjusted using @code{sb-ext:*on-package-variance*}: + +@include var-sb-ext-star-on-package-variance-star.texinfo + @node Garbage Collection @comment node-name, next, previous, up @section Garbage Collection @@ -57,13 +145,15 @@ Extensions}. @include var-sb-ext-star-gc-run-time-star.texinfo @include fun-sb-ext-bytes-consed-between-gcs.texinfo +@include fun-sb-ext-dynamic-space-size.texinfo +@include fun-sb-ext-get-bytes-consed.texinfo +@include fun-sb-ext-gc-logfile.texinfo @include fun-sb-ext-generation-average-age.texinfo @include fun-sb-ext-generation-bytes-allocated.texinfo @include fun-sb-ext-generation-bytes-consed-between-gcs.texinfo @include fun-sb-ext-generation-minimum-age-before-gc.texinfo @include fun-sb-ext-generation-number-of-gcs-before-promotion.texinfo @include fun-sb-ext-generation-number-of-gcs.texinfo -@include fun-sb-ext-get-bytes-consed.texinfo @node Metaobject Protocol @comment node-name, next, previous, up @@ -264,7 +354,7 @@ between classes and proper names and between lists of the form @vindex @sbpcl{+slot-unbound+} @findex @sbmop{standard-instance-access} @findex @sbmop{funcallable-standard-instance-access} -distinguising unbound instance allocated slots from bound ones when +distinguishing unbound instance allocated slots from bound ones when using @code{standard-instance-access} and @code{funcallable-standard-instance-access} is possible by comparison to the constant @code{+slot-unbound+}. @@ -276,9 +366,9 @@ to the constant @code{+slot-unbound+}. @section Support For Unix @menu -* Command-line arguments:: -* Querying the process environment:: -* Running external programs:: +* Command-line arguments:: +* Querying the process environment:: +* Running external programs:: @end menu @node Command-line arguments @@ -416,6 +506,81 @@ arguments to @code{make-hash-table}. @include fun-sb-ext-hash-table-weakness.texinfo +@node Random Number Generation +@comment node-name, next, previous, up +@section Random Number Generation +@cindex Random Number Generation + +The initial value of @code{*random-state*} is the same each time SBCL +is started. This makes it possible for user code to obtain repeatable +pseudo random numbers using only standard-provided functionality. See +@code{seed-random-state} below for an SBCL extension that allows to +seed the random number generator from given data for an additional +possibility to achieve this. Non-repeatable random numbers can always +be obtained using @code{(make-random-state t)}. + +The sequence of numbers produced by repeated calls to @code{random} +starting with the same random state and using the same sequence of +@code{limit} arguments is guaranteed to be reproducible only in the +same version of SBCL on the same platform, using the same code under +the same evaluator mode and compiler optimization qualities. Just two +examples of differences that may occur otherwise: calls to +@code{random} can be compiled differently depending on how much is +known about the @code{limit} argument at compile time, yielding +different results even if called with the same argument at run time, +and the results can differ depending on the machine's word size, for +example for limits that are fixnums under 64-bit word size but bignums +under 32-bit word size. + +@include fun-sb-ext-seed-random-state.texinfo + +Some notes on random floats: The standard doesn't prescribe a specific +method of generating random floats. The following paragraph describes +SBCL's current implementation and should be taken purely informational, +that is, user code should not depend on any of its specific properties. +The method used has been chosen because it is common, conceptually +simple and fast. + +To generate random floats, SBCL evaluates code that has an equivalent +effect as +@lisp +(* limit + (float (/ (random (expt 2 23)) (expt 2 23)) 1.0f0)) +@end lisp +(for single-floats) and correspondingly (with @code{52} and +@code{1.0d0} instead of @code{23} and @code{1.0f0}) for double-floats. +Note especially that this means that zero is a possible return value +occurring with probability @code{(expt 2 -23)} respectively +@code{(expt 2 -52)}. Also note that there exist twice as many +equidistant floats between 0 and 1 as are generated. For example, the +largest number that @code{(random 1.0f0)} ever returns is +@code{(float (/ (1- (expt 2 23)) (expt 2 23)) 1.0f0)} while +@code{(float (/ (1- (expt 2 24)) (expt 2 24)) 1.0f0)} is the +largest single-float less than 1. This is a side effect of the fact +that the implementation uses the fastest possible conversion from bits +to floats. + +SBCL currently uses the Mersenne Twister as its random number +generator, specifically the 32-bit version under both 32- and 64-bit +word size. The seeding algorithm has been improved several times by +the authors of the Mersenne Twister; SBCL uses the third version +(from 2002) which is still the most recent as of June 2012. The +implementation has been tested to provide output identical to the +recommended C implementation. + +While the Mersenne Twister generates random numbers of much better +statistical quality than other widely used generators, it uses only +linear operations modulo 2 and thus fails some statistical +tests@footnote{See chapter 7 "Testing widely used RNGs" in +@cite{TestU01: A C Library for Empirical Testing of Random Number +Generators} by Pierre L'Ecuyer and Richard Simard, ACM Transactions on +Mathematical Software, Vol. 33, article 22, 2007.}. +For example, the distribution of ranks of (sufficiently large) random +binary matrices is much distorted compared to the theoretically +expected one when the matrices are generated by the Mersenne Twister. +Thus, applications that are sensitive to this aspect should use a +different type of generator. + @node Miscellaneous Extensions @comment node-name, next, previous, up @section Miscellaneous Extensions @@ -423,7 +588,7 @@ arguments to @code{make-hash-table}. @include fun-sb-ext-array-storage-vector.texinfo @include fun-sb-ext-delete-directory.texinfo @include fun-sb-ext-get-time-of-day.texinfo -@include fun-sb-ext-seed-random-state.texinfo +@include macro-sb-ext-wait-for.texinfo @node Stale Extensions @comment node-name, next, previous, up