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.
This commit is contained in:
Chong Yidong
parent
4c5779ab90
commit
d15aac6820
4 changed files with 104 additions and 137 deletions
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -1,3 +1,13 @@
|
|||
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.)
|
||||
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.)
|
||||
|
||||
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
|
||||
@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. (This name is traditional, but ``garbage recycler''
|
||||
might be a more intuitive metaphor for this facility.)
|
||||
|
||||
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.
|
||||
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
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue