From 7b09ed28ba395030e5117344bb5b97b8ee4a8b40 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sun, 20 Nov 2022 13:10:08 +0200 Subject: [PATCH] Advise against using too-high GC thresholds * doc/lispref/internals.texi (Garbage Collection): * src/alloc.c (syms_of_alloc) : Advise against enlarging the GC thresholds more than needed and for prolonged periods of time. --- doc/lispref/internals.texi | 20 ++++++++++++++------ src/alloc.c | 12 +++++++++++- 2 files changed, 25 insertions(+), 7 deletions(-) diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi index ea1679f6934..4640b6d7591 100644 --- a/doc/lispref/internals.texi +++ b/doc/lispref/internals.texi @@ -554,12 +554,17 @@ trigger another garbage collection. You can use the result returned by object type; space allocated to the contents of buffers does not count. 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 -is 400,000 for the default 32-bit configuration and 800,000 for the 64-bit -one. If you specify a larger value, garbage collection will happen less -often. This reduces the amount of time spent garbage collecting, but -increases total memory use. You may want to do this when running a program -that creates lots of Lisp data. +@file{alloc.c}. Since it's defined in @code{word_size} units, the +value is 400,000 for the default 32-bit configuration and 800,000 for +the 64-bit one. If you specify a larger value, garbage collection +will happen less often. This reduces the amount of time spent garbage +collecting, but increases total memory use. You may want to do this +when running a program that creates lots of Lisp data. However, we +recommend against increasing the threshold for prolonged periods of +time, and advise that you never set it higher than needed for the +program to run in reasonable time. Using thresholds higher than +necessary could potentially cause system-wide memory pressure, and +should therefore be avoided. You can make collections more frequent by specifying a smaller value, down to 1/10th of @code{GC_DEFAULT_THRESHOLD}. A value less than this minimum @@ -576,6 +581,9 @@ garbage collection occurs only when both criteria are satisfied. As the heap size increases, the time to perform a garbage collection increases. Thus, it can be desirable to do them less frequently in proportion. + +As with @code{gc-cons-threshold}, do not enlarge this more than +necessary, and never for prolonged periods of time. @end defopt Control over the garbage collector via @code{gc-cons-threshold} and diff --git a/src/alloc.c b/src/alloc.c index b9d12dff7e0..d3f696d5ade 100644 --- a/src/alloc.c +++ b/src/alloc.c @@ -7775,13 +7775,23 @@ allocated since the last garbage collection. All data types count. Garbage collection happens automatically only when `eval' is called. By binding this temporarily to a large number, you can effectively -prevent garbage collection during a part of the program. +prevent garbage collection during a part of the program. But be +sure to get back to the normal value soon enough, to avoid system-wide +memory pressure, and never use a too-high value for prolonged periods +of time. See also `gc-cons-percentage'. */); DEFVAR_LISP ("gc-cons-percentage", Vgc_cons_percentage, doc: /* Portion of the heap used for allocation. Garbage collection can happen automatically once this portion of the heap has been allocated since the last garbage collection. + +By binding this temporarily to a large number, you can effectively +prevent garbage collection during a part of the program. But be +sure to get back to the normal value soon enough, to avoid system-wide +memory pressure, and never use a too-high value for prolonged periods +of time. + If this portion is smaller than `gc-cons-threshold', this is ignored. */); Vgc_cons_percentage = make_float (0.1);