Mercurial > hg > xemacs-beta
diff man/internals/internals.texi @ 1920:c66036f59678
[xemacs-hg @ 2004-02-20 07:29:16 by stephent]
GCPRO documentation <87y8qynrj0.fsf@tleepslib.sk.tsukuba.ac.jp>
author | stephent |
---|---|
date | Fri, 20 Feb 2004 07:29:23 +0000 |
parents | f43f9ca6c7d9 |
children | 2ba4f06a264d |
line wrap: on
line diff
--- a/man/internals/internals.texi Thu Feb 19 22:50:36 2004 +0000 +++ b/man/internals/internals.texi Fri Feb 20 07:29:23 2004 +0000 @@ -5943,20 +5943,37 @@ frequently, there will be no other pointer to the object while the function is running, and if a garbage collection occurs and the object needs to be referenced again, bad things will happen. The solution is -to mark those objects with @code{GCPRO}. Unfortunately this is easy to -forget, and there is basically no way around this problem. Here are -some rules, though: +to mark those references with @code{GCPRO}. Note that it is a +@emph{reference} that is marked with @code{GCPRO}, not an object. If +you declare a @code{Lisp_Object} variable, assign to it, @code{GCPRO} +it, and then assign to it again, the first object assigned @emph{is not} +protected, while the second object @emph{is} protected. Unfortunately +@code{GCPRO}ing is easy to forget, and there is basically no way around +this problem. Here are some rules, though: @enumerate @item -For every @code{GCPRO@var{n}}, there have to be declarations of -@code{struct gcpro gcpro1, gcpro2}, etc. +A garbage collection can occur whenever anything calls @code{Feval}, or +whenever a @code{QUIT} can occur where execution can continue past +this. (Remember, this is almost anywhere.) Note that @code{Fsignal} can +GC, and it can return (even though it normally doesn't). This means +that you must @code{GCPRO} before calling most of the error functions, +including the @samp{CONCHECK} family of macros, if references occur +after the call. @item You @emph{must} @code{UNGCPRO} anything that's @code{GCPRO}ed, and you @emph{must not} @code{UNGCPRO} if you haven't @code{GCPRO}ed. Getting either of these wrong will lead to crashes, often in completely random -places unrelated to where the problem lies. +places unrelated to where the problem lies. There are some functions +(@code{Fsignal} is the canonical example) which may or may not return. +In these cases, the function is responsible for cleaning up the +@code{GCPRO}s if it doesn't return, so you should treat it as an +ordinary function. + +@item +For every @code{GCPRO@var{n}}, there have to be declarations of +@code{struct gcpro gcpro1, gcpro2, ..., gcpro@var{n}}. @item The way this actually works is that all currently active @code{GCPRO}s @@ -6015,11 +6032,6 @@ need to use the object. Even then, consider @code{GCPRO}ing. @item -A garbage collection can occur whenever anything calls @code{Feval}, or -whenever a QUIT can occur where execution can continue past -this. (Remember, this is almost anywhere.) - -@item If you have the @emph{least smidgeon of doubt} about whether you need to @code{GCPRO}, you should @code{GCPRO}.