Commit d15aac68 authored by Chong Yidong's avatar Chong Yidong

Copyedits for Internals and OS chapters of Lisp manual.

* doc/lispref/internals.texi (Building Emacs, Garbage Collection): Copyedits.
(Writing Emacs Primitives): Re-organize discussion of functions
with variable Lisp arguments are handled.  Delete an obsolete
remark, previously tagged as FIXME.

* doc/lispref/os.texi (Idle Timers): Minor clarification.
(Idle Timers): Link to Time of Day for description of time list.
parent 4c5779ab
......@@ -203,8 +203,7 @@ hash.texi cyd
help.texi cyd
hooks.texi rgm
index.texi
internals.texi rgm (I don't know much about this, so it would be
good if someone else could at least look at the FIXME? comments.)
internals.texi rgm cyd
intro.texi cyd
keymaps.texi cyd
lists.texi cyd
......@@ -217,7 +216,7 @@ modes.texi cyd
nonascii.texi cyd
numbers.texi cyd
objects.texi cyd
os.texi
os.texi cyd
package.texi rgm
positions.texi cyd
processes.texi
......
2012-03-18 Chong Yidong <cyd@gnu.org>
* internals.texi (Building Emacs, Garbage Collection): Copyedits.
(Writing Emacs Primitives): Re-organize discussion of functions
with variable Lisp arguments are handled. Delete an obsolete
remark, previously tagged as FIXME.
* os.texi (Idle Timers): Minor clarification.
(Idle Timers): Link to Time of Day for description of time list.
2012-03-18 Glenn Morris <rgm@gnu.org>
* os.texi (System Interface): Flow control was removed.
......
......@@ -28,42 +28,39 @@ internal aspects of GNU Emacs that may be of interest to C programmers.
This section explains the steps involved in building the Emacs
executable. You don't have to know this material to build and install
Emacs, since the makefiles do all these things automatically. This
information is pertinent to Emacs maintenance.
information is pertinent to Emacs developers.
Compilation of the C source files in the @file{src} directory
produces an executable file called @file{temacs}, also called a
@dfn{bare impure Emacs}. It contains the Emacs Lisp interpreter and I/O
routines, but not the editing commands.
@dfn{bare impure Emacs}. It contains the Emacs Lisp interpreter and
I/O routines, but not the editing commands.
@cindex @file{loadup.el}
The command @w{@samp{temacs -l loadup}} uses @file{temacs} to create
the real runnable Emacs executable. These arguments direct
@file{temacs} to evaluate the Lisp files specified in the file
@file{loadup.el}. These files set up the normal Emacs editing
environment, resulting in an Emacs that is still impure but no longer
bare.
The command @w{@command{temacs -l loadup}} would run @file{temacs}
and direct it to load @file{loadup.el}. The @code{loadup} library
loads additional Lisp libraries, which set up the normal Emacs editing
environment. After this step, the Emacs executable is no longer
@dfn{bare}.
@cindex dumping Emacs
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
load the files. This is the Emacs executable that is normally
installed.
Because it takes some time to load the standard Lisp files, the
@file{temacs} executable usually isn't run directly by users.
Instead, as one of the last steps of building Emacs, the command
@samp{temacs -batch -l loadup dump} is run. The special @samp{dump}
argument causes @command{temacs} to dump out an executable program,
called @file{emacs}, which has all the standard Lisp files preloaded.
(The @samp{-batch} argument prevents @file{temacs} from trying to
initialize any of its data on the terminal, so that the tables of
terminal information are empty in the dumped Emacs.)
@cindex preloaded Lisp files
@vindex preloaded-file-list
@cindex dumped Lisp files
To create @file{emacs}, use the command @samp{temacs -batch -l loadup
dump}. The purpose of @samp{-batch} here is to prevent @file{temacs}
from trying to initialize any of its data on the terminal; this ensures
that the tables of terminal information are empty in the dumped Emacs.
The argument @samp{dump} tells @file{loadup.el} to dump a new executable
named @file{emacs}. The variable @code{preloaded-file-list} stores a
list of the Lisp files that were dumped with the @file{emacs} executable.
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.
The dumped @file{emacs} executable (also called a @dfn{pure} Emacs)
is the one which is installed. The variable
@code{preloaded-file-list} stores a list of the Lisp files preloaded
into the dumped Emacs. 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
......@@ -163,7 +160,7 @@ all the new data created during an Emacs session are kept
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
Pure storage is allocated only while @command{temacs} is loading the
standard preloaded Lisp libraries. In the file @file{emacs}, it is
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
......@@ -214,31 +211,27 @@ You should not change this flag in a running Emacs.
@node Garbage Collection
@section Garbage Collection
@cindex garbage collection
@cindex memory allocation
When a program creates a list or the user defines a new function (such
as by loading a library), that data is placed in normal storage. If
normal storage runs low, then Emacs asks the operating system to
allocate more memory in blocks of 1k bytes. Each block is used for one
type of Lisp object, so symbols, cons cells, markers, etc., are
segregated in distinct blocks in memory. (Vectors, long strings,
buffers and certain other editing types, which are fairly large, are
allocated in individual blocks, one per object, while small strings are
packed into blocks of 8k bytes.)
It is quite common to use some storage for a while, then release it by
(for example) killing a buffer or deleting the last pointer to an
object. Emacs provides a @dfn{garbage collector} to reclaim this
abandoned storage. (This name is traditional, but ``garbage recycler''
might be a more intuitive metaphor for this facility.)
When a program creates a list or the user defines a new function
(such as by loading a library), that data is placed in normal storage.
If normal storage runs low, then Emacs asks the operating system to
allocate more memory. Different types of Lisp objects, such as
symbols, cons cells, markers, etc., are segregated in distinct blocks
in memory. (Vectors, long strings, buffers and certain other editing
types, which are fairly large, are allocated in individual blocks, one
per object, while small strings are packed into blocks of 8k bytes.)
The garbage collector operates by finding and marking all Lisp objects
that are still accessible to Lisp programs. To begin with, it assumes
all the symbols, their values and associated function definitions, and
any data presently on the stack, are accessible. Any objects that can
be reached indirectly through other accessible objects are also
accessible.
@cindex garbage collection
It is quite common to use some storage for a while, then release it
by (for example) killing a buffer or deleting the last pointer to an
object. Emacs provides a @dfn{garbage collector} to reclaim this
abandoned storage. The garbage collector operates by finding and
marking all Lisp objects that are still accessible to Lisp programs.
To begin with, it assumes all the symbols, their values and associated
function definitions, and any data presently on the stack, are
accessible. Any objects that can be reached indirectly through other
accessible objects are also accessible.
When marking is finished, all objects still unmarked are garbage. No
matter what the Lisp program or the user does, it is impossible to refer
......@@ -336,11 +329,9 @@ The total size of all strings, in characters.
The total number of elements of existing vectors.
@item used-floats
@c Emacs 19 feature
The number of floats in use.
@item free-floats
@c Emacs 19 feature
The number of floats for which space has been obtained from the
operating system, but that are not currently being used.
......@@ -417,7 +408,6 @@ memory used by Lisp data, broken down by data type. By contrast, the
function @code{memory-limit} provides information on the total amount of
memory Emacs is currently using.
@c Emacs 19 feature
@defun memory-limit
This function returns the address of the last byte Emacs has allocated,
divided by 1024. We divide the value by 1024 to make sure it fits in a
......@@ -428,7 +418,7 @@ memory usage.
@end defun
@defvar memory-full
This variable is @code{t} if Emacs is close to out of memory for Lisp
This variable is @code{t} if Emacs is nearly out of memory for Lisp
objects, and @code{nil} otherwise.
@end defvar
......@@ -519,8 +509,9 @@ appearance.)
@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
......@@ -566,14 +557,11 @@ This is the name of the Lisp symbol to define as the function name; in
the example above, it is @code{or}.
@item fname
This is the C function name for this function. This is
the name that is used in C code for calling the function. The name is,
by convention, @samp{F} prepended to the Lisp name, with all dashes
(@samp{-}) in the Lisp name changed to underscores. Thus, to call this
function from C code, call @code{For}. Remember that the arguments must
be of type @code{Lisp_Object}; various macros and functions for creating
values of type @code{Lisp_Object} are declared in the file
@file{lisp.h}.
This is the C function name for this function. This is the name that
is used in C code for calling the function. The name is, by
convention, @samp{F} prepended to the Lisp name, with all dashes
(@samp{-}) in the Lisp name changed to underscores. Thus, to call
this function from C code, call @code{For}.
@item sname
This is a C variable name to use for a structure that holds the data for
......@@ -627,38 +615,35 @@ too.
@end table
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 *}}.
argument list for the C function, including the types for the
arguments. If the primitive accepts a fixed maximum number of Lisp
arguments, there must be one C argument for each Lisp argument, and
each argument must be of type @code{Lisp_Object}. (Various macros and
functions for creating values of type @code{Lisp_Object} are declared
in the file @file{lisp.h}.) If the primitive has no upper limit on
the number of Lisp arguments, it must have exactly two C arguments:
the first is the number of Lisp arguments, and the second is the
address of a block containing their values. These have types
@code{int} and @w{@code{Lisp_Object *}} respectively.
@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. GC protection is necessary whenever you call
@code{eval_sub} (or @code{Feval}) either directly or indirectly.
At such a time, any Lisp object that this function may refer to again
must be protected somehow.
@code{GCPRO1} and @code{UNGCPRO}. These macros are defined for the
sake of the few platforms which do not use Emacs' default
stack-marking garbage collector. The @code{GCPRO1} macro ``protects''
a variable from garbage collection, explicitly informing the garbage
collector that that variable and all its contents must be as
accessible. GC protection is necessary in any function which can
perform Lisp evaluation by calling @code{eval_sub} or @code{Feval} as
a subroutine, either directly or indirectly.
It suffices to ensure that at least one pointer to each object is
GC-protected; that way, the object cannot be recycled, so all pointers
to it remain valid. Thus, a particular local variable can do without
GC-protected. 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 that
has a @code{GCPRO}).
@ignore
@footnote{Formerly, strings were a special exception; in older Emacs
versions, every local variable that might point to a string needed a
@code{GCPRO}.}.
@end ignore
Otherwise, the local variable needs a @code{GCPRO}.
has 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 variables, use @code{GCPRO2} instead; repeating
......@@ -667,34 +652,17 @@ want to protect two variables, use @code{GCPRO2} instead; repeating
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
arguments. This C vector may be part of a Lisp vector, but it need
not be. The responsibility for using @code{GCPRO} to protect the Lisp
arguments from GC if necessary rests with the caller in this case,
since the caller allocated or found the storage for them.
You must not use C initializers for static or global variables unless
the variables are never written once Emacs is dumped. These variables
with initializers are allocated in an area of memory that becomes
read-only (on certain operating systems) as a result of dumping Emacs.
@xref{Pure Storage}.
@c FIXME is this still true? I don't think so...
Do not use static variables within functions---place all static
variables at top level in the file. This is necessary because Emacs on
some operating systems defines the keyword @code{static} as a null
macro. (This definition is used because those systems put all variables
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
......
......@@ -1760,9 +1760,9 @@ certain length of time. Aside from how to set them up, idle timers
work just like ordinary timers.
@deffn Command run-with-idle-timer secs repeat function &rest args
Set up a timer which runs when Emacs has been idle for @var{secs}
seconds. The value of @var{secs} may be an integer or a floating point
number; a value of the type returned by @code{current-idle-time}
Set up a timer which runs the next time Emacs is idle for @var{secs}
seconds. The value of @var{secs} may be an integer or a floating
point number; a value of the type returned by @code{current-idle-time}
is also allowed.
If @var{repeat} is @code{nil}, the timer runs just once, the first time
......@@ -1775,13 +1775,13 @@ can use in calling @code{cancel-timer} (@pxref{Timers}).
@end deffn
@cindex idleness
Emacs becomes ``idle'' when it starts waiting for user input, and it
remains idle until the user provides some input. If a timer is set for
five seconds of idleness, it runs approximately five seconds after Emacs
first becomes idle. Even if @var{repeat} is non-@code{nil}, this timer
will not run again as long as Emacs remains idle, because the duration
of idleness will continue to increase and will not go down to five
seconds again.
Emacs becomes @dfn{idle} when it starts waiting for user input, and
it remains idle until the user provides some input. If a timer is set
for five seconds of idleness, it runs approximately five seconds after
Emacs first becomes idle. Even if @var{repeat} is non-@code{nil},
this timer will not run again as long as Emacs remains idle, because
the duration of idleness will continue to increase and will not go
down to five seconds again.
Emacs can do various things while idle: garbage collect, autosave or
handle data from a subprocess. But these interludes during idleness do
......@@ -1795,22 +1795,12 @@ minutes, and even if there have been garbage collections and autosaves.
input. Then it becomes idle again, and all the idle timers that are
set up to repeat will subsequently run another time, one by one.
@c Emacs 19 feature
@defun current-idle-time
If Emacs is idle, this function returns the length of time Emacs has
been idle, as a list of three integers: @code{(@var{high} @var{low}
@var{microsec})}. The integers @var{high} and @var{low} combine to
give the number of seconds of idleness, which is
@ifnottex
@var{high} * 2**16 + @var{low}.
@end ifnottex
@tex
$high*2^{16}+low$.
@end tex
The third element, @var{microsec}, gives the microseconds since the
start of the current second (or 0 for systems that return time with
the resolution of only one second).
been idle, as a list of three integers: @code{(@var{sec-high}
@var{sec-low} @var{microsec})}, where @var{high} and @var{low} are the
high and low bits for the number of seconds and @var{microsec} is the
additional number of microseconds (@pxref{Time of Day}).
When Emacs is not idle, @code{current-idle-time} returns @code{nil}.
This is a convenient way to test whether Emacs is idle.
......@@ -1843,9 +1833,9 @@ Here's an example:
@end smallexample
@end defun
Some idle timer functions in user Lisp packages have a loop that
does a certain amount of processing each time around, and exits when
@code{(input-pending-p)} is non-@code{nil}. That approach seems very
Do not write an idle timer function containing a loop which does a
certain amount of processing each time around, and exits when
@code{(input-pending-p)} is non-@code{nil}. This approach seems very
natural but has two problems:
@itemize
......@@ -1858,9 +1848,9 @@ It blocks out any idle timers that ought to run during that time.
@end itemize
@noindent
To avoid these problems, don't use that technique. Instead, write
such idle timers to reschedule themselves after a brief pause, using
the method in the @code{timer-function} example above.
The correct approach is for the idle timer to reschedule itself after
a brief pause, using the method in the @code{timer-function} example
above.
@node Terminal Input
@section Terminal Input
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment