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 eed9cb0a10979d82c4061ef1eec92427387a62ac..8c55f4ea3730959f76be48b19fdb4f6ce3261a52 100644 (file)
--- 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 9fbd0d057393f9ca04623fab3f4791998dc07b43..6a17bedc75b40b2e97f3e4940b659263ab3ca937 100644 (file)
--- 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)
 {