| 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 |