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