@c Copyright (C) 2002, 2003, 2004, 2007, 2008, 2009
|
@c Copyright (C) 2002, 2003, 2004, 2007, 2008, 2009
|
@c Free Software Foundation, Inc.
|
@c Free Software Foundation, Inc.
|
@c This is part of the GCC manual.
|
@c This is part of the GCC manual.
|
@c For copying conditions, see the file gcc.texi.
|
@c For copying conditions, see the file gcc.texi.
|
|
|
@node Type Information
|
@node Type Information
|
@chapter Memory Management and Type Information
|
@chapter Memory Management and Type Information
|
@cindex GGC
|
@cindex GGC
|
@findex GTY
|
@findex GTY
|
|
|
GCC uses some fairly sophisticated memory management techniques, which
|
GCC uses some fairly sophisticated memory management techniques, which
|
involve determining information about GCC's data structures from GCC's
|
involve determining information about GCC's data structures from GCC's
|
source code and using this information to perform garbage collection and
|
source code and using this information to perform garbage collection and
|
implement precompiled headers.
|
implement precompiled headers.
|
|
|
A full C parser would be too complicated for this task, so a limited
|
A full C parser would be too complicated for this task, so a limited
|
subset of C is interpreted and special markers are used to determine
|
subset of C is interpreted and special markers are used to determine
|
what parts of the source to look at. All @code{struct} and
|
what parts of the source to look at. All @code{struct} and
|
@code{union} declarations that define data structures that are
|
@code{union} declarations that define data structures that are
|
allocated under control of the garbage collector must be marked. All
|
allocated under control of the garbage collector must be marked. All
|
global variables that hold pointers to garbage-collected memory must
|
global variables that hold pointers to garbage-collected memory must
|
also be marked. Finally, all global variables that need to be saved
|
also be marked. Finally, all global variables that need to be saved
|
and restored by a precompiled header must be marked. (The precompiled
|
and restored by a precompiled header must be marked. (The precompiled
|
header mechanism can only save static variables if they're scalar.
|
header mechanism can only save static variables if they're scalar.
|
Complex data structures must be allocated in garbage-collected memory
|
Complex data structures must be allocated in garbage-collected memory
|
to be saved in a precompiled header.)
|
to be saved in a precompiled header.)
|
|
|
The full format of a marker is
|
The full format of a marker is
|
@smallexample
|
@smallexample
|
GTY (([@var{option}] [(@var{param})], [@var{option}] [(@var{param})] @dots{}))
|
GTY (([@var{option}] [(@var{param})], [@var{option}] [(@var{param})] @dots{}))
|
@end smallexample
|
@end smallexample
|
@noindent
|
@noindent
|
but in most cases no options are needed. The outer double parentheses
|
but in most cases no options are needed. The outer double parentheses
|
are still necessary, though: @code{GTY(())}. Markers can appear:
|
are still necessary, though: @code{GTY(())}. Markers can appear:
|
|
|
@itemize @bullet
|
@itemize @bullet
|
@item
|
@item
|
In a structure definition, before the open brace;
|
In a structure definition, before the open brace;
|
@item
|
@item
|
In a global variable declaration, after the keyword @code{static} or
|
In a global variable declaration, after the keyword @code{static} or
|
@code{extern}; and
|
@code{extern}; and
|
@item
|
@item
|
In a structure field definition, before the name of the field.
|
In a structure field definition, before the name of the field.
|
@end itemize
|
@end itemize
|
|
|
Here are some examples of marking simple data structures and globals.
|
Here are some examples of marking simple data structures and globals.
|
|
|
@smallexample
|
@smallexample
|
struct GTY(()) @var{tag}
|
struct GTY(()) @var{tag}
|
@{
|
@{
|
@var{fields}@dots{}
|
@var{fields}@dots{}
|
@};
|
@};
|
|
|
typedef struct GTY(()) @var{tag}
|
typedef struct GTY(()) @var{tag}
|
@{
|
@{
|
@var{fields}@dots{}
|
@var{fields}@dots{}
|
@} *@var{typename};
|
@} *@var{typename};
|
|
|
static GTY(()) struct @var{tag} *@var{list}; /* @r{points to GC memory} */
|
static GTY(()) struct @var{tag} *@var{list}; /* @r{points to GC memory} */
|
static GTY(()) int @var{counter}; /* @r{save counter in a PCH} */
|
static GTY(()) int @var{counter}; /* @r{save counter in a PCH} */
|
@end smallexample
|
@end smallexample
|
|
|
The parser understands simple typedefs such as
|
The parser understands simple typedefs such as
|
@code{typedef struct @var{tag} *@var{name};} and
|
@code{typedef struct @var{tag} *@var{name};} and
|
@code{typedef int @var{name};}.
|
@code{typedef int @var{name};}.
|
These don't need to be marked.
|
These don't need to be marked.
|
|
|
@menu
|
@menu
|
* GTY Options:: What goes inside a @code{GTY(())}.
|
* GTY Options:: What goes inside a @code{GTY(())}.
|
* GGC Roots:: Making global variables GGC roots.
|
* GGC Roots:: Making global variables GGC roots.
|
* Files:: How the generated files work.
|
* Files:: How the generated files work.
|
* Invoking the garbage collector:: How to invoke the garbage collector.
|
* Invoking the garbage collector:: How to invoke the garbage collector.
|
@end menu
|
@end menu
|
|
|
@node GTY Options
|
@node GTY Options
|
@section The Inside of a @code{GTY(())}
|
@section The Inside of a @code{GTY(())}
|
|
|
Sometimes the C code is not enough to fully describe the type
|
Sometimes the C code is not enough to fully describe the type
|
structure. Extra information can be provided with @code{GTY} options
|
structure. Extra information can be provided with @code{GTY} options
|
and additional markers. Some options take a parameter, which may be
|
and additional markers. Some options take a parameter, which may be
|
either a string or a type name, depending on the parameter. If an
|
either a string or a type name, depending on the parameter. If an
|
option takes no parameter, it is acceptable either to omit the
|
option takes no parameter, it is acceptable either to omit the
|
parameter entirely, or to provide an empty string as a parameter. For
|
parameter entirely, or to provide an empty string as a parameter. For
|
example, @code{@w{GTY ((skip))}} and @code{@w{GTY ((skip ("")))}} are
|
example, @code{@w{GTY ((skip))}} and @code{@w{GTY ((skip ("")))}} are
|
equivalent.
|
equivalent.
|
|
|
When the parameter is a string, often it is a fragment of C code. Four
|
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
|
special escapes may be used in these strings, to refer to pieces of
|
the data structure being marked:
|
the data structure being marked:
|
|
|
@cindex % in GTY option
|
@cindex % in GTY option
|
@table @code
|
@table @code
|
@item %h
|
@item %h
|
The current structure.
|
The current structure.
|
@item %1
|
@item %1
|
The structure that immediately contains the current structure.
|
The structure that immediately contains the current structure.
|
@item %0
|
@item %0
|
The outermost structure that contains the current structure.
|
The outermost structure that contains the current structure.
|
@item %a
|
@item %a
|
A partial expression of the form @code{[i1][i2]@dots{}} that indexes
|
A partial expression of the form @code{[i1][i2]@dots{}} that indexes
|
the array item currently being marked.
|
the array item currently being marked.
|
@end table
|
@end table
|
|
|
For instance, suppose that you have a structure of the form
|
For instance, suppose that you have a structure of the form
|
@smallexample
|
@smallexample
|
struct A @{
|
struct A @{
|
@dots{}
|
@dots{}
|
@};
|
@};
|
struct B @{
|
struct B @{
|
struct A foo[12];
|
struct A foo[12];
|
@};
|
@};
|
@end smallexample
|
@end smallexample
|
@noindent
|
@noindent
|
and @code{b} is a variable of type @code{struct B}. When marking
|
and @code{b} is a variable of type @code{struct B}. When marking
|
@samp{b.foo[11]}, @code{%h} would expand to @samp{b.foo[11]},
|
@samp{b.foo[11]}, @code{%h} would expand to @samp{b.foo[11]},
|
@code{%0} and @code{%1} would both expand to @samp{b}, and @code{%a}
|
@code{%0} and @code{%1} would both expand to @samp{b}, and @code{%a}
|
would expand to @samp{[11]}.
|
would expand to @samp{[11]}.
|
|
|
As in ordinary C, adjacent strings will be concatenated; this is
|
As in ordinary C, adjacent strings will be concatenated; this is
|
helpful when you have a complicated expression.
|
helpful when you have a complicated expression.
|
@smallexample
|
@smallexample
|
@group
|
@group
|
GTY ((chain_next ("TREE_CODE (&%h.generic) == INTEGER_TYPE"
|
GTY ((chain_next ("TREE_CODE (&%h.generic) == INTEGER_TYPE"
|
" ? TYPE_NEXT_VARIANT (&%h.generic)"
|
" ? TYPE_NEXT_VARIANT (&%h.generic)"
|
" : TREE_CHAIN (&%h.generic)")))
|
" : TREE_CHAIN (&%h.generic)")))
|
@end group
|
@end group
|
@end smallexample
|
@end smallexample
|
|
|
The available options are:
|
The available options are:
|
|
|
@table @code
|
@table @code
|
@findex length
|
@findex length
|
@item length ("@var{expression}")
|
@item length ("@var{expression}")
|
|
|
There are two places the type machinery will need to be explicitly told
|
There are two places the type machinery will need to be explicitly told
|
the length of an array. The first case is when a structure ends in a
|
the length of an array. The first case is when a structure ends in a
|
variable-length array, like this:
|
variable-length array, like this:
|
@smallexample
|
@smallexample
|
struct GTY(()) rtvec_def @{
|
struct GTY(()) rtvec_def @{
|
int num_elem; /* @r{number of elements} */
|
int num_elem; /* @r{number of elements} */
|
rtx GTY ((length ("%h.num_elem"))) elem[1];
|
rtx GTY ((length ("%h.num_elem"))) elem[1];
|
@};
|
@};
|
@end smallexample
|
@end smallexample
|
|
|
In this case, the @code{length} option is used to override the specified
|
In this case, the @code{length} option is used to override the specified
|
array length (which should usually be @code{1}). The parameter of the
|
array length (which should usually be @code{1}). The parameter of the
|
option is a fragment of C code that calculates the length.
|
option is a fragment of C code that calculates the length.
|
|
|
The second case is when a structure or a global variable contains a
|
The second case is when a structure or a global variable contains a
|
pointer to an array, like this:
|
pointer to an array, like this:
|
@smallexample
|
@smallexample
|
tree *
|
tree *
|
GTY ((length ("%h.regno_pointer_align_length"))) regno_decl;
|
GTY ((length ("%h.regno_pointer_align_length"))) regno_decl;
|
@end smallexample
|
@end smallexample
|
In this case, @code{regno_decl} has been allocated by writing something like
|
In this case, @code{regno_decl} has been allocated by writing something like
|
@smallexample
|
@smallexample
|
x->regno_decl =
|
x->regno_decl =
|
ggc_alloc (x->regno_pointer_align_length * sizeof (tree));
|
ggc_alloc (x->regno_pointer_align_length * sizeof (tree));
|
@end smallexample
|
@end smallexample
|
and the @code{length} provides the length of the field.
|
and the @code{length} provides the length of the field.
|
|
|
This second use of @code{length} also works on global variables, like:
|
This second use of @code{length} also works on global variables, like:
|
@verbatim
|
@verbatim
|
static GTY((length ("reg_base_value_size")))
|
static GTY((length ("reg_base_value_size")))
|
rtx *reg_base_value;
|
rtx *reg_base_value;
|
@end verbatim
|
@end verbatim
|
|
|
@findex skip
|
@findex skip
|
@item skip
|
@item skip
|
|
|
If @code{skip} is applied to a field, the type machinery will ignore it.
|
If @code{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
|
This is somewhat dangerous; the only safe use is in a union when one
|
field really isn't ever used.
|
field really isn't ever used.
|
|
|
@findex desc
|
@findex desc
|
@findex tag
|
@findex tag
|
@findex default
|
@findex default
|
@item desc ("@var{expression}")
|
@item desc ("@var{expression}")
|
@itemx tag ("@var{constant}")
|
@itemx tag ("@var{constant}")
|
@itemx default
|
@itemx default
|
|
|
The type machinery needs to be told which field of a @code{union} is
|
The type machinery needs to be told which field of a @code{union} is
|
currently active. This is done by giving each field a constant
|
currently active. This is done by giving each field a constant
|
@code{tag} value, and then specifying a discriminator using @code{desc}.
|
@code{tag} value, and then specifying a discriminator using @code{desc}.
|
The value of the expression given by @code{desc} is compared against
|
The value of the expression given by @code{desc} is compared against
|
each @code{tag} value, each of which should be different. If no
|
each @code{tag} value, each of which should be different. If no
|
@code{tag} is matched, the field marked with @code{default} is used if
|
@code{tag} is matched, the field marked with @code{default} is used if
|
there is one, otherwise no field in the union will be marked.
|
there is one, otherwise no field in the union will be marked.
|
|
|
In the @code{desc} option, the ``current structure'' is the union that
|
In the @code{desc} option, the ``current structure'' is the union that
|
it discriminates. Use @code{%1} to mean the structure containing it.
|
it discriminates. Use @code{%1} to mean the structure containing it.
|
There are no escapes available to the @code{tag} option, since it is a
|
There are no escapes available to the @code{tag} option, since it is a
|
constant.
|
constant.
|
|
|
For example,
|
For example,
|
@smallexample
|
@smallexample
|
struct GTY(()) tree_binding
|
struct GTY(()) tree_binding
|
@{
|
@{
|
struct tree_common common;
|
struct tree_common common;
|
union tree_binding_u @{
|
union tree_binding_u @{
|
tree GTY ((tag ("0"))) scope;
|
tree GTY ((tag ("0"))) scope;
|
struct cp_binding_level * GTY ((tag ("1"))) level;
|
struct cp_binding_level * GTY ((tag ("1"))) level;
|
@} GTY ((desc ("BINDING_HAS_LEVEL_P ((tree)&%0)"))) xscope;
|
@} GTY ((desc ("BINDING_HAS_LEVEL_P ((tree)&%0)"))) xscope;
|
tree value;
|
tree value;
|
@};
|
@};
|
@end smallexample
|
@end smallexample
|
|
|
In this example, the value of BINDING_HAS_LEVEL_P when applied to a
|
In this example, the value of BINDING_HAS_LEVEL_P when applied to a
|
@code{struct tree_binding *} is presumed to be 0 or 1. If 1, the type
|
@code{struct tree_binding *} is presumed to be 0 or 1. If 1, the type
|
mechanism will treat the field @code{level} as being present and if 0,
|
mechanism will treat the field @code{level} as being present and if 0,
|
will treat the field @code{scope} as being present.
|
will treat the field @code{scope} as being present.
|
|
|
@findex param_is
|
@findex param_is
|
@findex use_param
|
@findex use_param
|
@item param_is (@var{type})
|
@item param_is (@var{type})
|
@itemx use_param
|
@itemx use_param
|
|
|
Sometimes it's convenient to define some data structure to work on
|
Sometimes it's convenient to define some data structure to work on
|
generic pointers (that is, @code{PTR}) and then use it with a specific
|
generic pointers (that is, @code{PTR}) and then use it with a specific
|
type. @code{param_is} specifies the real type pointed to, and
|
type. @code{param_is} specifies the real type pointed to, and
|
@code{use_param} says where in the generic data structure that type
|
@code{use_param} says where in the generic data structure that type
|
should be put.
|
should be put.
|
|
|
For instance, to have a @code{htab_t} that points to trees, one would
|
For instance, to have a @code{htab_t} that points to trees, one would
|
write the definition of @code{htab_t} like this:
|
write the definition of @code{htab_t} like this:
|
@smallexample
|
@smallexample
|
typedef struct GTY(()) @{
|
typedef struct GTY(()) @{
|
@dots{}
|
@dots{}
|
void ** GTY ((use_param, @dots{})) entries;
|
void ** GTY ((use_param, @dots{})) entries;
|
@dots{}
|
@dots{}
|
@} htab_t;
|
@} htab_t;
|
@end smallexample
|
@end smallexample
|
and then declare variables like this:
|
and then declare variables like this:
|
@smallexample
|
@smallexample
|
static htab_t GTY ((param_is (union tree_node))) ict;
|
static htab_t GTY ((param_is (union tree_node))) ict;
|
@end smallexample
|
@end smallexample
|
|
|
@findex param@var{n}_is
|
@findex param@var{n}_is
|
@findex use_param@var{n}
|
@findex use_param@var{n}
|
@item param@var{n}_is (@var{type})
|
@item param@var{n}_is (@var{type})
|
@itemx use_param@var{n}
|
@itemx use_param@var{n}
|
|
|
In more complicated cases, the data structure might need to work on
|
In more complicated cases, the data structure might need to work on
|
several different types, which might not necessarily all be pointers.
|
several different types, which might not necessarily all be pointers.
|
For this, @code{param1_is} through @code{param9_is} may be used to
|
For this, @code{param1_is} through @code{param9_is} may be used to
|
specify the real type of a field identified by @code{use_param1} through
|
specify the real type of a field identified by @code{use_param1} through
|
@code{use_param9}.
|
@code{use_param9}.
|
|
|
@findex use_params
|
@findex use_params
|
@item use_params
|
@item use_params
|
|
|
When a structure contains another structure that is parameterized,
|
When a structure contains another structure that is parameterized,
|
there's no need to do anything special, the inner structure inherits the
|
there's no need to do anything special, the inner structure inherits the
|
parameters of the outer one. When a structure contains a pointer to a
|
parameters of the outer one. When a structure contains a pointer to a
|
parameterized structure, the type machinery won't automatically detect
|
parameterized structure, the type machinery won't automatically detect
|
this (it could, it just doesn't yet), so it's necessary to tell it that
|
this (it could, it just doesn't yet), so it's necessary to tell it that
|
the pointed-to structure should use the same parameters as the outer
|
the pointed-to structure should use the same parameters as the outer
|
structure. This is done by marking the pointer with the
|
structure. This is done by marking the pointer with the
|
@code{use_params} option.
|
@code{use_params} option.
|
|
|
@findex deletable
|
@findex deletable
|
@item deletable
|
@item deletable
|
|
|
@code{deletable}, when applied to a global variable, indicates that when
|
@code{deletable}, when applied to a global variable, indicates that when
|
garbage collection runs, there's no need to mark anything pointed to
|
garbage collection runs, there's no need to mark anything pointed to
|
by this variable, it can just be set to @code{NULL} instead. This is used
|
by this variable, it can just be set to @code{NULL} instead. This is used
|
to keep a list of free structures around for re-use.
|
to keep a list of free structures around for re-use.
|
|
|
@findex if_marked
|
@findex if_marked
|
@item if_marked ("@var{expression}")
|
@item if_marked ("@var{expression}")
|
|
|
Suppose you want some kinds of object to be unique, and so you put them
|
Suppose you want some kinds of object to be unique, and so you put them
|
in a hash table. If garbage collection marks the hash table, these
|
in a hash table. If garbage collection marks the hash table, these
|
objects will never be freed, even if the last other reference to them
|
objects will never be freed, even if the last other reference to them
|
goes away. GGC has special handling to deal with this: if you use the
|
goes away. GGC has special handling to deal with this: if you use the
|
@code{if_marked} option on a global hash table, GGC will call the
|
@code{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
|
routine whose name is the parameter to the option on each hash table
|
entry. If the routine returns nonzero, the hash table entry will
|
entry. If the routine returns nonzero, the hash table entry will
|
be marked as usual. If the routine returns zero, the hash table entry
|
be marked as usual. If the routine returns zero, the hash table entry
|
will be deleted.
|
will be deleted.
|
|
|
The routine @code{ggc_marked_p} can be used to determine if an element
|
The routine @code{ggc_marked_p} can be used to determine if an element
|
has been marked already; in fact, the usual case is to use
|
has been marked already; in fact, the usual case is to use
|
@code{if_marked ("ggc_marked_p")}.
|
@code{if_marked ("ggc_marked_p")}.
|
|
|
@findex mark_hook
|
@findex mark_hook
|
@item mark_hook ("@var{hook-routine-name}")
|
@item mark_hook ("@var{hook-routine-name}")
|
|
|
If provided for a structure or union type, the given
|
If provided for a structure or union type, the given
|
@var{hook-routine-name} (between double-quotes) is the name of a
|
@var{hook-routine-name} (between double-quotes) is the name of a
|
routine called when the garbage collector has just marked the data as
|
routine called when the garbage collector has just marked the data as
|
reachable. This routine should not change the data, or call any ggc
|
reachable. This routine should not change the data, or call any ggc
|
routine. Its only argument is a pointer to the just marked (const)
|
routine. Its only argument is a pointer to the just marked (const)
|
structure or union.
|
structure or union.
|
|
|
@findex maybe_undef
|
@findex maybe_undef
|
@item maybe_undef
|
@item maybe_undef
|
|
|
When applied to a field, @code{maybe_undef} indicates that it's OK if
|
When applied to a field, @code{maybe_undef} indicates that it's OK if
|
the structure that this fields points to is never defined, so long as
|
the structure that this fields points to is never defined, so long as
|
this field is always @code{NULL}. This is used to avoid requiring
|
this field is always @code{NULL}. This is used to avoid requiring
|
backends to define certain optional structures. It doesn't work with
|
backends to define certain optional structures. It doesn't work with
|
language frontends.
|
language frontends.
|
|
|
@findex nested_ptr
|
@findex nested_ptr
|
@item nested_ptr (@var{type}, "@var{to expression}", "@var{from expression}")
|
@item nested_ptr (@var{type}, "@var{to expression}", "@var{from expression}")
|
|
|
The type machinery expects all pointers to point to the start of an
|
The type machinery expects all pointers to point to the start of an
|
object. Sometimes for abstraction purposes it's convenient to have
|
object. Sometimes for abstraction purposes it's convenient to have
|
a pointer which points inside an object. So long as it's possible to
|
a pointer which points inside an object. So long as it's possible to
|
convert the original object to and from the pointer, such pointers
|
convert the original object to and from the pointer, such pointers
|
can still be used. @var{type} is the type of the original object,
|
can still be used. @var{type} is the type of the original object,
|
the @var{to expression} returns the pointer given the original object,
|
the @var{to expression} returns the pointer given the original object,
|
and the @var{from expression} returns the original object given
|
and the @var{from expression} returns the original object given
|
the pointer. The pointer will be available using the @code{%h}
|
the pointer. The pointer will be available using the @code{%h}
|
escape.
|
escape.
|
|
|
@findex chain_next
|
@findex chain_next
|
@findex chain_prev
|
@findex chain_prev
|
@findex chain_circular
|
@findex chain_circular
|
@item chain_next ("@var{expression}")
|
@item chain_next ("@var{expression}")
|
@itemx chain_prev ("@var{expression}")
|
@itemx chain_prev ("@var{expression}")
|
@itemx chain_circular ("@var{expression}")
|
@itemx chain_circular ("@var{expression}")
|
|
|
It's helpful for the type machinery to know if objects are often
|
It's helpful for the type machinery to know if objects are often
|
chained together in long lists; this lets it generate code that uses
|
chained together in long lists; this lets it generate code that uses
|
less stack space by iterating along the list instead of recursing down
|
less stack space by iterating along the list instead of recursing down
|
it. @code{chain_next} is an expression for the next item in the list,
|
it. @code{chain_next} is an expression for the next item in the list,
|
@code{chain_prev} is an expression for the previous item. For singly
|
@code{chain_prev} is an expression for the previous item. For singly
|
linked lists, use only @code{chain_next}; for doubly linked lists, use
|
linked lists, use only @code{chain_next}; for doubly linked lists, use
|
both. The machinery requires that taking the next item of the
|
both. The machinery requires that taking the next item of the
|
previous item gives the original item. @code{chain_circular} is similar
|
previous item gives the original item. @code{chain_circular} is similar
|
to @code{chain_next}, but can be used for circular single linked lists.
|
to @code{chain_next}, but can be used for circular single linked lists.
|
|
|
@findex reorder
|
@findex reorder
|
@item reorder ("@var{function name}")
|
@item reorder ("@var{function name}")
|
|
|
Some data structures depend on the relative ordering of pointers. If
|
Some data structures depend on the relative ordering of pointers. If
|
the precompiled header machinery needs to change that ordering, it
|
the precompiled header machinery needs to change that ordering, it
|
will call the function referenced by the @code{reorder} option, before
|
will call the function referenced by the @code{reorder} option, before
|
changing the pointers in the object that's pointed to by the field the
|
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
|
option applies to. The function must take four arguments, with the
|
signature @samp{@w{void *, void *, gt_pointer_operator, void *}}.
|
signature @samp{@w{void *, void *, gt_pointer_operator, void *}}.
|
The first parameter is a pointer to the structure that contains the
|
The first parameter is a pointer to the structure that contains the
|
object being updated, or the object itself if there is no containing
|
object being updated, or the object itself if there is no containing
|
structure. The second parameter is a cookie that should be ignored.
|
structure. The second parameter is a cookie that should be ignored.
|
The third parameter is a routine that, given a pointer, will update it
|
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
|
to its correct new value. The fourth parameter is a cookie that must
|
be passed to the second parameter.
|
be passed to the second parameter.
|
|
|
PCH cannot handle data structures that depend on the absolute values
|
PCH cannot handle data structures that depend on the absolute values
|
of pointers. @code{reorder} functions can be expensive. When
|
of pointers. @code{reorder} functions can be expensive. When
|
possible, it is better to depend on properties of the data, like an ID
|
possible, it is better to depend on properties of the data, like an ID
|
number or the hash of a string instead.
|
number or the hash of a string instead.
|
|
|
@findex special
|
@findex special
|
@item special ("@var{name}")
|
@item special ("@var{name}")
|
|
|
The @code{special} option is used to mark types that have to be dealt
|
The @code{special} option is used to mark types that have to be dealt
|
with by special case machinery. The parameter is the name of the
|
with by special case machinery. The parameter is the name of the
|
special case. See @file{gengtype.c} for further details. Avoid
|
special case. See @file{gengtype.c} for further details. Avoid
|
adding new special cases unless there is no other alternative.
|
adding new special cases unless there is no other alternative.
|
@end table
|
@end table
|
|
|
@node GGC Roots
|
@node GGC Roots
|
@section Marking Roots for the Garbage Collector
|
@section Marking Roots for the Garbage Collector
|
@cindex roots, marking
|
@cindex roots, marking
|
@cindex marking roots
|
@cindex marking roots
|
|
|
In addition to keeping track of types, the type machinery also locates
|
In addition to keeping track of types, the type machinery also locates
|
the global variables (@dfn{roots}) that the garbage collector starts
|
the global variables (@dfn{roots}) that the garbage collector starts
|
at. Roots must be declared using one of the following syntaxes:
|
at. Roots must be declared using one of the following syntaxes:
|
|
|
@itemize @bullet
|
@itemize @bullet
|
@item
|
@item
|
@code{extern GTY(([@var{options}])) @var{type} @var{name};}
|
@code{extern GTY(([@var{options}])) @var{type} @var{name};}
|
@item
|
@item
|
@code{static GTY(([@var{options}])) @var{type} @var{name};}
|
@code{static GTY(([@var{options}])) @var{type} @var{name};}
|
@end itemize
|
@end itemize
|
@noindent
|
@noindent
|
The syntax
|
The syntax
|
@itemize @bullet
|
@itemize @bullet
|
@item
|
@item
|
@code{GTY(([@var{options}])) @var{type} @var{name};}
|
@code{GTY(([@var{options}])) @var{type} @var{name};}
|
@end itemize
|
@end itemize
|
@noindent
|
@noindent
|
is @emph{not} accepted. There should be an @code{extern} declaration
|
is @emph{not} accepted. There should be an @code{extern} declaration
|
of such a variable in a header somewhere---mark that, not the
|
of such a variable in a header somewhere---mark that, not the
|
definition. Or, if the variable is only used in one file, make it
|
definition. Or, if the variable is only used in one file, make it
|
@code{static}.
|
@code{static}.
|
|
|
@node Files
|
@node Files
|
@section Source Files Containing Type Information
|
@section Source Files Containing Type Information
|
@cindex generated files
|
@cindex generated files
|
@cindex files, generated
|
@cindex files, generated
|
|
|
Whenever you add @code{GTY} markers to a source file that previously
|
Whenever you add @code{GTY} markers to a source file that previously
|
had none, or create a new source file containing @code{GTY} markers,
|
had none, or create a new source file containing @code{GTY} markers,
|
there are three things you need to do:
|
there are three things you need to do:
|
|
|
@enumerate
|
@enumerate
|
@item
|
@item
|
You need to add the file to the list of source files the type
|
You need to add the file to the list of source files the type
|
machinery scans. There are four cases:
|
machinery scans. There are four cases:
|
|
|
@enumerate a
|
@enumerate a
|
@item
|
@item
|
For a back-end file, this is usually done
|
For a back-end file, this is usually done
|
automatically; if not, you should add it to @code{target_gtfiles} in
|
automatically; if not, you should add it to @code{target_gtfiles} in
|
the appropriate port's entries in @file{config.gcc}.
|
the appropriate port's entries in @file{config.gcc}.
|
|
|
@item
|
@item
|
For files shared by all front ends, add the filename to the
|
For files shared by all front ends, add the filename to the
|
@code{GTFILES} variable in @file{Makefile.in}.
|
@code{GTFILES} variable in @file{Makefile.in}.
|
|
|
@item
|
@item
|
For files that are part of one front end, add the filename to the
|
For files that are part of one front end, add the filename to the
|
@code{gtfiles} variable defined in the appropriate
|
@code{gtfiles} variable defined in the appropriate
|
@file{config-lang.in}. For C, the file is @file{c-config-lang.in}.
|
@file{config-lang.in}. For C, the file is @file{c-config-lang.in}.
|
Headers should appear before non-headers in this list.
|
Headers should appear before non-headers in this list.
|
|
|
@item
|
@item
|
For files that are part of some but not all front ends, add the
|
For files that are part of some but not all front ends, add the
|
filename to the @code{gtfiles} variable of @emph{all} the front ends
|
filename to the @code{gtfiles} variable of @emph{all} the front ends
|
that use it.
|
that use it.
|
@end enumerate
|
@end enumerate
|
|
|
@item
|
@item
|
If the file was a header file, you'll need to check that it's included
|
If the file was a header file, you'll need to check that it's included
|
in the right place to be visible to the generated files. For a back-end
|
in the right place to be visible to the generated files. For a back-end
|
header file, this should be done automatically. For a front-end header
|
header file, this should be done automatically. For a front-end header
|
file, it needs to be included by the same file that includes
|
file, it needs to be included by the same file that includes
|
@file{gtype-@var{lang}.h}. For other header files, it needs to be
|
@file{gtype-@var{lang}.h}. For other header files, it needs to be
|
included in @file{gtype-desc.c}, which is a generated file, so add it to
|
included in @file{gtype-desc.c}, which is a generated file, so add it to
|
@code{ifiles} in @code{open_base_file} in @file{gengtype.c}.
|
@code{ifiles} in @code{open_base_file} in @file{gengtype.c}.
|
|
|
For source files that aren't header files, the machinery will generate a
|
For source files that aren't header files, the machinery will generate a
|
header file that should be included in the source file you just changed.
|
header file that should be included in the source file you just changed.
|
The file will be called @file{gt-@var{path}.h} where @var{path} is the
|
The file will be called @file{gt-@var{path}.h} where @var{path} is the
|
pathname relative to the @file{gcc} directory with slashes replaced by
|
pathname relative to the @file{gcc} directory with slashes replaced by
|
@verb{|-|}, so for example the header file to be included in
|
@verb{|-|}, so for example the header file to be included in
|
@file{cp/parser.c} is called @file{gt-cp-parser.c}. The
|
@file{cp/parser.c} is called @file{gt-cp-parser.c}. The
|
generated header file should be included after everything else in the
|
generated header file should be included after everything else in the
|
source file. Don't forget to mention this file as a dependency in the
|
source file. Don't forget to mention this file as a dependency in the
|
@file{Makefile}!
|
@file{Makefile}!
|
|
|
@end enumerate
|
@end enumerate
|
|
|
For language frontends, there is another file that needs to be included
|
For language frontends, there is another file that needs to be included
|
somewhere. It will be called @file{gtype-@var{lang}.h}, where
|
somewhere. It will be called @file{gtype-@var{lang}.h}, where
|
@var{lang} is the name of the subdirectory the language is contained in.
|
@var{lang} is the name of the subdirectory the language is contained in.
|
|
|
Plugins can add additional root tables. Run the @code{gengtype}
|
Plugins can add additional root tables. Run the @code{gengtype}
|
utility in plugin mode as @code{gengtype -P pluginout.h @var{source-dir}
|
utility in plugin mode as @code{gengtype -P pluginout.h @var{source-dir}
|
@var{file-list} @var{plugin*.c}} with your plugin files
|
@var{file-list} @var{plugin*.c}} with your plugin files
|
@var{plugin*.c} using @code{GTY} to generate the @var{pluginout.h} file.
|
@var{plugin*.c} using @code{GTY} to generate the @var{pluginout.h} file.
|
The GCC build tree is needed to be present in that mode.
|
The GCC build tree is needed to be present in that mode.
|
|
|
|
|
@node Invoking the garbage collector
|
@node Invoking the garbage collector
|
@section How to invoke the garbage collector
|
@section How to invoke the garbage collector
|
@cindex garbage collector, invocation
|
@cindex garbage collector, invocation
|
@findex ggc_collect
|
@findex ggc_collect
|
|
|
The GCC garbage collector GGC is only invoked explicitly. In contrast
|
The GCC garbage collector GGC is only invoked explicitly. In contrast
|
with many other garbage collectors, it is not implicitly invoked by
|
with many other garbage collectors, it is not implicitly invoked by
|
allocation routines when a lot of memory has been consumed. So the
|
allocation routines when a lot of memory has been consumed. So the
|
only way to have GGC reclaim storage it to call the @code{ggc_collect}
|
only way to have GGC reclaim storage it to call the @code{ggc_collect}
|
function explicitly. This call is an expensive operation, as it may
|
function explicitly. This call is an expensive operation, as it may
|
have to scan the entire heap. Beware that local variables (on the GCC
|
have to scan the entire heap. Beware that local variables (on the GCC
|
call stack) are not followed by such an invocation (as many other
|
call stack) are not followed by such an invocation (as many other
|
garbage collectors do): you should reference all your data from static
|
garbage collectors do): you should reference all your data from static
|
or external @code{GTY}-ed variables, and it is advised to call
|
or external @code{GTY}-ed variables, and it is advised to call
|
@code{ggc_collect} with a shallow call stack. The GGC is an exact mark
|
@code{ggc_collect} with a shallow call stack. The GGC is an exact mark
|
and sweep garbage collector (so it does not scan the call stack for
|
and sweep garbage collector (so it does not scan the call stack for
|
pointers). In practice GCC passes don't often call @code{ggc_collect}
|
pointers). In practice GCC passes don't often call @code{ggc_collect}
|
themselves, because it is called by the pass manager between passes.
|
themselves, because it is called by the pass manager between passes.
|
|
|
