Debian Codegraph @

gcc/doc/gty.texi

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