gccint: GTY Options
1
1 23.1 The Inside of a 'GTY(())'
1 ==============================
1
1 Sometimes the C code is not enough to fully describe the type structure.
1 Extra information can be provided with 'GTY' options and additional
1 markers. Some options take a parameter, which may be either a string or
1 a type name, depending on the parameter. If an option takes no
1 parameter, it is acceptable either to omit the parameter entirely, or to
1 provide an empty string as a parameter. For example, 'GTY ((skip))' and
1 'GTY ((skip ("")))' are equivalent.
1
1 When the parameter is a string, often it is a fragment of C code. Four
1 special escapes may be used in these strings, to refer to pieces of the
1 data structure being marked:
1
1 '%h'
1 The current structure.
1 '%1'
1 The structure that immediately contains the current structure.
1 '%0'
1 The outermost structure that contains the current structure.
1 '%a'
1 A partial expression of the form '[i1][i2]...' that indexes the
1 array item currently being marked.
1
1 For instance, suppose that you have a structure of the form
1 struct A {
1 ...
1 };
1 struct B {
1 struct A foo[12];
1 };
1 and 'b' is a variable of type 'struct B'. When marking 'b.foo[11]',
1 '%h' would expand to 'b.foo[11]', '%0' and '%1' would both expand to
1 'b', and '%a' would expand to '[11]'.
1
1 As in ordinary C, adjacent strings will be concatenated; this is
1 helpful when you have a complicated expression.
1 GTY ((chain_next ("TREE_CODE (&%h.generic) == INTEGER_TYPE"
1 " ? TYPE_NEXT_VARIANT (&%h.generic)"
1 " : TREE_CHAIN (&%h.generic)")))
1
1 The available options are:
1
1 'length ("EXPRESSION")'
1
1 There are two places the type machinery will need to be explicitly
1 told the length of an array of non-atomic objects. The first case
1 is when a structure ends in a variable-length array, like this:
1 struct GTY(()) rtvec_def {
1 int num_elem; /* number of elements */
1 rtx GTY ((length ("%h.num_elem"))) elem[1];
1 };
1
1 In this case, the 'length' option is used to override the specified
1 array length (which should usually be '1'). The parameter of the
1 option is a fragment of C code that calculates the length.
1
1 The second case is when a structure or a global variable contains a
1 pointer to an array, like this:
1 struct gimple_omp_for_iter * GTY((length ("%h.collapse"))) iter;
1 In this case, 'iter' has been allocated by writing something like
1 x->iter = ggc_alloc_cleared_vec_gimple_omp_for_iter (collapse);
1 and the 'collapse' provides the length of the field.
1
1 This second use of 'length' also works on global variables, like:
1 static GTY((length("reg_known_value_size"))) rtx *reg_known_value;
1
1 Note that the 'length' option is only meant for use with arrays of
1 non-atomic objects, that is, objects that contain pointers pointing
1 to other GTY-managed objects. For other GC-allocated arrays and
1 strings you should use 'atomic'.
1
1 'skip'
1
1 If 'skip' is applied to a field, the type machinery will ignore it.
1 This is somewhat dangerous; the only safe use is in a union when
1 one field really isn't ever used.
1
1 'callback'
1
1 'callback' should be applied to fields with pointer to function
1 type and causes the field to be ignored similarly to 'skip', except
1 when writing PCH and the field is non-NULL it will remember the
1 field's address for relocation purposes if the process writing PCH
1 has different load base from a process reading PCH.
1
1 'for_user'
1
1 Use this to mark types that need to be marked by user gc routines,
1 but are not refered to in a template argument. So if you have some
1 user gc type T1 and a non user gc type T2 you can give T2 the
1 for_user option so that the marking functions for T1 can call non
1 mangled functions to mark T2.
1
1 'desc ("EXPRESSION")'
1 'tag ("CONSTANT")'
1 'default'
1
1 The type machinery needs to be told which field of a 'union' is
1 currently active. This is done by giving each field a constant
1 'tag' value, and then specifying a discriminator using 'desc'. The
1 value of the expression given by 'desc' is compared against each
1 'tag' value, each of which should be different. If no 'tag' is
1 matched, the field marked with 'default' is used if there is one,
1 otherwise no field in the union will be marked.
1
1 In the 'desc' option, the "current structure" is the union that it
1 discriminates. Use '%1' to mean the structure containing it.
1 There are no escapes available to the 'tag' option, since it is a
1 constant.
1
1 For example,
1 struct GTY(()) tree_binding
1 {
1 struct tree_common common;
1 union tree_binding_u {
1 tree GTY ((tag ("0"))) scope;
1 struct cp_binding_level * GTY ((tag ("1"))) level;
1 } GTY ((desc ("BINDING_HAS_LEVEL_P ((tree)&%0)"))) xscope;
1 tree value;
1 };
1
1 In this example, the value of BINDING_HAS_LEVEL_P when applied to a
1 'struct tree_binding *' is presumed to be 0 or 1. If 1, the type
1 mechanism will treat the field 'level' as being present and if 0,
1 will treat the field 'scope' as being present.
1
1 The 'desc' and 'tag' options can also be used for inheritance to
11 denote which subclass an instance is. See ⇒Inheritance and
GTY for more information.
1
1 'cache'
1
1 When the 'cache' option is applied to a global variable
1 gt_clear_cache is called on that variable between the mark and
1 sweep phases of garbage collection. The gt_clear_cache function is
1 free to mark blocks as used, or to clear pointers in the variable.
1
1 'deletable'
1
1 'deletable', when applied to a global variable, indicates that when
1 garbage collection runs, there's no need to mark anything pointed
1 to by this variable, it can just be set to 'NULL' instead. This is
1 used to keep a list of free structures around for re-use.
1
1 'maybe_undef'
1
1 When applied to a field, 'maybe_undef' indicates that it's OK if
1 the structure that this fields points to is never defined, so long
1 as this field is always 'NULL'. This is used to avoid requiring
1 backends to define certain optional structures. It doesn't work
1 with language frontends.
1
1 'nested_ptr (TYPE, "TO EXPRESSION", "FROM EXPRESSION")'
1
1 The type machinery expects all pointers to point to the start of an
1 object. Sometimes for abstraction purposes it's convenient to have
1 a pointer which points inside an object. So long as it's possible
1 to convert the original object to and from the pointer, such
1 pointers can still be used. TYPE is the type of the original
1 object, the TO EXPRESSION returns the pointer given the original
1 object, and the FROM EXPRESSION returns the original object given
1 the pointer. The pointer will be available using the '%h' escape.
1
1 'chain_next ("EXPRESSION")'
1 'chain_prev ("EXPRESSION")'
1 'chain_circular ("EXPRESSION")'
1
1 It's helpful for the type machinery to know if objects are often
1 chained together in long lists; this lets it generate code that
1 uses less stack space by iterating along the list instead of
1 recursing down it. 'chain_next' is an expression for the next item
1 in the list, 'chain_prev' is an expression for the previous item.
1 For singly linked lists, use only 'chain_next'; for doubly linked
1 lists, use both. The machinery requires that taking the next item
1 of the previous item gives the original item. 'chain_circular' is
1 similar to 'chain_next', but can be used for circular single linked
1 lists.
1
1 'reorder ("FUNCTION NAME")'
1
1 Some data structures depend on the relative ordering of pointers.
1 If the precompiled header machinery needs to change that ordering,
1 it will call the function referenced by the 'reorder' option,
1 before changing the pointers in the object that's pointed to by the
1 field the option applies to. The function must take four
1 arguments, with the signature
1 'void *, void *, gt_pointer_operator, void *'. The first parameter
1 is a pointer to the structure that contains the object being
1 updated, or the object itself if there is no containing structure.
1 The second parameter is a cookie that should be ignored. The third
1 parameter is a routine that, given a pointer, will update it to its
1 correct new value. The fourth parameter is a cookie that must be
1 passed to the second parameter.
1
1 PCH cannot handle data structures that depend on the absolute
1 values of pointers. 'reorder' functions can be expensive. When
1 possible, it is better to depend on properties of the data, like an
1 ID number or the hash of a string instead.
1
1 'atomic'
1
1 The 'atomic' option can only be used with pointers. It informs the
1 GC machinery that the memory that the pointer points to does not
1 contain any pointers, and hence it should be treated by the GC and
1 PCH machinery as an "atomic" block of memory that does not need to
1 be examined when scanning memory for pointers. In particular, the
1 machinery will not scan that memory for pointers to mark them as
1 reachable (when marking pointers for GC) or to relocate them (when
1 writing a PCH file).
1
1 The 'atomic' option differs from the 'skip' option. 'atomic' keeps
1 the memory under Garbage Collection, but makes the GC ignore the
1 contents of the memory. 'skip' is more drastic in that it causes
1 the pointer and the memory to be completely ignored by the Garbage
1 Collector. So, memory marked as 'atomic' is automatically freed
1 when no longer reachable, while memory marked as 'skip' is not.
1
1 The 'atomic' option must be used with great care, because all sorts
1 of problem can occur if used incorrectly, that is, if the memory
1 the pointer points to does actually contain a pointer.
1
1 Here is an example of how to use it:
1 struct GTY(()) my_struct {
1 int number_of_elements;
1 unsigned int * GTY ((atomic)) elements;
1 };
1 In this case, 'elements' is a pointer under GC, and the memory it
1 points to needs to be allocated using the Garbage Collector, and
1 will be freed automatically by the Garbage Collector when it is no
1 longer referenced. But the memory that the pointer points to is an
1 array of 'unsigned int' elements, and the GC must not try to scan
1 it to find pointers to mark or relocate, which is why it is marked
1 with the 'atomic' option.
1
1 Note that, currently, global variables can not be marked with
1 'atomic'; only fields of a struct can. This is a known limitation.
1 It would be useful to be able to mark global pointers with 'atomic'
1 to make the PCH machinery aware of them so that they are saved and
1 restored correctly to PCH files.
1
1 'special ("NAME")'
1
1 The 'special' option is used to mark types that have to be dealt
1 with by special case machinery. The parameter is the name of the
1 special case. See 'gengtype.c' for further details. Avoid adding
1 new special cases unless there is no other alternative.
1
1 'user'
1
1 The 'user' option indicates that the code to mark structure fields
11 is completely handled by user-provided routines. See section ⇒
User GC for details on what functions need to be provided.
1