changeset 50638:5a24a10b0246

(Writing Emacs Primitives): Strings are no longer special for GCPROs. Mention GCPRO5, GCPRO6. Explain GCPRO convention for varargs function args.

--- a/lispref/internals.texi	Fri Apr 18 22:49:41 2003 +0000
+++ b/lispref/internals.texi	Sat Apr 19 04:16:15 2003 +0000
@@ -572,22 +572,29 @@
 @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.
+  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.
 
-  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