X-Git-Url: http://repo.macrolet.net/gitweb/?a=blobdiff_plain;f=doc%2Fmanual%2Fbeyond-ansi.texinfo;h=f9622064cdf5aae3e7a227d4fa6bdcf7e6cb92d6;hb=e35a79c777f51eddd3dcb0ca27000ce4cfa60e73;hp=e595663533d4c2e428a6e2165b604dda69a81b96;hpb=4ec0d70e08ea4b512d45ddbd6c82e8f6a91a914f;p=sbcl.git diff --git a/doc/manual/beyond-ansi.texinfo b/doc/manual/beyond-ansi.texinfo index e595663..f962206 100644 --- a/doc/manual/beyond-ansi.texinfo +++ b/doc/manual/beyond-ansi.texinfo @@ -7,6 +7,7 @@ ANSI standard. SBCL doesn't support as many extensions as CMUCL, but it still has quite a few. @xref{Contributed Modules}. @menu +* Reader Extensions:: * Garbage Collection:: * Metaobject Protocol:: * Support For Unix:: @@ -14,11 +15,34 @@ it still has quite a few. @xref{Contributed Modules}. * 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 Garbage Collection @comment node-name, next, previous, up @section Garbage Collection @@ -57,18 +81,22 @@ 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 @section Metaobject Protocol +@subsection AMOP Compatibility of Metaobject Protocol + SBCL supports a metaobject protocol which is intended to be compatible with AMOP; present exceptions to this (as distinct from current bugs) are: @@ -76,20 +104,18 @@ are: @itemize @item -@findex compute-effective-method -@findex sb-mop:compute-effective-method +@findex @sbmop{compute-effective-method} @code{compute-effective-method} only returns one value, not two. There is no record of what the second return value was meant to indicate, and apparently no clients for it. @item -@tindex generic-function -@tindex standard-generic-function -@tindex funcallable-standard-object -@tindex sb-mop:funcallable-standard-object -@tindex standard-object -@tindex function +@tindex @cl{generic-function} +@tindex @cl{standard-generic-function} +@tindex @sbmop{funcallable-standard-object} +@tindex @cl{standard-object} +@tindex @cl{function} The direct superclasses of @code{sb-mop:funcallable-standard-object} are @code{(function standard-object)}, not @code{(standard-object function)}. @@ -100,9 +126,8 @@ precedence list of @code{generic-function} and ANSI specification. @item -@findex ensure-generic-function -@findex generic-function-declarations -@findex sb-mop:generic-function-declarations +@findex @cl{ensure-generic-function} +@findex @sbmop{generic-function-declarations} the arguments @code{:declare} and @code{:declarations} to @code{ensure-generic-function} are both accepted, with the leftmost argument defining the declarations to be stored and returned by @@ -113,16 +138,12 @@ Where AMOP specifies @code{:declarations} as the keyword argument to @code{:declare}. Portable code should use @code{:declare}. @item -@findex validate-superclass -@findex finalize-inheritance -@findex sb-mop:validate-superclass -@findex sb-mop:finalize-inheritance -@tindex standard-class -@tindex funcallable-standard-class -@tindex sb-mop:funcallable-standard-class -@tindex function -@findex sb-mop:class-prototype -@findex class-prototype +@findex @sbmop{validate-superclass} +@findex @sbmop{finalize-inheritance} +@tindex @cl{standard-class} +@tindex @sbmop{funcallable-standard-class} +@tindex @cl{function} +@findex @sbmop{class-prototype} although SBCL obeys the requirement in AMOP that @code{validate-superclass} should treat @code{standard-class} and @code{funcallable-standard-class} as compatible metaclasses, we @@ -131,9 +152,9 @@ of metaclass @code{funcallable-standard-class} must have @code{function} in its superclasses, and a class of metaclass @code{standard-class} must not. -@findex typep -@findex class-of -@findex subtypep +@findex @cl{typep} +@findex @cl{class-of} +@findex @cl{subtypep} After a class has been finalized, it is associated with a class prototype which is accessible by a standard mop function @code{sb-mop:class-prototype}. The user can then ask whether this @@ -165,8 +186,7 @@ The following definition is acceptable: @end lisp and leads to a class whose instances are funcallable and have one slot. -@tindex funcallable-standard-object -@tindex sb-mop:funcallable-standard-object +@tindex @sbmop{funcallable-standard-object} Note that this requirement also applies to the class @code{sb-mop:funcallable-standard-object}, which has metaclass @code{sb-mop:funcallable-standard-class} rather than @@ -187,12 +207,9 @@ by symbols in the Common Lisp package: preventing two independent pieces of software from colliding with each other. @item -@findex slot-value-using-class -@findex sb-mop:slot-value-using-class -@findex (setf slot-value-using-class) -@findex (setf sb-mop:slot-value-using-class) -@findex slot-boundp-using-class -@findex sb-mop:slot-boundp-using-class +@findex @sbmop{slot-value-using-class} +@findex @setf{@sbmop{slot-value-using-class}} +@findex @sbmop{slot-boundp-using-class} specializations of the @code{new-value} argument to @code{(setf sb-mop:slot-value-using-class)} are not allowed: all user-defined methods must have a specializer of the class @code{t}. @@ -211,13 +228,11 @@ Note that application code may specialize on the @code{new-value} argument of slot accessors. @item -@findex defclass -@findex ensure-class -@findex ensure-class-using-class -@findex sb-mop:ensure-class -@findex sb-mop:ensure-class-using-class -@findex find-class -@findex class-name +@findex @cl{defclass} +@findex @sbmop{ensure-class} +@findex @sbmop{ensure-class-using-class} +@findex @cl{find-class} +@findex @cl{class-name} the class named by the @code{name} argument to @code{ensure-class}, if any, is only redefined if it is the proper name of that class; otherwise, a new class is created. @@ -230,20 +245,19 @@ states that any class found by @code{find-class}, no matter what its @end itemize +@subsection Metaobject Protocol Extensions + In addition, SBCL supports extensions to the Metaobject protocol from AMOP; at present, they are: @itemize @item -@findex defmethod -@findex find-class -@findex intern-eql-specializer -@findex sb-mop:intern-eql-specializer -@findex make-method-specializers-form -@findex sb-pcl:make-method-specializers-form -@findex make-method-lambda -@findex sb-mop:make-method-lambda +@findex @cl{defmethod} +@findex @cl{find-class} +@findex @sbmop{intern-eql-specializer} +@findex @sbpcl{make-method-specializers-form} +@findex @sbmop{make-method-lambda} compile-time support for generating specializer metaobjects from specializer names in @code{defmethod} forms is provided by the @code{make-method-specializers-form} function, which returns a form @@ -259,11 +273,9 @@ name, and a call to @code{intern-eql-specializer} for each @code{(eql @var{x})} specializer name. @item -@findex find-method -@findex parse-specializer-using-class -@findex unparse-specializer-using-class -@findex sb-pcl:parse-specializer-using-class -@findex sb-pcl:unparse-specializer-using-class +@findex @cl{find-method} +@findex @sbpcl{parse-specializer-using-class} +@findex @sbpcl{unparse-specializer-using-class} run-time support for converting between specializer names and specializer metaobjects, mostly for the purposes of @code{find-method}, is provided by @@ -274,6 +286,15 @@ specializer. The system-provided methods on those methods convert between classes and proper names and between lists of the form @code{(eql @var{x})} and interned eql specializer objects. +@item +@vindex @sbpcl{+slot-unbound+} +@findex @sbmop{standard-instance-access} +@findex @sbmop{funcallable-standard-instance-access} +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+}. + @end itemize @node Support For Unix @@ -288,8 +309,7 @@ between classes and proper names and between lists of the form @node Command-line arguments @subsection Command-line arguments -@vindex sb-ext:*posix-argv* -@vindex *posix-argv* +@vindex @sbext{@earmuffs{posix-argv}} The UNIX command line can be read from the variable @code{sb-ext:*posix-argv*}. @@ -379,8 +399,8 @@ muffle these warnings at runtime, SBCL provides a variable @node Tools To Help Developers @comment node-name, next, previous, up @section Tools To Help Developers -@findex trace -@findex inspect +@findex @cl{trace} +@findex @cl{inspect} SBCL provides a profiler and other extensions to the ANSI @code{trace} facility. For more information, see @ref{Macro common-lisp:trace}. @@ -393,10 +413,8 @@ the @code{inspect} prompt. @node Resolution of Name Conflicts @section Resolution of Name Conflicts -@tindex sb-ext:name-conflict -@tindex name-conflict -@findex sb-ext:name-conflict-symbols -@findex name-conflict-symbols +@tindex @sbext{name-conflict} +@findex @sbext{name-conflict-symbols} The ANSI standard (section 11.1.1.2.5) requires that name conflicts in packages be resolvable in favour of any of the conflicting symbols. In @@ -424,11 +442,89 @@ 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 @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 macro-sb-ext-wait-for.texinfo @node Stale Extensions @comment node-name, next, previous, up