@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1998, 1999, 2002, 2003, 2004,
-@c 2005 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1998, 1999, 2001, 2002, 2003,
+@c 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/internals
@node GNU Emacs Internals, Standard Errors, Tips, Top
environment, resulting in an Emacs that is still impure but no longer
bare.
+@cindex dumping Emacs
It takes a substantial 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
Snarf-documentation,, Accessing Documentation}).
@cindex @file{site-init.el}
+@cindex preloading additional functions and variables
You can specify other Lisp expressions to execute just before dumping
by putting them in a library named @file{site-init.el}. This file is
executed after the documentation strings are found.
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}:
+
+@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
+
@defun dump-emacs to-file from-file
@cindex unexec
This function dumps the current state of Emacs into an executable file
marked as read-only (on operating systems that permit this), so that
the memory space can be shared by all the Emacs jobs running on the
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} crashes. If that happens, you must
-increase the compilation parameter @code{PURESIZE} in the file
-@file{src/puresize.h}. This normally won't happen unless you try to
-preload additional libraries or add features to the standard ones.
+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.
@defun purecopy object
This function makes a copy in pure storage of @var{object}, and returns
object consists of a header and the storage for the string text
itself; the latter is only allocated when the string is created.)
@end table
+
+If there was overflow in pure space (see the previous section),
+@code{garbage-collect} returns @code{nil}, because a real garbage
+collection can not be done in this situation.
@end deffn
@defopt garbage-collection-messages
memory usage.
@end defun
+@defvar memory-full
+This variable is @code{t} if Emacs is close to out of memory for Lisp
+objects, and @code{nil} otherwise.
+@end defvar
+
@defun memory-use-counts
This returns a list of numbers that count the number of objects
created in this Emacs session. Each of these counters increments for
@node Writing Emacs Primitives
@appendixsec Writing Emacs Primitives
@cindex primitive function internals
+@cindex writing Emacs primitives
Lisp primitives are Lisp functions implemented in C. The details of
interfacing the C function so that Lisp can call it are handled by a few
@smallexample
@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.
+ doc: /* Eval args until one of them yields non-nil, then return that
+value. The remaining args are not evalled at all.
If all args return nil, return nil.
@end group
@group
@end group
@end smallexample
+@cindex @code{DEFUN}, C macro to define Lisp primitives
Let's start with a precise explanation of the arguments to the
@code{DEFUN} macro. Here is a template for them:
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
Within the function @code{For} itself, note the use of the macros
-@code{GCPRO1} and @code{UNGCPRO}. @code{GCPRO1} is used to ``protect''
-a variable from garbage collection---to inform the garbage collector that
-it must look in that variable and regard its contents as an accessible
-object. This is necessary whenever you call @code{Feval} or anything
-that can directly or indirectly call @code{Feval}. At such a time, any
-Lisp object that you intend to refer to again must be protected somehow.
-@code{UNGCPRO} cancels the protection of the variables that are
-protected in the current function. It is necessary to do this explicitly.
+@code{GCPRO1} and @code{UNGCPRO}. @code{GCPRO1} is used to
+``protect'' a variable from garbage collection---to inform the garbage
+collector that it must look in that variable and regard its contents
+as an accessible object. GC protection is necessary whenever you call
+@code{Feval} or anything that can directly or indirectly call
+@code{Feval}. At such a time, any Lisp object that this function may
+refer to again must be protected somehow.
It suffices to ensure that at least one pointer to each object is
-GC-protected; as long as the object is not recycled, all pointers to
-it remain valid. So if you are sure that a local variable points to
-an object that will be preserved by some other pointer, that local
-variable does not need a @code{GCPRO}. (Formerly, strings were an
-exception to this rule; in older Emacs versions, every pointer to a
-string needed to be marked by GC.)
+GC-protected; that way, the object cannot be recycled, so all pointers
+to it remain valid. Thus, a particular local variable can do without
+protection if it is certain that the object it points to will be
+preserved by some other pointer (such as another local variable which
+has a @code{GCPRO})@footnote{Formerly, strings were a special
+exception; in older Emacs versions, every local variable that might
+point to a string needed a @code{GCPRO}.}. Otherwise, the local
+variable needs a @code{GCPRO}.
The macro @code{GCPRO1} protects just one local variable. If you
-want to protect two, use @code{GCPRO2} instead; repeating
-@code{GCPRO1} will not work. Macros, @code{GCPRO3}, @code{GCPRO4},
-@code{GCPRO5}, and @code{GCPRO6} also exist. These macros implicitly
-use local variables such as @code{gcpro1}; you must declare these
-explicitly, with type @code{struct gcpro}. Thus, if you use
+want to protect two variables, use @code{GCPRO2} instead; repeating
+@code{GCPRO1} will not work. Macros @code{GCPRO3}, @code{GCPRO4},
+@code{GCPRO5}, and @code{GCPRO6} also exist. All these macros
+implicitly use local variables such as @code{gcpro1}; you must declare
+these explicitly, with type @code{struct gcpro}. Thus, if you use
@code{GCPRO2}, you must declare @code{gcpro1} and @code{gcpro2}.
Alas, we can't explain all the tricky details here.
+ @code{UNGCPRO} cancels the protection of the variables that are
+protected in the current function. It is necessary to do this
+explicitly.
+
Built-in functions that take a variable number of arguments actually
accept two arguments at the C level: the number of Lisp arguments, and
a @code{Lisp_Object *} pointer to a C vector containing those Lisp
declared static in a place that becomes read-only after dumping, whether
they have initializers or not.)
+@cindex @code{defsubr}, Lisp symbol for a primitive
Defining the C function is not enough to make a Lisp primitive
available; you must also create the Lisp symbol for the primitive and
store a suitable subr object in its function cell. The code looks like
@anchor{Defining Lisp variables in C}
@vindex byte-boolean-vars
+@cindex defining Lisp variables in C
+@cindex @code{DEFVAR_INT}, @code{DEFVAR_LISP}, @code{DEFVAR_BOOL}
The function @code{syms_of_@var{filename}} is also the place to define
any C variables that are to be visible as Lisp variables.
@code{DEFVAR_LISP} makes a C variable of type @code{Lisp_Object} visible
defined with @code{DEFVAR_BOOL} are automatically added to the list
@code{byte-boolean-vars} used by the byte compiler.
+@cindex @code{staticpro}, protect file-scope variables from GC
If you define a file-scope C variable of type @code{Lisp_Object},
you must protect it from garbage-collection by calling @code{staticpro}
in @code{syms_of_@var{filename}}, like this:
is @code{nil}, no mode line will be displayed.
@item header_line_format
-This field is analoguous to @code{mode_line_format} for the mode
+This field is analogous to @code{mode_line_format} for the mode
line displayed at the top of windows.
@item keymap
when it was chosen.
@item too_small_ok
-Non-@code{nil} means don't delete this window for becoming ``too small''.
+Non-@code{nil} means don't delete this window for becoming ``too small.''
@item height_fixed_p
This field is temporarily set to 1 to fix the height of the selected
HCoop / bpt / emacs.git / blobdiff