mirror/emacs
1
0
Fork 0
mirror of https://git.savannah.gnu.org/git/emacs.git synced 2024-11-28 07:45:00 +00:00
Code Issues Releases Activity

(Writing Emacs Primitives): Clarify GCPRO rules.

Browse Source
This commit is contained in:
Richard M. Stallman 2006-05-11 00:59:41 +00:00
parent 3e12c6736d
commit e4c068c063
2 changed files with 28 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
lispref/ChangeLog
View File

@ -1,3 +1,7 @@
2006-05-10 Richard Stallman <rms@gnu.org>
* internals.texi (Writing Emacs Primitives): Clarify GCPRO rules.
2006-05-10 Reiner Steib <Reiner.Steib@gmx.de>
* variables.texi (File Local Variables): Recommend to quote lambda

43
lispref/internals.texi
View File

@ -615,32 +615,37 @@ arguments, and the second is the address of a block containing their
values. They have types @code{int} and @w{@code{Lisp_Object *}}.
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