From 999dd333061ea5d65f6130a6d4357f4782675b8c Mon Sep 17 00:00:00 2001 From: Glenn Morris Date: Fri, 2 Mar 2012 19:59:22 -0800 Subject: [PATCH] lispref/internals.texi Pure Storage updates * doc/lispref/internals.texi: (Pure Storage): Small changes. * src/alloc.c (Fgarbage_collect): Doc fix. --- doc/lispref/ChangeLog | 1 + doc/lispref/internals.texi | 33 ++++++++++++++++----------------- src/ChangeLog | 4 ++++ src/alloc.c | 10 ++++++---- 4 files changed, 27 insertions(+), 21 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 1cf91340b9e..47705612146 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -3,6 +3,7 @@ * internals.texi: Change @appendix section commands to @section. (Building Emacs): Say less about CANNOT_DUMP platforms. Replace deleted eval-at-startup with custom-initialize-delay. + (Pure Storage): Small changes. * tips.texi: Copyedits. (Coding Conventions): Mention autoloads. diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi index 2769b39e5e0..35759d39f1d 100644 --- a/doc/lispref/internals.texi +++ b/doc/lispref/internals.texi @@ -158,10 +158,10 @@ you must run Emacs with @samp{-batch}. Emacs Lisp uses two kinds of storage for user-created Lisp objects: @dfn{normal storage} and @dfn{pure storage}. Normal storage is where -all the new data created during an Emacs session are kept; see the -following section for information on normal storage. Pure storage is -used for certain data in the preloaded standard Lisp files---data that -should never change during actual use of Emacs. +all the new data created during an Emacs session are kept +(@pxref{Garbage Collection}). Pure storage is used for certain data +in the preloaded standard Lisp files---data that should never change +during actual use of Emacs. Pure storage is allocated only while @file{temacs} is loading the standard preloaded Lisp libraries. In the file @file{emacs}, it is @@ -170,14 +170,14 @@ 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. If that happens, you should increase the -compilation parameter @code{PURESIZE} in the file -@file{src/puresize.h} and rebuild Emacs, even though the resulting -image will work: 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. +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 +parameter @code{SYSTEM_PURESIZE_EXTRA} in the file +@file{src/puresize.h} and rebuild Emacs. @defun purecopy object This function makes a copy in pure storage of @var{object}, and returns @@ -188,8 +188,7 @@ not make copies of other objects such as symbols, but just returns them unchanged. It signals an error if asked to copy markers. This function is a no-op except while Emacs is being built and dumped; -it is usually called only in the file @file{emacs/lisp/loaddefs.el}, but -a few packages call it just in case you decide to preload them. +it is usually called only in preloaded Lisp files. @end defun @defvar pure-bytes-used @@ -363,7 +362,7 @@ object consists of a header and the storage for the string text itself; the latter is only allocated when the string is created.) @end table -If there was overflow in pure space (see the previous section), +If there was overflow in pure space (@pxref{Pure Storage}), @code{garbage-collect} returns @code{nil}, because a real garbage collection can not be done in this situation. @end deffn @@ -371,7 +370,7 @@ collection can not be done in this situation. @defopt garbage-collection-messages If this variable is non-@code{nil}, Emacs displays a message at the beginning and end of garbage collection. The default value is -@code{nil}, meaning there are no such messages. +@code{nil}. @end defopt @defvar post-gc-hook @@ -390,7 +389,7 @@ that the subsequent garbage collection does not happen immediately when the threshold is exhausted, but only the next time the Lisp evaluator is called. -The initial threshold value is 400,000. If you specify a larger +The initial threshold value is 800,000. 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 diff --git a/src/ChangeLog b/src/ChangeLog index f0e4fa62175..9f1823d34b6 100644 --- a/src/ChangeLog +++ b/src/ChangeLog @@ -1,3 +1,7 @@ +2012-03-03 Glenn Morris + + * alloc.c (Fgarbage_collect): Doc fix. + 2012-03-02 Eli Zaretskii * xdisp.c (try_window_reusing_current_matrix): Don't move cursor diff --git a/src/alloc.c b/src/alloc.c index a3e8033db18..29388870d93 100644 --- a/src/alloc.c +++ b/src/alloc.c @@ -1,6 +1,7 @@ /* Storage allocation and gc for GNU Emacs Lisp interpreter. - Copyright (C) 1985-1986, 1988, 1993-1995, 1997-2012 - Free Software Foundation, Inc. + +Copyright (C) 1985-1986, 1988, 1993-1995, 1997-2012 + Free Software Foundation, Inc. This file is part of GNU Emacs. @@ -5010,11 +5011,12 @@ Garbage collection happens automatically if you cons more than `gc-cons-threshold' bytes of Lisp data since previous garbage collection. `garbage-collect' normally returns a list with info on amount of space in use: ((USED-CONSES . FREE-CONSES) (USED-SYMS . FREE-SYMS) - (USED-MARKERS . FREE-MARKERS) USED-STRING-CHARS USED-VECTOR-SLOTS + (USED-MISCS . FREE-MISCS) USED-STRING-CHARS USED-VECTOR-SLOTS (USED-FLOATS . FREE-FLOATS) (USED-INTERVALS . FREE-INTERVALS) (USED-STRINGS . FREE-STRINGS)) However, if there was overflow in pure space, `garbage-collect' -returns nil, because real GC can't be done. */) +returns nil, because real GC can't be done. +See Info node `(elisp)Garbage Collection'. */) (void) { register struct specbinding *bind; -- 2.39.2