Improve doc of GC thresholds

* doc/lispref/internals.texi (Garbage Collection), etc/NEWS:
Warn that control over GC is only approximate.

diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi
index f85c266edef781e495a948f44990abef6d08d210..c52999e1cd2f10653a17787aeb3044cbb8bcda78 100644 (file)
--- a/doc/lispref/internals.texi
+++ b/doc/lispref/internals.texi
@@ -533,9 +533,6 @@ be allocated for Lisp objects after one garbage collection in order to
 trigger another garbage collection.  You can use the result returned by
 @code{garbage-collect} to get an information about size of the particular
 object type; space allocated to the contents of buffers does not count.
-Note that the subsequent garbage collection does not happen immediately
-when the threshold is exhausted, but only the next time the Lisp interpreter
-is called.
 
 The initial threshold value is @code{GC_DEFAULT_THRESHOLD}, defined in
 @file{alloc.c}.  Since it's defined in @code{word_size} units, the value
@@ -562,6 +559,16 @@ increases.  Thus, it can be desirable to do them less frequently in
 proportion.
 @end defopt
 
+  Control over the garbage collector via @code{gc-cons-threshold} and
+@code{gc-cons-percentage} is only approximate.  Although Emacs checks
+for threshold exhaustion regularly, for efficiency reasons it does not
+do so immediately after every change to the heap or to
+@code{gc-cons-threshold} or @code{gc-cons-percentage}, so exhausting
+the threshold does not immediately trigger garbage collection.  Also,
+for efficency in threshold calculations Emacs approximates the heap
+size, which counts the bytes used by currently-accessible objects in
+the heap.
+
   The value returned by @code{garbage-collect} describes the amount of
 memory used by Lisp data, broken down by data type.  By contrast, the
 function @code{memory-limit} provides information on the total amount of

diff --git a/etc/NEWS b/etc/NEWS
index 94c98a7ebe00b6fdbbee2de6eda21854188fc34b..252c6bf9b9ff3f15213874e3f288e496ecf57450 100644 (file)
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -2429,6 +2429,13 @@ remote systems, which support this check.
 +++
 ** 'memory-limit' now returns a better estimate of memory consumption.
 
++++
+** When interpreting 'gc-cons-percentage', Emacs now estimates the
+heap size more often and (we hope) more accurately.  E.g., formerly
+(progn (let ((gc-cons-percentage 0.8)) BODY1) BODY2) continued to use
+the 0.8 value during BODY2 until the next garbage collection, but that
+is no longer true.  Applications may need to re-tune their GC tricks.
+
 +++
 ** New macro 'combine-change-calls' arranges to call the change hooks
 ('before-change-functions' and 'after-change-functions') just once