[Emacs-diffs] Changes to emacs/lispref/internals.texi

[Richard M. Stallman]

Index: emacs/lispref/internals.texi
diff -c emacs/lispref/internals.texi:1.26 emacs/lispref/internals.texi:1.27
*** emacs/lispref/internals.texi:1.26   Sat Dec  7 08:37:04 2002
--- emacs/lispref/internals.texi        Sat Apr 19 00:16:15 2003
***************
*** 572,593 ****
  @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}.
  Alas, we can't explain all the tricky details here.
  
    You must not use C initializers for static or global variables unless
  the variables are never written once Emacs is dumped.  These variables
--- 572,600 ----
  @code{UNGCPRO} cancels the protection of the variables that are
  protected in the current function.  It is necessary to do this explicitly.
  
!   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