]>
Commit | Line | Data |
---|---|---|
818ab71a | 1 | @c Copyright (C) 2002-2016 Free Software Foundation, Inc. |
e2500fed GK |
2 | @c This is part of the GCC manual. |
3 | @c For copying conditions, see the file gcc.texi. | |
4 | ||
5 | @node Type Information | |
6 | @chapter Memory Management and Type Information | |
7 | @cindex GGC | |
8 | @findex GTY | |
9 | ||
10 | GCC uses some fairly sophisticated memory management techniques, which | |
11 | involve determining information about GCC's data structures from GCC's | |
17211ab5 GK |
12 | source code and using this information to perform garbage collection and |
13 | implement precompiled headers. | |
e2500fed | 14 | |
0823efed DN |
15 | A full C++ parser would be too complicated for this task, so a limited |
16 | subset of C++ is interpreted and special markers are used to determine | |
17 | what parts of the source to look at. All @code{struct}, @code{union} | |
18 | and @code{template} structure declarations that define data structures | |
19 | that are allocated under control of the garbage collector must be | |
20 | marked. All global variables that hold pointers to garbage-collected | |
21 | memory must also be marked. Finally, all global variables that need | |
22 | to be saved and restored by a precompiled header must be marked. (The | |
23 | precompiled header mechanism can only save static variables if they're | |
24 | scalar. Complex data structures must be allocated in garbage-collected | |
25 | memory to be saved in a precompiled header.) | |
1431042e ZW |
26 | |
27 | The full format of a marker is | |
28 | @smallexample | |
29 | GTY (([@var{option}] [(@var{param})], [@var{option}] [(@var{param})] @dots{})) | |
30 | @end smallexample | |
31 | @noindent | |
32 | but in most cases no options are needed. The outer double parentheses | |
33 | are still necessary, though: @code{GTY(())}. Markers can appear: | |
e2500fed | 34 | |
e2500fed GK |
35 | @itemize @bullet |
36 | @item | |
37 | In a structure definition, before the open brace; | |
38 | @item | |
daf2f129 | 39 | In a global variable declaration, after the keyword @code{static} or |
e2500fed GK |
40 | @code{extern}; and |
41 | @item | |
42 | In a structure field definition, before the name of the field. | |
43 | @end itemize | |
44 | ||
1431042e ZW |
45 | Here are some examples of marking simple data structures and globals. |
46 | ||
47 | @smallexample | |
d1b38208 | 48 | struct GTY(()) @var{tag} |
1431042e ZW |
49 | @{ |
50 | @var{fields}@dots{} | |
51 | @}; | |
52 | ||
d1b38208 | 53 | typedef struct GTY(()) @var{tag} |
1431042e ZW |
54 | @{ |
55 | @var{fields}@dots{} | |
56 | @} *@var{typename}; | |
57 | ||
58 | static GTY(()) struct @var{tag} *@var{list}; /* @r{points to GC memory} */ | |
59 | static GTY(()) int @var{counter}; /* @r{save counter in a PCH} */ | |
60 | @end smallexample | |
61 | ||
62 | The parser understands simple typedefs such as | |
f0eb93a8 | 63 | @code{typedef struct @var{tag} *@var{name};} and |
1431042e ZW |
64 | @code{typedef int @var{name};}. |
65 | These don't need to be marked. | |
66 | ||
313465bb DN |
67 | Since @code{gengtype}'s understanding of C++ is limited, there are |
68 | several constructs and declarations that are not supported inside | |
69 | classes/structures marked for automatic GC code generation. The | |
70 | following C++ constructs produce a @code{gengtype} error on | |
71 | structures/classes marked for automatic GC code generation: | |
72 | ||
73 | @itemize @bullet | |
74 | @item | |
75 | Type definitions inside classes/structures are not supported. | |
76 | @item | |
77 | Enumerations inside classes/structures are not supported. | |
78 | @end itemize | |
79 | ||
80 | If you have a class or structure using any of the above constructs, | |
81 | you need to mark that class as @code{GTY ((user))} and provide your | |
82 | own marking routines (see section @ref{User GC} for details). | |
83 | ||
84 | It is always valid to include function definitions inside classes. | |
85 | Those are always ignored by @code{gengtype}, as it only cares about | |
86 | data members. | |
87 | ||
1431042e | 88 | @menu |
6ccde948 | 89 | * GTY Options:: What goes inside a @code{GTY(())}. |
1ed5a6cc | 90 | * Inheritance and GTY:: Adding GTY to a class hierarchy. |
0823efed | 91 | * User GC:: Adding user-provided GC marking routines. |
40bf31ed | 92 | * GGC Roots:: Making global variables GGC roots. |
6ccde948 | 93 | * Files:: How the generated files work. |
7de2b688 | 94 | * Invoking the garbage collector:: How to invoke the garbage collector. |
e65f1db7 | 95 | * Troubleshooting:: When something does not work as expected. |
1431042e ZW |
96 | @end menu |
97 | ||
98 | @node GTY Options | |
99 | @section The Inside of a @code{GTY(())} | |
100 | ||
101 | Sometimes the C code is not enough to fully describe the type | |
102 | structure. Extra information can be provided with @code{GTY} options | |
103 | and additional markers. Some options take a parameter, which may be | |
104 | either a string or a type name, depending on the parameter. If an | |
105 | option takes no parameter, it is acceptable either to omit the | |
106 | parameter entirely, or to provide an empty string as a parameter. For | |
107 | example, @code{@w{GTY ((skip))}} and @code{@w{GTY ((skip ("")))}} are | |
108 | equivalent. | |
e2500fed | 109 | |
1431042e ZW |
110 | When the parameter is a string, often it is a fragment of C code. Four |
111 | special escapes may be used in these strings, to refer to pieces of | |
112 | the data structure being marked: | |
e2500fed GK |
113 | |
114 | @cindex % in GTY option | |
115 | @table @code | |
116 | @item %h | |
1431042e | 117 | The current structure. |
e2500fed | 118 | @item %1 |
1431042e | 119 | The structure that immediately contains the current structure. |
e2500fed | 120 | @item %0 |
1431042e | 121 | The outermost structure that contains the current structure. |
36a5eadd | 122 | @item %a |
923158be | 123 | A partial expression of the form @code{[i1][i2]@dots{}} that indexes |
1431042e | 124 | the array item currently being marked. |
e2500fed GK |
125 | @end table |
126 | ||
1431042e ZW |
127 | For instance, suppose that you have a structure of the form |
128 | @smallexample | |
129 | struct A @{ | |
923158be | 130 | @dots{} |
1431042e ZW |
131 | @}; |
132 | struct B @{ | |
133 | struct A foo[12]; | |
134 | @}; | |
135 | @end smallexample | |
136 | @noindent | |
137 | and @code{b} is a variable of type @code{struct B}. When marking | |
138 | @samp{b.foo[11]}, @code{%h} would expand to @samp{b.foo[11]}, | |
139 | @code{%0} and @code{%1} would both expand to @samp{b}, and @code{%a} | |
140 | would expand to @samp{[11]}. | |
141 | ||
142 | As in ordinary C, adjacent strings will be concatenated; this is | |
143 | helpful when you have a complicated expression. | |
144 | @smallexample | |
145 | @group | |
146 | GTY ((chain_next ("TREE_CODE (&%h.generic) == INTEGER_TYPE" | |
147 | " ? TYPE_NEXT_VARIANT (&%h.generic)" | |
148 | " : TREE_CHAIN (&%h.generic)"))) | |
149 | @end group | |
150 | @end smallexample | |
151 | ||
e2500fed GK |
152 | The available options are: |
153 | ||
154 | @table @code | |
155 | @findex length | |
1431042e | 156 | @item length ("@var{expression}") |
e2500fed GK |
157 | |
158 | There are two places the type machinery will need to be explicitly told | |
c0fd3497 LB |
159 | the length of an array of non-atomic objects. The first case is when a |
160 | structure ends in a variable-length array, like this: | |
1431042e | 161 | @smallexample |
d1b38208 | 162 | struct GTY(()) rtvec_def @{ |
6ccde948 | 163 | int num_elem; /* @r{number of elements} */ |
e2500fed | 164 | rtx GTY ((length ("%h.num_elem"))) elem[1]; |
1431042e ZW |
165 | @}; |
166 | @end smallexample | |
167 | ||
e2500fed GK |
168 | In this case, the @code{length} option is used to override the specified |
169 | array length (which should usually be @code{1}). The parameter of the | |
170 | option is a fragment of C code that calculates the length. | |
171 | ||
172 | The second case is when a structure or a global variable contains a | |
173 | pointer to an array, like this: | |
478c9e72 | 174 | @smallexample |
a9429e29 | 175 | struct gimple_omp_for_iter * GTY((length ("%h.collapse"))) iter; |
478c9e72 | 176 | @end smallexample |
a9429e29 | 177 | In this case, @code{iter} has been allocated by writing something like |
478c9e72 | 178 | @smallexample |
a9429e29 | 179 | x->iter = ggc_alloc_cleared_vec_gimple_omp_for_iter (collapse); |
478c9e72 | 180 | @end smallexample |
a9429e29 | 181 | and the @code{collapse} provides the length of the field. |
e2500fed GK |
182 | |
183 | This second use of @code{length} also works on global variables, like: | |
184 | @verbatim | |
a9429e29 | 185 | static GTY((length("reg_known_value_size"))) rtx *reg_known_value; |
e2500fed GK |
186 | @end verbatim |
187 | ||
c0fd3497 LB |
188 | Note that the @code{length} option is only meant for use with arrays of |
189 | non-atomic objects, that is, objects that contain pointers pointing to | |
190 | other GTY-managed objects. For other GC-allocated arrays and strings | |
191 | you should use @code{atomic}. | |
192 | ||
e2500fed GK |
193 | @findex skip |
194 | @item skip | |
195 | ||
196 | If @code{skip} is applied to a field, the type machinery will ignore it. | |
197 | This is somewhat dangerous; the only safe use is in a union when one | |
198 | field really isn't ever used. | |
199 | ||
2a22f99c TS |
200 | @findex for_user |
201 | Use this to mark types that need to be marked by user gc routines, but are not | |
202 | refered to in a template argument. So if you have some user gc type T1 and a | |
203 | non user gc type T2 you can give T2 the for_user option so that the marking | |
204 | functions for T1 can call non mangled functions to mark T2. | |
205 | ||
e2500fed GK |
206 | @findex desc |
207 | @findex tag | |
36a5eadd | 208 | @findex default |
1431042e ZW |
209 | @item desc ("@var{expression}") |
210 | @itemx tag ("@var{constant}") | |
36a5eadd | 211 | @itemx default |
e2500fed GK |
212 | |
213 | The type machinery needs to be told which field of a @code{union} is | |
aef6a624 RK |
214 | currently active. This is done by giving each field a constant |
215 | @code{tag} value, and then specifying a discriminator using @code{desc}. | |
216 | The value of the expression given by @code{desc} is compared against | |
217 | each @code{tag} value, each of which should be different. If no | |
218 | @code{tag} is matched, the field marked with @code{default} is used if | |
219 | there is one, otherwise no field in the union will be marked. | |
220 | ||
221 | In the @code{desc} option, the ``current structure'' is the union that | |
222 | it discriminates. Use @code{%1} to mean the structure containing it. | |
1431042e ZW |
223 | There are no escapes available to the @code{tag} option, since it is a |
224 | constant. | |
aef6a624 RK |
225 | |
226 | For example, | |
478c9e72 | 227 | @smallexample |
d1b38208 | 228 | struct GTY(()) tree_binding |
478c9e72 | 229 | @{ |
e2500fed | 230 | struct tree_common common; |
478c9e72 | 231 | union tree_binding_u @{ |
e2500fed GK |
232 | tree GTY ((tag ("0"))) scope; |
233 | struct cp_binding_level * GTY ((tag ("1"))) level; | |
aef6a624 | 234 | @} GTY ((desc ("BINDING_HAS_LEVEL_P ((tree)&%0)"))) xscope; |
e2500fed | 235 | tree value; |
478c9e72 JJ |
236 | @}; |
237 | @end smallexample | |
e2500fed | 238 | |
aef6a624 RK |
239 | In this example, the value of BINDING_HAS_LEVEL_P when applied to a |
240 | @code{struct tree_binding *} is presumed to be 0 or 1. If 1, the type | |
241 | mechanism will treat the field @code{level} as being present and if 0, | |
242 | will treat the field @code{scope} as being present. | |
e2500fed | 243 | |
1ed5a6cc DM |
244 | The @code{desc} and @code{tag} options can also be used for inheritance |
245 | to denote which subclass an instance is. See @ref{Inheritance and GTY} | |
246 | for more information. | |
247 | ||
aebf76a2 TS |
248 | @findex cache |
249 | @item cache | |
250 | ||
251 | When the @code{cache} option is applied to a global variable gt_clear_cache is | |
252 | called on that variable between the mark and sweep phases of garbage | |
253 | collection. The gt_clear_cache function is free to mark blocks as used, or to | |
254 | clear pointers in the variable. | |
255 | ||
e2500fed GK |
256 | @findex deletable |
257 | @item deletable | |
258 | ||
259 | @code{deletable}, when applied to a global variable, indicates that when | |
260 | garbage collection runs, there's no need to mark anything pointed to | |
261 | by this variable, it can just be set to @code{NULL} instead. This is used | |
262 | to keep a list of free structures around for re-use. | |
263 | ||
8d6419b2 BS |
264 | @findex mark_hook |
265 | @item mark_hook ("@var{hook-routine-name}") | |
266 | ||
267 | If provided for a structure or union type, the given | |
268 | @var{hook-routine-name} (between double-quotes) is the name of a | |
269 | routine called when the garbage collector has just marked the data as | |
270 | reachable. This routine should not change the data, or call any ggc | |
271 | routine. Its only argument is a pointer to the just marked (const) | |
272 | structure or union. | |
273 | ||
e2500fed GK |
274 | @findex maybe_undef |
275 | @item maybe_undef | |
276 | ||
277 | When applied to a field, @code{maybe_undef} indicates that it's OK if | |
278 | the structure that this fields points to is never defined, so long as | |
279 | this field is always @code{NULL}. This is used to avoid requiring | |
280 | backends to define certain optional structures. It doesn't work with | |
281 | language frontends. | |
282 | ||
b453c95f GK |
283 | @findex nested_ptr |
284 | @item nested_ptr (@var{type}, "@var{to expression}", "@var{from expression}") | |
285 | ||
286 | The type machinery expects all pointers to point to the start of an | |
287 | object. Sometimes for abstraction purposes it's convenient to have | |
288 | a pointer which points inside an object. So long as it's possible to | |
289 | convert the original object to and from the pointer, such pointers | |
290 | can still be used. @var{type} is the type of the original object, | |
291 | the @var{to expression} returns the pointer given the original object, | |
292 | and the @var{from expression} returns the original object given | |
293 | the pointer. The pointer will be available using the @code{%h} | |
294 | escape. | |
295 | ||
17211ab5 GK |
296 | @findex chain_next |
297 | @findex chain_prev | |
623f8e39 | 298 | @findex chain_circular |
1431042e ZW |
299 | @item chain_next ("@var{expression}") |
300 | @itemx chain_prev ("@var{expression}") | |
623f8e39 | 301 | @itemx chain_circular ("@var{expression}") |
17211ab5 GK |
302 | |
303 | It's helpful for the type machinery to know if objects are often | |
304 | chained together in long lists; this lets it generate code that uses | |
305 | less stack space by iterating along the list instead of recursing down | |
306 | it. @code{chain_next} is an expression for the next item in the list, | |
1431042e ZW |
307 | @code{chain_prev} is an expression for the previous item. For singly |
308 | linked lists, use only @code{chain_next}; for doubly linked lists, use | |
309 | both. The machinery requires that taking the next item of the | |
623f8e39 JJ |
310 | previous item gives the original item. @code{chain_circular} is similar |
311 | to @code{chain_next}, but can be used for circular single linked lists. | |
17211ab5 GK |
312 | |
313 | @findex reorder | |
1431042e | 314 | @item reorder ("@var{function name}") |
17211ab5 GK |
315 | |
316 | Some data structures depend on the relative ordering of pointers. If | |
1431042e ZW |
317 | the precompiled header machinery needs to change that ordering, it |
318 | will call the function referenced by the @code{reorder} option, before | |
319 | changing the pointers in the object that's pointed to by the field the | |
320 | option applies to. The function must take four arguments, with the | |
321 | signature @samp{@w{void *, void *, gt_pointer_operator, void *}}. | |
322 | The first parameter is a pointer to the structure that contains the | |
323 | object being updated, or the object itself if there is no containing | |
324 | structure. The second parameter is a cookie that should be ignored. | |
325 | The third parameter is a routine that, given a pointer, will update it | |
326 | to its correct new value. The fourth parameter is a cookie that must | |
327 | be passed to the second parameter. | |
328 | ||
329 | PCH cannot handle data structures that depend on the absolute values | |
330 | of pointers. @code{reorder} functions can be expensive. When | |
331 | possible, it is better to depend on properties of the data, like an ID | |
332 | number or the hash of a string instead. | |
17211ab5 | 333 | |
555c3771 NP |
334 | @findex atomic |
335 | @item atomic | |
336 | ||
337 | The @code{atomic} option can only be used with pointers. It informs | |
338 | the GC machinery that the memory that the pointer points to does not | |
339 | contain any pointers, and hence it should be treated by the GC and PCH | |
340 | machinery as an ``atomic'' block of memory that does not need to be | |
341 | examined when scanning memory for pointers. In particular, the | |
342 | machinery will not scan that memory for pointers to mark them as | |
343 | reachable (when marking pointers for GC) or to relocate them (when | |
344 | writing a PCH file). | |
345 | ||
346 | The @code{atomic} option differs from the @code{skip} option. | |
347 | @code{atomic} keeps the memory under Garbage Collection, but makes the | |
348 | GC ignore the contents of the memory. @code{skip} is more drastic in | |
349 | that it causes the pointer and the memory to be completely ignored by | |
350 | the Garbage Collector. So, memory marked as @code{atomic} is | |
351 | automatically freed when no longer reachable, while memory marked as | |
352 | @code{skip} is not. | |
353 | ||
354 | The @code{atomic} option must be used with great care, because all | |
355 | sorts of problem can occur if used incorrectly, that is, if the memory | |
356 | the pointer points to does actually contain a pointer. | |
357 | ||
358 | Here is an example of how to use it: | |
359 | @smallexample | |
360 | struct GTY(()) my_struct @{ | |
361 | int number_of_elements; | |
c0fd3497 | 362 | unsigned int * GTY ((atomic)) elements; |
555c3771 NP |
363 | @}; |
364 | @end smallexample | |
365 | In this case, @code{elements} is a pointer under GC, and the memory it | |
366 | points to needs to be allocated using the Garbage Collector, and will | |
367 | be freed automatically by the Garbage Collector when it is no longer | |
368 | referenced. But the memory that the pointer points to is an array of | |
369 | @code{unsigned int} elements, and the GC must not try to scan it to | |
370 | find pointers to mark or relocate, which is why it is marked with the | |
371 | @code{atomic} option. | |
372 | ||
373 | Note that, currently, global variables can not be marked with | |
374 | @code{atomic}; only fields of a struct can. This is a known | |
375 | limitation. It would be useful to be able to mark global pointers | |
376 | with @code{atomic} to make the PCH machinery aware of them so that | |
377 | they are saved and restored correctly to PCH files. | |
378 | ||
e2500fed | 379 | @findex special |
1431042e | 380 | @item special ("@var{name}") |
e2500fed | 381 | |
1431042e ZW |
382 | The @code{special} option is used to mark types that have to be dealt |
383 | with by special case machinery. The parameter is the name of the | |
384 | special case. See @file{gengtype.c} for further details. Avoid | |
385 | adding new special cases unless there is no other alternative. | |
0823efed DN |
386 | |
387 | @findex user | |
388 | @item user | |
389 | ||
390 | The @code{user} option indicates that the code to mark structure | |
391 | fields is completely handled by user-provided routines. See section | |
392 | @ref{User GC} for details on what functions need to be provided. | |
e2500fed GK |
393 | @end table |
394 | ||
1ed5a6cc DM |
395 | @node Inheritance and GTY |
396 | @section Support for inheritance | |
397 | gengtype has some support for simple class hierarchies. You can use | |
398 | this to have gengtype autogenerate marking routines, provided: | |
399 | ||
400 | @itemize @bullet | |
401 | @item | |
402 | There must be a concrete base class, with a discriminator expression | |
403 | that can be used to identify which subclass an instance is. | |
404 | @item | |
405 | Only single inheritance is used. | |
406 | @item | |
407 | None of the classes within the hierarchy are templates. | |
408 | @end itemize | |
409 | ||
410 | If your class hierarchy does not fit in this pattern, you must use | |
411 | @ref{User GC} instead. | |
412 | ||
413 | The base class and its discriminator must be identified using the ``desc'' | |
414 | option. Each concrete subclass must use the ``tag'' option to identify | |
415 | which value of the discriminator it corresponds to. | |
416 | ||
32fe5271 DM |
417 | Every class in the hierarchy must have a @code{GTY(())} marker, as |
418 | gengtype will only attempt to parse classes that have such a marker | |
419 | @footnote{Classes lacking such a marker will not be identified as being | |
420 | part of the hierarchy, and so the marking routines will not handle them, | |
421 | leading to a assertion failure within the marking routines due to an | |
422 | unknown tag value (assuming that assertions are enabled).}. | |
423 | ||
1ed5a6cc DM |
424 | @smallexample |
425 | class GTY((desc("%h.kind"), tag("0"))) example_base | |
426 | @{ | |
427 | public: | |
428 | int kind; | |
429 | tree a; | |
430 | @}; | |
431 | ||
381846b1 | 432 | class GTY((tag("1"))) some_subclass : public example_base |
1ed5a6cc DM |
433 | @{ |
434 | public: | |
435 | tree b; | |
436 | @}; | |
437 | ||
381846b1 | 438 | class GTY((tag("2"))) some_other_subclass : public example_base |
1ed5a6cc DM |
439 | @{ |
440 | public: | |
441 | tree c; | |
442 | @}; | |
443 | @end smallexample | |
444 | ||
445 | The generated marking routines for the above will contain a ``switch'' | |
446 | on ``kind'', visiting all appropriate fields. For example, if kind is | |
447 | 2, it will cast to ``some_other_subclass'' and visit fields a, b, and c. | |
448 | ||
0823efed DN |
449 | @node User GC |
450 | @section Support for user-provided GC marking routines | |
451 | @cindex user gc | |
452 | The garbage collector supports types for which no automatic marking | |
453 | code is generated. For these types, the user is required to provide | |
454 | three functions: one to act as a marker for garbage collection, and | |
455 | two functions to act as marker and pointer walker for pre-compiled | |
456 | headers. | |
457 | ||
458 | Given a structure @code{struct GTY((user)) my_struct}, the following functions | |
459 | should be defined to mark @code{my_struct}: | |
460 | ||
461 | @smallexample | |
462 | void gt_ggc_mx (my_struct *p) | |
463 | @{ | |
464 | /* This marks field 'fld'. */ | |
465 | gt_ggc_mx (p->fld); | |
466 | @} | |
467 | ||
468 | void gt_pch_nx (my_struct *p) | |
469 | @{ | |
470 | /* This marks field 'fld'. */ | |
471 | gt_pch_nx (tp->fld); | |
472 | @} | |
473 | ||
474 | void gt_pch_nx (my_struct *p, gt_pointer_operator op, void *cookie) | |
475 | @{ | |
476 | /* For every field 'fld', call the given pointer operator. */ | |
477 | op (&(tp->fld), cookie); | |
478 | @} | |
479 | @end smallexample | |
480 | ||
481 | In general, each marker @code{M} should call @code{M} for every | |
482 | pointer field in the structure. Fields that are not allocated in GC | |
483 | or are not pointers must be ignored. | |
484 | ||
485 | For embedded lists (e.g., structures with a @code{next} or @code{prev} | |
486 | pointer), the marker must follow the chain and mark every element in | |
487 | it. | |
488 | ||
489 | Note that the rules for the pointer walker @code{gt_pch_nx (my_struct | |
490 | *, gt_pointer_operator, void *)} are slightly different. In this | |
491 | case, the operation @code{op} must be applied to the @emph{address} of | |
492 | every pointer field. | |
493 | ||
40bf31ed | 494 | @subsection User-provided marking routines for template types |
0823efed DN |
495 | When a template type @code{TP} is marked with @code{GTY}, all |
496 | instances of that type are considered user-provided types. This means | |
497 | that the individual instances of @code{TP} do not need to be marked | |
498 | with @code{GTY}. The user needs to provide template functions to mark | |
499 | all the fields of the type. | |
500 | ||
501 | The following code snippets represent all the functions that need to | |
502 | be provided. Note that type @code{TP} may reference to more than one | |
503 | type. In these snippets, there is only one type @code{T}, but there | |
504 | could be more. | |
505 | ||
506 | @smallexample | |
507 | template<typename T> | |
508 | void gt_ggc_mx (TP<T> *tp) | |
509 | @{ | |
510 | extern void gt_ggc_mx (T&); | |
511 | ||
512 | /* This marks field 'fld' of type 'T'. */ | |
513 | gt_ggc_mx (tp->fld); | |
514 | @} | |
515 | ||
516 | template<typename T> | |
517 | void gt_pch_nx (TP<T> *tp) | |
518 | @{ | |
519 | extern void gt_pch_nx (T&); | |
520 | ||
521 | /* This marks field 'fld' of type 'T'. */ | |
522 | gt_pch_nx (tp->fld); | |
523 | @} | |
524 | ||
525 | template<typename T> | |
526 | void gt_pch_nx (TP<T *> *tp, gt_pointer_operator op, void *cookie) | |
527 | @{ | |
528 | /* For every field 'fld' of 'tp' with type 'T *', call the given | |
529 | pointer operator. */ | |
530 | op (&(tp->fld), cookie); | |
531 | @} | |
532 | ||
533 | template<typename T> | |
534 | void gt_pch_nx (TP<T> *tp, gt_pointer_operator, void *cookie) | |
535 | @{ | |
536 | extern void gt_pch_nx (T *, gt_pointer_operator, void *); | |
537 | ||
538 | /* For every field 'fld' of 'tp' with type 'T', call the pointer | |
539 | walker for all the fields of T. */ | |
540 | gt_pch_nx (&(tp->fld), op, cookie); | |
541 | @} | |
542 | @end smallexample | |
543 | ||
544 | Support for user-defined types is currently limited. The following | |
545 | restrictions apply: | |
546 | ||
547 | @enumerate | |
548 | @item Type @code{TP} and all the argument types @code{T} must be | |
549 | marked with @code{GTY}. | |
550 | ||
551 | @item Type @code{TP} can only have type names in its argument list. | |
552 | ||
553 | @item The pointer walker functions are different for @code{TP<T>} and | |
554 | @code{TP<T *>}. In the case of @code{TP<T>}, references to | |
555 | @code{T} must be handled by calling @code{gt_pch_nx} (which | |
556 | will, in turn, walk all the pointers inside fields of @code{T}). | |
557 | In the case of @code{TP<T *>}, references to @code{T *} must be | |
558 | handled by calling the @code{op} function on the address of the | |
559 | pointer (see the code snippets above). | |
560 | @end enumerate | |
561 | ||
e2500fed GK |
562 | @node GGC Roots |
563 | @section Marking Roots for the Garbage Collector | |
564 | @cindex roots, marking | |
565 | @cindex marking roots | |
566 | ||
567 | In addition to keeping track of types, the type machinery also locates | |
1431042e ZW |
568 | the global variables (@dfn{roots}) that the garbage collector starts |
569 | at. Roots must be declared using one of the following syntaxes: | |
e2500fed | 570 | |
1431042e | 571 | @itemize @bullet |
e2500fed | 572 | @item |
1431042e | 573 | @code{extern GTY(([@var{options}])) @var{type} @var{name};} |
e2500fed | 574 | @item |
1431042e ZW |
575 | @code{static GTY(([@var{options}])) @var{type} @var{name};} |
576 | @end itemize | |
577 | @noindent | |
578 | The syntax | |
579 | @itemize @bullet | |
580 | @item | |
581 | @code{GTY(([@var{options}])) @var{type} @var{name};} | |
582 | @end itemize | |
583 | @noindent | |
584 | is @emph{not} accepted. There should be an @code{extern} declaration | |
585 | of such a variable in a header somewhere---mark that, not the | |
586 | definition. Or, if the variable is only used in one file, make it | |
587 | @code{static}. | |
cba57c9d | 588 | |
e2500fed GK |
589 | @node Files |
590 | @section Source Files Containing Type Information | |
591 | @cindex generated files | |
592 | @cindex files, generated | |
593 | ||
1431042e ZW |
594 | Whenever you add @code{GTY} markers to a source file that previously |
595 | had none, or create a new source file containing @code{GTY} markers, | |
596 | there are three things you need to do: | |
e2500fed GK |
597 | |
598 | @enumerate | |
599 | @item | |
8ac9d31f | 600 | You need to add the file to the list of source files the type |
1431042e | 601 | machinery scans. There are four cases: |
8ac9d31f TJ |
602 | |
603 | @enumerate a | |
604 | @item | |
605 | For a back-end file, this is usually done | |
ef69da62 | 606 | automatically; if not, you should add it to @code{target_gtfiles} in |
daf2f129 | 607 | the appropriate port's entries in @file{config.gcc}. |
8ac9d31f TJ |
608 | |
609 | @item | |
1431042e ZW |
610 | For files shared by all front ends, add the filename to the |
611 | @code{GTFILES} variable in @file{Makefile.in}. | |
e2500fed | 612 | |
daf2f129 | 613 | @item |
1431042e ZW |
614 | For files that are part of one front end, add the filename to the |
615 | @code{gtfiles} variable defined in the appropriate | |
d4a10d0a | 616 | @file{config-lang.in}. |
105f48ae | 617 | Headers should appear before non-headers in this list. |
8ac9d31f | 618 | |
1431042e ZW |
619 | @item |
620 | For files that are part of some but not all front ends, add the | |
621 | filename to the @code{gtfiles} variable of @emph{all} the front ends | |
622 | that use it. | |
8ac9d31f TJ |
623 | @end enumerate |
624 | ||
e2500fed | 625 | @item |
cba57c9d GK |
626 | If the file was a header file, you'll need to check that it's included |
627 | in the right place to be visible to the generated files. For a back-end | |
628 | header file, this should be done automatically. For a front-end header | |
629 | file, it needs to be included by the same file that includes | |
630 | @file{gtype-@var{lang}.h}. For other header files, it needs to be | |
631 | included in @file{gtype-desc.c}, which is a generated file, so add it to | |
daf2f129 | 632 | @code{ifiles} in @code{open_base_file} in @file{gengtype.c}. |
cba57c9d GK |
633 | |
634 | For source files that aren't header files, the machinery will generate a | |
635 | header file that should be included in the source file you just changed. | |
636 | The file will be called @file{gt-@var{path}.h} where @var{path} is the | |
637 | pathname relative to the @file{gcc} directory with slashes replaced by | |
638 | @verb{|-|}, so for example the header file to be included in | |
da543234 | 639 | @file{cp/parser.c} is called @file{gt-cp-parser.c}. The |
cba57c9d GK |
640 | generated header file should be included after everything else in the |
641 | source file. Don't forget to mention this file as a dependency in the | |
642 | @file{Makefile}! | |
e2500fed | 643 | |
e2500fed GK |
644 | @end enumerate |
645 | ||
646 | For language frontends, there is another file that needs to be included | |
647 | somewhere. It will be called @file{gtype-@var{lang}.h}, where | |
648 | @var{lang} is the name of the subdirectory the language is contained in. | |
7de2b688 | 649 | |
bd117bb6 | 650 | Plugins can add additional root tables. Run the @code{gengtype} |
9b39cba9 | 651 | utility in plugin mode as @code{gengtype -P pluginout.h @var{source-dir} |
bd117bb6 | 652 | @var{file-list} @var{plugin*.c}} with your plugin files |
9b39cba9 BS |
653 | @var{plugin*.c} using @code{GTY} to generate the @var{pluginout.h} file. |
654 | The GCC build tree is needed to be present in that mode. | |
bd117bb6 BS |
655 | |
656 | ||
7de2b688 BS |
657 | @node Invoking the garbage collector |
658 | @section How to invoke the garbage collector | |
659 | @cindex garbage collector, invocation | |
660 | @findex ggc_collect | |
661 | ||
662 | The GCC garbage collector GGC is only invoked explicitly. In contrast | |
663 | with many other garbage collectors, it is not implicitly invoked by | |
664 | allocation routines when a lot of memory has been consumed. So the | |
fb489f55 | 665 | only way to have GGC reclaim storage is to call the @code{ggc_collect} |
e65f1db7 LB |
666 | function explicitly. This call is an expensive operation, as it may |
667 | have to scan the entire heap. Beware that local variables (on the GCC | |
7de2b688 BS |
668 | call stack) are not followed by such an invocation (as many other |
669 | garbage collectors do): you should reference all your data from static | |
670 | or external @code{GTY}-ed variables, and it is advised to call | |
e65f1db7 | 671 | @code{ggc_collect} with a shallow call stack. The GGC is an exact mark |
7de2b688 | 672 | and sweep garbage collector (so it does not scan the call stack for |
e65f1db7 | 673 | pointers). In practice GCC passes don't often call @code{ggc_collect} |
7de2b688 | 674 | themselves, because it is called by the pass manager between passes. |
e65f1db7 LB |
675 | |
676 | At the time of the @code{ggc_collect} call all pointers in the GC-marked | |
677 | structures must be valid or @code{NULL}. In practice this means that | |
678 | there should not be uninitialized pointer fields in the structures even | |
679 | if your code never reads or writes those fields at a particular | |
680 | instance. One way to ensure this is to use cleared versions of | |
681 | allocators unless all the fields are initialized manually immediately | |
682 | after allocation. | |
683 | ||
684 | @node Troubleshooting | |
685 | @section Troubleshooting the garbage collector | |
686 | @cindex garbage collector, troubleshooting | |
687 | ||
688 | With the current garbage collector implementation, most issues should | |
689 | show up as GCC compilation errors. Some of the most commonly | |
690 | encountered issues are described below. | |
691 | ||
692 | @itemize @bullet | |
693 | @item Gengtype does not produce allocators for a @code{GTY}-marked type. | |
694 | Gengtype checks if there is at least one possible path from GC roots to | |
695 | at least one instance of each type before outputting allocators. If | |
696 | there is no such path, the @code{GTY} markers will be ignored and no | |
697 | allocators will be output. Solve this by making sure that there exists | |
698 | at least one such path. If creating it is unfeasible or raises a ``code | |
699 | smell'', consider if you really must use GC for allocating such type. | |
700 | ||
701 | @item Link-time errors about undefined @code{gt_ggc_r_foo_bar} and | |
702 | similarly-named symbols. Check if your @file{foo_bar} source file has | |
703 | @code{#include "gt-foo_bar.h"} as its very last line. | |
704 | ||
705 | @end itemize |