annotate lisp/README @ 5160:ab9ee10a53e4

fix various problems with allocation statistics, track overhead properly -------------------- ChangeLog entries follow: -------------------- lisp/ChangeLog addition: 2010-03-20 Ben Wing <ben@xemacs.org> * diagnose.el (show-memory-usage): * diagnose.el (show-object-memory-usage-stats): Further changes to correspond with changes in the C code; add an additional column showing the overhead used with each type, and add it into the grand total memory usage. src/ChangeLog addition: 2010-03-20 Ben Wing <ben@xemacs.org> * alloc.c: * alloc.c (init_lrecord_stats): * alloc.c (free_normal_lisp_object): * alloc.c (struct): * alloc.c (clear_lrecord_stats): * alloc.c (tick_lrecord_stats): * alloc.c (COUNT_FROB_BLOCK_USAGE): * alloc.c (COPY_INTO_LRECORD_STATS): * alloc.c (sweep_strings): * alloc.c (UNMARK_string): * alloc.c (gc_sweep_1): * alloc.c (finish_object_memory_usage_stats): * alloc.c (object_memory_usage_stats): * alloc.c (object_dead_p): * alloc.c (fixed_type_block_overhead): * alloc.c (lisp_object_storage_size): * emacs.c (main_1): * lisp.h: * lrecord.h: Export lisp_object_storage_size() and malloced_storage_size() even when not MEMORY_USAGE_STATS, to get the non-MEMORY_USAGE_STATS build to compile. Don't export fixed_type_block_overhead() any more. Some code cleanup, rearrangement, add some section headers. Clean up various bugs especially involving computation of overhead and double-counting certain usage in total_gc_usage. Add statistics computing the overhead used by all types. Don't add a special entry for string headers in the object-memory-usage-stats because it's already present as just "string". But do count the overhead used by long strings. Don't try to call the memory_usage() methods when NEW_GC because there's nowhere obvious in the sweep stage to make the calls. * marker.c (compute_buffer_marker_usage): Just use lisp_object_storage_size() rather than trying to reimplement it.
author Ben Wing <ben@xemacs.org>
date Sat, 20 Mar 2010 20:20:30 -0500
parents 2cf5d151eeb9
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
652
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
1 The files in this directory contain source code for the core XEmacs
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
2 facilities written in Emacs Lisp. *.el files are Elisp source, and
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
3 *.elc files are byte-compiled versions of the corresponding *.el
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
4 files. Byte-compiled files are architecture-independent.
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
5
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
6 Functions used only by files in this directory are considered
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
7 "internal" and are subject to change at any time. All commands, and
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
8 most functions with docstrings, are part of the exported API. In
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
9 particular, it is considered good style to use the Common Lisp
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
10 facilities provided in cl*.el. (Yes, that's ambiguous. Sorry, we
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
11 don't have a full specification of the API, as the Lispref is
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
12 chronically incomplete. Anything described in the Lispref is part of
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
13 the API, of course.)
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
14
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
15 Libraries which implement applications and enhancements are placed in
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
16 the "packages", which are distributed separately from the core
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
17 sources.
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
18
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
19 #### Someone please update this.
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
20 #### Partially updated 2001-08-25 by sjt. Needs more work. Mike?
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
21
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
22 When XEmacs starts up, it adds certain directories in various
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
23 hierarchies containing Lisp libraries to `load-path' (the list of
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
24 directories to be searched when loading files). These are: this
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
25 directory, its subdirectory ./mule (in Mule-enabled XEmacs only), the
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
26 site-lisp directory (deprecated), and all the lisp/PACKAGE
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
27 subdirectories of the xemacs-packages, mule-packages, and
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
28 site-packages hierarchies. See setup-paths.el.
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
29
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
30 #### Is the following true or relevant any more?
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
31 bogus> Directories whose names begin with "-" or "." are not added to
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
32 bogus> the default load-path.
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
33
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
34 Some files which you might reasonably want to alter when installing or
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
35 customizing XEmacs at your site are:
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
36
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
37 paths.el You may need to change the default pathnames here,
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
38 but probably not. This is loaded before XEmacs is
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
39 dumped.
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
40
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
41 site-init.el #### obsolete and removed?
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
42 To pre-load additional libraries into XEmacs and dump
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
43 them in the executable, load them from this file.
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
44 Read the instructions in this file for a description
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
45 of how to do this.
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
46
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
47 site-load.el #### description is obsolete
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
48 This is like site-init.el, but if you want the
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
49 docstrings of your preloaded libraries to be kept in
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
50 the DOC file instead of in the executable, you should
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
51 load them from this file instead. To do this, you must
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
52 also cause them to be scanned when the DOC file is
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
53 generated by editing ../src/Makefile.in.in and
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
54 rerunning configure.
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
55 #### new semantics
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
56 This file will preload additional libraries listed in
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
57 ../site-packages and dump them into XEmacs.
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
58
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
59 ../site-packages List of additional libraries read by site-load.el.
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
60
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
61 site-start.el This is loaded each time XEmacs starts up, before the
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
62 user's .emacs file. (Sysadmin must create.) Can be
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
63 inhibited for a given invocation with `--no-site-file'.
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
64
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
65 default.el This is loaded each time XEmacs starts up, after the
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
66 user's .emacs file, unless .emacs sets the variable
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
67 inhibit-default-init to t. (Sysadmin must create.)
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
68 Can be inhibited for a given invocation with `-q'.
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
69
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
70 version.el This contains the version information for XEmacs.
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
71
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
72 ========================================================================
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
73 Original text follows:
2cf5d151eeb9 [xemacs-hg @ 2001-08-26 10:25:11 by stephent]
stephent
parents: 428
diff changeset
74
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
75 The files in this directory contain source code for the XEmacs
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
76 facilities written in Emacs Lisp. *.el files are Elisp source, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
77 *.elc files are byte-compiled versions of the corresponding *.el
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
78 files. Byte-compiled files are architecture-independent.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
79
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
80 #### Someone please update this.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
81
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
82 bogus> When XEmacs starts up, it adds all subdirectories of the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
83 bogus> site-lisp directory. The site-lisp directory normally exists
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
84 bogus> only in installation trees. For more information about the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
85 bogus> site-lisp directory see the NEWS file.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
86
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
87 bogus> After XEmacs adds all subdirectories of the site-lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
88 bogus> directory, it adds all subdirectories of this directory to the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
89 bogus> load-path (the list of directories to be searched when loading
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
90 bogus> files.) To speed up this process, this directory has been
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
91 bogus> rearranged to have very few files at the top-level, so that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
92 bogus> emacs doesn't have to stat() several hundred files to find the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
93 bogus> dozen or so which are actually subdirectories.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
94
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
95 bogus> Directories whose names begin with "-" or "." are not added to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
96 bogus> the default load-path.
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 The only files which remain at top-level are those which you might
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
99 reasonably want to alter when installing or customizing XEmacs at your
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
100 site. The files which may appear at top level are:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
101
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
102 paths.el You may need to change the default pathnames here,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
103 but probably not. This is loaded before XEmacs is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
104 dumped.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
105
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
106 site-init.el To pre-load additional libraries into XEmacs and dump
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
107 them in the executable, load them from this file.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
108 Read the instructions in this file for a description
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
109 of how to do this.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
110
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
111 site-load.el This is like site-init.el, but if you want the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
112 docstrings of your preloaded libraries to be kept in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
113 the DOC file instead of in the executable, you should
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
114 load them from this file instead. To do this, you must
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
115 also cause them to be scanned when the DOC file is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
116 generated by editing ../src/Makefile.in.in and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
117 rerunning configure.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
118
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
119 site-start.el This is loaded each time XEmacs starts up, before the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
120 user's .emacs file.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
121
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
122 default.el This is loaded each time XEmacs starts up, after the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
123 user's .emacs file, unless .emacs sets the variable
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
124 inhibit-default-init to t.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
125
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
126 version.el This contains the version information for XEmacs.