From: Eli Zaretskii <eliz@gnu.org>
Date: Sat, 14 Dec 2019 18:02:11 +0000 (+0200)
Subject: Update documentation of pure-space overflow
X-Git-Tag: emacs-27.0.90~351
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=a01a7222829682962a229e26688a4d44829b6d5f;p=emacs.git

Update documentation of pure-space overflow

* doc/lispref/internals.texi (Garbage Collection)
(Pure Storage):
* src/alloc.c (Fgarbage_collect): Update the documentation of
pure-space overflow for when pdumper is used.  (Bug#38492)
---

diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi
index eed9cb0a109..8c55f4ea373 100644
--- a/doc/lispref/internals.texi
+++ b/doc/lispref/internals.texi
@@ -261,12 +261,17 @@ the memory space can be shared by all the Emacs jobs running on the
 machine at once.  Pure storage is not expandable; a fixed amount is
 allocated when Emacs is compiled, and if that is not sufficient for
 the preloaded libraries, @file{temacs} allocates dynamic memory for
-the part that didn't fit.  The resulting image will work, but garbage
-collection (@pxref{Garbage Collection}) is disabled in this situation,
-causing a memory leak.  Such an overflow normally won't happen unless
-you try to preload additional libraries or add features to the
-standard ones.  Emacs will display a warning about the overflow when
-it starts.  If this happens, you should increase the compilation
+the part that didn't fit.  If Emacs will be dumped using the
+@code{pdump} method (@pxref{Building Emacs}), the pure-space overflow
+is of no special importance (it just means some of the preloaded stuff
+cannot be shared with other Emacs jobs).  However, if Emacs will be
+dumped using the now obsolete @code{unexec} method, the resulting
+image will work, but garbage collection (@pxref{Garbage Collection})
+is disabled in this situation, causing a memory leak.  Such an
+overflow normally won't happen unless you try to preload additional
+libraries or add features to the standard ones.  Emacs will display a
+warning about the overflow when it starts, if it was dumped using
+@code{unexec}.  If this happens, you should increase the compilation
 parameter @code{SYSTEM_PURESIZE_EXTRA} in the file
 @file{src/puresize.h} and rebuild Emacs.
 
@@ -510,9 +515,11 @@ Total heap size, in @var{unit-size} units.
 Heap space which is not currently used, in @var{unit-size} units.
 @end table
 
-If there was overflow in pure space (@pxref{Pure Storage}),
-@code{garbage-collect} returns @code{nil}, because a real garbage
-collection cannot be done.
+If there was overflow in pure space (@pxref{Pure Storage}), and Emacs
+was dumped using the (now obsolete) @code{unexec} method
+(@pxref{Building Emacs}), then @code{garbage-collect} returns
+@code{nil}, because a real garbage collection cannot be done in that
+case.
 @end deffn
 
 @defopt garbage-collection-messages
diff --git a/src/alloc.c b/src/alloc.c
index 9fbd0d05739..6a17bedc75b 100644
--- a/src/alloc.c
+++ b/src/alloc.c
@@ -6050,8 +6050,9 @@ where each entry has the form (NAME SIZE USED FREE), where:
 - FREE is the number of those objects that are not live but that Emacs
   keeps around for future allocations (maybe because it does not know how
   to return them to the OS).
-However, if there was overflow in pure space, `garbage-collect'
-returns nil, because real GC can't be done.
+However, if there was overflow in pure space, and Emacs was dumped
+using the 'unexec' method, `garbage-collect' returns nil, because
+real GC can't be done.
 See Info node `(elisp)Garbage Collection'.  */)
   (void)
 {