annotate man/lispref/building.texi @ 2640:a4040d921acc

[xemacs-hg @ 2005-03-09 05:36:28 by stephent] internals and lispref <871xapfkkq.fsf@tleepslib.sk.tsukuba.ac.jp>
author stephent
date Wed, 09 Mar 2005 05:36:50 +0000
parents 87e011e66a78
children 9fa10603c898
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1 @c -*-texinfo-*-
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2 @c This is part of the XEmacs Lisp Reference Manual.
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 428
diff changeset
3 @c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4 @c See the file lispref.texi for copying conditions.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5 @setfilename ../../info/building.info
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6 @node Building XEmacs and Object Allocation, Standard Errors, Tips, Top
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7 @appendix Building XEmacs; Allocation of Objects
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9 This chapter describes how the runnable XEmacs executable is dumped
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
10 with the preloaded Lisp libraries in it and how storage is allocated.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
11
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
12 There is an entire separate document, the @cite{XEmacs Internals
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
13 Manual}, devoted to the internals of XEmacs from the perspective of the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
14 C programmer. It contains much more detailed information about the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
15 build process, the allocation and garbage-collection process, and other
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
16 aspects related to the internals of XEmacs.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
17
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
18 @menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
19 * Building XEmacs:: How to preload Lisp libraries into XEmacs.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
20 * Pure Storage:: A kludge to make preloaded Lisp functions sharable.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
21 * Garbage Collection:: Reclaiming space for Lisp objects no longer used.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
22 @end menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
23
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
24 @node Building XEmacs
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
25 @appendixsec Building XEmacs
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
26 @cindex building XEmacs
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
27 @pindex temacs
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
28
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
29 This section explains the steps involved in building the XEmacs
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
30 executable. You don't have to know this material to build and install
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
31 XEmacs, since the makefiles do all these things automatically. This
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
32 information is pertinent to XEmacs maintenance.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
33
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
34 The @cite{XEmacs Internals Manual} contains more information about this.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
35
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
36 Compilation of the C source files in the @file{src} directory
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
37 produces an executable file called @file{temacs}, also called a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
38 @dfn{bare impure XEmacs}. It contains the XEmacs Lisp interpreter and I/O
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
39 routines, but not the editing commands.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
40
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
41 @cindex @file{loadup.el}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
42 Before XEmacs is actually usable, a number of Lisp files need to be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
43 loaded. These define all the editing commands, plus most of the startup
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
44 code and many very basic Lisp primitives. This is accomplished by
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
45 loading the file @file{loadup.el}, which in turn loads all of the other
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
46 standardly-loaded Lisp files.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
47
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
48 It takes a substantial time to load the standard Lisp files. Luckily,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
49 you don't have to do this each time you run XEmacs; @file{temacs} can
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
50 dump out an executable program called @file{xemacs} that has these files
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
51 preloaded. @file{xemacs} starts more quickly because it does not need to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
52 load the files. This is the XEmacs executable that is normally
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
53 installed.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
54
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
55 To create @file{xemacs}, use the command @samp{temacs -batch -l loadup
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
56 dump}. The purpose of @samp{-batch} here is to tell @file{temacs} to run
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
57 in non-interactive, command-line mode. (@file{temacs} can @emph{only} run
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
58 in this fashion. Part of the code required to initialize frames and faces
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
59 is in Lisp, and must be loaded before XEmacs is able to create any frames.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
60 The argument @samp{dump} tells @file{loadup.el} to dump a new executable
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
61 named @file{xemacs}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
62
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
63 The dumping process is highly system-specific, and some operating
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
64 systems don't support dumping. On those systems, you must start XEmacs
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
65 with the @samp{temacs -batch -l loadup run-temacs} command each time you
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
66 use it. This takes a substantial time, but since you need to start
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
67 Emacs once a day at most---or once a week if you never log out---the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
68 extra time is not too severe a problem. (In older versions of Emacs,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
69 you started Emacs from @file{temacs} using @samp{temacs -l loadup}.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
70
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
71 @cindex runnable @file{temacs}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
72 @cindex bootstrapping XEmacs from @file{temacs}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
73 You are free to start XEmacs directly from @file{temacs} if you want,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
74 even if there is already a dumped @file{xemacs}. Normally you wouldn't
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
75 want to do that; but the Makefiles do this when you rebuild XEmacs using
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
76 @samp{make all-elc}, which builds XEmacs and simultaneously compiles any
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
77 out-of-date Lisp files. (You need @file{xemacs} in order to compile Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
78 files. However, you also need the compiled Lisp files in order to dump
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
79 out @file{xemacs}. If both of these are missing or corrupted, you are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
80 out of luck unless you're able to bootstrap @file{xemacs} from
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
81 @file{temacs}. Note that @samp{make all-elc} actually loads the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
82 alternative loadup file @file{loadup-el.el}, which works like
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
83 @file{loadup.el} but disables the pure-copying process and forces
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
84 XEmacs to ignore any compiled Lisp files even if they exist.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
85
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
86 @cindex @file{site-load.el}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
87 You can specify additional files to preload by writing a library named
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
88 @file{site-load.el} that loads them. You may need to increase the value
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
89 of @code{PURESIZE}, in @file{src/puresize.h}, to make room for the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
90 additional files. You should @emph{not} modify this file directly,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
91 however; instead, use the @samp{--puresize} configuration option. (If
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
92 you run out of pure space while dumping @file{xemacs}, you will be told
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
93 how much pure space you actually will need.) However, the advantage of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
94 preloading additional files decreases as machines get faster. On modern
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
95 machines, it is often not advisable, especially if the Lisp code is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
96 on a file system local to the machine running XEmacs.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
97
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
98 @cindex @file{site-init.el}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
99 You can specify other Lisp expressions to execute just before dumping
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
100 by putting them in a library named @file{site-init.el}. However, if
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
101 they might alter the behavior that users expect from an ordinary
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
102 unmodified XEmacs, it is better to put them in @file{default.el}, so that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
103 users can override them if they wish. @xref{Start-up Summary}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
104
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
105 Before @file{loadup.el} dumps the new executable, it finds the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
106 documentation strings for primitive and preloaded functions (and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
107 variables) in the file where they are stored, by calling
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
108 @code{Snarf-documentation} (@pxref{Accessing Documentation}). These
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
109 strings were moved out of the @file{xemacs} executable to make it
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
110 smaller. @xref{Documentation Basics}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
111
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
112 @defun dump-emacs to-file from-file
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
113 @cindex unexec
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
114 This function dumps the current state of XEmacs into an executable file
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
115 @var{to-file}. It takes symbols from @var{from-file} (this is normally
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
116 the executable file @file{temacs}).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
117
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
118 If you use this function in an XEmacs that was already dumped, you must
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
119 set @code{command-line-processed} to @code{nil} first for good results.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
120 @xref{Command Line Arguments}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
121 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
122
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
123 @defun run-emacs-from-temacs &rest args
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
124 This is the function that implements the @file{run-temacs} command-line
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
125 argument. It is called from @file{loadup.el} as appropriate. You should
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
126 most emphatically @emph{not} call this yourself; it will reinitialize
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
127 your XEmacs process and you'll be sorry.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
128 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
129
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 428
diff changeset
130 @deffn Command emacs-version &optional arg
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
131 This function returns a string describing the version of XEmacs that is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
132 running. It is useful to include this string in bug reports.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
133
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 428
diff changeset
134 When called interactively with a prefix argument, insert string at point.
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 428
diff changeset
135 Don't use this function in programs to choose actions according
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 428
diff changeset
136 to the system configuration; look at @code{system-configuration} instead.
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 428
diff changeset
137
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
138 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
139 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
140 (emacs-version)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
141 @result{} "XEmacs 20.1 [Lucid] (i586-unknown-linux2.0.29)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
142 of Mon Apr 7 1997 on altair.xemacs.org"
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
143 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
144 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
145
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
146 Called interactively, the function prints the same information in the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
147 echo area.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
148 @end deffn
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
149
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
150 @defvar emacs-build-time
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
151 The value of this variable is the time at which XEmacs was built at the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
152 local site.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
153
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
154 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
155 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
156 emacs-build-time "Mon Apr 7 20:28:52 1997"
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 428
diff changeset
157 @result{}
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
158 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
159 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
160 @end defvar
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
161
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
162 @defvar emacs-version
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
163 The value of this variable is the version of Emacs being run. It is a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
164 string, e.g. @code{"20.1 XEmacs Lucid"}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
165 @end defvar
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
166
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
167 The following two variables did not exist before FSF GNU Emacs version
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
168 19.23 and XEmacs version 19.10, which reduces their usefulness at
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
169 present, but we hope they will be convenient in the future.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
170
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
171 @defvar emacs-major-version
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
172 The major version number of Emacs, as an integer. For XEmacs version
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
173 20.1, the value is 20.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
174 @end defvar
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
175
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
176 @defvar emacs-minor-version
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
177 The minor version number of Emacs, as an integer. For XEmacs version
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
178 20.1, the value is 1.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
179 @end defvar
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
180
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
181 @node Pure Storage
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
182 @appendixsec Pure Storage
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
183 @cindex pure storage
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
184
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
185 XEmacs Lisp uses two kinds of storage for user-created Lisp objects:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
186 @dfn{normal storage} and @dfn{pure storage}. Normal storage is where
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
187 all the new data created during an XEmacs session is kept; see the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
188 following section for information on normal storage. Pure storage is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
189 used for certain data in the preloaded standard Lisp files---data that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
190 should never change during actual use of XEmacs.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
191
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
192 Pure storage is allocated only while @file{temacs} is loading the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
193 standard preloaded Lisp libraries. In the file @file{xemacs}, it is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
194 marked as read-only (on operating systems that permit this), so that the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
195 memory space can be shared by all the XEmacs jobs running on the machine
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
196 at once. Pure storage is not expandable; a fixed amount is allocated
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
197 when XEmacs is compiled, and if that is not sufficient for the preloaded
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
198 libraries, @file{temacs} aborts with an error message. If that happens,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
199 you must increase the compilation parameter @code{PURESIZE} using the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
200 @samp{--puresize} option to @file{configure}. This normally won't
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
201 happen unless you try to preload additional libraries or add features to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
202 the standard ones.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
203
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
204 @defun purecopy object
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
205 This function makes a copy of @var{object} in pure storage and returns
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
206 it. It copies strings by simply making a new string with the same
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
207 characters in pure storage. It recursively copies the contents of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
208 vectors and cons cells. It does not make copies of other objects such
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
209 as symbols, but just returns them unchanged. It signals an error if
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
210 asked to copy markers.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
211
959
87e011e66a78 [xemacs-hg @ 2002-08-12 07:45:36 by youngs]
youngs
parents: 444
diff changeset
212 This function is a no-op in XEmacs, and its use is deprecated.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
213 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
214
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
215 @defvar pure-bytes-used
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
216 The value of this variable is the number of bytes of pure storage
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
217 allocated so far. Typically, in a dumped XEmacs, this number is very
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
218 close to the total amount of pure storage available---if it were not,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
219 we would preallocate less.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
220 @end defvar
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
221
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
222 @defvar purify-flag
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
223 This variable determines whether @code{defun} should make a copy of the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
224 function definition in pure storage. If it is non-@code{nil}, then the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
225 function definition is copied into pure storage.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
226
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
227 This flag is @code{t} while loading all of the basic functions for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
228 building XEmacs initially (allowing those functions to be sharable and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
229 non-collectible). Dumping XEmacs as an executable always writes
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
230 @code{nil} in this variable, regardless of the value it actually has
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
231 before and after dumping.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
232
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
233 You should not change this flag in a running XEmacs.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
234 @end defvar
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
235
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
236 @node Garbage Collection
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
237 @appendixsec Garbage Collection
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
238 @cindex garbage collector
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
239
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
240 @cindex memory allocation
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
241 When a program creates a list or the user defines a new function (such
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
242 as by loading a library), that data is placed in normal storage. If
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
243 normal storage runs low, then XEmacs asks the operating system to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
244 allocate more memory in blocks of 2k bytes. Each block is used for one
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
245 type of Lisp object, so symbols, cons cells, markers, etc., are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
246 segregated in distinct blocks in memory. (Vectors, long strings,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
247 buffers and certain other editing types, which are fairly large, are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
248 allocated in individual blocks, one per object, while small strings are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
249 packed into blocks of 8k bytes. [More correctly, a string is allocated
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
250 in two sections: a fixed size chunk containing the length, list of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
251 extents, etc.; and a chunk containing the actual characters in the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
252 string. It is this latter chunk that is either allocated individually
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
253 or packed into 8k blocks. The fixed size chunk is packed into 2k
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
254 blocks, as for conses, markers, etc.])
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
255
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
256 It is quite common to use some storage for a while, then release it by
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
257 (for example) killing a buffer or deleting the last pointer to an
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
258 object. XEmacs provides a @dfn{garbage collector} to reclaim this
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
259 abandoned storage. (This name is traditional, but ``garbage recycler''
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
260 might be a more intuitive metaphor for this facility.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
261
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
262 The garbage collector operates by finding and marking all Lisp objects
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
263 that are still accessible to Lisp programs. To begin with, it assumes
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
264 all the symbols, their values and associated function definitions, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
265 any data presently on the stack, are accessible. Any objects that can
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
266 be reached indirectly through other accessible objects are also
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
267 accessible.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
268
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
269 When marking is finished, all objects still unmarked are garbage. No
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
270 matter what the Lisp program or the user does, it is impossible to refer
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
271 to them, since there is no longer a way to reach them. Their space
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
272 might as well be reused, since no one will miss them. The second
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
273 (``sweep'') phase of the garbage collector arranges to reuse them.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
274
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
275 @cindex free list
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
276 The sweep phase puts unused cons cells onto a @dfn{free list} for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
277 future allocation; likewise for symbols, markers, extents, events,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
278 floats, compiled-function objects, and the fixed-size portion of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
279 strings. It compacts the accessible small string-chars chunks so they
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
280 occupy fewer 8k blocks; then it frees the other 8k blocks. Vectors,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
281 buffers, windows, and other large objects are individually allocated and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
282 freed using @code{malloc} and @code{free}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
283
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
284 @cindex CL note---allocate more storage
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
285 @quotation
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
286 @b{Common Lisp note:} unlike other Lisps, XEmacs Lisp does not
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
287 call the garbage collector when the free list is empty. Instead, it
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
288 simply requests the operating system to allocate more storage, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
289 processing continues until @code{gc-cons-threshold} bytes have been
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
290 used.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
291
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
292 This means that you can make sure that the garbage collector will not
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
293 run during a certain portion of a Lisp program by calling the garbage
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
294 collector explicitly just before it (provided that portion of the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
295 program does not use so much space as to force a second garbage
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
296 collection).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
297 @end quotation
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
298
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
299 @deffn Command garbage-collect
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
300 This command runs a garbage collection, and returns information on
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
301 the amount of space in use. (Garbage collection can also occur
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
302 spontaneously if you use more than @code{gc-cons-threshold} bytes of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
303 Lisp data since the previous garbage collection.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
304
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
305 @code{garbage-collect} returns a list containing the following
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
306 information:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
307
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
308 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
309 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
310 ((@var{used-conses} . @var{free-conses})
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
311 (@var{used-syms} . @var{free-syms})
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
312 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
313 (@var{used-markers} . @var{free-markers})
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 428
diff changeset
314 @var{used-string-chars}
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
315 @var{used-vector-slots}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
316 (@var{plist}))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
317
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
318 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
319 @result{} ((73362 . 8325) (13718 . 164)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
320 (5089 . 5098) 949121 118677
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
321 (conses-used 73362 conses-free 8329 cons-storage 658168
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
322 symbols-used 13718 symbols-free 164 symbol-storage 335216
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
323 bit-vectors-used 0 bit-vectors-total-length 0
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
324 bit-vector-storage 0 vectors-used 7882
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
325 vectors-total-length 118677 vector-storage 537764
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
326 compiled-functions-used 1336 compiled-functions-free 37
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
327 compiled-function-storage 44440 short-strings-used 28829
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
328 long-strings-used 2 strings-free 7722
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
329 short-strings-total-length 916657 short-string-storage 1179648
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
330 long-strings-total-length 32464 string-header-storage 441504
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
331 floats-used 3 floats-free 43 float-storage 2044 markers-used 5089
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
332 markers-free 5098 marker-storage 245280 events-used 103
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
333 events-free 835 event-storage 110656 extents-used 10519
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
334 extents-free 2718 extent-storage 372736
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
335 extent-auxiliarys-used 111 extent-auxiliarys-freed 3
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
336 extent-auxiliary-storage 4440 window-configurations-used 39
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
337 window-configurations-on-free-list 5
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
338 window-configurations-freed 10 window-configuration-storage 9492
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
339 popup-datas-used 3 popup-data-storage 72 toolbar-buttons-used 62
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
340 toolbar-button-storage 4960 toolbar-datas-used 12
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
341 toolbar-data-storage 240 symbol-value-buffer-locals-used 182
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
342 symbol-value-buffer-local-storage 5824
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
343 symbol-value-lisp-magics-used 22
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
344 symbol-value-lisp-magic-storage 1496
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
345 symbol-value-varaliases-used 43
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
346 symbol-value-varalias-storage 1032 opaque-lists-used 2
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
347 opaque-list-storage 48 color-instances-used 12
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
348 color-instance-storage 288 font-instances-used 5
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
349 font-instance-storage 180 opaques-used 11 opaque-storage 312
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
350 range-tables-used 1 range-table-storage 16 faces-used 34
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
351 face-storage 2584 glyphs-used 124 glyph-storage 4464
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
352 specifiers-used 775 specifier-storage 43869 weak-lists-used 786
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
353 weak-list-storage 18864 char-tables-used 40
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
354 char-table-storage 41920 buffers-used 25 buffer-storage 7000
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
355 extent-infos-used 457 extent-infos-freed 73
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
356 extent-info-storage 9140 keymaps-used 275 keymap-storage 12100
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
357 consoles-used 4 console-storage 384 command-builders-used 2
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
358 command-builder-storage 120 devices-used 2 device-storage 344
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
359 frames-used 3 frame-storage 624 image-instances-used 47
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
360 image-instance-storage 3008 windows-used 27 windows-freed 2
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
361 window-storage 9180 lcrecord-lists-used 15
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
362 lcrecord-list-storage 360 hash-tables-used 631
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
363 hash-table-storage 25240 streams-used 1 streams-on-free-list 3
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
364 streams-freed 12 stream-storage 91))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
365 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
366 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
367
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
368 Here is a table explaining each element:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
369
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
370 @table @var
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
371 @item used-conses
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
372 The number of cons cells in use.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
373
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
374 @item free-conses
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
375 The number of cons cells for which space has been obtained from the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
376 operating system, but that are not currently being used.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
377
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
378 @item used-syms
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
379 The number of symbols in use.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
380
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
381 @item free-syms
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
382 The number of symbols for which space has been obtained from the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
383 operating system, but that are not currently being used.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
384
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
385 @item used-markers
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
386 The number of markers in use.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
387
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
388 @item free-markers
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
389 The number of markers for which space has been obtained from the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
390 operating system, but that are not currently being used.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
391
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
392 @item used-string-chars
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
393 The total size of all strings, in characters.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
394
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
395 @item used-vector-slots
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
396 The total number of elements of existing vectors.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
397
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
398 @item plist
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
399 A list of alternating keyword/value pairs providing more detailed
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
400 information. (As you can see above, quite a lot of information is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
401 provided.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
402 @ignore @c Different in XEmacs
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
403
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
404 @item used-floats
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
405 @c Emacs 19 feature
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
406 The number of floats in use.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
407
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
408 @item free-floats
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
409 @c Emacs 19 feature
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
410 The number of floats for which space has been obtained from the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
411 operating system, but that are not currently being used.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
412 @end ignore
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
413 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
414 @end deffn
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
415
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
416 @defopt gc-cons-threshold
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
417 The value of this variable is the number of bytes of storage that must
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
418 be allocated for Lisp objects after one garbage collection in order to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
419 trigger another garbage collection. A cons cell counts as eight bytes,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
420 a string as one byte per character plus a few bytes of overhead, and so
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
421 on; space allocated to the contents of buffers does not count. Note
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
422 that the subsequent garbage collection does not happen immediately when
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
423 the threshold is exhausted, but only the next time the Lisp evaluator is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
424 called.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
425
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
426 The initial threshold value is 500,000. If you specify a larger
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
427 value, garbage collection will happen less often. This reduces the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
428 amount of time spent garbage collecting, but increases total memory use.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
429 You may want to do this when running a program that creates lots of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
430 Lisp data.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
431
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
432 You can make collections more frequent by specifying a smaller value,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
433 down to 10,000. A value less than 10,000 will remain in effect only
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
434 until the subsequent garbage collection, at which time
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
435 @code{garbage-collect} will set the threshold back to 10,000. (This does
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
436 not apply if XEmacs was configured with @samp{--debug}. Therefore, be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
437 careful when setting @code{gc-cons-threshold} in that case!)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
438 @end defopt
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
439
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 428
diff changeset
440 @ignore
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
441 @c Emacs 19 feature
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
442 @defun memory-limit
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
443 This function returns the address of the last byte XEmacs has allocated,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
444 divided by 1024. We divide the value by 1024 to make sure it fits in a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
445 Lisp integer.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
446
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
447 You can use this to get a general idea of how your actions affect the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
448 memory usage.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
449 @end defun
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 428
diff changeset
450 @end ignore
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
451
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
452 @defvar pre-gc-hook
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
453 This is a normal hook to be run just before each garbage collection.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
454 Interrupts, garbage collection, and errors are inhibited while this hook
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
455 runs, so be extremely careful in what you add here. In particular,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
456 avoid consing, and do not interact with the user.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
457 @end defvar
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
458
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
459 @defvar post-gc-hook
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
460 This is a normal hook to be run just after each garbage collection.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
461 Interrupts, garbage collection, and errors are inhibited while this hook
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
462 runs, so be extremely careful in what you add here. In particular,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
463 avoid consing, and do not interact with the user.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
464 @end defvar
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
465
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
466 @defvar gc-message
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
467 This is a string to print to indicate that a garbage collection is in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
468 progress. This is printed in the echo area. If the selected frame is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
469 on a window system and @code{gc-pointer-glyph} specifies a value (i.e. a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
470 pointer image instance) in the domain of the selected frame, the mouse
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
471 cursor will change instead of this message being printed.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
472 @end defvar
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
473
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
474 @defvr Glyph gc-pointer-glyph
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
475 This holds the pointer glyph used to indicate that a garbage collection
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
476 is in progress. If the selected window is on a window system and this
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
477 glyph specifies a value (i.e. a pointer image instance) in the domain of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
478 the selected window, the cursor will be changed as specified during
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
479 garbage collection. Otherwise, a message will be printed in the echo
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
480 area, as controlled by @code{gc-message}. @xref{Glyphs}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
481 @end defvr
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
482
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
483 If XEmacs was configured with @samp{--debug}, you can set the following
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
484 two variables to get direct information about all the allocation that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
485 is happening in a segment of Lisp code.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
486
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
487 @defvar debug-allocation
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
488 If non-zero, print out information to stderr about all objects
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
489 allocated.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
490 @end defvar
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
491
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
492 @defvar debug-allocation-backtrace
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
493 Length (in stack frames) of short backtrace printed out by
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
494 @code{debug-allocation}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
495 @end defvar