diff options
Diffstat (limited to 'gcc/doc/gty.texi')
| -rw-r--r-- | gcc/doc/gty.texi | 284 |
1 files changed, 173 insertions, 111 deletions
diff --git a/gcc/doc/gty.texi b/gcc/doc/gty.texi index 2dc5b86dce3..05d9b9e6699 100644 --- a/gcc/doc/gty.texi +++ b/gcc/doc/gty.texi @@ -13,37 +13,26 @@ involve determining information about GCC's data structures from GCC's source code and using this information to perform garbage collection and implement precompiled headers. -A full C parser would be too overcomplicated 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 -what parts of the source to look at. The parser can also detect -simple typedefs of the form @code{typedef struct ID1 *ID2;} and -@code{typedef int ID3;}, and these don't need to be specially marked. - -The two forms that do need to be marked are: -@verbatim -struct ID1 GTY(([options])) -{ - [fields] -}; - -typedef struct ID2 GTY(([options])) -{ - [fields] -} ID3; -@end verbatim - -@menu -* GTY Options:: What goes inside a @code{GTY(())}. -* GGC Roots:: Making global variables GGC roots. -* Files:: How the generated files work. -@end menu - -@node GTY Options -@section The Inside of a @code{GTY(())} +what parts of the source to look at. All @code{struct} and +@code{union} declarations that define data structures that are +allocated under control of the garbage collector must be marked. All +global variables that hold pointers to garbage-collected memory must +also be marked. Finally, all global variables that need to be saved +and restored by a precompiled header must be marked. (The precompiled +header mechanism can only save static variables if they're scalar. +Complex data structures must be allocated in garbage-collected memory +to be saved in a precompiled header.) + +The full format of a marker is +@smallexample +GTY (([@var{option}] [(@var{param})], [@var{option}] [(@var{param})] @dots{})) +@end smallexample +@noindent +but in most cases no options are needed. The outer double parentheses +are still necessary, though: @code{GTY(())}. Markers can appear: -Sometimes the C code is not enough to fully describe the type structure. -Extra information can be provided by using more @code{GTY} markers. -These markers can be placed: @itemize @bullet @item In a structure definition, before the open brace; @@ -54,46 +43,104 @@ In a global variable declaration, after the keyword @code{static} or In a structure field definition, before the name of the field. @end itemize -The format of a marker is -@verbatim -GTY (([name] ([param]), [name] ([param]) ...)) -@end verbatim -The parameter is either a string or a type name. +Here are some examples of marking simple data structures and globals. + +@smallexample +struct @var{tag} GTY(()) +@{ + @var{fields}@dots{} +@}; + +typedef struct @var{tag} GTY(()) +@{ + @var{fields}@dots{} +@} *@var{typename}; + +static GTY(()) struct @var{tag} *@var{list}; /* @r{points to GC memory} */ +static GTY(()) int @var{counter}; /* @r{save counter in a PCH} */ +@end smallexample + +The parser understands simple typedefs such as +@code{typedef struct @var{tag} *@var{name};} and +@code{typedef int @var{name};}. +These don't need to be marked. + +@menu +* GTY Options:: What goes inside a @code{GTY(())}. +* GGC Roots:: Making global variables GGC roots. +* Files:: How the generated files work. +@end menu + +@node GTY Options +@section The Inside of a @code{GTY(())} + +Sometimes the C code is not enough to fully describe the type +structure. Extra information can be provided with @code{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, @code{@w{GTY ((skip))}} and @code{@w{GTY ((skip ("")))}} are +equivalent. -When the parameter is a string, often it is a fragment of C code. Three -special escapes may be available: +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: @cindex % in GTY option @table @code @item %h -This expands to an expression that evaluates to the current structure. +The current structure. @item %1 -This expands to an expression that evaluates to the structure that -immediately contains the current structure. +The structure that immediately contains the current structure. @item %0 -This expands to an expression that evaluates to the outermost structure -that contains the current structure. +The outermost structure that contains the current structure. @item %a -This expands to the string of the form @code{[i1][i2]...} that indexes -the array item currently being marked. For instance, if the field -being marked is @code{foo}, then @code{%1.foo%a} is the same as @code{%h}. +A partial expression of the form @code{[i1][i2]...} that indexes +the array item currently being marked. @end table +For instance, suppose that you have a structure of the form +@smallexample +struct A @{ + ... +@}; +struct B @{ + struct A foo[12]; +@}; +@end smallexample +@noindent +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]}, +@code{%0} and @code{%1} would both expand to @samp{b}, and @code{%a} +would expand to @samp{[11]}. + +As in ordinary C, adjacent strings will be concatenated; this is +helpful when you have a complicated expression. +@smallexample +@group +GTY ((chain_next ("TREE_CODE (&%h.generic) == INTEGER_TYPE" + " ? TYPE_NEXT_VARIANT (&%h.generic)" + " : TREE_CHAIN (&%h.generic)"))) +@end group +@end smallexample + The available options are: @table @code @findex length -@item length +@item length ("@var{expression}") 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 variable-length array, like this: -@verbatim -struct rtvec_def GTY(()) { - int num_elem; /* number of elements */ +@smallexample +struct rtvec_def GTY(()) @{ + int num_elem; /* @r{number of elements} */ rtx GTY ((length ("%h.num_elem"))) elem[1]; -}; -@end verbatim +@}; +@end smallexample + 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 option is a fragment of C code that calculates the length. @@ -127,8 +174,8 @@ field really isn't ever used. @findex desc @findex tag @findex default -@item desc -@itemx tag +@item desc ("@var{expression}") +@itemx tag ("@var{constant}") @itemx default The type machinery needs to be told which field of a @code{union} is @@ -141,8 +188,8 @@ there is one, otherwise no field in the union will be marked. In the @code{desc} option, the ``current structure'' is the union that it discriminates. Use @code{%1} to mean the structure containing it. -(There are no escapes available to the @code{tag} option, since it's -supposed to be a constant.) +There are no escapes available to the @code{tag} option, since it is a +constant. For example, @smallexample @@ -164,7 +211,7 @@ will treat the field @code{scope} as being present. @findex param_is @findex use_param -@item param_is +@item param_is (@var{type}) @itemx use_param Sometimes it's convenient to define some data structure to work on @@ -173,14 +220,23 @@ type. @code{param_is} specifies the real type pointed to, and @code{use_param} says where in the generic data structure that type should be put. -For instance, to have a @code{htab_t} that points to trees, one should write -@verbatim +For instance, to have a @code{htab_t} that points to trees, one would +write the definition of @code{htab_t} like this: +@smallexample +typedef struct GTY(()) @{ + @dots{} + void ** GTY ((use_param, @dots{})) entries; + @dots{} +@} htab_t; +@end smallexample +and then declare variables like this: +@smallexample htab_t GTY ((param_is (union tree_node))) ict; -@end verbatim +@end smallexample @findex param@var{n}_is @findex use_param@var{n} -@item param@var{n}_is +@item param@var{n}_is (@var{type}) @itemx use_param@var{n} In more complicated cases, the data structure might need to work on @@ -210,7 +266,7 @@ 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. @findex if_marked -@item if_marked +@item if_marked ("@var{expression}") 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 @@ -237,43 +293,46 @@ language frontends. @findex chain_next @findex chain_prev -@item chain_next -@itemx chain_prev +@item chain_next ("@var{expression}") +@itemx chain_prev ("@var{expression}") 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 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, -@code{chain_prev} is an expression for the previous item. The -machinery requires that taking the next item of the previous item -gives the original item. +@code{chain_prev} is an expression for the previous item. For singly +linked lists, use only @code{chain_next}; for doubly linked lists, use +both. The machinery requires that taking the next item of the +previous item gives the original item. @findex reorder -@item reorder +@item reorder ("@var{function name}") Some data structures depend on the relative ordering of pointers. If -the type machinery needs to change that ordering, it 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 option -applies to. The function must be of the type @code{void ()(void *, -void *, gt_pointer_operator, void *)}. The second parameter is the -pointed-to object; the third parameter is a routine that, given a -pointer, can update it to its new value. The fourth parameter is a -cookie to be passed to the third parameter. The first parameter is -the structure that contains the object, or the object itself if it is -a structure. - -No data structure may depend on the absolute value of pointers. Even -relying on relative orderings and using @code{reorder} functions can -be expensive. It is better to depend on properties of the data, like -an ID number or the hash of a string instead. +the precompiled header machinery needs to change that ordering, it +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 +option applies to. The function must take four arguments, with the +signature @samp{@w{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. @code{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. @findex special -@item special - -The @code{special} option is used for those bizarre cases that are just -too hard to deal with otherwise. Don't use it for new code. +@item special ("@var{name}") +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 +special case. See @file{gengtype.c} for further details. Avoid +adding new special cases unless there is no other alternative. @end table @node GGC Roots @@ -282,36 +341,40 @@ too hard to deal with otherwise. Don't use it for new code. @cindex marking roots In addition to keeping track of types, the type machinery also locates -the global variables that the garbage collector starts at. There are -two syntaxes it accepts to indicate a root: +the global variables (@dfn{roots}) that the garbage collector starts +at. Roots must be declared using one of the following syntaxes: -@enumerate +@itemize @bullet @item -@verb{|extern GTY (([options])) [type] ID;|} +@code{extern GTY(([@var{options}])) @var{type} @var{name};} @item -@verb{|static GTY (([options])) [type] ID;|} -@end enumerate - -These are the only syntaxes that are accepted. In particular, if you -want to mark a variable that is only declared as -@verbatim -int ID; -@end verbatim -or similar, you should either make it @code{static} or you should create -a @code{extern} declaration in a header file somewhere. +@code{static GTY(([@var{options}])) @var{type} @var{name};} +@end itemize +@noindent +The syntax +@itemize @bullet +@item +@code{GTY(([@var{options}])) @var{type} @var{name};} +@end itemize +@noindent +is @emph{not} accepted. There should be an @code{extern} declaration +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 +@code{static}. @node Files @section Source Files Containing Type Information @cindex generated files @cindex files, generated -Whenever you add @code{GTY} markers to a new source file, there are three -things you need to do: +Whenever you add @code{GTY} markers to a source file that previously +had none, or create a new source file containing @code{GTY} markers, +there are three things you need to do: @enumerate @item You need to add the file to the list of source files the type -machinery scans. There are three cases: +machinery scans. There are four cases: @enumerate a @item @@ -320,19 +383,18 @@ automatically; if not, you should add it to @code{target_gtfiles} in the appropriate port's entries in @file{config.gcc}. @item -For files shared by all front ends, this is done by adding the -filename to the @code{GTFILES} variable in @file{Makefile.in}. +For files shared by all front ends, add the filename to the +@code{GTFILES} variable in @file{Makefile.in}. @item -For any other file used by a front end, this is done by adding the -filename to the @code{gtfiles} variable defined in +For files that are part of one front end, add the filename to the +@code{gtfiles} variable defined in the appropriate @file{config-lang.in}. For C, the file is @file{c-config-lang.in}. -This list should include all files that have GTY macros in them that -are used in that front end, other than those defined in the previous -list items. For example, it is common for front end writers to use -@file{c-common.c} and other files from the C front end, and these -should be included in the @file{gtfiles} variable for such front ends. +@item +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 +that use it. @end enumerate @item |