1*ec02198aSmrg@c Copyright (C) 2002-2020 Free Software Foundation, Inc. 210d565efSmrg@c This is part of the GCC manual. 310d565efSmrg@c For copying conditions, see the file gcc.texi. 410d565efSmrg 510d565efSmrg@node Type Information 610d565efSmrg@chapter Memory Management and Type Information 710d565efSmrg@cindex GGC 810d565efSmrg@findex GTY 910d565efSmrg 1010d565efSmrgGCC uses some fairly sophisticated memory management techniques, which 1110d565efSmrginvolve determining information about GCC's data structures from GCC's 1210d565efSmrgsource code and using this information to perform garbage collection and 1310d565efSmrgimplement precompiled headers. 1410d565efSmrg 1510d565efSmrgA full C++ parser would be too complicated for this task, so a limited 1610d565efSmrgsubset of C++ is interpreted and special markers are used to determine 1710d565efSmrgwhat parts of the source to look at. All @code{struct}, @code{union} 1810d565efSmrgand @code{template} structure declarations that define data structures 1910d565efSmrgthat are allocated under control of the garbage collector must be 2010d565efSmrgmarked. All global variables that hold pointers to garbage-collected 2110d565efSmrgmemory must also be marked. Finally, all global variables that need 2210d565efSmrgto be saved and restored by a precompiled header must be marked. (The 2310d565efSmrgprecompiled header mechanism can only save static variables if they're 2410d565efSmrgscalar. Complex data structures must be allocated in garbage-collected 2510d565efSmrgmemory to be saved in a precompiled header.) 2610d565efSmrg 2710d565efSmrgThe full format of a marker is 2810d565efSmrg@smallexample 2910d565efSmrgGTY (([@var{option}] [(@var{param})], [@var{option}] [(@var{param})] @dots{})) 3010d565efSmrg@end smallexample 3110d565efSmrg@noindent 3210d565efSmrgbut in most cases no options are needed. The outer double parentheses 3310d565efSmrgare still necessary, though: @code{GTY(())}. Markers can appear: 3410d565efSmrg 3510d565efSmrg@itemize @bullet 3610d565efSmrg@item 3710d565efSmrgIn a structure definition, before the open brace; 3810d565efSmrg@item 3910d565efSmrgIn a global variable declaration, after the keyword @code{static} or 4010d565efSmrg@code{extern}; and 4110d565efSmrg@item 4210d565efSmrgIn a structure field definition, before the name of the field. 4310d565efSmrg@end itemize 4410d565efSmrg 4510d565efSmrgHere are some examples of marking simple data structures and globals. 4610d565efSmrg 4710d565efSmrg@smallexample 4810d565efSmrgstruct GTY(()) @var{tag} 4910d565efSmrg@{ 5010d565efSmrg @var{fields}@dots{} 5110d565efSmrg@}; 5210d565efSmrg 5310d565efSmrgtypedef struct GTY(()) @var{tag} 5410d565efSmrg@{ 5510d565efSmrg @var{fields}@dots{} 5610d565efSmrg@} *@var{typename}; 5710d565efSmrg 5810d565efSmrgstatic GTY(()) struct @var{tag} *@var{list}; /* @r{points to GC memory} */ 5910d565efSmrgstatic GTY(()) int @var{counter}; /* @r{save counter in a PCH} */ 6010d565efSmrg@end smallexample 6110d565efSmrg 6210d565efSmrgThe parser understands simple typedefs such as 6310d565efSmrg@code{typedef struct @var{tag} *@var{name};} and 6410d565efSmrg@code{typedef int @var{name};}. 6510d565efSmrgThese don't need to be marked. 6610d565efSmrg 6710d565efSmrgSince @code{gengtype}'s understanding of C++ is limited, there are 6810d565efSmrgseveral constructs and declarations that are not supported inside 6910d565efSmrgclasses/structures marked for automatic GC code generation. The 7010d565efSmrgfollowing C++ constructs produce a @code{gengtype} error on 7110d565efSmrgstructures/classes marked for automatic GC code generation: 7210d565efSmrg 7310d565efSmrg@itemize @bullet 7410d565efSmrg@item 7510d565efSmrgType definitions inside classes/structures are not supported. 7610d565efSmrg@item 7710d565efSmrgEnumerations inside classes/structures are not supported. 7810d565efSmrg@end itemize 7910d565efSmrg 8010d565efSmrgIf you have a class or structure using any of the above constructs, 8110d565efSmrgyou need to mark that class as @code{GTY ((user))} and provide your 8210d565efSmrgown marking routines (see section @ref{User GC} for details). 8310d565efSmrg 8410d565efSmrgIt is always valid to include function definitions inside classes. 8510d565efSmrgThose are always ignored by @code{gengtype}, as it only cares about 8610d565efSmrgdata members. 8710d565efSmrg 8810d565efSmrg@menu 8910d565efSmrg* GTY Options:: What goes inside a @code{GTY(())}. 9010d565efSmrg* Inheritance and GTY:: Adding GTY to a class hierarchy. 9110d565efSmrg* User GC:: Adding user-provided GC marking routines. 9210d565efSmrg* GGC Roots:: Making global variables GGC roots. 9310d565efSmrg* Files:: How the generated files work. 9410d565efSmrg* Invoking the garbage collector:: How to invoke the garbage collector. 9510d565efSmrg* Troubleshooting:: When something does not work as expected. 9610d565efSmrg@end menu 9710d565efSmrg 9810d565efSmrg@node GTY Options 9910d565efSmrg@section The Inside of a @code{GTY(())} 10010d565efSmrg 10110d565efSmrgSometimes the C code is not enough to fully describe the type 10210d565efSmrgstructure. Extra information can be provided with @code{GTY} options 10310d565efSmrgand additional markers. Some options take a parameter, which may be 10410d565efSmrgeither a string or a type name, depending on the parameter. If an 10510d565efSmrgoption takes no parameter, it is acceptable either to omit the 10610d565efSmrgparameter entirely, or to provide an empty string as a parameter. For 10710d565efSmrgexample, @code{@w{GTY ((skip))}} and @code{@w{GTY ((skip ("")))}} are 10810d565efSmrgequivalent. 10910d565efSmrg 11010d565efSmrgWhen the parameter is a string, often it is a fragment of C code. Four 11110d565efSmrgspecial escapes may be used in these strings, to refer to pieces of 11210d565efSmrgthe data structure being marked: 11310d565efSmrg 11410d565efSmrg@cindex % in GTY option 11510d565efSmrg@table @code 11610d565efSmrg@item %h 11710d565efSmrgThe current structure. 11810d565efSmrg@item %1 11910d565efSmrgThe structure that immediately contains the current structure. 12010d565efSmrg@item %0 12110d565efSmrgThe outermost structure that contains the current structure. 12210d565efSmrg@item %a 12310d565efSmrgA partial expression of the form @code{[i1][i2]@dots{}} that indexes 12410d565efSmrgthe array item currently being marked. 12510d565efSmrg@end table 12610d565efSmrg 12710d565efSmrgFor instance, suppose that you have a structure of the form 12810d565efSmrg@smallexample 12910d565efSmrgstruct A @{ 13010d565efSmrg @dots{} 13110d565efSmrg@}; 13210d565efSmrgstruct B @{ 13310d565efSmrg struct A foo[12]; 13410d565efSmrg@}; 13510d565efSmrg@end smallexample 13610d565efSmrg@noindent 13710d565efSmrgand @code{b} is a variable of type @code{struct B}. When marking 13810d565efSmrg@samp{b.foo[11]}, @code{%h} would expand to @samp{b.foo[11]}, 13910d565efSmrg@code{%0} and @code{%1} would both expand to @samp{b}, and @code{%a} 14010d565efSmrgwould expand to @samp{[11]}. 14110d565efSmrg 14210d565efSmrgAs in ordinary C, adjacent strings will be concatenated; this is 14310d565efSmrghelpful when you have a complicated expression. 14410d565efSmrg@smallexample 14510d565efSmrg@group 14610d565efSmrgGTY ((chain_next ("TREE_CODE (&%h.generic) == INTEGER_TYPE" 14710d565efSmrg " ? TYPE_NEXT_VARIANT (&%h.generic)" 14810d565efSmrg " : TREE_CHAIN (&%h.generic)"))) 14910d565efSmrg@end group 15010d565efSmrg@end smallexample 15110d565efSmrg 15210d565efSmrgThe available options are: 15310d565efSmrg 15410d565efSmrg@table @code 15510d565efSmrg@findex length 15610d565efSmrg@item length ("@var{expression}") 15710d565efSmrg 15810d565efSmrgThere are two places the type machinery will need to be explicitly told 15910d565efSmrgthe length of an array of non-atomic objects. The first case is when a 16010d565efSmrgstructure ends in a variable-length array, like this: 16110d565efSmrg@smallexample 16210d565efSmrgstruct GTY(()) rtvec_def @{ 16310d565efSmrg int num_elem; /* @r{number of elements} */ 16410d565efSmrg rtx GTY ((length ("%h.num_elem"))) elem[1]; 16510d565efSmrg@}; 16610d565efSmrg@end smallexample 16710d565efSmrg 16810d565efSmrgIn this case, the @code{length} option is used to override the specified 16910d565efSmrgarray length (which should usually be @code{1}). The parameter of the 17010d565efSmrgoption is a fragment of C code that calculates the length. 17110d565efSmrg 17210d565efSmrgThe second case is when a structure or a global variable contains a 17310d565efSmrgpointer to an array, like this: 17410d565efSmrg@smallexample 17510d565efSmrgstruct gimple_omp_for_iter * GTY((length ("%h.collapse"))) iter; 17610d565efSmrg@end smallexample 17710d565efSmrgIn this case, @code{iter} has been allocated by writing something like 17810d565efSmrg@smallexample 17910d565efSmrg x->iter = ggc_alloc_cleared_vec_gimple_omp_for_iter (collapse); 18010d565efSmrg@end smallexample 18110d565efSmrgand the @code{collapse} provides the length of the field. 18210d565efSmrg 18310d565efSmrgThis second use of @code{length} also works on global variables, like: 18410d565efSmrg@verbatim 18510d565efSmrgstatic GTY((length("reg_known_value_size"))) rtx *reg_known_value; 18610d565efSmrg@end verbatim 18710d565efSmrg 18810d565efSmrgNote that the @code{length} option is only meant for use with arrays of 18910d565efSmrgnon-atomic objects, that is, objects that contain pointers pointing to 19010d565efSmrgother GTY-managed objects. For other GC-allocated arrays and strings 19110d565efSmrgyou should use @code{atomic}. 19210d565efSmrg 19310d565efSmrg@findex skip 19410d565efSmrg@item skip 19510d565efSmrg 19610d565efSmrgIf @code{skip} is applied to a field, the type machinery will ignore it. 19710d565efSmrgThis is somewhat dangerous; the only safe use is in a union when one 19810d565efSmrgfield really isn't ever used. 19910d565efSmrg 20010d565efSmrg@findex for_user 20110d565efSmrg@item for_user 20210d565efSmrg 20310d565efSmrgUse this to mark types that need to be marked by user gc routines, but are not 20410d565efSmrgrefered to in a template argument. So if you have some user gc type T1 and a 20510d565efSmrgnon user gc type T2 you can give T2 the for_user option so that the marking 20610d565efSmrgfunctions for T1 can call non mangled functions to mark T2. 20710d565efSmrg 20810d565efSmrg@findex desc 20910d565efSmrg@findex tag 21010d565efSmrg@findex default 21110d565efSmrg@item desc ("@var{expression}") 21210d565efSmrg@itemx tag ("@var{constant}") 21310d565efSmrg@itemx default 21410d565efSmrg 21510d565efSmrgThe type machinery needs to be told which field of a @code{union} is 21610d565efSmrgcurrently active. This is done by giving each field a constant 21710d565efSmrg@code{tag} value, and then specifying a discriminator using @code{desc}. 21810d565efSmrgThe value of the expression given by @code{desc} is compared against 21910d565efSmrgeach @code{tag} value, each of which should be different. If no 22010d565efSmrg@code{tag} is matched, the field marked with @code{default} is used if 22110d565efSmrgthere is one, otherwise no field in the union will be marked. 22210d565efSmrg 22310d565efSmrgIn the @code{desc} option, the ``current structure'' is the union that 22410d565efSmrgit discriminates. Use @code{%1} to mean the structure containing it. 22510d565efSmrgThere are no escapes available to the @code{tag} option, since it is a 22610d565efSmrgconstant. 22710d565efSmrg 22810d565efSmrgFor example, 22910d565efSmrg@smallexample 23010d565efSmrgstruct GTY(()) tree_binding 23110d565efSmrg@{ 23210d565efSmrg struct tree_common common; 23310d565efSmrg union tree_binding_u @{ 23410d565efSmrg tree GTY ((tag ("0"))) scope; 23510d565efSmrg struct cp_binding_level * GTY ((tag ("1"))) level; 23610d565efSmrg @} GTY ((desc ("BINDING_HAS_LEVEL_P ((tree)&%0)"))) xscope; 23710d565efSmrg tree value; 23810d565efSmrg@}; 23910d565efSmrg@end smallexample 24010d565efSmrg 24110d565efSmrgIn this example, the value of BINDING_HAS_LEVEL_P when applied to a 24210d565efSmrg@code{struct tree_binding *} is presumed to be 0 or 1. If 1, the type 24310d565efSmrgmechanism will treat the field @code{level} as being present and if 0, 24410d565efSmrgwill treat the field @code{scope} as being present. 24510d565efSmrg 24610d565efSmrgThe @code{desc} and @code{tag} options can also be used for inheritance 24710d565efSmrgto denote which subclass an instance is. See @ref{Inheritance and GTY} 24810d565efSmrgfor more information. 24910d565efSmrg 25010d565efSmrg@findex cache 25110d565efSmrg@item cache 25210d565efSmrg 25310d565efSmrgWhen the @code{cache} option is applied to a global variable gt_clear_cache is 25410d565efSmrgcalled on that variable between the mark and sweep phases of garbage 25510d565efSmrgcollection. The gt_clear_cache function is free to mark blocks as used, or to 25610d565efSmrgclear pointers in the variable. 25710d565efSmrg 25810d565efSmrg@findex deletable 25910d565efSmrg@item deletable 26010d565efSmrg 26110d565efSmrg@code{deletable}, when applied to a global variable, indicates that when 26210d565efSmrggarbage collection runs, there's no need to mark anything pointed to 26310d565efSmrgby this variable, it can just be set to @code{NULL} instead. This is used 26410d565efSmrgto keep a list of free structures around for re-use. 26510d565efSmrg 26610d565efSmrg@findex maybe_undef 26710d565efSmrg@item maybe_undef 26810d565efSmrg 26910d565efSmrgWhen applied to a field, @code{maybe_undef} indicates that it's OK if 27010d565efSmrgthe structure that this fields points to is never defined, so long as 27110d565efSmrgthis field is always @code{NULL}. This is used to avoid requiring 27210d565efSmrgbackends to define certain optional structures. It doesn't work with 27310d565efSmrglanguage frontends. 27410d565efSmrg 27510d565efSmrg@findex nested_ptr 27610d565efSmrg@item nested_ptr (@var{type}, "@var{to expression}", "@var{from expression}") 27710d565efSmrg 27810d565efSmrgThe type machinery expects all pointers to point to the start of an 27910d565efSmrgobject. Sometimes for abstraction purposes it's convenient to have 28010d565efSmrga pointer which points inside an object. So long as it's possible to 28110d565efSmrgconvert the original object to and from the pointer, such pointers 28210d565efSmrgcan still be used. @var{type} is the type of the original object, 28310d565efSmrgthe @var{to expression} returns the pointer given the original object, 28410d565efSmrgand the @var{from expression} returns the original object given 28510d565efSmrgthe pointer. The pointer will be available using the @code{%h} 28610d565efSmrgescape. 28710d565efSmrg 28810d565efSmrg@findex chain_next 28910d565efSmrg@findex chain_prev 29010d565efSmrg@findex chain_circular 29110d565efSmrg@item chain_next ("@var{expression}") 29210d565efSmrg@itemx chain_prev ("@var{expression}") 29310d565efSmrg@itemx chain_circular ("@var{expression}") 29410d565efSmrg 29510d565efSmrgIt's helpful for the type machinery to know if objects are often 29610d565efSmrgchained together in long lists; this lets it generate code that uses 29710d565efSmrgless stack space by iterating along the list instead of recursing down 29810d565efSmrgit. @code{chain_next} is an expression for the next item in the list, 29910d565efSmrg@code{chain_prev} is an expression for the previous item. For singly 30010d565efSmrglinked lists, use only @code{chain_next}; for doubly linked lists, use 30110d565efSmrgboth. The machinery requires that taking the next item of the 30210d565efSmrgprevious item gives the original item. @code{chain_circular} is similar 30310d565efSmrgto @code{chain_next}, but can be used for circular single linked lists. 30410d565efSmrg 30510d565efSmrg@findex reorder 30610d565efSmrg@item reorder ("@var{function name}") 30710d565efSmrg 30810d565efSmrgSome data structures depend on the relative ordering of pointers. If 30910d565efSmrgthe precompiled header machinery needs to change that ordering, it 31010d565efSmrgwill call the function referenced by the @code{reorder} option, before 31110d565efSmrgchanging the pointers in the object that's pointed to by the field the 31210d565efSmrgoption applies to. The function must take four arguments, with the 31310d565efSmrgsignature @samp{@w{void *, void *, gt_pointer_operator, void *}}. 31410d565efSmrgThe first parameter is a pointer to the structure that contains the 31510d565efSmrgobject being updated, or the object itself if there is no containing 31610d565efSmrgstructure. The second parameter is a cookie that should be ignored. 31710d565efSmrgThe third parameter is a routine that, given a pointer, will update it 31810d565efSmrgto its correct new value. The fourth parameter is a cookie that must 31910d565efSmrgbe passed to the second parameter. 32010d565efSmrg 32110d565efSmrgPCH cannot handle data structures that depend on the absolute values 32210d565efSmrgof pointers. @code{reorder} functions can be expensive. When 32310d565efSmrgpossible, it is better to depend on properties of the data, like an ID 32410d565efSmrgnumber or the hash of a string instead. 32510d565efSmrg 32610d565efSmrg@findex atomic 32710d565efSmrg@item atomic 32810d565efSmrg 32910d565efSmrgThe @code{atomic} option can only be used with pointers. It informs 33010d565efSmrgthe GC machinery that the memory that the pointer points to does not 33110d565efSmrgcontain any pointers, and hence it should be treated by the GC and PCH 33210d565efSmrgmachinery as an ``atomic'' block of memory that does not need to be 33310d565efSmrgexamined when scanning memory for pointers. In particular, the 33410d565efSmrgmachinery will not scan that memory for pointers to mark them as 33510d565efSmrgreachable (when marking pointers for GC) or to relocate them (when 33610d565efSmrgwriting a PCH file). 33710d565efSmrg 33810d565efSmrgThe @code{atomic} option differs from the @code{skip} option. 33910d565efSmrg@code{atomic} keeps the memory under Garbage Collection, but makes the 34010d565efSmrgGC ignore the contents of the memory. @code{skip} is more drastic in 34110d565efSmrgthat it causes the pointer and the memory to be completely ignored by 34210d565efSmrgthe Garbage Collector. So, memory marked as @code{atomic} is 34310d565efSmrgautomatically freed when no longer reachable, while memory marked as 34410d565efSmrg@code{skip} is not. 34510d565efSmrg 34610d565efSmrgThe @code{atomic} option must be used with great care, because all 34710d565efSmrgsorts of problem can occur if used incorrectly, that is, if the memory 34810d565efSmrgthe pointer points to does actually contain a pointer. 34910d565efSmrg 35010d565efSmrgHere is an example of how to use it: 35110d565efSmrg@smallexample 35210d565efSmrgstruct GTY(()) my_struct @{ 35310d565efSmrg int number_of_elements; 35410d565efSmrg unsigned int * GTY ((atomic)) elements; 35510d565efSmrg@}; 35610d565efSmrg@end smallexample 35710d565efSmrgIn this case, @code{elements} is a pointer under GC, and the memory it 35810d565efSmrgpoints to needs to be allocated using the Garbage Collector, and will 35910d565efSmrgbe freed automatically by the Garbage Collector when it is no longer 36010d565efSmrgreferenced. But the memory that the pointer points to is an array of 36110d565efSmrg@code{unsigned int} elements, and the GC must not try to scan it to 36210d565efSmrgfind pointers to mark or relocate, which is why it is marked with the 36310d565efSmrg@code{atomic} option. 36410d565efSmrg 36510d565efSmrgNote that, currently, global variables cannot be marked with 36610d565efSmrg@code{atomic}; only fields of a struct can. This is a known 36710d565efSmrglimitation. It would be useful to be able to mark global pointers 36810d565efSmrgwith @code{atomic} to make the PCH machinery aware of them so that 36910d565efSmrgthey are saved and restored correctly to PCH files. 37010d565efSmrg 37110d565efSmrg@findex special 37210d565efSmrg@item special ("@var{name}") 37310d565efSmrg 37410d565efSmrgThe @code{special} option is used to mark types that have to be dealt 37510d565efSmrgwith by special case machinery. The parameter is the name of the 37610d565efSmrgspecial case. See @file{gengtype.c} for further details. Avoid 37710d565efSmrgadding new special cases unless there is no other alternative. 37810d565efSmrg 37910d565efSmrg@findex user 38010d565efSmrg@item user 38110d565efSmrg 38210d565efSmrgThe @code{user} option indicates that the code to mark structure 38310d565efSmrgfields is completely handled by user-provided routines. See section 38410d565efSmrg@ref{User GC} for details on what functions need to be provided. 38510d565efSmrg@end table 38610d565efSmrg 38710d565efSmrg@node Inheritance and GTY 38810d565efSmrg@section Support for inheritance 38910d565efSmrggengtype has some support for simple class hierarchies. You can use 39010d565efSmrgthis to have gengtype autogenerate marking routines, provided: 39110d565efSmrg 39210d565efSmrg@itemize @bullet 39310d565efSmrg@item 39410d565efSmrgThere must be a concrete base class, with a discriminator expression 39510d565efSmrgthat can be used to identify which subclass an instance is. 39610d565efSmrg@item 39710d565efSmrgOnly single inheritance is used. 39810d565efSmrg@item 39910d565efSmrgNone of the classes within the hierarchy are templates. 40010d565efSmrg@end itemize 40110d565efSmrg 40210d565efSmrgIf your class hierarchy does not fit in this pattern, you must use 40310d565efSmrg@ref{User GC} instead. 40410d565efSmrg 40510d565efSmrgThe base class and its discriminator must be identified using the ``desc'' 40610d565efSmrgoption. Each concrete subclass must use the ``tag'' option to identify 40710d565efSmrgwhich value of the discriminator it corresponds to. 40810d565efSmrg 40910d565efSmrgEvery class in the hierarchy must have a @code{GTY(())} marker, as 41010d565efSmrggengtype will only attempt to parse classes that have such a marker 41110d565efSmrg@footnote{Classes lacking such a marker will not be identified as being 41210d565efSmrgpart of the hierarchy, and so the marking routines will not handle them, 41310d565efSmrgleading to a assertion failure within the marking routines due to an 41410d565efSmrgunknown tag value (assuming that assertions are enabled).}. 41510d565efSmrg 41610d565efSmrg@smallexample 41710d565efSmrgclass GTY((desc("%h.kind"), tag("0"))) example_base 41810d565efSmrg@{ 41910d565efSmrgpublic: 42010d565efSmrg int kind; 42110d565efSmrg tree a; 42210d565efSmrg@}; 42310d565efSmrg 42410d565efSmrgclass GTY((tag("1"))) some_subclass : public example_base 42510d565efSmrg@{ 42610d565efSmrgpublic: 42710d565efSmrg tree b; 42810d565efSmrg@}; 42910d565efSmrg 43010d565efSmrgclass GTY((tag("2"))) some_other_subclass : public example_base 43110d565efSmrg@{ 43210d565efSmrgpublic: 43310d565efSmrg tree c; 43410d565efSmrg@}; 43510d565efSmrg@end smallexample 43610d565efSmrg 43710d565efSmrgThe generated marking routines for the above will contain a ``switch'' 43810d565efSmrgon ``kind'', visiting all appropriate fields. For example, if kind is 43910d565efSmrg2, it will cast to ``some_other_subclass'' and visit fields a, b, and c. 44010d565efSmrg 44110d565efSmrg@node User GC 44210d565efSmrg@section Support for user-provided GC marking routines 44310d565efSmrg@cindex user gc 44410d565efSmrgThe garbage collector supports types for which no automatic marking 44510d565efSmrgcode is generated. For these types, the user is required to provide 44610d565efSmrgthree functions: one to act as a marker for garbage collection, and 44710d565efSmrgtwo functions to act as marker and pointer walker for pre-compiled 44810d565efSmrgheaders. 44910d565efSmrg 45010d565efSmrgGiven a structure @code{struct GTY((user)) my_struct}, the following functions 45110d565efSmrgshould be defined to mark @code{my_struct}: 45210d565efSmrg 45310d565efSmrg@smallexample 45410d565efSmrgvoid gt_ggc_mx (my_struct *p) 45510d565efSmrg@{ 45610d565efSmrg /* This marks field 'fld'. */ 45710d565efSmrg gt_ggc_mx (p->fld); 45810d565efSmrg@} 45910d565efSmrg 46010d565efSmrgvoid gt_pch_nx (my_struct *p) 46110d565efSmrg@{ 46210d565efSmrg /* This marks field 'fld'. */ 46310d565efSmrg gt_pch_nx (tp->fld); 46410d565efSmrg@} 46510d565efSmrg 46610d565efSmrgvoid gt_pch_nx (my_struct *p, gt_pointer_operator op, void *cookie) 46710d565efSmrg@{ 46810d565efSmrg /* For every field 'fld', call the given pointer operator. */ 46910d565efSmrg op (&(tp->fld), cookie); 47010d565efSmrg@} 47110d565efSmrg@end smallexample 47210d565efSmrg 47310d565efSmrgIn general, each marker @code{M} should call @code{M} for every 47410d565efSmrgpointer field in the structure. Fields that are not allocated in GC 47510d565efSmrgor are not pointers must be ignored. 47610d565efSmrg 47710d565efSmrgFor embedded lists (e.g., structures with a @code{next} or @code{prev} 47810d565efSmrgpointer), the marker must follow the chain and mark every element in 47910d565efSmrgit. 48010d565efSmrg 48110d565efSmrgNote that the rules for the pointer walker @code{gt_pch_nx (my_struct 48210d565efSmrg*, gt_pointer_operator, void *)} are slightly different. In this 48310d565efSmrgcase, the operation @code{op} must be applied to the @emph{address} of 48410d565efSmrgevery pointer field. 48510d565efSmrg 48610d565efSmrg@subsection User-provided marking routines for template types 48710d565efSmrgWhen a template type @code{TP} is marked with @code{GTY}, all 48810d565efSmrginstances of that type are considered user-provided types. This means 48910d565efSmrgthat the individual instances of @code{TP} do not need to be marked 49010d565efSmrgwith @code{GTY}. The user needs to provide template functions to mark 49110d565efSmrgall the fields of the type. 49210d565efSmrg 49310d565efSmrgThe following code snippets represent all the functions that need to 49410d565efSmrgbe provided. Note that type @code{TP} may reference to more than one 49510d565efSmrgtype. In these snippets, there is only one type @code{T}, but there 49610d565efSmrgcould be more. 49710d565efSmrg 49810d565efSmrg@smallexample 49910d565efSmrgtemplate<typename T> 50010d565efSmrgvoid gt_ggc_mx (TP<T> *tp) 50110d565efSmrg@{ 50210d565efSmrg extern void gt_ggc_mx (T&); 50310d565efSmrg 50410d565efSmrg /* This marks field 'fld' of type 'T'. */ 50510d565efSmrg gt_ggc_mx (tp->fld); 50610d565efSmrg@} 50710d565efSmrg 50810d565efSmrgtemplate<typename T> 50910d565efSmrgvoid gt_pch_nx (TP<T> *tp) 51010d565efSmrg@{ 51110d565efSmrg extern void gt_pch_nx (T&); 51210d565efSmrg 51310d565efSmrg /* This marks field 'fld' of type 'T'. */ 51410d565efSmrg gt_pch_nx (tp->fld); 51510d565efSmrg@} 51610d565efSmrg 51710d565efSmrgtemplate<typename T> 51810d565efSmrgvoid gt_pch_nx (TP<T *> *tp, gt_pointer_operator op, void *cookie) 51910d565efSmrg@{ 52010d565efSmrg /* For every field 'fld' of 'tp' with type 'T *', call the given 52110d565efSmrg pointer operator. */ 52210d565efSmrg op (&(tp->fld), cookie); 52310d565efSmrg@} 52410d565efSmrg 52510d565efSmrgtemplate<typename T> 52610d565efSmrgvoid gt_pch_nx (TP<T> *tp, gt_pointer_operator, void *cookie) 52710d565efSmrg@{ 52810d565efSmrg extern void gt_pch_nx (T *, gt_pointer_operator, void *); 52910d565efSmrg 53010d565efSmrg /* For every field 'fld' of 'tp' with type 'T', call the pointer 53110d565efSmrg walker for all the fields of T. */ 53210d565efSmrg gt_pch_nx (&(tp->fld), op, cookie); 53310d565efSmrg@} 53410d565efSmrg@end smallexample 53510d565efSmrg 53610d565efSmrgSupport for user-defined types is currently limited. The following 53710d565efSmrgrestrictions apply: 53810d565efSmrg 53910d565efSmrg@enumerate 54010d565efSmrg@item Type @code{TP} and all the argument types @code{T} must be 54110d565efSmrgmarked with @code{GTY}. 54210d565efSmrg 54310d565efSmrg@item Type @code{TP} can only have type names in its argument list. 54410d565efSmrg 54510d565efSmrg@item The pointer walker functions are different for @code{TP<T>} and 54610d565efSmrg@code{TP<T *>}. In the case of @code{TP<T>}, references to 54710d565efSmrg@code{T} must be handled by calling @code{gt_pch_nx} (which 54810d565efSmrgwill, in turn, walk all the pointers inside fields of @code{T}). 54910d565efSmrgIn the case of @code{TP<T *>}, references to @code{T *} must be 55010d565efSmrghandled by calling the @code{op} function on the address of the 55110d565efSmrgpointer (see the code snippets above). 55210d565efSmrg@end enumerate 55310d565efSmrg 55410d565efSmrg@node GGC Roots 55510d565efSmrg@section Marking Roots for the Garbage Collector 55610d565efSmrg@cindex roots, marking 55710d565efSmrg@cindex marking roots 55810d565efSmrg 55910d565efSmrgIn addition to keeping track of types, the type machinery also locates 56010d565efSmrgthe global variables (@dfn{roots}) that the garbage collector starts 56110d565efSmrgat. Roots must be declared using one of the following syntaxes: 56210d565efSmrg 56310d565efSmrg@itemize @bullet 56410d565efSmrg@item 56510d565efSmrg@code{extern GTY(([@var{options}])) @var{type} @var{name};} 56610d565efSmrg@item 56710d565efSmrg@code{static GTY(([@var{options}])) @var{type} @var{name};} 56810d565efSmrg@end itemize 56910d565efSmrg@noindent 57010d565efSmrgThe syntax 57110d565efSmrg@itemize @bullet 57210d565efSmrg@item 57310d565efSmrg@code{GTY(([@var{options}])) @var{type} @var{name};} 57410d565efSmrg@end itemize 57510d565efSmrg@noindent 57610d565efSmrgis @emph{not} accepted. There should be an @code{extern} declaration 57710d565efSmrgof such a variable in a header somewhere---mark that, not the 57810d565efSmrgdefinition. Or, if the variable is only used in one file, make it 57910d565efSmrg@code{static}. 58010d565efSmrg 58110d565efSmrg@node Files 58210d565efSmrg@section Source Files Containing Type Information 58310d565efSmrg@cindex generated files 58410d565efSmrg@cindex files, generated 58510d565efSmrg 58610d565efSmrgWhenever you add @code{GTY} markers to a source file that previously 58710d565efSmrghad none, or create a new source file containing @code{GTY} markers, 58810d565efSmrgthere are three things you need to do: 58910d565efSmrg 59010d565efSmrg@enumerate 59110d565efSmrg@item 59210d565efSmrgYou need to add the file to the list of source files the type 59310d565efSmrgmachinery scans. There are four cases: 59410d565efSmrg 59510d565efSmrg@enumerate a 59610d565efSmrg@item 59710d565efSmrgFor a back-end file, this is usually done 59810d565efSmrgautomatically; if not, you should add it to @code{target_gtfiles} in 59910d565efSmrgthe appropriate port's entries in @file{config.gcc}. 60010d565efSmrg 60110d565efSmrg@item 60210d565efSmrgFor files shared by all front ends, add the filename to the 60310d565efSmrg@code{GTFILES} variable in @file{Makefile.in}. 60410d565efSmrg 60510d565efSmrg@item 60610d565efSmrgFor files that are part of one front end, add the filename to the 60710d565efSmrg@code{gtfiles} variable defined in the appropriate 60810d565efSmrg@file{config-lang.in}. 60910d565efSmrgHeaders should appear before non-headers in this list. 61010d565efSmrg 61110d565efSmrg@item 61210d565efSmrgFor files that are part of some but not all front ends, add the 61310d565efSmrgfilename to the @code{gtfiles} variable of @emph{all} the front ends 61410d565efSmrgthat use it. 61510d565efSmrg@end enumerate 61610d565efSmrg 61710d565efSmrg@item 61810d565efSmrgIf the file was a header file, you'll need to check that it's included 61910d565efSmrgin the right place to be visible to the generated files. For a back-end 62010d565efSmrgheader file, this should be done automatically. For a front-end header 62110d565efSmrgfile, it needs to be included by the same file that includes 62210d565efSmrg@file{gtype-@var{lang}.h}. For other header files, it needs to be 62310d565efSmrgincluded in @file{gtype-desc.c}, which is a generated file, so add it to 62410d565efSmrg@code{ifiles} in @code{open_base_file} in @file{gengtype.c}. 62510d565efSmrg 62610d565efSmrgFor source files that aren't header files, the machinery will generate a 62710d565efSmrgheader file that should be included in the source file you just changed. 62810d565efSmrgThe file will be called @file{gt-@var{path}.h} where @var{path} is the 62910d565efSmrgpathname relative to the @file{gcc} directory with slashes replaced by 63010d565efSmrg@verb{|-|}, so for example the header file to be included in 63110d565efSmrg@file{cp/parser.c} is called @file{gt-cp-parser.c}. The 63210d565efSmrggenerated header file should be included after everything else in the 63310d565efSmrgsource file. Don't forget to mention this file as a dependency in the 63410d565efSmrg@file{Makefile}! 63510d565efSmrg 63610d565efSmrg@end enumerate 63710d565efSmrg 63810d565efSmrgFor language frontends, there is another file that needs to be included 63910d565efSmrgsomewhere. It will be called @file{gtype-@var{lang}.h}, where 64010d565efSmrg@var{lang} is the name of the subdirectory the language is contained in. 64110d565efSmrg 64210d565efSmrgPlugins can add additional root tables. Run the @code{gengtype} 64310d565efSmrgutility in plugin mode as @code{gengtype -P pluginout.h @var{source-dir} 64410d565efSmrg@var{file-list} @var{plugin*.c}} with your plugin files 64510d565efSmrg@var{plugin*.c} using @code{GTY} to generate the @var{pluginout.h} file. 64610d565efSmrgThe GCC build tree is needed to be present in that mode. 64710d565efSmrg 64810d565efSmrg 64910d565efSmrg@node Invoking the garbage collector 65010d565efSmrg@section How to invoke the garbage collector 65110d565efSmrg@cindex garbage collector, invocation 65210d565efSmrg@findex ggc_collect 65310d565efSmrg 65410d565efSmrgThe GCC garbage collector GGC is only invoked explicitly. In contrast 65510d565efSmrgwith many other garbage collectors, it is not implicitly invoked by 65610d565efSmrgallocation routines when a lot of memory has been consumed. So the 65710d565efSmrgonly way to have GGC reclaim storage is to call the @code{ggc_collect} 65810d565efSmrgfunction explicitly. This call is an expensive operation, as it may 65910d565efSmrghave to scan the entire heap. Beware that local variables (on the GCC 66010d565efSmrgcall stack) are not followed by such an invocation (as many other 66110d565efSmrggarbage collectors do): you should reference all your data from static 66210d565efSmrgor external @code{GTY}-ed variables, and it is advised to call 66310d565efSmrg@code{ggc_collect} with a shallow call stack. The GGC is an exact mark 66410d565efSmrgand sweep garbage collector (so it does not scan the call stack for 66510d565efSmrgpointers). In practice GCC passes don't often call @code{ggc_collect} 66610d565efSmrgthemselves, because it is called by the pass manager between passes. 66710d565efSmrg 66810d565efSmrgAt the time of the @code{ggc_collect} call all pointers in the GC-marked 66910d565efSmrgstructures must be valid or @code{NULL}. In practice this means that 67010d565efSmrgthere should not be uninitialized pointer fields in the structures even 67110d565efSmrgif your code never reads or writes those fields at a particular 67210d565efSmrginstance. One way to ensure this is to use cleared versions of 67310d565efSmrgallocators unless all the fields are initialized manually immediately 67410d565efSmrgafter allocation. 67510d565efSmrg 67610d565efSmrg@node Troubleshooting 67710d565efSmrg@section Troubleshooting the garbage collector 67810d565efSmrg@cindex garbage collector, troubleshooting 67910d565efSmrg 68010d565efSmrgWith the current garbage collector implementation, most issues should 68110d565efSmrgshow up as GCC compilation errors. Some of the most commonly 68210d565efSmrgencountered issues are described below. 68310d565efSmrg 68410d565efSmrg@itemize @bullet 68510d565efSmrg@item Gengtype does not produce allocators for a @code{GTY}-marked type. 68610d565efSmrgGengtype checks if there is at least one possible path from GC roots to 68710d565efSmrgat least one instance of each type before outputting allocators. If 68810d565efSmrgthere is no such path, the @code{GTY} markers will be ignored and no 68910d565efSmrgallocators will be output. Solve this by making sure that there exists 69010d565efSmrgat least one such path. If creating it is unfeasible or raises a ``code 69110d565efSmrgsmell'', consider if you really must use GC for allocating such type. 69210d565efSmrg 69310d565efSmrg@item Link-time errors about undefined @code{gt_ggc_r_foo_bar} and 69410d565efSmrgsimilarly-named symbols. Check if your @file{foo_bar} source file has 69510d565efSmrg@code{#include "gt-foo_bar.h"} as its very last line. 69610d565efSmrg 69710d565efSmrg@end itemize 698