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

(Writing Emacs Primitives): Strings are

Browse Source 
no longer special for GCPROs.  Mention GCPRO5, GCPRO6.
Explain GCPRO convention for varargs function args.
This commit is contained in:
Richard M. Stallman 2003-04-19 04:16:15 +00:00
parent 80d9508acf
commit 70bb440262
1 changed files with 21 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
lispref/internals.texi
View File

@ -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.
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} 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}.
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