Commit 70bb4402 authored by Richard M. Stallman's avatar Richard M. Stallman
Browse files

(Writing Emacs Primitives): Strings are

no longer special for GCPROs.  Mention GCPRO5, GCPRO6.
Explain GCPRO convention for varargs function args.
parent 80d9508a
......@@ -572,23 +572,30 @@ 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.
For most data types, it suffices to protect at least one pointer to
the object; as long as the object is not recycled, all pointers to it
remain valid. This is not so for strings, because the garbage collector
can move them. When the garbage collector moves a string, it relocates
all the pointers it knows about; any other pointers become invalid.
Therefore, you must protect all pointers to strings across any point
where garbage collection may be possible.
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} and @code{GCPRO4} 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 @code{GCPRO2}, you must declare @code{gcpro1} and @code{gcpro2}.
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 GCPRO. (Formerly, strings were an exception
to this rule; in older Emacs versions, every pointer to a string
needed to be marked by GC.)
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
@code{GCPRO2}, you must declare @code{gcpro1} and @code{gcpro2}.
Alas, we can't explain all the tricky details here.
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 protecting the Lisp arguments from GC
rests with the caller in this case.
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
......
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