0.9.10.28

[sbcl.git] / doc / manual / efficiency.texinfo

diff --git a/doc/manual/efficiency.texinfo b/doc/manual/efficiency.texinfo
index 7559abf..6931ed0 100644 (file)
--- a/doc/manual/efficiency.texinfo
+++ b/doc/manual/efficiency.texinfo
@@ -1,6 +1,7 @@
-@node Efficiency, Beyond The ANSI Standard, The Debugger, Top
+@node Efficiency
 @comment  node-name,  next,  previous,  up
 @chapter Efficiency
+@cindex Efficiency
 
 FIXME: The material in the CMUCL manual about getting good
 performance from the compiler should be reviewed, reformatted in
@@ -122,7 +123,7 @@ examples (some straightforward, some less so).
 * Modular arithmetic::          
 @end menu
 
-@node  Dynamic-extent allocation, Modular arithmetic, Efficiency, Efficiency
+@node  Dynamic-extent allocation
 @comment  node-name,  next,  previous,  up
 @section Dynamic-extent allocation
 @cindex Dynamic-extent declaration
@@ -161,15 +162,53 @@ it would not be in the following situation:
 because both the allocation of the @code{&rest} list and the variable
 binding are outside the scope of the @code{optimize} declaration.
 
-There are many cases when dynamic-extent declarations could be useful.
-At present, SBCL implements
+There are many cases when @code{dynamic-extent} declarations could be
+useful. At present, SBCL implements
 
-@itemize 
+@itemize
 
 @item
 Stack allocation of @code{&rest} lists, where these are declared
 @code{dynamic-extent}.
 
+@item
+Stack allocation of @code{list} and @code{list*}, whose result is
+bound to a variable, declared @code{dynamic-extent}, such as
+
+@lisp
+(let ((list (list 1 2 3)))
+  (declare (dynamic-extent list)
+  ...))
+@end lisp
+
+or
+
+@lisp
+(flet ((f (x)
+         (declare (dynamic-extent x))
+         ...))
+  ...
+  (f (list 1 2 3))
+  ...)
+@end lisp
+
+@item
+Stack allocation of simple forms of @code{make-array}, whose result is
+bound to a variable, declared @code{dynamic-extent}. The resulting
+array should be one-dimensional, the only allowed keyword argument is
+@code{:element-type}.
+
+Notice, that stack space is limited, so allocation of a large vector
+may cause stack overflow and abnormal termination of the SBCL process.
+
+@item
+Stack allocation of closures, defined with @code{flet} or
+@code{labels} with a bound declaration @code{dynamic-extent}.
+Closed-over variables, which are assigned (either inside or outside
+the closure) are still allocated on the heap. Blocks and tags are also
+allocated on the heap, unless all non-local control transfers to them
+are compiled with zero @code{safety}.
+
 @end itemize
 
 Future plans include
@@ -197,7 +236,7 @@ closure, even when the closure is not declared @code{dynamic-extent}.
 
 @end itemize
 
-@node  Modular arithmetic,  , Dynamic-extent allocation, Efficiency
+@node  Modular arithmetic
 @comment  node-name,  next,  previous,  up
 @section Modular arithmetic
 @cindex Modular arithmetic
@@ -231,10 +270,9 @@ with versions cutting results to 32 bits, and because terminals
 (here---expressions @code{x} and @code{y}) are also of type
 @code{(unsigned-byte 32)}, 32-bit machine arithmetic can be used.
 
-
 As of SBCL 0.8.5 ``good'' functions are @code{+}, @code{-};
 @code{logand}, @code{logior}, @code{logxor}, @code{lognot} and their
 combinations; and @code{ash} with the positive second
-argument. ``Good'' widths are 32 on HPPA, MIPS, PPC, Sparc and X86 and
-64 on Alpha. While it is possible to support smaller widths as well,
-currently it is not implemented.
+argument. ``Good'' widths are 32 on HPPA, MIPS, PPC, Sparc and x86 and
+64 on Alpha.  While it is possible to support smaller widths as well,
+currently this is not implemented.