diff --git a/lispref/internals.texi b/lispref/internals.texi index a6ddd02afe5..a96eacf39d2 100644 --- a/lispref/internals.texi +++ b/lispref/internals.texi @@ -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