* internals.texi (Stack-allocated Objects): Describe this feature.

2 files changed, 30 insertions, 0 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 1a85b126ffe..36918dac2e4 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,7 @@
+2014-09-30  Dmitry Antipov  <dmantipov@yandex.ru>
+
+        * internals.texi (Stack-allocated Objects): Describe this feature.
+
 2014-09-15  Daniel Colascione  <dancol@dancol.org>
 
         * text.texi (Registers): Make `insert-register' documentation
diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi
index 3d85b474d4b..1bafd22fd43 100644
--- a/doc/lispref/internals.texi
+++ b/doc/lispref/internals.texi
@@ -14,6 +14,7 @@ internal aspects of GNU Emacs that may be of interest to C programmers.
 * Building Emacs::      How the dumped Emacs is made.
 * Pure Storage::        Kludge to make preloaded Lisp functions shareable.
 * Garbage Collection::  Reclaiming space for Lisp objects no longer used.
+* Stack-allocated Objects::    Temporary conses and strings on C stack.
 * Memory Usage::        Info about total size of Lisp objects made so far.
 * C Dialect::           What C variant Emacs is written in.
 * Writing Emacs Primitives::   Writing C code for Emacs.
@@ -529,6 +530,31 @@ during garbage collection so far in this Emacs session, as a
 floating-point number.
 @end defvar
 
+@node Stack-allocated Objects
+@section Stack-allocated Objects
+
+@cindex stack allocation overview
+  The garbage collector described above is used to manage data visible
+from Lisp program, as well as the most of data internally used by the
+interpreter.  But sometimes it may be useful to allocate temporary
+internal (i.e. not visible for Lisp program) objects using C stack of
+an interpreter.  Currently conses and strings are the only objects which
+can be allocated in that way.  Strings are limited to ASCII characters
+only and should be treated as immutable (calling @code{ASET} on them is
+undefined).
+
+@cindex stack allocation internals
+  In C, this is implemented as a special macros which expands to
+a @code{Lisp_Object} with block-scoped semantics and lifetime (see
+the code around @code{USE_STACK_LISP_OBJECTS} in @file{lisp.h}).  This
+means that these objects are not managed by the garbage collector;
+instead, they are allocated like local variables in C and automatically
+freed when an execution reaches an end of the corresponding scope.  Thus,
+allocation and freeing are faster than using garbage collector.  But
+remember that passing them out of their scope results in undefined
+behavior.  Think twice before using this feature and carefully debug
+your code with @code{GC_CHECK_MARKED_OBJECTS} (see @file{alloc.c}).
+
 @node Memory Usage
 @section Memory Usage
 @cindex memory usage