Mercurial > hg > xemacs-beta

comparison man/internals/internals.texi @ 1920:c66036f59678

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[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
comparison
equal deleted inserted replaced
1919:9bde73b8c020 1920:c66036f59678
5941 Marking with @code{GCPRO} is necessary because some C functions (quite 5941 Marking with @code{GCPRO} is necessary because some C functions (quite
5942 a lot, in fact), allocate objects during their operation. Quite 5942 a lot, in fact), allocate objects during their operation. Quite
5943 frequently, there will be no other pointer to the object while the 5943 frequently, there will be no other pointer to the object while the
5944 function is running, and if a garbage collection occurs and the object 5944 function is running, and if a garbage collection occurs and the object
5945 needs to be referenced again, bad things will happen. The solution is 5945 needs to be referenced again, bad things will happen. The solution is
5946 to mark those objects with @code{GCPRO}. Unfortunately this is easy to 5946 to mark those references with @code{GCPRO}. Note that it is a
5947 forget, and there is basically no way around this problem. Here are 5947 @emph{reference} that is marked with @code{GCPRO}, not an object. If
5948 some rules, though: 5948 you declare a @code{Lisp_Object} variable, assign to it, @code{GCPRO}
5949 it, and then assign to it again, the first object assigned @emph{is not}
5950 protected, while the second object @emph{is} protected. Unfortunately
5951 @code{GCPRO}ing is easy to forget, and there is basically no way around
5952 this problem. Here are some rules, though:
5949 5953
5950 @enumerate 5954 @enumerate
5951 @item 5955 @item
5952 For every @code{GCPRO@var{n}}, there have to be declarations of 5956 A garbage collection can occur whenever anything calls @code{Feval}, or
5953 @code{struct gcpro gcpro1, gcpro2}, etc. 5957 whenever a @code{QUIT} can occur where execution can continue past
5958 this. (Remember, this is almost anywhere.) Note that @code{Fsignal} can
5959 GC, and it can return (even though it normally doesn't). This means
5960 that you must @code{GCPRO} before calling most of the error functions,
5961 including the @samp{CONCHECK} family of macros, if references occur
5962 after the call.
5954 5963
5955 @item 5964 @item
5956 You @emph{must} @code{UNGCPRO} anything that's @code{GCPRO}ed, and you 5965 You @emph{must} @code{UNGCPRO} anything that's @code{GCPRO}ed, and you
5957 @emph{must not} @code{UNGCPRO} if you haven't @code{GCPRO}ed. Getting 5966 @emph{must not} @code{UNGCPRO} if you haven't @code{GCPRO}ed. Getting
5958 either of these wrong will lead to crashes, often in completely random 5967 either of these wrong will lead to crashes, often in completely random
5959 places unrelated to where the problem lies. 5968 places unrelated to where the problem lies. There are some functions
5969 (@code{Fsignal} is the canonical example) which may or may not return.
5970 In these cases, the function is responsible for cleaning up the
5971 @code{GCPRO}s if it doesn't return, so you should treat it as an
5972 ordinary function.
5973
5974 @item
5975 For every @code{GCPRO@var{n}}, there have to be declarations of
5976 @code{struct gcpro gcpro1, gcpro2, ..., gcpro@var{n}}.
5960 5977
5961 @item 5978 @item
5962 The way this actually works is that all currently active @code{GCPRO}s 5979 The way this actually works is that all currently active @code{GCPRO}s
5963 are chained through the @code{struct gcpro} local variables, with the 5980 are chained through the @code{struct gcpro} local variables, with the
5964 variable @samp{gcprolist} pointing to the head of the list and the nth 5981 variable @samp{gcprolist} pointing to the head of the list and the nth
6011 So, if you create any Lisp objects (remember, this happens in all sorts 6028 So, if you create any Lisp objects (remember, this happens in all sorts
6012 of circumstances, e.g. with @code{Fcons()}, etc.), you are responsible 6029 of circumstances, e.g. with @code{Fcons()}, etc.), you are responsible
6013 for @code{GCPRO}ing them, unless you are @emph{absolutely sure} that 6030 for @code{GCPRO}ing them, unless you are @emph{absolutely sure} that
6014 there's no possibility that a garbage-collection can occur while you 6031 there's no possibility that a garbage-collection can occur while you
6015 need to use the object. Even then, consider @code{GCPRO}ing. 6032 need to use the object. Even then, consider @code{GCPRO}ing.
6016
6017 @item
6018 A garbage collection can occur whenever anything calls @code{Feval}, or
6019 whenever a QUIT can occur where execution can continue past
6020 this. (Remember, this is almost anywhere.)
6021 6033
6022 @item 6034 @item
6023 If you have the @emph{least smidgeon of doubt} about whether 6035 If you have the @emph{least smidgeon of doubt} about whether
6024 you need to @code{GCPRO}, you should @code{GCPRO}. 6036 you need to @code{GCPRO}, you should @code{GCPRO}.
6025 6037