Mercurial > hg > CbC > CbC_gcc
annotate gcc/doc/gty.texi @ 67:f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
author | nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp> |
---|---|
date | Tue, 22 Mar 2011 17:18:12 +0900 |
parents | 77e2b8dfacca |
children | 04ced10e8804 |
rev | line source |
---|---|
67
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
1 @c Copyright (C) 2002, 2003, 2004, 2007, 2008, 2009, 2010 |
0 | 2 @c Free Software Foundation, Inc. |
3 @c This is part of the GCC manual. | |
4 @c For copying conditions, see the file gcc.texi. | |
5 | |
6 @node Type Information | |
7 @chapter Memory Management and Type Information | |
8 @cindex GGC | |
9 @findex GTY | |
10 | |
11 GCC uses some fairly sophisticated memory management techniques, which | |
12 involve determining information about GCC's data structures from GCC's | |
13 source code and using this information to perform garbage collection and | |
14 implement precompiled headers. | |
15 | |
16 A full C parser would be too complicated for this task, so a limited | |
17 subset of C is interpreted and special markers are used to determine | |
18 what parts of the source to look at. All @code{struct} and | |
19 @code{union} declarations that define data structures that are | |
20 allocated under control of the garbage collector must be marked. All | |
21 global variables that hold pointers to garbage-collected memory must | |
22 also be marked. Finally, all global variables that need to be saved | |
23 and restored by a precompiled header must be marked. (The precompiled | |
24 header mechanism can only save static variables if they're scalar. | |
25 Complex data structures must be allocated in garbage-collected memory | |
26 to be saved in a precompiled header.) | |
27 | |
28 The full format of a marker is | |
29 @smallexample | |
30 GTY (([@var{option}] [(@var{param})], [@var{option}] [(@var{param})] @dots{})) | |
31 @end smallexample | |
32 @noindent | |
33 but in most cases no options are needed. The outer double parentheses | |
34 are still necessary, though: @code{GTY(())}. Markers can appear: | |
35 | |
36 @itemize @bullet | |
37 @item | |
38 In a structure definition, before the open brace; | |
39 @item | |
40 In a global variable declaration, after the keyword @code{static} or | |
41 @code{extern}; and | |
42 @item | |
43 In a structure field definition, before the name of the field. | |
44 @end itemize | |
45 | |
46 Here are some examples of marking simple data structures and globals. | |
47 | |
48 @smallexample | |
55
77e2b8dfacca
update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
49 struct GTY(()) @var{tag} |
0 | 50 @{ |
51 @var{fields}@dots{} | |
52 @}; | |
53 | |
55
77e2b8dfacca
update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
54 typedef struct GTY(()) @var{tag} |
0 | 55 @{ |
56 @var{fields}@dots{} | |
57 @} *@var{typename}; | |
58 | |
59 static GTY(()) struct @var{tag} *@var{list}; /* @r{points to GC memory} */ | |
60 static GTY(()) int @var{counter}; /* @r{save counter in a PCH} */ | |
61 @end smallexample | |
62 | |
63 The parser understands simple typedefs such as | |
64 @code{typedef struct @var{tag} *@var{name};} and | |
65 @code{typedef int @var{name};}. | |
66 These don't need to be marked. | |
67 | |
68 @menu | |
69 * GTY Options:: What goes inside a @code{GTY(())}. | |
70 * GGC Roots:: Making global variables GGC roots. | |
71 * Files:: How the generated files work. | |
72 * Invoking the garbage collector:: How to invoke the garbage collector. | |
67
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
73 * Troubleshooting:: When something does not work as expected. |
0 | 74 @end menu |
75 | |
76 @node GTY Options | |
77 @section The Inside of a @code{GTY(())} | |
78 | |
79 Sometimes the C code is not enough to fully describe the type | |
80 structure. Extra information can be provided with @code{GTY} options | |
81 and additional markers. Some options take a parameter, which may be | |
82 either a string or a type name, depending on the parameter. If an | |
83 option takes no parameter, it is acceptable either to omit the | |
84 parameter entirely, or to provide an empty string as a parameter. For | |
85 example, @code{@w{GTY ((skip))}} and @code{@w{GTY ((skip ("")))}} are | |
86 equivalent. | |
87 | |
88 When the parameter is a string, often it is a fragment of C code. Four | |
89 special escapes may be used in these strings, to refer to pieces of | |
90 the data structure being marked: | |
91 | |
92 @cindex % in GTY option | |
93 @table @code | |
94 @item %h | |
95 The current structure. | |
96 @item %1 | |
97 The structure that immediately contains the current structure. | |
98 @item %0 | |
99 The outermost structure that contains the current structure. | |
100 @item %a | |
101 A partial expression of the form @code{[i1][i2]@dots{}} that indexes | |
102 the array item currently being marked. | |
103 @end table | |
104 | |
105 For instance, suppose that you have a structure of the form | |
106 @smallexample | |
107 struct A @{ | |
108 @dots{} | |
109 @}; | |
110 struct B @{ | |
111 struct A foo[12]; | |
112 @}; | |
113 @end smallexample | |
114 @noindent | |
115 and @code{b} is a variable of type @code{struct B}. When marking | |
116 @samp{b.foo[11]}, @code{%h} would expand to @samp{b.foo[11]}, | |
117 @code{%0} and @code{%1} would both expand to @samp{b}, and @code{%a} | |
118 would expand to @samp{[11]}. | |
119 | |
120 As in ordinary C, adjacent strings will be concatenated; this is | |
121 helpful when you have a complicated expression. | |
122 @smallexample | |
123 @group | |
124 GTY ((chain_next ("TREE_CODE (&%h.generic) == INTEGER_TYPE" | |
125 " ? TYPE_NEXT_VARIANT (&%h.generic)" | |
126 " : TREE_CHAIN (&%h.generic)"))) | |
127 @end group | |
128 @end smallexample | |
129 | |
130 The available options are: | |
131 | |
132 @table @code | |
133 @findex length | |
134 @item length ("@var{expression}") | |
135 | |
136 There are two places the type machinery will need to be explicitly told | |
137 the length of an array. The first case is when a structure ends in a | |
138 variable-length array, like this: | |
139 @smallexample | |
55
77e2b8dfacca
update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
140 struct GTY(()) rtvec_def @{ |
0 | 141 int num_elem; /* @r{number of elements} */ |
142 rtx GTY ((length ("%h.num_elem"))) elem[1]; | |
143 @}; | |
144 @end smallexample | |
145 | |
146 In this case, the @code{length} option is used to override the specified | |
147 array length (which should usually be @code{1}). The parameter of the | |
148 option is a fragment of C code that calculates the length. | |
149 | |
150 The second case is when a structure or a global variable contains a | |
151 pointer to an array, like this: | |
152 @smallexample | |
67
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
153 struct gimple_omp_for_iter * GTY((length ("%h.collapse"))) iter; |
0 | 154 @end smallexample |
67
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
155 In this case, @code{iter} has been allocated by writing something like |
0 | 156 @smallexample |
67
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
157 x->iter = ggc_alloc_cleared_vec_gimple_omp_for_iter (collapse); |
0 | 158 @end smallexample |
67
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
159 and the @code{collapse} provides the length of the field. |
0 | 160 |
161 This second use of @code{length} also works on global variables, like: | |
162 @verbatim | |
67
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
163 static GTY((length("reg_known_value_size"))) rtx *reg_known_value; |
0 | 164 @end verbatim |
165 | |
166 @findex skip | |
167 @item skip | |
168 | |
169 If @code{skip} is applied to a field, the type machinery will ignore it. | |
170 This is somewhat dangerous; the only safe use is in a union when one | |
171 field really isn't ever used. | |
172 | |
173 @findex desc | |
174 @findex tag | |
175 @findex default | |
176 @item desc ("@var{expression}") | |
177 @itemx tag ("@var{constant}") | |
178 @itemx default | |
179 | |
180 The type machinery needs to be told which field of a @code{union} is | |
181 currently active. This is done by giving each field a constant | |
182 @code{tag} value, and then specifying a discriminator using @code{desc}. | |
183 The value of the expression given by @code{desc} is compared against | |
184 each @code{tag} value, each of which should be different. If no | |
185 @code{tag} is matched, the field marked with @code{default} is used if | |
186 there is one, otherwise no field in the union will be marked. | |
187 | |
188 In the @code{desc} option, the ``current structure'' is the union that | |
189 it discriminates. Use @code{%1} to mean the structure containing it. | |
190 There are no escapes available to the @code{tag} option, since it is a | |
191 constant. | |
192 | |
193 For example, | |
194 @smallexample | |
55
77e2b8dfacca
update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
195 struct GTY(()) tree_binding |
0 | 196 @{ |
197 struct tree_common common; | |
198 union tree_binding_u @{ | |
199 tree GTY ((tag ("0"))) scope; | |
200 struct cp_binding_level * GTY ((tag ("1"))) level; | |
201 @} GTY ((desc ("BINDING_HAS_LEVEL_P ((tree)&%0)"))) xscope; | |
202 tree value; | |
203 @}; | |
204 @end smallexample | |
205 | |
206 In this example, the value of BINDING_HAS_LEVEL_P when applied to a | |
207 @code{struct tree_binding *} is presumed to be 0 or 1. If 1, the type | |
208 mechanism will treat the field @code{level} as being present and if 0, | |
209 will treat the field @code{scope} as being present. | |
210 | |
211 @findex param_is | |
212 @findex use_param | |
213 @item param_is (@var{type}) | |
214 @itemx use_param | |
215 | |
216 Sometimes it's convenient to define some data structure to work on | |
217 generic pointers (that is, @code{PTR}) and then use it with a specific | |
218 type. @code{param_is} specifies the real type pointed to, and | |
219 @code{use_param} says where in the generic data structure that type | |
220 should be put. | |
221 | |
222 For instance, to have a @code{htab_t} that points to trees, one would | |
223 write the definition of @code{htab_t} like this: | |
224 @smallexample | |
225 typedef struct GTY(()) @{ | |
226 @dots{} | |
227 void ** GTY ((use_param, @dots{})) entries; | |
228 @dots{} | |
229 @} htab_t; | |
230 @end smallexample | |
231 and then declare variables like this: | |
232 @smallexample | |
233 static htab_t GTY ((param_is (union tree_node))) ict; | |
234 @end smallexample | |
235 | |
236 @findex param@var{n}_is | |
237 @findex use_param@var{n} | |
238 @item param@var{n}_is (@var{type}) | |
239 @itemx use_param@var{n} | |
240 | |
241 In more complicated cases, the data structure might need to work on | |
242 several different types, which might not necessarily all be pointers. | |
243 For this, @code{param1_is} through @code{param9_is} may be used to | |
244 specify the real type of a field identified by @code{use_param1} through | |
245 @code{use_param9}. | |
246 | |
247 @findex use_params | |
248 @item use_params | |
249 | |
250 When a structure contains another structure that is parameterized, | |
251 there's no need to do anything special, the inner structure inherits the | |
252 parameters of the outer one. When a structure contains a pointer to a | |
253 parameterized structure, the type machinery won't automatically detect | |
254 this (it could, it just doesn't yet), so it's necessary to tell it that | |
255 the pointed-to structure should use the same parameters as the outer | |
256 structure. This is done by marking the pointer with the | |
257 @code{use_params} option. | |
258 | |
259 @findex deletable | |
260 @item deletable | |
261 | |
262 @code{deletable}, when applied to a global variable, indicates that when | |
263 garbage collection runs, there's no need to mark anything pointed to | |
264 by this variable, it can just be set to @code{NULL} instead. This is used | |
265 to keep a list of free structures around for re-use. | |
266 | |
267 @findex if_marked | |
268 @item if_marked ("@var{expression}") | |
269 | |
270 Suppose you want some kinds of object to be unique, and so you put them | |
271 in a hash table. If garbage collection marks the hash table, these | |
272 objects will never be freed, even if the last other reference to them | |
273 goes away. GGC has special handling to deal with this: if you use the | |
274 @code{if_marked} option on a global hash table, GGC will call the | |
275 routine whose name is the parameter to the option on each hash table | |
276 entry. If the routine returns nonzero, the hash table entry will | |
277 be marked as usual. If the routine returns zero, the hash table entry | |
278 will be deleted. | |
279 | |
280 The routine @code{ggc_marked_p} can be used to determine if an element | |
281 has been marked already; in fact, the usual case is to use | |
282 @code{if_marked ("ggc_marked_p")}. | |
283 | |
284 @findex mark_hook | |
285 @item mark_hook ("@var{hook-routine-name}") | |
286 | |
287 If provided for a structure or union type, the given | |
288 @var{hook-routine-name} (between double-quotes) is the name of a | |
289 routine called when the garbage collector has just marked the data as | |
290 reachable. This routine should not change the data, or call any ggc | |
291 routine. Its only argument is a pointer to the just marked (const) | |
292 structure or union. | |
293 | |
294 @findex maybe_undef | |
295 @item maybe_undef | |
296 | |
297 When applied to a field, @code{maybe_undef} indicates that it's OK if | |
298 the structure that this fields points to is never defined, so long as | |
299 this field is always @code{NULL}. This is used to avoid requiring | |
300 backends to define certain optional structures. It doesn't work with | |
301 language frontends. | |
302 | |
303 @findex nested_ptr | |
304 @item nested_ptr (@var{type}, "@var{to expression}", "@var{from expression}") | |
305 | |
306 The type machinery expects all pointers to point to the start of an | |
307 object. Sometimes for abstraction purposes it's convenient to have | |
308 a pointer which points inside an object. So long as it's possible to | |
309 convert the original object to and from the pointer, such pointers | |
310 can still be used. @var{type} is the type of the original object, | |
311 the @var{to expression} returns the pointer given the original object, | |
312 and the @var{from expression} returns the original object given | |
313 the pointer. The pointer will be available using the @code{%h} | |
314 escape. | |
315 | |
316 @findex chain_next | |
317 @findex chain_prev | |
318 @findex chain_circular | |
319 @item chain_next ("@var{expression}") | |
320 @itemx chain_prev ("@var{expression}") | |
321 @itemx chain_circular ("@var{expression}") | |
322 | |
323 It's helpful for the type machinery to know if objects are often | |
324 chained together in long lists; this lets it generate code that uses | |
325 less stack space by iterating along the list instead of recursing down | |
326 it. @code{chain_next} is an expression for the next item in the list, | |
327 @code{chain_prev} is an expression for the previous item. For singly | |
328 linked lists, use only @code{chain_next}; for doubly linked lists, use | |
329 both. The machinery requires that taking the next item of the | |
330 previous item gives the original item. @code{chain_circular} is similar | |
331 to @code{chain_next}, but can be used for circular single linked lists. | |
332 | |
333 @findex reorder | |
334 @item reorder ("@var{function name}") | |
335 | |
336 Some data structures depend on the relative ordering of pointers. If | |
337 the precompiled header machinery needs to change that ordering, it | |
338 will call the function referenced by the @code{reorder} option, before | |
339 changing the pointers in the object that's pointed to by the field the | |
340 option applies to. The function must take four arguments, with the | |
341 signature @samp{@w{void *, void *, gt_pointer_operator, void *}}. | |
342 The first parameter is a pointer to the structure that contains the | |
343 object being updated, or the object itself if there is no containing | |
344 structure. The second parameter is a cookie that should be ignored. | |
345 The third parameter is a routine that, given a pointer, will update it | |
346 to its correct new value. The fourth parameter is a cookie that must | |
347 be passed to the second parameter. | |
348 | |
349 PCH cannot handle data structures that depend on the absolute values | |
350 of pointers. @code{reorder} functions can be expensive. When | |
351 possible, it is better to depend on properties of the data, like an ID | |
352 number or the hash of a string instead. | |
353 | |
67
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
354 @findex variable_size |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
355 @item variable_size |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
356 |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
357 The type machinery expects the types to be of constant size. When this |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
358 is not true, for example, with structs that have array fields or unions, |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
359 the type machinery cannot tell how many bytes need to be allocated at |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
360 each allocation. The @code{variable_size} is used to mark such types. |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
361 The type machinery then provides allocators that take a parameter |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
362 indicating an exact size of object being allocated. Note that the size |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
363 must be provided in bytes whereas the @code{length} option works with |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
364 array lengths in number of elements. |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
365 |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
366 For example, |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
367 @smallexample |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
368 struct GTY((variable_size)) sorted_fields_type @{ |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
369 int len; |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
370 tree GTY((length ("%h.len"))) elts[1]; |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
371 @}; |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
372 @end smallexample |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
373 |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
374 Then the objects of @code{struct sorted_fields_type} are allocated in GC |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
375 memory as follows: |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
376 @smallexample |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
377 field_vec = ggc_alloc_sorted_fields_type (size); |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
378 @end smallexample |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
379 |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
380 If @var{field_vec->elts} stores @var{n} elements, then @var{size} |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
381 could be calculated as follows: |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
382 @smallexample |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
383 size_t size = sizeof (struct sorted_fields_type) + n * sizeof (tree); |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
384 @end smallexample |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
385 |
0 | 386 @findex special |
387 @item special ("@var{name}") | |
388 | |
389 The @code{special} option is used to mark types that have to be dealt | |
390 with by special case machinery. The parameter is the name of the | |
391 special case. See @file{gengtype.c} for further details. Avoid | |
392 adding new special cases unless there is no other alternative. | |
393 @end table | |
394 | |
395 @node GGC Roots | |
396 @section Marking Roots for the Garbage Collector | |
397 @cindex roots, marking | |
398 @cindex marking roots | |
399 | |
400 In addition to keeping track of types, the type machinery also locates | |
401 the global variables (@dfn{roots}) that the garbage collector starts | |
402 at. Roots must be declared using one of the following syntaxes: | |
403 | |
404 @itemize @bullet | |
405 @item | |
406 @code{extern GTY(([@var{options}])) @var{type} @var{name};} | |
407 @item | |
408 @code{static GTY(([@var{options}])) @var{type} @var{name};} | |
409 @end itemize | |
410 @noindent | |
411 The syntax | |
412 @itemize @bullet | |
413 @item | |
414 @code{GTY(([@var{options}])) @var{type} @var{name};} | |
415 @end itemize | |
416 @noindent | |
417 is @emph{not} accepted. There should be an @code{extern} declaration | |
418 of such a variable in a header somewhere---mark that, not the | |
419 definition. Or, if the variable is only used in one file, make it | |
420 @code{static}. | |
421 | |
422 @node Files | |
423 @section Source Files Containing Type Information | |
424 @cindex generated files | |
425 @cindex files, generated | |
426 | |
427 Whenever you add @code{GTY} markers to a source file that previously | |
428 had none, or create a new source file containing @code{GTY} markers, | |
429 there are three things you need to do: | |
430 | |
431 @enumerate | |
432 @item | |
433 You need to add the file to the list of source files the type | |
434 machinery scans. There are four cases: | |
435 | |
436 @enumerate a | |
437 @item | |
438 For a back-end file, this is usually done | |
439 automatically; if not, you should add it to @code{target_gtfiles} in | |
440 the appropriate port's entries in @file{config.gcc}. | |
441 | |
442 @item | |
443 For files shared by all front ends, add the filename to the | |
444 @code{GTFILES} variable in @file{Makefile.in}. | |
445 | |
446 @item | |
447 For files that are part of one front end, add the filename to the | |
448 @code{gtfiles} variable defined in the appropriate | |
449 @file{config-lang.in}. For C, the file is @file{c-config-lang.in}. | |
450 Headers should appear before non-headers in this list. | |
451 | |
452 @item | |
453 For files that are part of some but not all front ends, add the | |
454 filename to the @code{gtfiles} variable of @emph{all} the front ends | |
455 that use it. | |
456 @end enumerate | |
457 | |
458 @item | |
459 If the file was a header file, you'll need to check that it's included | |
460 in the right place to be visible to the generated files. For a back-end | |
461 header file, this should be done automatically. For a front-end header | |
462 file, it needs to be included by the same file that includes | |
463 @file{gtype-@var{lang}.h}. For other header files, it needs to be | |
464 included in @file{gtype-desc.c}, which is a generated file, so add it to | |
465 @code{ifiles} in @code{open_base_file} in @file{gengtype.c}. | |
466 | |
467 For source files that aren't header files, the machinery will generate a | |
468 header file that should be included in the source file you just changed. | |
469 The file will be called @file{gt-@var{path}.h} where @var{path} is the | |
470 pathname relative to the @file{gcc} directory with slashes replaced by | |
471 @verb{|-|}, so for example the header file to be included in | |
472 @file{cp/parser.c} is called @file{gt-cp-parser.c}. The | |
473 generated header file should be included after everything else in the | |
474 source file. Don't forget to mention this file as a dependency in the | |
475 @file{Makefile}! | |
476 | |
477 @end enumerate | |
478 | |
479 For language frontends, there is another file that needs to be included | |
480 somewhere. It will be called @file{gtype-@var{lang}.h}, where | |
481 @var{lang} is the name of the subdirectory the language is contained in. | |
482 | |
55
77e2b8dfacca
update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
483 Plugins can add additional root tables. Run the @code{gengtype} |
77e2b8dfacca
update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
484 utility in plugin mode as @code{gengtype -P pluginout.h @var{source-dir} |
77e2b8dfacca
update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
485 @var{file-list} @var{plugin*.c}} with your plugin files |
77e2b8dfacca
update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
486 @var{plugin*.c} using @code{GTY} to generate the @var{pluginout.h} file. |
77e2b8dfacca
update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
487 The GCC build tree is needed to be present in that mode. |
77e2b8dfacca
update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
488 |
77e2b8dfacca
update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
0
diff
changeset
|
489 |
0 | 490 @node Invoking the garbage collector |
491 @section How to invoke the garbage collector | |
492 @cindex garbage collector, invocation | |
493 @findex ggc_collect | |
494 | |
495 The GCC garbage collector GGC is only invoked explicitly. In contrast | |
496 with many other garbage collectors, it is not implicitly invoked by | |
497 allocation routines when a lot of memory has been consumed. So the | |
498 only way to have GGC reclaim storage it to call the @code{ggc_collect} | |
67
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
499 function explicitly. This call is an expensive operation, as it may |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
500 have to scan the entire heap. Beware that local variables (on the GCC |
0 | 501 call stack) are not followed by such an invocation (as many other |
502 garbage collectors do): you should reference all your data from static | |
503 or external @code{GTY}-ed variables, and it is advised to call | |
67
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
504 @code{ggc_collect} with a shallow call stack. The GGC is an exact mark |
0 | 505 and sweep garbage collector (so it does not scan the call stack for |
67
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
506 pointers). In practice GCC passes don't often call @code{ggc_collect} |
0 | 507 themselves, because it is called by the pass manager between passes. |
67
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
508 |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
509 At the time of the @code{ggc_collect} call all pointers in the GC-marked |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
510 structures must be valid or @code{NULL}. In practice this means that |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
511 there should not be uninitialized pointer fields in the structures even |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
512 if your code never reads or writes those fields at a particular |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
513 instance. One way to ensure this is to use cleared versions of |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
514 allocators unless all the fields are initialized manually immediately |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
515 after allocation. |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
516 |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
517 @node Troubleshooting |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
518 @section Troubleshooting the garbage collector |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
519 @cindex garbage collector, troubleshooting |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
520 |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
521 With the current garbage collector implementation, most issues should |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
522 show up as GCC compilation errors. Some of the most commonly |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
523 encountered issues are described below. |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
524 |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
525 @itemize @bullet |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
526 @item Gengtype does not produce allocators for a @code{GTY}-marked type. |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
527 Gengtype checks if there is at least one possible path from GC roots to |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
528 at least one instance of each type before outputting allocators. If |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
529 there is no such path, the @code{GTY} markers will be ignored and no |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
530 allocators will be output. Solve this by making sure that there exists |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
531 at least one such path. If creating it is unfeasible or raises a ``code |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
532 smell'', consider if you really must use GC for allocating such type. |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
533 |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
534 @item Link-time errors about undefined @code{gt_ggc_r_foo_bar} and |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
535 similarly-named symbols. Check if your @file{foo_bar} source file has |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
536 @code{#include "gt-foo_bar.h"} as its very last line. |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
537 |
f6334be47118
update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents:
55
diff
changeset
|
538 @end itemize |