[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] Changes to emacs/lispref/internals.texi
From: |
Richard M. Stallman |
Subject: |
[Emacs-diffs] Changes to emacs/lispref/internals.texi |
Date: |
Sat, 19 Apr 2003 00:16:15 -0400 |
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