aboutsummaryrefslogtreecommitdiff
path: root/gcc/doc/gty.texi
blob: 54809f1a09e7e4f79fc091c99cc3bdc0fac4f6dd (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
@c Copyright (C) 2002-2017 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.

@node Type Information
@chapter Memory Management and Type Information
@cindex GGC
@findex GTY

GCC uses some fairly sophisticated memory management techniques, which
involve determining information about GCC's data structures from GCC's
source code and using this information to perform garbage collection and
implement precompiled headers.

A full C++ parser would be too complicated for this task, so a limited
subset of C++ is interpreted and special markers are used to determine
what parts of the source to look at.  All @code{struct}, @code{union}
and @code{template} structure declarations that define data structures
that are allocated under control of the garbage collector must be
marked.  All global variables that hold pointers to garbage-collected
memory must also be marked.  Finally, all global variables that need
to be saved and restored by a precompiled header must be marked.  (The
precompiled header mechanism can only save static variables if they're
scalar. Complex data structures must be allocated in garbage-collected
memory to be saved in a precompiled header.)

The full format of a marker is
@smallexample
GTY (([@var{option}] [(@var{param})], [@var{option}] [(@var{param})] @dots{}))
@end smallexample
@noindent
but in most cases no options are needed.  The outer double parentheses
are still necessary, though: @code{GTY(())}.  Markers can appear:

@itemize @bullet
@item
In a structure definition, before the open brace;
@item
In a global variable declaration, after the keyword @code{static} or
@code{extern}; and
@item
In a structure field definition, before the name of the field.
@end itemize

Here are some examples of marking simple data structures and globals.

@smallexample
struct GTY(()) @var{tag}
@{
  @var{fields}@dots{}
@};

typedef struct GTY(()) @var{tag}
@{
  @var{fields}@dots{}
@} *@var{typename};

static GTY(()) struct @var{tag} *@var{list};   /* @r{points to GC memory} */
static GTY(()) int @var{counter};        /* @r{save counter in a PCH} */
@end smallexample

The parser understands simple typedefs such as
@code{typedef struct @var{tag} *@var{name};} and
@code{typedef int @var{name};}.
These don't need to be marked.

Since @code{gengtype}'s understanding of C++ is limited, there are
several constructs and declarations that are not supported inside
classes/structures marked for automatic GC code generation.  The
following C++ constructs produce a @code{gengtype} error on
structures/classes marked for automatic GC code generation:

@itemize @bullet
@item
Type definitions inside classes/structures are not supported.
@item
Enumerations inside classes/structures are not supported.
@end itemize

If you have a class or structure using any of the above constructs,
you need to mark that class as @code{GTY ((user))} and provide your
own marking routines (see section @ref{User GC} for details).

It is always valid to include function definitions inside classes.
Those are always ignored by @code{gengtype}, as it only cares about
data members.

@menu
* GTY Options::         What goes inside a @code{GTY(())}.
* Inheritance and GTY:: Adding GTY to a class hierarchy.
* User GC::		Adding user-provided GC marking routines.
* GGC Roots::           Making global variables GGC roots.
* Files::               How the generated files work.
* Invoking the garbage collector::   How to invoke the garbage collector.
* Troubleshooting::     When something does not work as expected.
@end menu

@node GTY Options
@section The Inside of a @code{GTY(())}

Sometimes the C code is not enough to fully describe the type
structure.  Extra information can be provided with @code{GTY} options
and additional markers.  Some options take a parameter, which may be
either a string or a type name, depending on the parameter.  If an
option takes no parameter, it is acceptable either to omit the
parameter entirely, or to provide an empty string as a parameter.  For
example, @code{@w{GTY ((skip))}} and @code{@w{GTY ((skip ("")))}} are
equivalent.

When the parameter is a string, often it is a fragment of C code.  Four
special escapes may be used in these strings, to refer to pieces of
the data structure being marked:

@cindex % in GTY option
@table @code
@item %h
The current structure.
@item %1
The structure that immediately contains the current structure.
@item %0
The outermost structure that contains the current structure.
@item %a
A partial expression of the form @code{[i1][i2]@dots{}} that indexes
the array item currently being marked.
@end table

For instance, suppose that you have a structure of the form
@smallexample
struct A @{
  @dots{}
@};
struct B @{
  struct A foo[12];
@};
@end smallexample
@noindent
and @code{b} is a variable of type @code{struct B}.  When marking
@samp{b.foo[11]}, @code{%h} would expand to @samp{b.foo[11]},
@code{%0} and @code{%1} would both expand to @samp{b}, and @code{%a}
would expand to @samp{[11]}.

As in ordinary C, adjacent strings will be concatenated; this is
helpful when you have a complicated expression.
@smallexample
@group
GTY ((chain_next ("TREE_CODE (&%h.generic) == INTEGER_TYPE"
                  " ? TYPE_NEXT_VARIANT (&%h.generic)"
                  " : TREE_CHAIN (&%h.generic)")))
@end group
@end smallexample

The available options are:

@table @code
@findex length
@item length ("@var{expression}")

There are two places the type machinery will need to be explicitly told
the length of an array of non-atomic objects.  The first case is when a
structure ends in a variable-length array, like this:
@smallexample
struct GTY(()) rtvec_def @{
  int num_elem;         /* @r{number of elements} */
  rtx GTY ((length ("%h.num_elem"))) elem[1];
@};
@end smallexample

In this case, the @code{length} option is used to override the specified
array length (which should usually be @code{1}).  The parameter of the
option is a fragment of C code that calculates the length.

The second case is when a structure or a global variable contains a
pointer to an array, like this:
@smallexample
struct gimple_omp_for_iter * GTY((length ("%h.collapse"))) iter;
@end smallexample
In this case, @code{iter} has been allocated by writing something like
@smallexample
  x->iter = ggc_alloc_cleared_vec_gimple_omp_for_iter (collapse);
@end smallexample
and the @code{collapse} provides the length of the field.

This second use of @code{length} also works on global variables, like:
@verbatim
static GTY((length("reg_known_value_size"))) rtx *reg_known_value;
@end verbatim

Note that the @code{length} option is only meant for use with arrays of
non-atomic objects, that is, objects that contain pointers pointing to
other GTY-managed objects.  For other GC-allocated arrays and strings
you should use @code{atomic}.

@findex skip
@item skip

If @code{skip} is applied to a field, the type machinery will ignore it.
This is somewhat dangerous; the only safe use is in a union when one
field really isn't ever used.

@findex for_user
@item for_user

Use this to mark types that need to be marked by user gc routines, but are not
refered to in a template argument.  So if you have some user gc type T1 and a
non user gc type T2 you can give T2 the for_user option so that the marking
functions for T1 can call non mangled functions to mark T2.

@findex desc
@findex tag
@findex default
@item desc ("@var{expression}")
@itemx tag ("@var{constant}")
@itemx default

The type machinery needs to be told which field of a @code{union} is
currently active.  This is done by giving each field a constant
@code{tag} value, and then specifying a discriminator using @code{desc}.
The value of the expression given by @code{desc} is compared against
each @code{tag} value, each of which should be different.  If no
@code{tag} is matched, the field marked with @code{default} is used if
there is one, otherwise no field in the union will be marked.

In the @code{desc} option, the ``current structure'' is the union that
it discriminates.  Use @code{%1} to mean the structure containing it.
There are no escapes available to the @code{tag} option, since it is a
constant.

For example,
@smallexample
struct GTY(()) tree_binding
@{
  struct tree_common common;
  union tree_binding_u @{
    tree GTY ((tag ("0"))) scope;
    struct cp_binding_level * GTY ((tag ("1"))) level;
  @} GTY ((desc ("BINDING_HAS_LEVEL_P ((tree)&%0)"))) xscope;
  tree value;
@};
@end smallexample

In this example, the value of BINDING_HAS_LEVEL_P when applied to a
@code{struct tree_binding *} is presumed to be 0 or 1.  If 1, the type
mechanism will treat the field @code{level} as being present and if 0,
will treat the field @code{scope} as being present.

The @code{desc} and @code{tag} options can also be used for inheritance
to denote which subclass an instance is.  See @ref{Inheritance and GTY}
for more information.

@findex cache
@item cache

When the @code{cache} option is applied to a global variable gt_clear_cache is
called on that variable between the mark and sweep phases of garbage
collection.  The gt_clear_cache function is free to mark blocks as used, or to
clear pointers in the variable.

@findex deletable
@item deletable

@code{deletable}, when applied to a global variable, indicates that when
garbage collection runs, there's no need to mark anything pointed to
by this variable, it can just be set to @code{NULL} instead.  This is used
to keep a list of free structures around for re-use.

@findex maybe_undef
@item maybe_undef

When applied to a field, @code{maybe_undef} indicates that it's OK if
the structure that this fields points to is never defined, so long as
this field is always @code{NULL}.  This is used to avoid requiring
backends to define certain optional structures.  It doesn't work with
language frontends.

@findex nested_ptr
@item nested_ptr (@var{type}, "@var{to expression}", "@var{from expression}")

The type machinery expects all pointers to point to the start of an
object.  Sometimes for abstraction purposes it's convenient to have
a pointer which points inside an object.  So long as it's possible to
convert the original object to and from the pointer, such pointers
can still be used.  @var{type} is the type of the original object,
the @var{to expression} returns the pointer given the original object,
and the @var{from expression} returns the original object given
the pointer.  The pointer will be available using the @code{%h}
escape.

@findex chain_next
@findex chain_prev
@findex chain_circular
@item chain_next ("@var{expression}")
@itemx chain_prev ("@var{expression}")
@itemx chain_circular ("@var{expression}")

It's helpful for the type machinery to know if objects are often
chained together in long lists; this lets it generate code that uses
less stack space by iterating along the list instead of recursing down
it.  @code{chain_next} is an expression for the next item in the list,
@code{chain_prev} is an expression for the previous item.  For singly
linked lists, use only @code{chain_next}; for doubly linked lists, use
both.  The machinery requires that taking the next item of the
previous item gives the original item.  @code{chain_circular} is similar
to @code{chain_next}, but can be used for circular single linked lists.

@findex reorder
@item reorder ("@var{function name}")

Some data structures depend on the relative ordering of pointers.  If
the precompiled header machinery needs to change that ordering, it
will call the function referenced by the @code{reorder} option, before
changing the pointers in the object that's pointed to by the field the
option applies to.  The function must take four arguments, with the
signature @samp{@w{void *, void *, gt_pointer_operator, void *}}.
The first parameter is a pointer to the structure that contains the
object being updated, or the object itself if there is no containing
structure.  The second parameter is a cookie that should be ignored.
The third parameter is a routine that, given a pointer, will update it
to its correct new value.  The fourth parameter is a cookie that must
be passed to the second parameter.

PCH cannot handle data structures that depend on the absolute values
of pointers.  @code{reorder} functions can be expensive.  When
possible, it is better to depend on properties of the data, like an ID
number or the hash of a string instead.

@findex atomic
@item atomic

The @code{atomic} option can only be used with pointers.  It informs
the GC machinery that the memory that the pointer points to does not
contain any pointers, and hence it should be treated by the GC and PCH
machinery as an ``atomic'' block of memory that does not need to be
examined when scanning memory for pointers.  In particular, the
machinery will not scan that memory for pointers to mark them as
reachable (when marking pointers for GC) or to relocate them (when
writing a PCH file).

The @code{atomic} option differs from the @code{skip} option.
@code{atomic} keeps the memory under Garbage Collection, but makes the
GC ignore the contents of the memory.  @code{skip} is more drastic in
that it causes the pointer and the memory to be completely ignored by
the Garbage Collector.  So, memory marked as @code{atomic} is
automatically freed when no longer reachable, while memory marked as
@code{skip} is not.

The @code{atomic} option must be used with great care, because all
sorts of problem can occur if used incorrectly, that is, if the memory
the pointer points to does actually contain a pointer.

Here is an example of how to use it:
@smallexample
struct GTY(()) my_struct @{
  int number_of_elements;
  unsigned int * GTY ((atomic)) elements;
@};
@end smallexample
In this case, @code{elements} is a pointer under GC, and the memory it
points to needs to be allocated using the Garbage Collector, and will
be freed automatically by the Garbage Collector when it is no longer
referenced.  But the memory that the pointer points to is an array of
@code{unsigned int} elements, and the GC must not try to scan it to
find pointers to mark or relocate, which is why it is marked with the
@code{atomic} option.

Note that, currently, global variables can not be marked with
@code{atomic}; only fields of a struct can.  This is a known
limitation.  It would be useful to be able to mark global pointers
with @code{atomic} to make the PCH machinery aware of them so that
they are saved and restored correctly to PCH files.

@findex special
@item special ("@var{name}")

The @code{special} option is used to mark types that have to be dealt
with by special case machinery.  The parameter is the name of the
special case.  See @file{gengtype.c} for further details.  Avoid
adding new special cases unless there is no other alternative.

@findex user
@item user

The @code{user} option indicates that the code to mark structure
fields is completely handled by user-provided routines.  See section
@ref{User GC} for details on what functions need to be provided.
@end table

@node Inheritance and GTY
@section Support for inheritance
gengtype has some support for simple class hierarchies.  You can use
this to have gengtype autogenerate marking routines, provided:

@itemize @bullet
@item
There must be a concrete base class, with a discriminator expression
that can be used to identify which subclass an instance is.
@item
Only single inheritance is used.
@item
None of the classes within the hierarchy are templates.
@end itemize

If your class hierarchy does not fit in this pattern, you must use
@ref{User GC} instead.

The base class and its discriminator must be identified using the ``desc''
option.  Each concrete subclass must use the ``tag'' option to identify
which value of the discriminator it corresponds to.

Every class in the hierarchy must have a @code{GTY(())} marker, as
gengtype will only attempt to parse classes that have such a marker
@footnote{Classes lacking such a marker will not be identified as being
part of the hierarchy, and so the marking routines will not handle them,
leading to a assertion failure within the marking routines due to an
unknown tag value (assuming that assertions are enabled).}.

@smallexample
class GTY((desc("%h.kind"), tag("0"))) example_base
@{
public:
    int kind;
    tree a;
@};

class GTY((tag("1"))) some_subclass : public example_base
@{
public:
    tree b;
@};

class GTY((tag("2"))) some_other_subclass : public example_base
@{
public:
    tree c;
@};
@end smallexample

The generated marking routines for the above will contain a ``switch''
on ``kind'', visiting all appropriate fields.  For example, if kind is
2, it will cast to ``some_other_subclass'' and visit fields a, b, and c.

@node User GC
@section Support for user-provided GC marking routines
@cindex user gc
The garbage collector supports types for which no automatic marking
code is generated.  For these types, the user is required to provide
three functions: one to act as a marker for garbage collection, and
two functions to act as marker and pointer walker for pre-compiled
headers.

Given a structure @code{struct GTY((user)) my_struct}, the following functions
should be defined to mark @code{my_struct}:

@smallexample
void gt_ggc_mx (my_struct *p)
@{
  /* This marks field 'fld'.  */
  gt_ggc_mx (p->fld);
@}

void gt_pch_nx (my_struct *p)
@{
  /* This marks field 'fld'.  */
  gt_pch_nx (tp->fld);
@}

void gt_pch_nx (my_struct *p, gt_pointer_operator op, void *cookie)
@{
  /* For every field 'fld', call the given pointer operator.  */
  op (&(tp->fld), cookie);
@}
@end smallexample

In general, each marker @code{M} should call @code{M} for every
pointer field in the structure.  Fields that are not allocated in GC
or are not pointers must be ignored.

For embedded lists (e.g., structures with a @code{next} or @code{prev}
pointer), the marker must follow the chain and mark every element in
it.

Note that the rules for the pointer walker @code{gt_pch_nx (my_struct
*, gt_pointer_operator, void *)} are slightly different.  In this
case, the operation @code{op} must be applied to the @emph{address} of
every pointer field.

@subsection User-provided marking routines for template types
When a template type @code{TP} is marked with @code{GTY}, all
instances of that type are considered user-provided types.  This means
that the individual instances of @code{TP} do not need to be marked
with @code{GTY}.  The user needs to provide template functions to mark
all the fields of the type.

The following code snippets represent all the functions that need to
be provided. Note that type @code{TP} may reference to more than one
type. In these snippets, there is only one type @code{T}, but there
could be more.

@smallexample
template<typename T>
void gt_ggc_mx (TP<T> *tp)
@{
  extern void gt_ggc_mx (T&);

  /* This marks field 'fld' of type 'T'.  */
  gt_ggc_mx (tp->fld);
@}

template<typename T>
void gt_pch_nx (TP<T> *tp)
@{
  extern void gt_pch_nx (T&);

  /* This marks field 'fld' of type 'T'.  */
  gt_pch_nx (tp->fld);
@}

template<typename T>
void gt_pch_nx (TP<T *> *tp, gt_pointer_operator op, void *cookie)
@{
  /* For every field 'fld' of 'tp' with type 'T *', call the given
     pointer operator.  */
  op (&(tp->fld), cookie);
@}

template<typename T>
void gt_pch_nx (TP<T> *tp, gt_pointer_operator, void *cookie)
@{
  extern void gt_pch_nx (T *, gt_pointer_operator, void *);

  /* For every field 'fld' of 'tp' with type 'T', call the pointer
     walker for all the fields of T.  */
  gt_pch_nx (&(tp->fld), op, cookie);
@}
@end smallexample

Support for user-defined types is currently limited. The following
restrictions apply:

@enumerate
@item Type @code{TP} and all the argument types @code{T} must be
marked with @code{GTY}.

@item Type @code{TP} can only have type names in its argument list.

@item The pointer walker functions are different for @code{TP<T>} and
@code{TP<T *>}. In the case of @code{TP<T>}, references to
@code{T} must be handled by calling @code{gt_pch_nx} (which
will, in turn, walk all the pointers inside fields of @code{T}).
In the case of @code{TP<T *>}, references to @code{T *} must be
handled by calling the @code{op} function on the address of the
pointer (see the code snippets above).
@end enumerate

@node GGC Roots
@section Marking Roots for the Garbage Collector
@cindex roots, marking
@cindex marking roots

In addition to keeping track of types, the type machinery also locates
the global variables (@dfn{roots}) that the garbage collector starts
at.  Roots must be declared using one of the following syntaxes:

@itemize @bullet
@item
@code{extern GTY(([@var{options}])) @var{type} @var{name};}
@item
@code{static GTY(([@var{options}])) @var{type} @var{name};}
@end itemize
@noindent
The syntax
@itemize @bullet
@item
@code{GTY(([@var{options}])) @var{type} @var{name};}
@end itemize
@noindent
is @emph{not} accepted.  There should be an @code{extern} declaration
of such a variable in a header somewhere---mark that, not the
definition.  Or, if the variable is only used in one file, make it
@code{static}.

@node Files
@section Source Files Containing Type Information
@cindex generated files
@cindex files, generated

Whenever you add @code{GTY} markers to a source file that previously
had none, or create a new source file containing @code{GTY} markers,
there are three things you need to do:

@enumerate
@item
You need to add the file to the list of source files the type
machinery scans.  There are four cases:

@enumerate a
@item
For a back-end file, this is usually done
automatically; if not, you should add it to @code{target_gtfiles} in
the appropriate port's entries in @file{config.gcc}.

@item
For files shared by all front ends, add the filename to the
@code{GTFILES} variable in @file{Makefile.in}.

@item
For files that are part of one front end, add the filename to the
@code{gtfiles} variable defined in the appropriate
@file{config-lang.in}.
Headers should appear before non-headers in this list.

@item
For files that are part of some but not all front ends, add the
filename to the @code{gtfiles} variable of @emph{all} the front ends
that use it.
@end enumerate

@item
If the file was a header file, you'll need to check that it's included
in the right place to be visible to the generated files.  For a back-end
header file, this should be done automatically.  For a front-end header
file, it needs to be included by the same file that includes
@file{gtype-@var{lang}.h}.  For other header files, it needs to be
included in @file{gtype-desc.c}, which is a generated file, so add it to
@code{ifiles} in @code{open_base_file} in @file{gengtype.c}.

For source files that aren't header files, the machinery will generate a
header file that should be included in the source file you just changed.
The file will be called @file{gt-@var{path}.h} where @var{path} is the
pathname relative to the @file{gcc} directory with slashes replaced by
@verb{|-|}, so for example the header file to be included in
@file{cp/parser.c} is called @file{gt-cp-parser.c}.  The
generated header file should be included after everything else in the
source file.  Don't forget to mention this file as a dependency in the
@file{Makefile}!

@end enumerate

For language frontends, there is another file that needs to be included
somewhere.  It will be called @file{gtype-@var{lang}.h}, where
@var{lang} is the name of the subdirectory the language is contained in.

Plugins can add additional root tables.  Run the @code{gengtype}
utility in plugin mode as @code{gengtype -P pluginout.h @var{source-dir}
@var{file-list} @var{plugin*.c}} with your plugin files
@var{plugin*.c} using @code{GTY} to generate the @var{pluginout.h} file.
The GCC build tree is needed to be present in that mode.


@node Invoking the garbage collector
@section How to invoke the garbage collector
@cindex garbage collector, invocation
@findex ggc_collect

The GCC garbage collector GGC is only invoked explicitly. In contrast
with many other garbage collectors, it is not implicitly invoked by
allocation routines when a lot of memory has been consumed. So the
only way to have GGC reclaim storage is to call the @code{ggc_collect}
function explicitly.  This call is an expensive operation, as it may
have to scan the entire heap.  Beware that local variables (on the GCC
call stack) are not followed by such an invocation (as many other
garbage collectors do): you should reference all your data from static
or external @code{GTY}-ed variables, and it is advised to call
@code{ggc_collect} with a shallow call stack.  The GGC is an exact mark
and sweep garbage collector (so it does not scan the call stack for
pointers).  In practice GCC passes don't often call @code{ggc_collect}
themselves, because it is called by the pass manager between passes.

At the time of the @code{ggc_collect} call all pointers in the GC-marked
structures must be valid or @code{NULL}.  In practice this means that
there should not be uninitialized pointer fields in the structures even
if your code never reads or writes those fields at a particular
instance.  One way to ensure this is to use cleared versions of
allocators unless all the fields are initialized manually immediately
after allocation.

@node Troubleshooting
@section Troubleshooting the garbage collector
@cindex garbage collector, troubleshooting

With the current garbage collector implementation, most issues should
show up as GCC compilation errors.  Some of the most commonly
encountered issues are described below.

@itemize @bullet
@item Gengtype does not produce allocators for a @code{GTY}-marked type.
Gengtype checks if there is at least one possible path from GC roots to
at least one instance of each type before outputting allocators.  If
there is no such path, the @code{GTY} markers will be ignored and no
allocators will be output.  Solve this by making sure that there exists
at least one such path.  If creating it is unfeasible or raises a ``code
smell'', consider if you really must use GC for allocating such type.

@item Link-time errors about undefined @code{gt_ggc_r_foo_bar} and
similarly-named symbols.  Check if your @file{foo_bar} source file has
@code{#include "gt-foo_bar.h"} as its very last line.

@end itemize