GTY(())
Sometimes the C code is not enough to fully describe the type
structure. Extra information can be provided with GTY
options
and additional markers. Some options take a parameter, which may be
either a string or a type name, depending on the parameter. If an
option takes no parameter, it is acceptable either to omit the
parameter entirely, or to provide an empty string as a parameter. For
example, GTY ((skip))
and GTY ((skip ("")))
are
equivalent.
When the parameter is a string, often it is a fragment of C code. Four special escapes may be used in these strings, to refer to pieces of the data structure being marked:
%h
%1
%0
%a
[i1][i2]...
that indexes
the array item currently being marked.
For instance, suppose that you have a structure of the form
struct A { ... }; struct B { struct A foo[12]; };
and b
is a variable of type struct B
. When marking
‘b.foo[11]’, %h
would expand to ‘b.foo[11]’,
%0
and %1
would both expand to ‘b’, and %a
would expand to ‘[11]’.
As in ordinary C, adjacent strings will be concatenated; this is helpful when you have a complicated expression.
GTY ((chain_next ("TREE_CODE (&%h.generic) == INTEGER_TYPE" " ? TYPE_NEXT_VARIANT (&%h.generic)" " : TREE_CHAIN (&%h.generic)")))
length ("
expression")
struct GTY(()) rtvec_def {
int num_elem; /* number of elements */
rtx GTY ((length ("%h.num_elem"))) elem[1];
};
In this case, the length
option is used to override the specified
array length (which should usually be 1
). The parameter of the
option is a fragment of C code that calculates the length.
The second case is when a structure or a global variable contains a pointer to an array, like this:
struct gimple_omp_for_iter * GTY((length ("%h.collapse"))) iter;
In this case, iter
has been allocated by writing something like
x->iter = ggc_alloc_cleared_vec_gimple_omp_for_iter (collapse);
and the collapse
provides the length of the field.
This second use of length
also works on global variables, like:
static GTY((length("reg_known_value_size"))) rtx *reg_known_value;
skip
skip
is applied to a field, the type machinery will ignore it.
This is somewhat dangerous; the only safe use is in a union when one
field really isn't ever used.
desc ("
expression")
tag ("
constant")
default
union
is
currently active. This is done by giving each field a constant
tag
value, and then specifying a discriminator using desc
.
The value of the expression given by desc
is compared against
each tag
value, each of which should be different. If no
tag
is matched, the field marked with default
is used if
there is one, otherwise no field in the union will be marked.
In the desc
option, the “current structure” is the union that
it discriminates. Use %1
to mean the structure containing it.
There are no escapes available to the tag
option, since it is a
constant.
For example,
struct GTY(()) tree_binding { struct tree_common common; union tree_binding_u { tree GTY ((tag ("0"))) scope; struct cp_binding_level * GTY ((tag ("1"))) level; } GTY ((desc ("BINDING_HAS_LEVEL_P ((tree)&%0)"))) xscope; tree value; };
In this example, the value of BINDING_HAS_LEVEL_P when applied to a
struct tree_binding *
is presumed to be 0 or 1. If 1, the type
mechanism will treat the field level
as being present and if 0,
will treat the field scope
as being present.
param_is (
type)
use_param
PTR
) and then use it with a specific
type. param_is
specifies the real type pointed to, and
use_param
says where in the generic data structure that type
should be put.
For instance, to have a htab_t
that points to trees, one would
write the definition of htab_t
like this:
typedef struct GTY(()) { ... void ** GTY ((use_param, ...)) entries; ... } htab_t;
and then declare variables like this:
static htab_t GTY ((param_is (union tree_node))) ict;
param
n_is (
type)
use_param
nparam1_is
through param9_is
may be used to
specify the real type of a field identified by use_param1
through
use_param9
.
use_params
use_params
option.
deletable
deletable
, when applied to a global variable, indicates that when
garbage collection runs, there's no need to mark anything pointed to
by this variable, it can just be set to NULL
instead. This is used
to keep a list of free structures around for re-use.
if_marked ("
expression")
if_marked
option on a global hash table, GGC will call the
routine whose name is the parameter to the option on each hash table
entry. If the routine returns nonzero, the hash table entry will
be marked as usual. If the routine returns zero, the hash table entry
will be deleted.
The routine ggc_marked_p
can be used to determine if an element
has been marked already; in fact, the usual case is to use
if_marked ("ggc_marked_p")
.
mark_hook ("
hook-routine-name")
maybe_undef
maybe_undef
indicates that it's OK if
the structure that this fields points to is never defined, so long as
this field is always NULL
. This is used to avoid requiring
backends to define certain optional structures. It doesn't work with
language frontends.
nested_ptr (
type, "
to expression", "
from expression")
%h
escape.
chain_next ("
expression")
chain_prev ("
expression")
chain_circular ("
expression")
chain_next
is an expression for the next item in the list,
chain_prev
is an expression for the previous item. For singly
linked lists, use only chain_next
; for doubly linked lists, use
both. The machinery requires that taking the next item of the
previous item gives the original item. chain_circular
is similar
to chain_next
, but can be used for circular single linked lists.
reorder ("
function name")
reorder
option, before
changing the pointers in the object that's pointed to by the field the
option applies to. The function must take four arguments, with the
signature ‘void *, void *, gt_pointer_operator, void *’.
The first parameter is a pointer to the structure that contains the
object being updated, or the object itself if there is no containing
structure. The second parameter is a cookie that should be ignored.
The third parameter is a routine that, given a pointer, will update it
to its correct new value. The fourth parameter is a cookie that must
be passed to the second parameter.
PCH cannot handle data structures that depend on the absolute values
of pointers. reorder
functions can be expensive. When
possible, it is better to depend on properties of the data, like an ID
number or the hash of a string instead.
variable_size
variable_size
is used to mark such types.
The type machinery then provides allocators that take a parameter
indicating an exact size of object being allocated. Note that the size
must be provided in bytes whereas the length
option works with
array lengths in number of elements.
For example,
struct GTY((variable_size)) sorted_fields_type { int len; tree GTY((length ("%h.len"))) elts[1]; };
Then the objects of struct sorted_fields_type
are allocated in GC
memory as follows:
field_vec = ggc_alloc_sorted_fields_type (size);
If field_vec->elts stores n elements, then size could be calculated as follows:
size_t size = sizeof (struct sorted_fields_type) + n * sizeof (tree);
atomic
atomic
option can only be used with pointers. It informs
the GC machinery that the memory that the pointer points to does not
contain any pointers, and hence it should be treated by the GC and PCH
machinery as an “atomic” block of memory that does not need to be
examined when scanning memory for pointers. In particular, the
machinery will not scan that memory for pointers to mark them as
reachable (when marking pointers for GC) or to relocate them (when
writing a PCH file).
The atomic
option differs from the skip
option.
atomic
keeps the memory under Garbage Collection, but makes the
GC ignore the contents of the memory. skip
is more drastic in
that it causes the pointer and the memory to be completely ignored by
the Garbage Collector. So, memory marked as atomic
is
automatically freed when no longer reachable, while memory marked as
skip
is not.
The atomic
option must be used with great care, because all
sorts of problem can occur if used incorrectly, that is, if the memory
the pointer points to does actually contain a pointer.
Here is an example of how to use it:
struct GTY(()) my_struct { int number_of_elements; unsigned int GTY ((atomic)) * elements; };
In this case, elements
is a pointer under GC, and the memory it
points to needs to be allocated using the Garbage Collector, and will
be freed automatically by the Garbage Collector when it is no longer
referenced. But the memory that the pointer points to is an array of
unsigned int
elements, and the GC must not try to scan it to
find pointers to mark or relocate, which is why it is marked with the
atomic
option.
Note that, currently, global variables can not be marked with
atomic
; only fields of a struct can. This is a known
limitation. It would be useful to be able to mark global pointers
with atomic
to make the PCH machinery aware of them so that
they are saved and restored correctly to PCH files.
special ("
name")
special
option is used to mark types that have to be dealt
with by special case machinery. The parameter is the name of the
special case. See gengtype.c for further details. Avoid
adding new special cases unless there is no other alternative.