@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1998, 1999, 2001, 2002, 2003,
-@c 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1993, 1998-1999, 2001-2012 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/internals
@node GNU Emacs Internals, Standard Errors, Tips, Top
@menu
* Building Emacs:: How the dumped Emacs is made.
-* Pure Storage:: A kludge to make preloaded Lisp functions sharable.
+* Pure Storage:: Kludge to make preloaded Lisp functions shareable.
* Garbage Collection:: Reclaiming space for Lisp objects no longer used.
* Memory Usage:: Info about total size of Lisp objects made so far.
* Writing Emacs Primitives:: Writing C code for Emacs.
@end menu
@node Building Emacs
-@appendixsec Building Emacs
+@section Building Emacs
@cindex building Emacs
@pindex temacs
bare.
@cindex dumping Emacs
- It takes a substantial time to load the standard Lisp files. Luckily,
+ It takes some time to load the standard Lisp files. Luckily,
you don't have to do this each time you run Emacs; @file{temacs} can
dump out an executable program called @file{emacs} that has these files
preloaded. @file{emacs} starts more quickly because it does not need to
named @file{emacs}. The variable @code{preloaded-file-list} stores a
list of the Lisp files that were dumped with the @file{emacs} executable.
- Some operating systems don't support dumping. On those systems, you
-must start Emacs with the @samp{temacs -l loadup} command each time you
-use it. This takes a substantial time, but since you need to start
-Emacs once a day at most---or once a week if you never log out---the
-extra time is not too severe a problem.
+ If you port Emacs to a new operating system, and are not able to
+implement dumping, then Emacs must load @file{loadup.el} each time it
+starts.
@cindex @file{site-load.el}
-
You can specify additional files to preload by writing a library named
-@file{site-load.el} that loads them. You may need to add a definition
+@file{site-load.el} that loads them. You may need to rebuild Emacs
+with an added definition
@example
#define SITELOAD_PURESIZE_EXTRA @var{n}
@end example
@noindent
-to make @var{n} added bytes of pure space to hold the additional files.
+to make @var{n} added bytes of pure space to hold the additional files;
+see @file{src/puresize.h}.
(Try adding increments of 20000 until it is big enough.) However, the
advantage of preloading additional files decreases as machines get
faster. On modern machines, it is usually not advisable.
installation directory for Lisp files when you install Emacs.
@item
-Specify a non-@code{nil} value for
-@code{byte-compile-dynamic-docstrings} as a local variable in each of these
-files, and load them with either @file{site-load.el} or
-@file{site-init.el}. (This method has the drawback that the
-documentation strings take up space in Emacs all the time.)
+Specify a @code{nil} value for @code{byte-compile-dynamic-docstrings}
+as a local variable in each of these files, and load them with either
+@file{site-load.el} or @file{site-init.el}. (This method has the
+drawback that the documentation strings take up space in Emacs all the
+time.)
@end itemize
It is not advisable to put anything in @file{site-load.el} or
normal features for your site, do it with @file{default.el}, so that
users can override your changes if they wish. @xref{Startup Summary}.
- In a package that can be preloaded, it is sometimes useful to
-specify a computation to be done when Emacs subsequently starts up.
-For this, use @code{eval-at-startup}:
+ In a package that can be preloaded, it is sometimes necessary (or
+useful) to delay certain evaluations until Emacs subsequently starts
+up. The vast majority of such cases relate to the values of
+customizable variables. For example, @code{tutorial-directory} is a
+variable defined in @file{startup.el}, which is preloaded. The default
+value is set based on @code{data-directory}. The variable needs to
+access the value of @code{data-directory} when Emacs starts, not when
+it is dumped, because the Emacs executable has probably been installed
+in a different location since it was dumped.
+
+@defun custom-initialize-delay symbol value
+This function delays the initialization of @var{symbol} to the next
+Emacs start. You normally use this function by specifying it as the
+@code{:initialize} property of a customizable variable. (The argument
+@var{value} is unused, and is provided only for compatiblity with the
+form Custom expects.)
+@end defun
-@defmac eval-at-startup body@dots{}
-This evaluates the @var{body} forms, either immediately if running in
-an Emacs that has already started up, or later when Emacs does start
-up. Since the value of the @var{body} forms is not necessarily
-available when the @code{eval-at-startup} form is run, that form
-always returns @code{nil}.
-@end defmac
+In the unlikely event that you need a more general functionality than
+@code{custom-initialize-delay} provides, you can use
+@code{before-init-hook} (@pxref{Startup Summary}).
@defun dump-emacs to-file from-file
@cindex unexec
@end defun
@node Pure Storage
-@appendixsec Pure Storage
+@section Pure Storage
@cindex pure storage
Emacs Lisp uses two kinds of storage for user-created Lisp objects:
@dfn{normal storage} and @dfn{pure storage}. Normal storage is where
-all the new data created during an Emacs session are kept; see the
-following section for information on normal storage. Pure storage is
-used for certain data in the preloaded standard Lisp files---data that
-should never change during actual use of Emacs.
+all the new data created during an Emacs session are kept
+(@pxref{Garbage Collection}). Pure storage is used for certain data
+in the preloaded standard Lisp files---data that should never change
+during actual use of Emacs.
Pure storage is allocated only while @file{temacs} is loading the
standard preloaded Lisp libraries. In the file @file{emacs}, it is
machine at once. Pure storage is not expandable; a fixed amount is
allocated when Emacs is compiled, and if that is not sufficient for
the preloaded libraries, @file{temacs} allocates dynamic memory for
-the part that didn't fit. If that happens, you should increase the
-compilation parameter @code{PURESIZE} in the file
-@file{src/puresize.h} and rebuild Emacs, even though the resulting
-image will work: garbage collection is disabled in this situation,
-causing a memory leak. Such an overflow normally won't happen unless you
-try to preload additional libraries or add features to the standard
-ones. Emacs will display a warning about the overflow when it
-starts.
+the part that didn't fit. The resulting image will work, but garbage
+collection (@pxref{Garbage Collection}) is disabled in this situation,
+causing a memory leak. Such an overflow normally won't happen unless
+you try to preload additional libraries or add features to the
+standard ones. Emacs will display a warning about the overflow when
+it starts. If this happens, you should increase the compilation
+parameter @code{SYSTEM_PURESIZE_EXTRA} in the file
+@file{src/puresize.h} and rebuild Emacs.
@defun purecopy object
This function makes a copy in pure storage of @var{object}, and returns
them unchanged. It signals an error if asked to copy markers.
This function is a no-op except while Emacs is being built and dumped;
-it is usually called only in the file @file{emacs/lisp/loaddefs.el}, but
-a few packages call it just in case you decide to preload them.
+it is usually called only in preloaded Lisp files.
@end defun
@defvar pure-bytes-used
function definition is copied into pure storage.
This flag is @code{t} while loading all of the basic functions for
-building Emacs initially (allowing those functions to be sharable and
+building Emacs initially (allowing those functions to be shareable and
non-collectible). Dumping Emacs as an executable always writes
@code{nil} in this variable, regardless of the value it actually has
before and after dumping.
@end defvar
@node Garbage Collection
-@appendixsec Garbage Collection
+@section Garbage Collection
@cindex garbage collection
@cindex memory allocation
itself; the latter is only allocated when the string is created.)
@end table
-If there was overflow in pure space (see the previous section),
+If there was overflow in pure space (@pxref{Pure Storage}),
@code{garbage-collect} returns @code{nil}, because a real garbage
collection can not be done in this situation.
@end deffn
@defopt garbage-collection-messages
If this variable is non-@code{nil}, Emacs displays a message at the
beginning and end of garbage collection. The default value is
-@code{nil}, meaning there are no such messages.
+@code{nil}.
@end defopt
@defvar post-gc-hook
the threshold is exhausted, but only the next time the Lisp evaluator is
called.
-The initial threshold value is 400,000. If you specify a larger
+The initial threshold value is 800,000. If you specify a larger
value, garbage collection will happen less often. This reduces the
amount of time spent garbage collecting, but increases total memory use.
You may want to do this when running a program that creates lots of
@end defvar
@node Writing Emacs Primitives
-@appendixsec Writing Emacs Primitives
+@section Writing Emacs Primitives
@cindex primitive function internals
@cindex writing Emacs primitives
@group
DEFUN ("or", For, Sor, 0, UNEVALLED, 0,
doc: /* Eval args until one of them yields non-nil, then return that
-value. The remaining args are not evalled at all.
+value. The remaining args are not evalled at all.
If all args return nil, return nil.
@end group
@group
usage: (or CONDITIONS ...) */)
- (args)
- Lisp_Object args;
+ (Lisp_Object args)
@{
register Lisp_Object val = Qnil;
struct gcpro gcpro1;
too.
@end table
- After the call to the @code{DEFUN} macro, you must write the argument
-name list that every C function must have, followed by ordinary C
-declarations for the arguments. For a function with a fixed maximum
-number of arguments, declare a C argument for each Lisp argument, and
-give them all type @code{Lisp_Object}. When a Lisp function has no
-upper limit on the number of arguments, its implementation in C actually
-receives exactly two arguments: the first is the number of Lisp
-arguments, and the second is the address of a block containing their
-values. They have types @code{int} and @w{@code{Lisp_Object *}}.
+ After the call to the @code{DEFUN} macro, you must write the
+argument list that every C function must have, including the types for
+the arguments. For a function with a fixed maximum number of
+arguments, declare a C argument for each Lisp argument, and give them
+all type @code{Lisp_Object}. When a Lisp function has no upper limit
+on the number of arguments, its implementation in C actually receives
+exactly two arguments: the first is the number of Lisp arguments, and
+the second is the address of a block containing their values. They
+have types @code{int} and @w{@code{Lisp_Object *}}.
@cindex @code{GCPRO} and @code{UNGCPRO}
@cindex protect C variables from garbage collection
@group
switch (coordinates_in_window (XWINDOW (window), &x, &y))
@{
- case 0: /* NOT in window at all. */
+ case 0: /* NOT in window at all. */
return Qnil;
@end group
@group
- case 1: /* In text part of window. */
+ case 1: /* In text part of window. */
return Fcons (make_number (x), make_number (y));
@end group
@group
- case 2: /* In mode line of window. */
+ case 2: /* In mode line of window. */
return Qmode_line;
@end group
@group
- case 3: /* On right border of window. */
+ case 3: /* On right border of window. */
return Qvertical_line;
@end group
knows about it.
@node Object Internals
-@appendixsec Object Internals
+@section Object Internals
@cindex object internals
GNU Emacs Lisp manipulates many different types of data. The actual
@end menu
@node Buffer Internals
-@appendixsubsec Buffer Internals
+@subsection Buffer Internals
@cindex internals, of buffer
@cindex buffer internals
@item unchanged_modified
@itemx overlay_unchanged_modified
The values of @code{modiff} and @code{overlay_modiff}, respectively,
-after the last compelete redisplay. If their current values match
+after the last complete redisplay. If their current values match
@code{modiff} or @code{overlay_modiff}, that means
@code{beg_unchanged} and @code{end_unchanged} contain no useful
information.
buffer-local (@pxref{Buffer-Local Variables}), whose corresponding
variable names have the additional prefix @code{buffer-} and have
underscores replaced with dashes. For instance, @code{undo_list}
-stores the value of @code{buffer-undo-list}. @xref{Standard
-Buffer-Local Variables}.
+stores the value of @code{buffer-undo-list}.
@item mark
The mark for the buffer. The mark is a marker, hence it is also
buffer-local (@pxref{Buffer-Local Variables}), whose corresponding
variable names have underscores replaced with dashes. For instance,
@code{mode_line_format} stores the value of @code{mode-line-format}.
-@xref{Standard Buffer-Local Variables}.
@item last_selected_window
This is the last window that was selected with this buffer in it, or @code{nil}
@end table
@node Window Internals
-@appendixsubsec Window Internals
+@subsection Window Internals
@cindex internals, of window
@cindex window internals
@item next
@itemx prev
The next sibling and previous sibling of this window. @code{next} is
-@code{nil} if the window is the rightmost or bottommost in its group;
-@code{prev} is @code{nil} if it is the leftmost or topmost in its
+@code{nil} if the window is the right-most or bottom-most in its group;
+@code{prev} is @code{nil} if it is the left-most or top-most in its
group.
@item left_col
@end table
@node Process Internals
-@appendixsubsec Process Internals
+@subsection Process Internals
@cindex internals, of process
@cindex process internals
@code{serial}
@end table
-
-@ignore
- arch-tag: 4b2c33bc-d7e4-43f5-bc20-27c0db52a53e
-@end ignore
HCoop / bpt / emacs.git / blobdiff