Mercurial > hg > xemacs-beta
annotate man/xemacs/startup.texi @ 5157:1fae11d56ad2
redo memory-usage mechanism, add way of dynamically initializing Lisp objects
-------------------- ChangeLog entries follow: --------------------
lisp/ChangeLog addition:
2010-03-18 Ben Wing <ben@xemacs.org>
* diagnose.el (show-memory-usage):
Rewrite to take into account API changes in memory-usage functions.
src/ChangeLog addition:
2010-03-18 Ben Wing <ben@xemacs.org>
* alloc.c:
* alloc.c (disksave_object_finalization_1):
* alloc.c (lisp_object_storage_size):
* alloc.c (listu):
* alloc.c (listn):
* alloc.c (Fobject_memory_usage_stats):
* alloc.c (compute_memusage_stats_length):
* alloc.c (Fobject_memory_usage):
* alloc.c (Ftotal_object_memory_usage):
* alloc.c (malloced_storage_size):
* alloc.c (common_init_alloc_early):
* alloc.c (reinit_alloc_objects_early):
* alloc.c (reinit_alloc_early):
* alloc.c (init_alloc_once_early):
* alloc.c (syms_of_alloc):
* alloc.c (reinit_vars_of_alloc):
* buffer.c:
* buffer.c (struct buffer_stats):
* buffer.c (compute_buffer_text_usage):
* buffer.c (compute_buffer_usage):
* buffer.c (buffer_memory_usage):
* buffer.c (buffer_objects_create):
* buffer.c (syms_of_buffer):
* buffer.c (vars_of_buffer):
* console-impl.h (struct console_methods):
* dynarr.c (Dynarr_memory_usage):
* emacs.c (main_1):
* events.c (clear_event_resource):
* extents.c:
* extents.c (compute_buffer_extent_usage):
* extents.c (extent_objects_create):
* extents.h:
* faces.c:
* faces.c (compute_face_cachel_usage):
* faces.c (face_objects_create):
* faces.h:
* general-slots.h:
* glyphs.c:
* glyphs.c (compute_glyph_cachel_usage):
* glyphs.c (glyph_objects_create):
* glyphs.h:
* lisp.h:
* lisp.h (struct usage_stats):
* lrecord.h:
* lrecord.h (enum lrecord_type):
* lrecord.h (struct lrecord_implementation):
* lrecord.h (MC_ALLOC_CALL_FINALIZER_FOR_DISKSAVE):
* lrecord.h (DEFINE_DUMPABLE_LISP_OBJECT):
* lrecord.h (DEFINE_DUMPABLE_SIZABLE_LISP_OBJECT):
* lrecord.h (DEFINE_DUMPABLE_FROB_BLOCK_LISP_OBJECT):
* lrecord.h (DEFINE_DUMPABLE_FROB_BLOCK_SIZABLE_LISP_OBJECT):
* lrecord.h (DEFINE_DUMPABLE_INTERNAL_LISP_OBJECT):
* lrecord.h (DEFINE_DUMPABLE_SIZABLE_INTERNAL_LISP_OBJECT):
* lrecord.h (DEFINE_NODUMP_LISP_OBJECT):
* lrecord.h (DEFINE_NODUMP_SIZABLE_LISP_OBJECT):
* lrecord.h (DEFINE_NODUMP_FROB_BLOCK_LISP_OBJECT):
* lrecord.h (DEFINE_NODUMP_FROB_BLOCK_SIZABLE_LISP_OBJECT):
* lrecord.h (DEFINE_NODUMP_INTERNAL_LISP_OBJECT):
* lrecord.h (DEFINE_NODUMP_SIZABLE_INTERNAL_LISP_OBJECT):
* lrecord.h (MAKE_LISP_OBJECT):
* lrecord.h (DEFINE_DUMPABLE_MODULE_LISP_OBJECT):
* lrecord.h (DEFINE_DUMPABLE_MODULE_SIZABLE_LISP_OBJECT):
* lrecord.h (DEFINE_NODUMP_MODULE_LISP_OBJECT):
* lrecord.h (DEFINE_NODUMP_MODULE_SIZABLE_LISP_OBJECT):
* lrecord.h (MAKE_MODULE_LISP_OBJECT):
* lrecord.h (INIT_LISP_OBJECT):
* lrecord.h (INIT_MODULE_LISP_OBJECT):
* lrecord.h (UNDEF_LISP_OBJECT):
* lrecord.h (UNDEF_MODULE_LISP_OBJECT):
* lrecord.h (DECLARE_LISP_OBJECT):
* lrecord.h (DECLARE_MODULE_API_LISP_OBJECT):
* lrecord.h (DECLARE_MODULE_LISP_OBJECT):
* lstream.c:
* lstream.c (syms_of_lstream):
* lstream.c (vars_of_lstream):
* marker.c:
* marker.c (compute_buffer_marker_usage):
* mc-alloc.c (mc_alloced_storage_size):
* mc-alloc.h:
* mule-charset.c:
* mule-charset.c (struct charset_stats):
* mule-charset.c (compute_charset_usage):
* mule-charset.c (charset_memory_usage):
* mule-charset.c (mule_charset_objects_create):
* mule-charset.c (syms_of_mule_charset):
* mule-charset.c (vars_of_mule_charset):
* redisplay.c:
* redisplay.c (compute_rune_dynarr_usage):
* redisplay.c (compute_display_block_dynarr_usage):
* redisplay.c (compute_glyph_block_dynarr_usage):
* redisplay.c (compute_display_line_dynarr_usage):
* redisplay.c (compute_line_start_cache_dynarr_usage):
* redisplay.h:
* scrollbar-gtk.c (gtk_compute_scrollbar_instance_usage):
* scrollbar-msw.c (mswindows_compute_scrollbar_instance_usage):
* scrollbar-x.c (x_compute_scrollbar_instance_usage):
* scrollbar.c (compute_scrollbar_instance_usage):
* scrollbar.h:
* symbols.c:
* symbols.c (reinit_symbol_objects_early):
* symbols.c (init_symbols_once_early):
* symbols.c (reinit_symbols_early):
* symbols.c (defsymbol_massage_name_1):
* symsinit.h:
* ui-gtk.c:
* ui-gtk.c (emacs_gtk_object_getprop):
* ui-gtk.c (emacs_gtk_object_putprop):
* ui-gtk.c (ui_gtk_objects_create):
* unicode.c (compute_from_unicode_table_size_1):
* unicode.c (compute_to_unicode_table_size_1):
* unicode.c (compute_from_unicode_table_size):
* unicode.c (compute_to_unicode_table_size):
* window.c:
* window.c (struct window_stats):
* window.c (compute_window_mirror_usage):
* window.c (compute_window_usage):
* window.c (window_memory_usage):
* window.c (window_objects_create):
* window.c (syms_of_window):
* window.c (vars_of_window):
* window.h:
Redo memory-usage mechanism, make it general; add way of dynamically
initializing Lisp object types -- OBJECT_HAS_METHOD(), similar to
CONSOLE_HAS_METHOD().
(1) Create OBJECT_HAS_METHOD(), OBJECT_HAS_PROPERTY() etc. for
specifying that a Lisp object type has a particular method or
property. Call such methods with OBJECT_METH, MAYBE_OBJECT_METH,
OBJECT_METH_OR_GIVEN; retrieve properties with OBJECT_PROPERTY.
Methods that formerly required a DEFINE_*GENERAL_LISP_OBJECT() to
specify them (getprop, putprop, remprop, plist, disksave) now
instead use the dynamic-method mechanism. The main benefit of
this is that new methods or properties can be added without
requiring that the declaration statements of all existing methods
be modified. We have to make the `struct lrecord_implementation'
non-const, but I don't think this should have any effect on speed --
the only possible method that's really speed-critical is the
mark method, and we already extract those out into a separate
(non-const) array for increased cache locality.
Object methods need to be reinitialized after pdump, so we put
them in separate functions such as face_objects_create(),
extent_objects_create() and call them appropriately from emacs.c
The only current object property (`memusage_stats_list') that
objects can specify is a Lisp object and gets staticpro()ed so it
only needs to be set during dump time, but because it references
symbols that might not exist in a syms_of_() function, we
initialize it in vars_of_(). There is also an object property
(`num_extra_memusage_stats') that is automatically initialized based
on `memusage_stats_list'; we do that in reinit_vars_of_alloc(),
which is called after all vars_of_() functions are called.
`disksaver' method was renamed `disksave' to correspond with the
name normally given to the function (e.g. disksave_lstream()).
(2) Generalize the memory-usage mechanism in `buffer-memory-usage',
`window-memory-usage', `charset-memory-usage' into an object-type-
specific mechanism called by a single function
`object-memory-usage'. (Former function `object-memory-usage'
renamed to `total-object-memory-usage'). Generalize the mechanism
of different "slices" so that we can have different "classes" of
memory described and different "slices" onto each class; `t'
separates classes, `nil' separates slices. Currently we have
three classes defined: the memory of an object itself,
non-Lisp-object memory associated with the object (e.g. arrays or
dynarrs stored as fields in the object), and Lisp-object memory
associated with the object (other internal Lisp objects stored in
the object). This isn't completely finished yet and we might need
to further separate the "other internal Lisp objects" class into
two classes.
The memory-usage mechanism uses a `struct usage_stats' (renamed
from `struct overhead_stats') to describe a malloc-view onto a set
of allocated memory (listing how much was requested and various
types of overhead) and a more general `struct generic_usage_stats'
(with a `struct usage_stats' in it) to hold all statistics about
object memory. `struct generic_usage_stats' contains an array of
32 Bytecounts, which are statistics of unspecified semantics. The
intention is that individual types declare a corresponding struct
(e.g. `struct window_stats') with the same structure but with
specific fields in place of the array, corresponding to specific
statistics. The number of such statistics is an object property
computed from the list of tags (Lisp symbols describing the
statistics) stored in `memusage_stats_list'. The idea here is to
allow particular object types to customize the number and
semantics of the statistics where completely avoiding consing.
This doesn't matter so much yet, but the intention is to have the
memory usage of all objects computed at the end of GC, at the same
time as other statistics are currently computed. The values for
all statistics for a single type would be added up to compute
aggregate values for all objects of a specific type. To make this
efficient, we can't allow any memory allocation at all.
(3) Create some additional functions for creating lists that
specify the elements directly as args rather than indirectly through
an array: listn() (number of args given), listu() (list terminated
by Qunbound).
(4) Delete a bit of remaining unused C window_config stuff, also
unused lrecord_type_popup_data.
| author | Ben Wing <ben@xemacs.org> |
|---|---|
| date | Thu, 18 Mar 2010 10:50:06 -0500 |
| parents | 15139dbf89f4 |
| children | 9c4bf82eaac2 |
| rev | line source |
|---|---|
| 444 | 1 @node Startup Paths, Packages, Command Switches, Top |
| 428 | 2 @comment node-name, next, previous, up |
| 3 @section How XEmacs finds Directories and Files | |
| 4 | |
| 5 @cindex startup paths | |
| 6 @cindex directories | |
| 7 | |
| 8 XEmacs deals with a multitude of files during operation. These files | |
| 9 are spread over many directories, and XEmacs determines the location of | |
| 10 most of these directories at startup and organizes them into various | |
| 11 paths. (A @dfn{path}, | |
| 12 @cindex path | |
| 13 for the purposes of this section, is simply a list of directories which | |
| 14 XEmacs searches successively in order to locate a file.) | |
| 15 | |
| 16 @subsection XEmacs Directory Hierarchies | |
| 17 @cindex hierarchies | |
| 18 @cindex directory hierarchies | |
| 19 | |
| 20 Many of the files XEmacs looks for are located within the XEmacs | |
| 21 installation itself. However, there are several views of what actually | |
| 22 constitutes the "XEmacs installation": XEmacs may be run from the | |
| 23 compilation directory, it may be installed into arbitrary directories, | |
| 24 spread over several directories unrelated to each other. Moreover, it | |
| 25 may subsequently be moved to a different place. (This last case is not | |
| 26 as uncommon as it sounds. Binary kits work this way.) Consequently, | |
| 27 XEmacs has quite complex procedures in place to find directories, no | |
| 28 matter where they may be hidden. | |
| 29 | |
| 30 XEmacs will always respect directory options passed to @code{configure}. | |
| 31 However, if it cannot locate a directory at the configured place, it | |
| 32 will initiate a search for the directory in any of a number of | |
| 33 @dfn{hierarchies} rooted under a directory which XEmacs assumes contain | |
| 34 parts of the XEmacs installation; it may locate several such hierarchies | |
| 35 and search across them. (Typically, there are just one or two | |
| 36 hierarchies: the hierarchy where XEmacs was or will be installed, and | |
| 37 the one where it is being built.) Such a directory containing a | |
| 38 hierarchy is called a @dfn{root}. | |
| 39 @cindex root of a hierarchy | |
| 40 Whenever this section refers to a directory using the shorthand | |
| 41 @code{<root>}, it means that XEmacs searches for it under all | |
| 442 | 42 hierarchies XEmacs was able to scrounge up. In a |
| 428 | 43 running XEmacs, the hierarchy roots are stored in the variable |
| 44 @code{emacs-roots}. | |
| 45 @vindex emacs-roots | |
| 46 | |
| 47 @subsection Package Hierarchies | |
| 48 @cindex package hierarchies | |
| 49 | |
| 50 Many relevant directories and files XEmacs uses are actually not part of | |
| 51 the core installation. They are part of any of the many packages | |
| 52 usually installed on top of an XEmacs installation. (@xref{Packages}.) | |
| 53 Hence, they play a prominent role in the various paths XEmacs sets up. | |
| 54 | |
| 55 XEmacs locates packages in any of a number of package hierarchies. | |
| 56 Package hierarchies fall into three groups: @dfn{early}, @dfn{late}, | |
| 57 and @dfn{last}, | |
| 58 @cindex early package hierarchies | |
| 59 @cindex late package hierarchies | |
| 60 @cindex last package hierarchies | |
| 61 according to the relative location at which they show | |
| 62 up in the various XEmacs paths. Early package hierarchies are at the | |
| 63 very front, late ones somewhere in the middle, and last hierarchies are | |
| 64 (you guessed it) last. | |
| 65 | |
| 442 | 66 By default, XEmacs expects an early package hierarchy in the |
| 67 subdirectory @file{.xemacs/xemacs-packages} of the user's home | |
| 68 directory. | |
| 428 | 69 |
| 70 Moreover, XEmacs expects late hierarchies in the subdirectories | |
| 71 @file{site-packages}, @file{mule-packages}, and @file{xemacs-packages} | |
| 72 (in that order) of the @file{<root>/lib/xemacs} subdirectory of one of | |
| 73 the installation hierarchies. (If you run in-place, these are direct | |
| 74 subdirectories of the build directory.) Furthermore, XEmacs will also | |
| 75 search these subdirectories in the @file{<root>/lib/xemacs-<VERSION>} | |
| 76 subdirectory and prefer directories found there. | |
| 77 | |
| 78 By default, XEmacs does not have a pre-configured last package | |
| 79 hierarchy. Last hierarchies are primarily for using package hierarchies | |
| 80 of outdated versions of XEmacs as a fallback option. For example, it is | |
| 442 | 81 possible to run XEmacs 21 with the 20.4 package hierarchy as a last |
| 428 | 82 hierarchy. |
| 83 | |
| 84 It is possible to specify at configure-time the location of the various | |
| 3179 | 85 package directories with the @code{--with-user-packages} (an alias for |
| 86 @samp{--with-early-packages}), @code{--with-system-packages} (an alias | |
| 87 for @samp{--with-late-packages}), and @code{--with-legacy-packages} (an | |
| 88 alias for @samp{--with-last-packages}) options to configure. | |
| 428 | 89 @cindex package path |
| 3179 | 90 At run time, the package directories may also be specified via the |
| 91 @code{EMACSEARLYPACKAGES}, @code{EMACSLATEPACKAGES}, and | |
| 92 @code{EMACSLASTPACKAGES} environment variables. | |
| 428 | 93 |
| 1183 | 94 An XEmacs package hierarchy is laid out just like a normal installed |
| 1258 | 95 XEmacs directory. It may have @file{lisp}, @file{etc}, @file{info}, and |
| 96 @file{lib-src} subdirectories. (The @file{lib-src} subdirectory | |
| 97 contains architecture-independent general-purpose scripts interpreted by | |
| 98 the shell or Perl. Java is also being widely used, but Java programs | |
| 99 are generally found under @file{etc}, because they are specific to | |
| 100 particular packages such as @file{JDE} and @file{xslt}.) XEmacs adds | |
| 101 these at appropriate places within the various system-wide paths. | |
| 428 | 102 |
| 103 There may be any number of package hierarchy directories. | |
| 104 | |
| 105 @subsection Directories and Paths | |
| 106 @cindex paths | |
| 107 | |
| 108 Here is a list of the various directories and paths XEmacs tries to | |
| 109 locate during startup. XEmacs distinguishes between directories and | |
| 110 paths specific to @dfn{version}, @dfn{site}, and @dfn{architecture} | |
| 111 when looking for them. | |
| 112 | |
| 113 @table @code | |
| 114 @item version-specific | |
| 115 @cindex version-specific directories | |
| 116 directories are specific to the version of XEmacs they belong to and | |
| 117 typically reside under @file{<root>/lib/xemacs-<VERSION>}. | |
| 118 @item site-specific | |
| 119 @cindex site-specific directories | |
| 120 directories are independent of the version of XEmacs they belong to and | |
| 121 typically reside under @file{<root>/lib/xemacs} | |
| 122 @item architecture-specific | |
| 123 @cindex architecture-specific directories | |
| 124 directories are specific both to the version of XEmacs and the | |
| 125 architecture it runs on and typically reside under | |
| 126 @file{<root>/lib/xemacs-<VERSION>/<ARCHITECTURE>}. | |
| 127 @end table | |
| 128 | |
| 129 During installation, all of these directories may also reside directly | |
| 130 under @file{<root>}, because that is where they are in the XEmacs tarball. | |
| 131 | |
| 132 If XEmacs runs with the @code{-debug-paths} option (@pxref{Command | |
| 133 Switches}), it will print the values of these variables, hopefully | |
| 134 aiding in debugging any problems which come up. | |
| 135 | |
| 136 @table @code | |
| 137 | |
| 138 @item lisp-directory | |
| 139 @vindex lisp-directory | |
| 140 Contains the version-specific location of the Lisp files that come with | |
| 141 the core distribution of XEmacs. XEmacs will search it recursively to a | |
| 142 depth of 1 when setting up @code{load-path}. | |
| 143 | |
| 144 @item load-path | |
| 145 @vindex load-path | |
| 146 Is where XEmacs searches for XEmacs Lisp files with commands like | |
| 147 @code{load-library}. | |
| 148 @findex load-library | |
| 149 It contains the package lisp directories (see further down) and the | |
| 150 version-specific core Lisp directories. If the environment variable | |
| 151 @code{EMACSLOADPATH} is set at startup, its directories are prepended to | |
| 152 @code{load-path}. | |
| 153 @vindex EMACSLOADPATH | |
| 154 | |
| 155 @item Info-directory-list | |
| 156 @vindex Info-directory-list | |
| 157 Contains the location of info files. (See @ref{(info)}.) It contains | |
| 158 the package info directories and the version-specific core | |
| 159 documentation. Moreover, XEmacs will add @file{/usr/info}, | |
| 160 @file{/usr/local/info} as well as the directories of the environment | |
| 161 variable @code{INFOPATH} | |
| 162 @vindex INFOPATH | |
| 163 to @code{Info-directory-list}. | |
| 164 | |
| 165 @item exec-directory | |
| 166 @vindex exec-directory | |
| 167 Is the directory of architecture-dependent files that come with XEmacs, | |
| 168 especially executable programs intended for XEmacs to invoke. | |
| 169 | |
| 170 @item exec-path | |
| 171 @vindex exec-path | |
| 172 Is the path for executables which XEmacs may want to start. It contains | |
| 173 the package executable paths as well as @code{exec-directory}, and the | |
| 174 directories of the environment variables @code{PATH} | |
| 175 @vindex PATH | |
| 176 and @code{EMACSPATH}. | |
| 177 @vindex EMACSPATH | |
| 178 | |
| 179 @item doc-directory | |
| 180 @vindex doc-directory | |
| 181 Is the directory containing the architecture-specific @file{DOC} file | |
| 182 that contains documentation for XEmacs' commands. | |
| 183 | |
| 184 @item data-directory | |
| 185 @vindex data-directory | |
| 186 Is the version-specific directory that contains core data files XEmacs uses. | |
| 187 It may be initialized from the @code{EMACSDATA} | |
| 188 @vindex EMACSDATA | |
| 189 environment variable. | |
| 190 | |
| 191 @item data-directory-list | |
| 192 @vindex data-directory-list | |
| 193 Is the path where XEmacs looks for data files. It contains package data | |
| 194 directories as well as @code{data-directory}. | |
| 195 | |
| 196 @end table | |
| 197 | |
| 198 |