[Emacs-diffs] trunk r117990: * internals.texi (Stack-allocated Objects): Further improvements.

[Paul Eggert]

------------------------------------------------------------
revno: 117990
revision-id: address@hidden
parent: address@hidden
committer: Paul Eggert <address@hidden>
branch nick: trunk
timestamp: Tue 2014-09-30 12:10:37 -0700
message:
  * internals.texi (Stack-allocated Objects): Further improvements.
  
  Give an example of misuse.
modified:
  doc/lispref/ChangeLog          changelog-20091113204419-o5vbwnq5f7feedwu-6155
  doc/lispref/internals.texi     
internals.texi-20091113204419-o5vbwnq5f7feedwu-6188

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2014-09-30 16:21:22 +0000
+++ b/doc/lispref/ChangeLog     2014-09-30 19:10:37 +0000
@@ -1,3 +1,8 @@
+2014-09-30  Paul Eggert  <address@hidden>
+
+       * internals.texi (Stack-allocated Objects): Further improvements.
+       Give an example of misuse.
+
 2014-09-30  Eli Zaretskii  <address@hidden>
 
        * internals.texi (Stack-allocated Objects): Minor improvements of

=== modified file 'doc/lispref/internals.texi'
--- a/doc/lispref/internals.texi        2014-09-30 16:21:22 +0000
+++ b/doc/lispref/internals.texi        2014-09-30 19:10:37 +0000
@@ -537,25 +537,50 @@
 @cindex Lisp objects, stack-allocated
   The garbage collector described above is used to manage data visible
 from Lisp programs, as well as most of the data internally used by the
-Lisp interpreter.  But sometimes it may be useful to allocate
-temporary internal (i.e.@: not visible for a Lisp program) objects
-using the C stack of the interpreter.  Currently, only cons cells and
-strings can be allocated that way.  Stack-allocated strings are
-limited to @acronym{ASCII} characters only, and should be treated as
-immutable (calling @code{ASET} on them produces undefined behavior).
-
-  In C, this is implemented as special macros which expand into a
address@hidden with block-scoped semantics and lifetime (see the
-code around @code{USE_STACK_LISP_OBJECTS} in @file{src/lisp.h}).  This
-means that these objects are not freed by the garbage collector;
-instead, they are allocated like local variables in C and
-automatically freed when execution goes out of the scope where the
-object was allocated.  Thus, allocating and freeing these objects is
-faster than when using heap memory to allocate and the garbage
-collector to free their memory.  Note that using such objects out of
-their scope will result in undefined behavior, so code using them
-should be well thought out and carefully debugged by using the
address@hidden feature (see @file{src/alloc.c}).
+Lisp interpreter.  Sometimes it may be useful to allocate temporary
+internal objects using the C stack of the interpreter.  This can help
+performance, as stack allocation is typically faster than using heap
+memory to allocate and the garbage collector to free.  The downside is
+that using such objects after they are freed results in undefined
+behavior, so uses should be well thought out and carefully debugged by
+using the @code{GC_CHECK_MARKED_OBJECTS} feature (see
address@hidden/alloc.c}).  In particular, stack-allocated objects should
+never be made visible to user Lisp code.
+
+  Currently, cons cells and strings can be allocated this way.  This
+is implemented by C macros like @code{scoped_cons} and
address@hidden that return a @code{Lisp_Object} with block
+lifetime.  These objects are not freed by the garbage collector;
+instead, they have automatic storage duration, i.e., they are
+allocated like local variables and are automatically freed at the end
+of execution of the C block where the object was allocated.  C blocks
+include compound statements (i.e., inside @address@hidden and @address@hidden),
+along with selection and iteration statements and their immediate
+substatements.  For example:
+
address@hidden
+/* Erroneous code.  */
+Lisp_Object x;
+if (foo)
+  x = SCOPED_STRING ("prefix");
+else
+  x = bar;
+return concat2 (x, baz);
address@hidden example
+
address@hidden
+This has undefined behavior because the @code{if} statement is a
+block, so @code{x} is used after the corresponding object has been
+freed.  Better would be:
+
address@hidden
+Lisp_Object x = foo ? SCOPED_STRING ("prefix") : bar;
+return concat2 (x, baz);
address@hidden example
+
+  For performance reasons, stack-allocated strings are limited to
address@hidden characters, and many of these strings are immutable,
+i.e., calling @code{ASET} on them produces undefined behavior.
 
 @node Memory Usage
 @section Memory Usage