Mercurial > hg > xemacs-beta
annotate man/lispref/internationalization.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 | 03ab78e48ef6 |
| children | 62b9ef1ed4ac |
| rev | line source |
|---|---|
| 428 | 1 @c -*-texinfo-*- |
| 2 @c This is part of the XEmacs Lisp Reference Manual. | |
| 444 | 3 @c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc. |
| 428 | 4 @c See the file lispref.texi for copying conditions. |
| 5 @setfilename ../../info/internationalization.info | |
| 442 | 6 @node Internationalization, MULE, PostgreSQL Support, top |
| 428 | 7 @chapter Internationalization |
| 8 | |
| 9 @menu | |
| 10 * I18N Levels 1 and 2:: Support for different time, date, and currency formats. | |
| 11 * I18N Level 3:: Support for localized messages. | |
| 12 * I18N Level 4:: Support for Asian languages. | |
| 13 @end menu | |
| 14 | |
| 15 | |
| 16 @node I18N Levels 1 and 2 | |
| 17 @section I18N Levels 1 and 2 | |
| 18 | |
| 19 XEmacs is now compliant with I18N levels 1 and 2. Specifically, this means | |
| 20 that it is 8-bit clean and correctly handles time and date functions. XEmacs | |
| 21 will correctly display the entire ISO-Latin 1 character set. | |
| 22 | |
| 23 The compose key may now be used to create any character in the ISO-Latin 1 | |
| 24 character set not directly available via the keyboard.. In order for the | |
| 25 compose key to work it is necessary to load the file @file{x-compose.el}. | |
| 26 At any time while composing a character, @code{C-h} will display all valid | |
| 27 completions and the character which would be produced. | |
| 28 | |
| 29 | |
| 30 @node I18N Level 3 | |
| 31 @section I18N Level 3 | |
| 32 | |
| 33 @menu | |
| 34 * Level 3 Basics:: | |
| 35 * Level 3 Primitives:: | |
| 36 * Dynamic Messaging:: | |
| 37 * Domain Specification:: | |
| 38 @end menu | |
| 39 | |
| 40 @node Level 3 Basics | |
| 41 @subsection Level 3 Basics | |
| 42 | |
| 43 XEmacs now provides alpha-level functionality for I18N Level 3. This means | |
| 44 that everything necessary for full messaging is available, but not every | |
| 45 file has been converted. | |
| 46 | |
| 47 The two message files which have been created are @file{src/emacs.po} and | |
| 48 @file{lisp/packages/mh-e.po}. Both files need to be converted using | |
| 49 @code{msgfmt}, and the resulting @file{.mo} files placed in some locale's | |
| 50 @code{LC_MESSAGES} directory. The test ``translations'' in these files are | |
| 51 the original messages prefixed by @code{TRNSLT_}. | |
| 52 | |
| 53 The domain for a variable is stored on the variable's property list under | |
| 54 the property name @var{variable-domain}. The function | |
| 55 @code{documentation-property} uses this information when translating a | |
| 56 variable's documentation. | |
| 57 | |
| 58 | |
| 59 @node Level 3 Primitives | |
| 60 @subsection Level 3 Primitives | |
| 61 | |
| 62 @defun gettext string | |
| 63 This function looks up @var{string} in the default message domain and | |
| 64 returns its translation. If @code{I18N3} was not enabled when XEmacs was | |
| 65 compiled, it just returns @var{string}. | |
| 66 @end defun | |
| 67 | |
| 68 @defun dgettext domain string | |
| 69 This function looks up @var{string} in the specified message domain and | |
| 70 returns its translation. If @code{I18N3} was not enabled when XEmacs was | |
| 71 compiled, it just returns @var{string}. | |
| 72 @end defun | |
| 73 | |
| 74 @defun bind-text-domain domain pathname | |
| 75 This function associates a pathname with a message domain. | |
| 76 Here's how the path to message file is constructed under SunOS 5.x: | |
| 77 | |
| 78 @example | |
| 79 @code{@{pathname@}/@{LANG@}/LC_MESSAGES/@{domain@}.mo} | |
| 80 @end example | |
| 81 | |
| 82 If @code{I18N3} was not enabled when XEmacs was compiled, this function does | |
| 83 nothing. | |
| 84 @end defun | |
| 85 | |
| 86 @defspec domain string | |
| 87 This function specifies the text domain used for translating documentation | |
| 88 strings and interactive prompts of a function. For example, write: | |
| 89 | |
| 90 @example | |
| 91 (defun foo (arg) "Doc string" (domain "emacs-foo") @dots{}) | |
| 92 @end example | |
| 93 | |
| 94 to specify @code{emacs-foo} as the text domain of the function @code{foo}. | |
| 95 The ``call'' to @code{domain} is actually a declaration rather than a | |
| 96 function; when actually called, @code{domain} just returns @code{nil}. | |
| 97 @end defspec | |
| 98 | |
| 99 @defun domain-of function | |
| 100 This function returns the text domain of @var{function}; it returns | |
| 101 @code{nil} if it is the default domain. If @code{I18N3} was not enabled | |
| 102 when XEmacs was compiled, it always returns @code{nil}. | |
| 103 @end defun | |
| 104 | |
| 105 | |
| 106 @node Dynamic Messaging | |
| 107 @subsection Dynamic Messaging | |
| 108 | |
| 109 The @code{format} function has been extended to permit you to change the | |
| 110 order of parameter insertion. For example, the conversion format | |
| 111 @code{%1$s} inserts parameter one as a string, while @code{%2$s} inserts | |
| 112 parameter two. This is useful when creating translations which require you | |
| 113 to change the word order. | |
| 114 | |
| 115 | |
| 116 @node Domain Specification | |
| 117 @subsection Domain Specification | |
| 118 | |
| 119 The default message domain of XEmacs is `emacs'. For add-on packages, it is | |
| 120 best to use a different domain. For example, let us say we want to convert | |
| 121 the ``gorilla'' package to use the domain `emacs-gorilla'. | |
| 122 To translate the message ``What gorilla?'', use @code{dgettext} as follows: | |
| 123 | |
| 124 @example | |
| 125 (dgettext "emacs-gorilla" "What gorilla?") | |
| 126 @end example | |
| 127 | |
| 128 A function (or macro) which has a documentation string or an interactive | |
| 129 prompt needs to be associated with the domain in order for the documentation | |
| 130 or prompt to be translated. This is done with the @code{domain} special | |
| 131 form as follows: | |
| 132 | |
| 133 @page | |
| 134 @example | |
| 135 (defun scratch (location) | |
| 136 "Scratch the specified location." | |
| 137 (domain "emacs-gorilla") | |
| 138 (interactive "sScratch: ") | |
| 139 @dots{} ) | |
| 140 @end example | |
| 141 | |
| 142 It is most efficient to specify the domain in the first line of the | |
| 143 function body, before the @code{interactive} form. | |
| 144 | |
| 145 For variables and constants which have documentation strings, specify the | |
| 146 domain after the documentation. | |
| 147 | |
| 148 @defspec defvar symbol [value [doc-string [domain]]] | |
| 149 Example: | |
| 150 @example | |
| 151 (defvar weight 250 "Weight of gorilla, in pounds." "emacs-gorilla") | |
| 152 @end example | |
| 153 @end defspec | |
| 154 | |
| 155 @defspec defconst symbol [value [doc-string [domain]]] | |
| 156 Example: | |
| 157 @example | |
| 158 (defconst limbs 4 "Number of limbs" "emacs-gorilla") | |
| 159 @end example | |
| 160 @end defspec | |
| 161 | |
| 444 | 162 @defun autoload function filename &optional docstring interactive type |
| 163 This function defines @var{function} to autoload from @var{filename} | |
| 428 | 164 Example: |
| 165 @example | |
| 166 (autoload 'explore "jungle" "Explore the jungle." nil nil "emacs-gorilla") | |
| 167 @end example | |
| 168 @end defun | |
| 169 | |
| 170 @node I18N Level 4 | |
| 171 @section I18N Level 4 | |
| 172 | |
| 173 The Asian-language support in XEmacs is called ``MULE''. @xref{MULE}. |